Skip to main content

Shared Services, Hooks, and Utilities Feature Context

Source: .agents/references/features/shared-services-hooks-and-utilities.md

Content​

Shared Services, Hooks, and Utilities Feature Context

Purpose​

Shared services, hooks, and utilities are cross-cutting infrastructure used by most product domains: service helpers, request wrappers, analytics, localization, storage wrappers, Sentry/PostHog, uploads, date/time helpers, route helpers, browser utilities, image sizing, safe rendering, and reusable hooks. Changes here have broad blast radius and require extra care.

User-Facing Workflows​

  • Most user-facing workflows indirectly rely on shared helpers for data fetching, auth, localization, analytics, uploads, error rendering, URL construction, and storage.
  • Shared hooks power pagination, query params, outside click detection, page leave warnings, uploads, unsplash search, chat widgets, and common public page data.
  • Utilities can run in browser, server, middleware, or test contexts. Verify runtime before using browser globals or Node/Bun APIs.

Key Entrypoints​

  • Services:
    • src/services/agentDiscovery/pageContextService.ts
    • src/services/helpers/
    • src/services/commonService.js
    • src/services/uploadService.js
    • src/services/uploadImageService.ts
    • src/services/videoUploadService.js
    • src/services/sessionAnalytics/sessionAnalyticsService.js
    • src/services/notificationService.ts
    • src/services/unsplashService.ts
  • Hooks:
    • src/hooks/useApi.ts
    • src/hooks/usePagination.ts
    • src/hooks/useQueryParams.ts
    • src/hooks/usePresignedImageUpload.ts
    • src/hooks/useUnsplashSearch.ts
    • src/hooks/usePageLeaveWarning.ts
    • src/hooks/useOutsideComponentClickDetect.js
    • src/hooks/useRemoveScrollDuringOverlay.ts
    • src/hooks/useLogEvent.js
    • src/hooks/useLocale.js
    • src/hooks/useSentryReplayOnPage.js
  • Utilities:
    • src/utility/webMcpPageContext.ts
    • src/utility/webMcpPublicPageRegistry.ts
    • src/utility/webMcpRouteFamilyContext.ts
    • src/utility/analytics.js
    • src/utility/analyticsConsts.js
    • src/utility/browserUtils.js
    • src/utility/config.js
    • src/utility/cookieService.ts
    • src/utility/dateHelper/
    • src/utility/domHelpers.js
    • src/utility/getImageUrlWithSizing.js
    • src/utility/helpers.ts
    • src/utility/intl.ts
    • src/utility/localStorageService.js
    • src/utility/localizationHelpers.js
    • src/utility/parseJSON.js
    • src/utility/routesHelper.ts
    • src/utility/safeErrorRender.tsx
    • src/utility/sentryService.ts
    • src/utility/sessionStorageService.js
    • src/utility/stringHelper.js
    • src/utility/urlHelpers.js
    • src/utility/validationHelper.ts

Data Flow and Service Boundaries​

  • Public page-context discovery is a read-only shared surface. The official hosted MCP endpoint is https://mcp.nas.com/mcp: discovery and supported onboarding tools are anonymous, while protected tools trigger lazy OAuth through https://auth.nas.com. Use live tools/list for its catalog.
  • The English-only MCP installation guide has one canonical route: /mcp. Keep it in NO_LOCALE_PATHS so untranslated locale-prefixed variants redirect to /mcp rather than creating duplicate indexable pages.
  • src/pages/api/mcp.page.ts remains an internal JSON-RPC compatibility resource for registered public resources/templates and reads public page context through getPublicPageAgentContext; public docs must not advertise it as the Nas.com MCP endpoint.
  • Page-context discovery flows through src/services/agentDiscovery/pageContextService.ts, registered static docs in src/utility/webMcpPublicPageRegistry.ts, route-family fallbacks in src/utility/webMcpRouteFamilyContext.ts, and path/URI helpers in src/utility/webMcpPageContext.ts.
  • Search indexing and agent discovery are separate contracts. Exact /get-started is indexable and an explicit read-only agent suggestion target. Exact /subscribe-plan remains noindex but is also an explicit read-only agent suggestion target. Nested variants remain blocked so agent context cannot expose private onboarding, subscription, payment, or checkout state.
  • Request helper changes can affect all service modules. Inspect callers and run lint/tests broadly when changing src/services/helpers/.
  • Browser storage must go through existing storage utilities; direct storage access violates repo rules and makes SSR/middleware behavior fragile.
  • Upload hooks/services often depend on presigned URL signatures, image/video compression, and external APIs. Preserve content type, file size, and error handling.
  • Analytics helpers should not expose secrets, tokens, or PII. Preserve event naming and action constants unless the task explicitly changes instrumentation.
  • Date/time helpers affect timezone-sensitive UI. Check tests in src/utility/dateHelper/ and adjacent utility tests when changing formatting or timezone logic.
  • Shared hooks should be runtime-safe and avoid unnecessary effects. If an effect is required for browser subscriptions or DOM APIs, keep cleanup explicit.
  • Shared editable Lexical editors treat a click below the final rendered top-level node as an intent to continue writing. Reuse an existing trailing empty paragraph or append exactly one; clicks within rendered content must retain Lexical's native selection behavior.

Conventions and Gotchas​

  • Prefer TypeScript for new shared files. For existing JavaScript utilities, keep the extension unless a migration is requested.
  • Avoid any, unsafe as, and non-null assertions in shared TypeScript. Fix types at boundaries.
  • For public discovery changes, keep public/openapi.json, public/.well-known/agent.json, public/.well-known/public-pages.json, public/sitemap.xml, public/schemamap.xml, Link headers in next.config.js, hosted MCP discovery manifests, and registered MCP/page-context docs aligned.
  • Public discovery guards must block private/authenticated/API internals and framework/static assets. Private/member-only examples are covered by focused tests in src/services/agentDiscovery/pageContextService.test.ts and src/pages/api/mcp.page.test.ts.
  • Do not add thin index re-export files. Put implementation in the main file.
  • Do not introduce generic abstractions unless they remove real duplication across current callers.
  • Keep helpers pure where possible; side effects should be explicit in service/hook boundaries.
  • Shared changes should include focused tests when existing tests exist or when behavior is easy to cover.
  • Sentry expected-error suppression should prefer source-level skips for already handled user/provider outcomes, such as checkout availability messages, payment-provider next-action declines, and captcha widget callbacks. Keep global ignore patterns narrow for variants that have no source-owned capture site.
  • .agents/rules/clean-typescript.mdc
  • .agents/rules/prefer-typescript-files.mdc
  • .agents/rules/no-type-assertion-as.mdc
  • .agents/rules/no-try-catch-service-api.mdc
  • .agents/rules/web-security.mdc
  • .agents/rules/bun-first.mdc
  • .agents/references/coding-standard/useeffect-guidance.md

Useful Graph Queries and Fallback Searches​

Use the terms below with search_graph/search_code, then run inbound and outbound trace_path for any shared symbol being changed. Run these shell searches only as documented fallbacks.

rtk rg "authorizedRequest|publicAxiosRequest|localStorageService|sessionStorageService|showErrorToast|analytics|Sentry|PostHog|presigned|upload" src/services src/hooks src/utility
rtk rg "getPublicPageAgentContext|REGISTERED_PUBLIC_PAGE_CONTEXTS|getPublicRouteFamilyContext|getMcpResourceUri|resources/templates/list|tools/list" src/services/agentDiscovery src/pages/api src/utility public
rtk find src/services/helpers src/hooks src/utility -maxdepth 3 -type f
rtk rg "describe\\(|it\\(|test\\(" src/utility src/hooks src/services

Update Triggers​

Update this reference when request helpers, storage wrappers, analytics utilities, upload services, shared hooks, shared editor behavior, localization helpers, date/time utilities, Web MCP resource discovery, or public page-context helpers change.