spaps-issue-reporting-react 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-06-04
+
+- Added the reporter-visible operator-to-reporter conversation thread (`IssueReportMessageThread`), rendered inside the issue detail modal when the client implements `issueReporting.listMessages`/`submitMessage`. It shows only `active`, reporter-visible projection rows (retracted/superseded/non-visible excluded), distinguishes operator vs reporter authorship and message kind, exposes a `needs_response` affordance plus a floating-entrypoint badge, and includes a clarification-response composer that submits with a client-generated `idempotency_key` and handles `409 ISSUE_REPORT_MESSAGE_CONFLICT`.
+
+## [0.4.1] - 2026-05-16
+
 - Added optional screenshot attachment UI that uploads private PNG/JPEG/WebP evidence through `issueReporting.uploadAttachment`, validates size/count locally, and submits only backend attachment IDs.
 
 ## [0.4.0] - 2026-05-11

package/README.md

@@ -73,6 +73,11 @@ export function AppShell() {
 - A client with `issueReporting.getStatus`, `list`, `get`, `create`, `update`, and `reply`.
 - A client with `issueReporting.createVoiceToken` when `inputModes` includes `voice`.
 - A client with `issueReporting.uploadAttachment(file, { filename })` when you want screenshot uploads.
+- Optionally, a client with `issueReporting.listMessages(issueReportId)` and
+  `issueReporting.submitMessage(issueReportId, { body, idempotency_key })` to wire the
+  operator-to-reporter message thread (and its `needs_response` badge). When these are present,
+  the bundled `IssueReportMessageThread` renders the conversation inside the issue detail modal
+  (see [Conversation Thread](#conversation-thread)).
 - 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.
@@ -148,18 +153,57 @@ The picker accepts PNG, JPEG, and WebP files, enforces the 10 MiB per-file limit
 
 This package does not store screenshots, generate public URLs, or redact image content. SPAPS stores screenshots through its shared hosted-asset boundary as private objects, and access URLs are minted by the backend after authorization. Host apps should warn users before upload when a screenshot might include PHI, credentials, payment data, or other sensitive content.
 
+## Conversation Thread
+
+Support operators can ask a reporter for clarification and post a final resolution message. Those messages flow into an allowlisted, reporter-visible projection that the reporter reads back as a conversation. This package renders that surface when the client implements the two optional message methods:
+
+```tsx
+const client = {
+  issueReporting: {
+    ...spaps.issueReporting,
+    listMessages: (issueReportId: string) =>
+      spaps.issueReporting.listMessages(issueReportId),
+    submitMessage: (issueReportId, payload) =>
+      spaps.issueReporting.submitMessage(issueReportId, payload),
+  },
+};
+```
+
+When `listMessages` is present, `FloatingIssueReportButton` mounts the exported `IssueReportMessageThread` inside the issue detail modal (the Edit/Reply views). The thread:
+
+- Renders only `active`, `reporter_visible` projection rows in chronological order. Retracted and superseded operator messages, non-visible rows, and raw `support_case_events` payloads are never displayed. The backend filters this; `selectReporterVisibleMessages` re-asserts the same rule in the UI.
+- Distinguishes operator (`Support`) vs reporter (`You`) authorship, labels each message kind (`clarification_request`, `reporter_response`, `final_response`), and shows a relative timestamp.
+- Shows a **needs-response** affordance when the API's `needs_response` flag is set (an open clarification request awaiting an answer), and surfaces a matching dot badge on the floating entrypoint while that thread is open.
+- Renders a reporter clarification-response composer (shown only when the client implements `submitMessage`). It calls `submitMessage(issueReportId, { body, idempotency_key })` with a client-generated `idempotency_key`. A key reused with a different body returns `409 ISSUE_REPORT_MESSAGE_CONFLICT`; the composer detects this (`isReporterMessageConflict`), shows the conflict copy, and rotates the key for retry.
+- Exposes loading, empty, and error (with retry) states.
+
+The composer does not reopen a closed case; reopen semantics stay with the Reply flow. You can also mount `IssueReportMessageThread` directly (outside the modal) inside your own issue detail view:
+
+```tsx
+import { IssueReportMessageThread } from "spaps-issue-reporting-react";
+
+<IssueReportMessageThread issueReportId={issue.id} />;
+```
+
+All thread strings are overridable through the provider `copy` prop. The thread copy keys are: `threadTitle`, `threadDescription`, `threadLoading`, `threadLoadFailed`, `threadEmpty`, `threadNeedsResponseBadge`, `threadAuthorOperator`, `threadAuthorReporter`, `threadKindClarificationRequest`, `threadKindReporterResponse`, `threadKindFinalResponse`, `threadResponseLabel`, `threadResponsePlaceholder`, `threadResponseSubmitAction`, `threadResponseSubmittingAction`, `threadResponseConflict`, and `threadResponseFailed`.
+
 ## 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 |
+| `FloatingIssueReportButton` | Renders the floating entry point, popover, modal, and (when the client supports messages) the conversation thread |
+| `IssueReportMessageThread` | Renders the reporter-visible operator-to-reporter conversation for one issue report, with a clarification-response composer |
 | `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 |
+| `useIssueReportingMessages` | Query helper for one issue report's reporter-visible message thread |
+| `useIssueReportingMessageMutation` | Mutation helper for submitting a reporter clarification response |
+| `selectReporterVisibleMessages` | Filters a message list to `active`, reporter-visible rows in chronological order |
+| `isReporterMessageConflict` | Detects a `409 ISSUE_REPORT_MESSAGE_CONFLICT` from the client transport |
 | `useReportMode` | Low-level selection state for custom wrappers |
 
 ## Styling Notes
@@ -217,6 +261,10 @@ Confirm that the SPAPS server has `ELEVENLABS_API_KEY` set and that the current
 
 Expose `issueReporting.uploadAttachment` on the client passed to `IssueReportingProvider`. The package intentionally hides the picker when the upload helper is absent.
 
+### The conversation thread does not appear
+
+Expose `issueReporting.listMessages` on the client passed to `IssueReportingProvider`, then open an existing issue's detail (Edit/Reply). The thread is intentionally hidden when the client cannot list messages. The response composer additionally requires `issueReporting.submitMessage`; without it the thread renders read-only.
+
 ## Limitations
 
 - This package assumes React Query is already part of the host app.
@@ -253,10 +301,19 @@ No. It only renders scope choices that your app explicitly allows.
 
 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`.
 
+## Design system
+
+This package is intentionally theme-neutral and uses accessible Radix behavior
+primitives plus a restrained slate palette so it blends into the host app. The
+Design System Registry (DSR) adoption decision for this surface is an **explicit
+deferral** because no suitable theme-neutral registry item exists yet. The
+repository-level `docs/DSR-DECISION.md` captures the reasoning, file-level audit,
+and revisit trigger.
+
 ## Metadata
 
 - `package_name`: `spaps-issue-reporting-react`
-- `latest_version`: `0.4.0`
+- `latest_version`: `0.4.2`
 - `minimum_runtime`: `Node.js >=18.0.0`
 - `api_base_url`: `https://api.sweetpotato.dev`
 

package/dist/index.d.mts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
 import * as spaps_types from 'spaps-types';
-import { IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, UpdateIssueReportRequest, ReplyIssueReportRequest, IssueReportingVoiceTokenResult, IssueReportAttachmentOut, IssueReportingInputMode, IssueReportingVoiceProvider } from 'spaps-types';
-export { CreateIssueReportRequest, IssueReport, IssueReportAttachmentOut, IssueReportListResult, IssueReportScope, IssueReportStatus, IssueReportStatusResult, ReplyIssueReportRequest, UpdateIssueReportRequest } from 'spaps-types';
+import { IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, UpdateIssueReportRequest, ReplyIssueReportRequest, IssueReportingVoiceTokenResult, IssueReportAttachmentOut, ListIssueReportMessagesResponse, CreateReporterMessageRequest, IssueReportMessage, IssueReportingInputMode, IssueReportingVoiceProvider } from 'spaps-types';
+export { CreateIssueReportRequest, CreateReporterMessageRequest, IssueReport, IssueReportAttachmentOut, IssueReportListResult, IssueReportMessage, IssueReportScope, IssueReportStatus, IssueReportStatusResult, ListIssueReportMessagesResponse, ReplyIssueReportRequest, UpdateIssueReportRequest } from 'spaps-types';
 import * as _tanstack_query_core from '@tanstack/query-core';
 import * as _tanstack_react_query from '@tanstack/react-query';
 
@@ -39,6 +39,8 @@ interface IssueReportingClient {
         uploadAttachment?: (file: Blob, options?: {
             filename?: string;
         }) => Promise<IssueReportAttachmentOut>;
+        listMessages?: (issueReportId: string) => Promise<ListIssueReportMessagesResponse>;
+        submitMessage?: (issueReportId: string, payload: CreateReporterMessageRequest) => Promise<IssueReportMessage>;
     };
 }
 interface ReportableTargetDescriptor {
@@ -96,6 +98,23 @@ interface IssueReportingCopy {
     originHumanLabel: string;
     originMachineLabel: string;
     machineOriginFallback: string;
+    threadTitle: string;
+    threadDescription: string;
+    threadLoading: string;
+    threadLoadFailed: string;
+    threadEmpty: string;
+    threadNeedsResponseBadge: string;
+    threadAuthorOperator: string;
+    threadAuthorReporter: string;
+    threadKindClarificationRequest: string;
+    threadKindReporterResponse: string;
+    threadKindFinalResponse: string;
+    threadResponsePlaceholder: string;
+    threadResponseLabel: string;
+    threadResponseSubmitAction: string;
+    threadResponseSubmittingAction: string;
+    threadResponseConflict: string;
+    threadResponseFailed: string;
 }
 interface IssueReportingProviderProps {
     client: IssueReportingClient;
@@ -120,6 +139,9 @@ interface IssueReportingPageConfigProps {
     createMode: IssueReportingCreateMode;
 }
 
+declare function IssueReportMessageThread({ issueReportId, }: {
+    issueReportId: string;
+}): react_jsx_runtime.JSX.Element | null;
 declare function FloatingIssueReportButton({ className, positionClassName, }: FloatingIssueReportButtonProps): react_jsx_runtime.JSX.Element | null;
 declare function ReportableSection({ reportableName, children, className, as: Component, }: {
     reportableName: ReportableInput;
@@ -174,6 +196,8 @@ type IssueReportingContextValue = {
     voice: Required<Pick<IssueReportingVoiceConfig, "provider" | "modelId" | "requireMicrophonePermission">> & {
         microphone?: IssueReportingVoiceConfig["microphone"];
     };
+    needsResponseIssueIds: string[];
+    setNeedsResponse: (issueReportId: string, needsResponse: boolean) => void;
 };
 declare const defaultIssueReportingCopy: IssueReportingCopy;
 declare const issueReportingKeys: {
@@ -181,6 +205,7 @@ declare const issueReportingKeys: {
     status: (scope: IssueReportScope) => readonly ["spaps-issue-reporting", "status", IssueReportScope];
     history: (scope: IssueReportScope) => readonly ["spaps-issue-reporting", "history", IssueReportScope];
     detail: (issueReportId: string) => readonly ["spaps-issue-reporting", "detail", string];
+    messages: (issueReportId: string) => readonly ["spaps-issue-reporting", "messages", string];
 };
 declare function isOpenIssueStatus(status: IssueReportStatus): boolean;
 declare function isClosedIssueStatus(status: IssueReportStatus): boolean;
@@ -192,6 +217,25 @@ declare function getEntryPointState(status?: {
     has_recent_resolved: boolean;
 } | null): "open" | "recent_resolved" | "neutral";
 declare function getEntryPointClassName(state: "open" | "recent_resolved" | "neutral"): string;
+/**
+ * Defensive reporter-visibility filter for the conversation surface.
+ *
+ * The reporter `GET /messages` endpoint already returns only `active`,
+ * reporter-visible projection rows (retracted/superseded operator messages and
+ * raw `support_case_events` payloads are excluded server-side). This filter
+ * re-asserts that contract in the UI so a non-allowlisted row can never be
+ * rendered to a reporter even if a client or fixture passes one through. Rows
+ * are returned in chronological (`created_at`) order.
+ */
+declare function selectReporterVisibleMessages(messages: IssueReportMessage[]): IssueReportMessage[];
+/**
+ * Detect the idempotency-key conflict surfaced by the reporter message API as
+ * `409 ISSUE_REPORT_MESSAGE_CONFLICT`. The provider only depends on the
+ * abstract `IssueReportingClient` contract, so this inspects whatever shape the
+ * host client throws (Error message, `code`, or HTTP `status`) without binding
+ * to a specific transport.
+ */
+declare function isReporterMessageConflict(error: unknown): boolean;
 declare function getIssueNoteLengthMessage(note: string, copy: IssueReportingCopy): string;
 declare function useIssueReporting(): IssueReportingContextValue;
 declare function IssueReportingPageConfig({ createMode, }: IssueReportingPageConfigProps): react_jsx_runtime.JSX.Element;
@@ -391,6 +435,30 @@ declare function useIssueReportingMutations(): {
         attachment_ids?: string[];
     }, unknown>;
 };
+/**
+ * Query helper for the reporter-visible message thread of one issue report.
+ *
+ * Keyed by `issue_report_id`. Enabled only when the caller is eligible, an
+ * issue id is provided, and the host client implements the optional
+ * `listMessages` contract method. The query returns the raw server response so
+ * consumers can read `needs_response` for the badge; rendering code should pass
+ * `data.items` through {@link selectReporterVisibleMessages} before display.
+ */
+declare function useIssueReportingMessages(issueReportId: string | null): _tanstack_react_query.UseQueryResult<ListIssueReportMessagesResponse, Error>;
+/**
+ * Mutation helper for submitting a reporter clarification response.
+ *
+ * Calls the host client's `submitMessage(issueReportId, { body, idempotency_key })`
+ * and, on success, invalidates the thread query so the new `reporter_response`
+ * row and refreshed `needs_response` flag are re-fetched. The caller supplies a
+ * client-generated `idempotency_key` for safe retries; a key reused with a
+ * different body surfaces as a `409` conflict the UI can detect with
+ * {@link isReporterMessageConflict}.
+ */
+declare function useIssueReportingMessageMutation(issueReportId: string | null): _tanstack_react_query.UseMutationResult<IssueReportMessage, unknown, {
+    body: string;
+    idempotency_key?: string;
+}, unknown>;
 declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, defaultCreateMode, inputModes, defaultInputMode, voice, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
 
 interface ReportModeContextValue {
@@ -404,4 +472,4 @@ interface ReportModeContextValue {
 declare const ReportModeContext: React.Context<ReportModeContextValue | null>;
 declare function useReportMode(): ReportModeContextValue | null;
 
-export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };
+export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, IssueReportMessageThread, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, isReporterMessageConflict, issueReportingKeys, selectReporterVisibleMessages, useIssueReporting, useIssueReportingHistory, useIssueReportingMessageMutation, useIssueReportingMessages, useIssueReportingMutations, useIssueReportingStatus, useReportMode };

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
 import * as spaps_types from 'spaps-types';
-import { IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, UpdateIssueReportRequest, ReplyIssueReportRequest, IssueReportingVoiceTokenResult, IssueReportAttachmentOut, IssueReportingInputMode, IssueReportingVoiceProvider } from 'spaps-types';
-export { CreateIssueReportRequest, IssueReport, IssueReportAttachmentOut, IssueReportListResult, IssueReportScope, IssueReportStatus, IssueReportStatusResult, ReplyIssueReportRequest, UpdateIssueReportRequest } from 'spaps-types';
+import { IssueReportScope, IssueReportStatusResult, IssueReportStatus, IssueReportListResult, IssueReport, CreateIssueReportRequest, UpdateIssueReportRequest, ReplyIssueReportRequest, IssueReportingVoiceTokenResult, IssueReportAttachmentOut, ListIssueReportMessagesResponse, CreateReporterMessageRequest, IssueReportMessage, IssueReportingInputMode, IssueReportingVoiceProvider } from 'spaps-types';
+export { CreateIssueReportRequest, CreateReporterMessageRequest, IssueReport, IssueReportAttachmentOut, IssueReportListResult, IssueReportMessage, IssueReportScope, IssueReportStatus, IssueReportStatusResult, ListIssueReportMessagesResponse, ReplyIssueReportRequest, UpdateIssueReportRequest } from 'spaps-types';
 import * as _tanstack_query_core from '@tanstack/query-core';
 import * as _tanstack_react_query from '@tanstack/react-query';
 
@@ -39,6 +39,8 @@ interface IssueReportingClient {
         uploadAttachment?: (file: Blob, options?: {
             filename?: string;
         }) => Promise<IssueReportAttachmentOut>;
+        listMessages?: (issueReportId: string) => Promise<ListIssueReportMessagesResponse>;
+        submitMessage?: (issueReportId: string, payload: CreateReporterMessageRequest) => Promise<IssueReportMessage>;
     };
 }
 interface ReportableTargetDescriptor {
@@ -96,6 +98,23 @@ interface IssueReportingCopy {
     originHumanLabel: string;
     originMachineLabel: string;
     machineOriginFallback: string;
+    threadTitle: string;
+    threadDescription: string;
+    threadLoading: string;
+    threadLoadFailed: string;
+    threadEmpty: string;
+    threadNeedsResponseBadge: string;
+    threadAuthorOperator: string;
+    threadAuthorReporter: string;
+    threadKindClarificationRequest: string;
+    threadKindReporterResponse: string;
+    threadKindFinalResponse: string;
+    threadResponsePlaceholder: string;
+    threadResponseLabel: string;
+    threadResponseSubmitAction: string;
+    threadResponseSubmittingAction: string;
+    threadResponseConflict: string;
+    threadResponseFailed: string;
 }
 interface IssueReportingProviderProps {
     client: IssueReportingClient;
@@ -120,6 +139,9 @@ interface IssueReportingPageConfigProps {
     createMode: IssueReportingCreateMode;
 }
 
+declare function IssueReportMessageThread({ issueReportId, }: {
+    issueReportId: string;
+}): react_jsx_runtime.JSX.Element | null;
 declare function FloatingIssueReportButton({ className, positionClassName, }: FloatingIssueReportButtonProps): react_jsx_runtime.JSX.Element | null;
 declare function ReportableSection({ reportableName, children, className, as: Component, }: {
     reportableName: ReportableInput;
@@ -174,6 +196,8 @@ type IssueReportingContextValue = {
     voice: Required<Pick<IssueReportingVoiceConfig, "provider" | "modelId" | "requireMicrophonePermission">> & {
         microphone?: IssueReportingVoiceConfig["microphone"];
     };
+    needsResponseIssueIds: string[];
+    setNeedsResponse: (issueReportId: string, needsResponse: boolean) => void;
 };
 declare const defaultIssueReportingCopy: IssueReportingCopy;
 declare const issueReportingKeys: {
@@ -181,6 +205,7 @@ declare const issueReportingKeys: {
     status: (scope: IssueReportScope) => readonly ["spaps-issue-reporting", "status", IssueReportScope];
     history: (scope: IssueReportScope) => readonly ["spaps-issue-reporting", "history", IssueReportScope];
     detail: (issueReportId: string) => readonly ["spaps-issue-reporting", "detail", string];
+    messages: (issueReportId: string) => readonly ["spaps-issue-reporting", "messages", string];
 };
 declare function isOpenIssueStatus(status: IssueReportStatus): boolean;
 declare function isClosedIssueStatus(status: IssueReportStatus): boolean;
@@ -192,6 +217,25 @@ declare function getEntryPointState(status?: {
     has_recent_resolved: boolean;
 } | null): "open" | "recent_resolved" | "neutral";
 declare function getEntryPointClassName(state: "open" | "recent_resolved" | "neutral"): string;
+/**
+ * Defensive reporter-visibility filter for the conversation surface.
+ *
+ * The reporter `GET /messages` endpoint already returns only `active`,
+ * reporter-visible projection rows (retracted/superseded operator messages and
+ * raw `support_case_events` payloads are excluded server-side). This filter
+ * re-asserts that contract in the UI so a non-allowlisted row can never be
+ * rendered to a reporter even if a client or fixture passes one through. Rows
+ * are returned in chronological (`created_at`) order.
+ */
+declare function selectReporterVisibleMessages(messages: IssueReportMessage[]): IssueReportMessage[];
+/**
+ * Detect the idempotency-key conflict surfaced by the reporter message API as
+ * `409 ISSUE_REPORT_MESSAGE_CONFLICT`. The provider only depends on the
+ * abstract `IssueReportingClient` contract, so this inspects whatever shape the
+ * host client throws (Error message, `code`, or HTTP `status`) without binding
+ * to a specific transport.
+ */
+declare function isReporterMessageConflict(error: unknown): boolean;
 declare function getIssueNoteLengthMessage(note: string, copy: IssueReportingCopy): string;
 declare function useIssueReporting(): IssueReportingContextValue;
 declare function IssueReportingPageConfig({ createMode, }: IssueReportingPageConfigProps): react_jsx_runtime.JSX.Element;
@@ -391,6 +435,30 @@ declare function useIssueReportingMutations(): {
         attachment_ids?: string[];
     }, unknown>;
 };
+/**
+ * Query helper for the reporter-visible message thread of one issue report.
+ *
+ * Keyed by `issue_report_id`. Enabled only when the caller is eligible, an
+ * issue id is provided, and the host client implements the optional
+ * `listMessages` contract method. The query returns the raw server response so
+ * consumers can read `needs_response` for the badge; rendering code should pass
+ * `data.items` through {@link selectReporterVisibleMessages} before display.
+ */
+declare function useIssueReportingMessages(issueReportId: string | null): _tanstack_react_query.UseQueryResult<ListIssueReportMessagesResponse, Error>;
+/**
+ * Mutation helper for submitting a reporter clarification response.
+ *
+ * Calls the host client's `submitMessage(issueReportId, { body, idempotency_key })`
+ * and, on success, invalidates the thread query so the new `reporter_response`
+ * row and refreshed `needs_response` flag are re-fetched. The caller supplies a
+ * client-generated `idempotency_key` for safe retries; a key reused with a
+ * different body surfaces as a `409` conflict the UI can detect with
+ * {@link isReporterMessageConflict}.
+ */
+declare function useIssueReportingMessageMutation(issueReportId: string | null): _tanstack_react_query.UseMutationResult<IssueReportMessage, unknown, {
+    body: string;
+    idempotency_key?: string;
+}, unknown>;
 declare function IssueReportingProvider({ client, isEligible, reporterRoleHint, principalId, getPageUrl, defaultScope, allowTenantScope, defaultCreateMode, inputModes, defaultInputMode, voice, copy, children, }: IssueReportingProviderProps): react_jsx_runtime.JSX.Element;
 
 interface ReportModeContextValue {
@@ -404,4 +472,4 @@ interface ReportModeContextValue {
 declare const ReportModeContext: React.Context<ReportModeContextValue | null>;
 declare function useReportMode(): ReportModeContextValue | null;
 
-export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, issueReportingKeys, useIssueReporting, useIssueReportingHistory, useIssueReportingMutations, useIssueReportingStatus, useReportMode };
+export { FloatingIssueReportButton, type FloatingIssueReportButtonProps, type IssueHistoryFilter, IssueReportMessageThread, type IssueReportingClient, type IssueReportingCopy, type IssueReportingCreateMode, IssueReportingPageConfig, type IssueReportingPageConfigProps, IssueReportingProvider, type IssueReportingProviderProps, ReportModeContext, type ReportModeContextValue, type ReportableInput, ReportableSection, type ReportableTargetDescriptor, defaultIssueReportingCopy, filterIssueReports, getEntryPointClassName, getEntryPointState, getIssueNoteLengthMessage, getIssueStatusBadgeLabel, getIssueStatusClassName, isClosedIssueStatus, isOpenIssueStatus, isReporterMessageConflict, issueReportingKeys, selectReporterVisibleMessages, useIssueReporting, useIssueReportingHistory, useIssueReportingMessageMutation, useIssueReportingMessages, useIssueReportingMutations, useIssueReportingStatus, useReportMode };