spaps-issue-reporting-react

Shared React issue-reporting UI for SPAPS-compatible apps.

Examples in this README use placeholder IDs and app labels. Replace them with values from your own product, session model, and API client.

Install

npm install spaps-issue-reporting-react react react-dom @tanstack/react-query

This package targets Node.js >=18 and React 18+. Voice input uses the package's @elevenlabs/react dependency and a SPAPS-minted single-use token.

When It Fits

| Need | Package gives you | | --- | --- | | A visible issue-report entry point | Floating button with open/recent state | | A guided reporting flow | Page-first create flow, optional section picking, create/edit/reply modal | | A lightweight integration contract | Any client that exposes issueReporting.* methods | | App-level control | Eligibility, reporter identity, scope, page policy, and copy stay in your app |

Quick Start

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import {
  FloatingIssueReportButton,
  IssueReportingPageConfig,
  IssueReportingProvider,
  ReportableSection,
} from "spaps-issue-reporting-react";
import { spaps } from "./spapsClient";

const queryClient = new QueryClient();

export function AppShell() {
  return (
    <QueryClientProvider client={queryClient}>
      <IssueReportingProvider
        client={spaps}
        isEligible={true}
        principalId="user_123"
        reporterRoleHint="staff"
        defaultScope="mine"
        inputModes={["text", "voice"]}
        defaultInputMode="text"
      >
        <IssueReportingPageConfig createMode="surface_preferred" />

        <ReportableSection
          reportableName={{
            componentKey: "patient_chart",
            componentLabel: "Patient Chart",
            metadata: { area: "overview" },
          }}
          className="rounded-xl"
        >
          <PatientChart />
        </ReportableSection>

        <FloatingIssueReportButton />
      </IssueReportingProvider>
    </QueryClientProvider>
  );
}

What Your App Still Owns

• A client with issueReporting.getStatus, list, get, create, update, and reply.
• A client with issueReporting.createVoiceToken when inputModes includes voice.
• Any auth and token refresh behavior needed by that client.
• Eligibility rules such as feature flags, account state, or role checks.
• The current principal ID and optional role hint passed into the provider.
• Whether users can switch between mine and a custom tenant queue scope. The stock SPAPS API supports mine only; use allowTenantScope only with a client that implements tenant reads.
• Whether a page defaults to general_page, surface_required, or surface_preferred reporting.
• Whether the app allows ["text"], ["voice"], or ["text", "voice"] report input.
• Styling integration if your build strips package utility classes.
• Any app-specific copy overrides.
• Origin registration on the owning SPAPS application if the browser calls SPAPS directly with a publishable key.

For direct browser integrations, allowed_origins is stored on the SPAPS applications row that owns the publishable key. It is not configured on this package. If multiple hostnames share one SPAPS application, put all of them on that row. Updating allowed_origins does not require restarting SPAPS.

Voice Input

Voice mode is opt-in per app. Configure the owning SPAPS application with either:

{
  "issue_reporting_input_modes": ["text", "voice"]
}

or:

{
  "issue_reporting": {
    "input_modes": ["voice"]
  }
}

The SPAPS server also needs ELEVENLABS_API_KEY. The browser calls your normal SPAPS client, which mints a short-lived Scribe token through issueReporting.createVoiceToken(). The committed transcript is submitted as the issue note; raw audio is not stored by this package.

<IssueReportingProvider
  client={spaps}
  isEligible={true}
  inputModes={["voice"]}
  defaultInputMode="voice"
  voice={{
    modelId: "scribe_v2_realtime",
    microphone: {
      echoCancellation: true,
      noiseSuppression: true,
      autoGainControl: true,
    },
  }}
>
  <FloatingIssueReportButton />
</IssueReportingProvider>

When text and voice are both enabled, the modal keeps the textarea available and lets the user append a committed transcript into the editable note.

Exported Surface

| Export | Purpose | | --- | --- | | IssueReportingProvider | Owns queries, modal state, copy, scope, and report-mode behavior | | IssueReportingPageConfig | Per-page override for general_page, surface_required, or surface_preferred create policy | | FloatingIssueReportButton | Renders the floating entry point, popover, and modal | | ReportableSection | Marks a region as selectable when report mode is active | | useIssueReporting | Full provider state, including startNewIssue(), openPageIssueModal(), and enterReportMode() | | useIssueReportingStatus | Query helper for summary state | | useIssueReportingHistory | Query helper for filtered history lists | | useIssueReportingMutations | Mutation helpers for create, update, and reply flows | | useReportMode | Low-level selection state for custom wrappers |

Styling Notes

• The package ships utility-class based markup for the button, popover, modal, and report-mode highlights.
• If your CSS build only scans local source files, include this package in the scan path or safelist the relevant classes.
• FloatingIssueReportButton accepts className and positionClassName for placement tweaks.
• Provider copy can be overridden with the copy prop.

Development

cd packages/issue-reporting-react
npm ci
npm run build
npm test

Troubleshooting

The button renders but the modal never opens

Make sure FloatingIssueReportButton is rendered inside IssueReportingProvider and that isEligible is true.

I want page-level reporting without wrapping every widget

That is the default. Report This Page opens immediately and captures the current route plus the inventory of visible registered reportable sections on the active page.

Report mode turns on, but sections do not respond

Wrap the target UI in ReportableSection, or call useIssueReporting().selectPanel(...) from a custom control.

This page should force a specific surface selection

Render IssueReportingPageConfig with createMode="surface_required" inside that page's visible provider subtree. Hidden mounted routes, tabs, or panels do not affect the active page's policy.

Tenant scope never appears

The stock SPAPS API supports mine only. Set allowTenantScope={true} only when your client implements tenant-scoped getStatus and list calls.

Styles look unformatted

Include the package in your Tailwind or CSS-content scan, or override the rendered classes in your host app.

Voice controls do not appear

Pass inputModes={["voice"]} or inputModes={["text", "voice"]} to the provider, and enable voice in the owning SPAPS application's issue-reporting settings.

Voice starts with a token error

Confirm that the SPAPS server has ELEVENLABS_API_KEY set and that the current user is authenticated and eligible for issue reporting.

Limitations

• This package assumes React Query is already part of the host app.
• It focuses on the issue-reporting UI flow; queue policy, triage rules, and backend delivery stay outside the package.
• Deep visual changes may require wrapping the exported components rather than using props alone.

FAQ

Do I need the full SPAPS SDK?

No. You only need a client object that implements the issueReporting methods expected by the provider.

Can I launch report mode from my own button?

Yes. Use useIssueReporting().enterReportMode() inside the provider tree.

Can I open a page-level report from my own button?

Yes. Use useIssueReporting().openPageIssueModal() or useIssueReporting().startNewIssue().

Can I report plain strings instead of structured descriptors?

Yes. reportableName accepts either a string or a { componentKey, componentLabel, ... } object.

Can I hide the feature for some accounts?

Yes. Drive that from isEligible.

Does this package manage tenant permissions?

No. It only renders scope choices that your app explicitly allows.

Does this package manage CORS or allowed_origins?

No. This package is UI only. If your browser app calls SPAPS directly with a publishable key, the relevant SPAPS application row must include that browser origin in allowed_origins.

Metadata

• package_name: spaps-issue-reporting-react
• latest_version: 0.2.0
• minimum_runtime: Node.js >=18.0.0
• api_base_url: https://api.sweetpotato.dev

About Contributions

About Contributions: Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

UNLICENSED