Issue Reporting And Support

The issue-reporting and support-telemetry domains give downstream apps a shared path for user-submitted issues, event ingest, deduplication, case linking, and operator review. They keep product support data near identity, application, and entitlement context instead of making every app invent a support pipeline.

Mental Model

Primary Domains

Domain	Responsibility
`issue_reporting_platform`	Canonical issue report creation, voice-token support, and case linking
`support_telemetry_platform`	Event ingest, deduplication, case lifecycle, and operator views
`security`	Security alerts that can be created by other domains
`audit`	Audit log query and retention lifecycle

Server-Side Telemetry Event

Send this shape to POST /api/v1/support-telemetry/events from a trusted server with the application’s secret key. event_key deduplicates retries. The application scope defaults to the key’s application.


{
  "event_key": "checkout-timeout-example-001",
  "occurred_at": "2026-10-23T12:00:00Z",
  "source_channel": "frontend",
  "event_type": "frontend_error",
  "severity": "error",
  "actor": { "type": "service" },
  "payload": {
    "route": "/checkout",
    "browser": "chrome"
  }
}

Common Mistakes

Support telemetry can grow quickly. Preserve dedupe and backpressure behavior when changing ingest paths.

Treating support telemetry as a general analytics pipeline.
Forgetting to scope operator views by application and role.
Logging sensitive content into issue metadata without checking PII handling.

Frontend Integration (`spaps-issue-reporting-react`)

Use the hosted issue-reporting API through the React client package; see Companion packages.

The React package expects a client object with an issueReporting surface:

getStatus
list
get
create
update
reply
optional createVoiceToken for voice mode


import { FloatingIssueReportButton, IssueReportingProvider } from 'spaps-issue-reporting-react'
;<IssueReportingProvider
  client={spaps}
  isEligible={isAuthenticated}
  principalId={user?.id ?? null}
  defaultScope="mine"
  inputModes={['text', 'voice']}
>
  <FloatingIssueReportButton />
</IssueReportingProvider>

Derive isAuthenticated and user from your current session. Place the provider under your React Query provider and configure spaps to send that user’s current token. The application must have issue reporting enabled.

Voice mode requires:

voice input enabled for the hosted staging or production application
an authenticated user token so createVoiceToken can mint short-lived browser tokens