Skip to main content
Version: 4.37.0

feat-error-catalog

✨ New Features​

Error Catalog with User-Friendly Messages, Spotlight Banner & Help Page​

Goal: Turn raw technical errors (SharePoint access denied, proxy failures, expired sessions, account mismatch...) into clear, actionable messages for end users, and let the team tweak those messages live — without shipping a new box version.

Solution: Added a remote error catalog hosted on Cloudflare (KV-backed, edited via a /errors/admin page). The box pulls the catalog at boot, refreshes it periodically, and resolves each failed task's error against it — displaying a friendly message inline, an "i" link to a dynamic help page, and, when flagged, a consolidated spotlight banner. The matching algorithm is documented in docs/error-catalog-matching.md.

Features:

  • Failed tasks show a user-friendly message directly on the card, inline with the source/destination tags, with an "i" icon linking to the help page (carrying every active error key).
  • An explicit "View details / Hide details" toggle (chevron) reveals the technical error chain with a smooth animation — no more hidden click on the whole card.
  • A single consolidated spotlight banner surfaces account/config problems ("Account misconfiguration detected") with a "Read more" link that opens the Tasks panel and the help page with all error keys.
  • A dynamic help page (/errors/help?key=KEY1,KEY2) renders each error with Markdown descriptions, grouped by category (account & configuration vs document deposit), served from the worker.
  • The "Help" button in the navbar opens the BCYIP Help Center (Notion).
  • The catalog (patterns, messages, descriptions, spotlight flag) is editable live via /errors/admin; changing rules does not require a box release.
  • Existing failed tasks are re-resolved whenever the catalog (re)loads, so message changes apply retroactively.
  • Error reports to neo-backend now include the file hash for easier triage.

Implementation Details:

  • Matching runs client-side over the error cause chain, prioritizing the match closest to the root cause; matchOn uses OR substring logic (see docs/error-catalog-matching.md).
  • Catalog is cached at boot with an in-code DEFAULT_CATALOG fallback if the endpoint is unreachable, merged with remote entries on each refresh.
  • REFS_BASE_URL is built from env.refs_domain (same convention as the other refs URLs).
  • Worker exposes GET/POST /errors/catalog (admin-key protected), serves the admin UI at /errors/admin and the dynamic help page at /errors/help. An OpenAPI spec (openapi.yaml) is published and rendered as interactive API docs (Scalar) at /api-docs.
  • Dev-only console helpers (__mockError / __clearMockErrors) inject realistic failed tasks; disabled in production builds.

Files Modified:

  • src/protocol/refsErrors.ts (new) - Catalog loading/cache/refresh, resolveError() chain matching, initErrorCatalog(), refresh callback
  • src/utils/errors/error.types.ts - errorKey / userMessage / spotlight on IPBError
  • src/utils/devErrorTester.ts (new) - Dev-only mock failed tasks
  • src/services/fileProtect/utils.pipe.ts - Resolve catalog entry on caught errors
  • src/services/fileProtect/taskActions.pipe.ts - Add fileHash to the error report context
  • src/components/TasksPanel/TaskView.tsx - Inline user message + "i" help link + animated details toggle
  • src/components/TasksPanel/SpotlightBanner.tsx (new) - Consolidated banner with help link
  • src/components/TasksPanel/TasksPanel.tsx - Render the spotlight banner
  • src/components/TasksPanel/redux/actions.ts - Resolve errors when loading persisted tasks
  • src/components/TasksPanel/TasksPanel.scss / src/scss/app.scss - Banner, message and toggle styles
  • src/components/Navabar/Navbar.tsx - Help button opens BCYIP Help Center
  • src/index.tsx / src/App.tsx - Init catalog, re-resolve existing failed tasks on refresh
  • index.js - Single reusable help window, open external links in system browser
  • docs/error-catalog-matching.md (new) - Matching algorithm documentation
  • microservices/refs-domain/refs-worker.js - /errors/catalog, /errors/admin, /errors/help, /api-docs routes (separate microservices repo)
  • microservices/refs-domain/wrangler.toml - account_id + static assets binding for ./public
  • microservices/refs-domain/public/ (new) - errors-admin.html, help-page.html, api-docs.html, openapi.yaml