feat(sp28): useClaimAcks + useAckClaims hooks with api types

src/types/index.ts

@@ -537,6 +537,13 @@ export interface Ack {
    * round-trip to the detail endpoint.
    */
   patientControlNumber?: string | null;
+  /**
+   * SP28: distinct claim ids this 999 ack is linked to. Populated by
+   * the backend list endpoint so the Acks page can show a "Claims"
+   * badge column without a per-row detail round-trip. Empty array
+   * means no auto-link resolved (orphan).
+   */
+  linkedClaimIds?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -569,6 +576,62 @@ export interface Ta1Ack {
   receiverId: string | null;
   sourceBatchId: string;
   parsedAt: string | null;
+  /**
+   * SP28: originating `Batch` ids this TA1 envelope is linked to
+   * (per D4, TA1 is envelope-level so it links to `Batch` rather
+   * than `Claim`). Empty array means no auto-link resolved.
+   */
+  linkedClaimIds?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// SP28: claim↔ack link rows.
+// Mirrors the `claim_acks` table (cyclone.db.ClaimAck) and the wire shape
+// of `GET /api/claims/{id}/acks` + `GET /api/acks/{kind}/{id}/claims`.
+// Per-AK2 granularity (D1): a single 999 with two AK2 set-responses
+// produces two ClaimAck rows. TA1 batch-level rows have `claimId === null`
+// — the `ClaimDrawer` panel filters those out; the `AckDrawer` panel
+// renders them with the originating Batch instead of a claim.
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminator for the ack flavor that produced a `ClaimAck` row.
+ *
+ * - `"999"` — per-AK2 set-response (one row per AK2 in the inbound 999).
+ * - `"277ca"` — per-`ClaimStatus` (one row per `STC` in the inbound 277CA).
+ * - `"ta1"` — envelope-level (one row per TA1, no per-claim granularity).
+ */
+export type ClaimAckKind = "999" | "277ca" | "ta1";
+
+/**
+ * One persisted claim↔ack link row, camelCased for the UI. The
+ * `claimId` is `null` for TA1 batch-level rows (D4) — the
+ * `ClaimDrawer` panel filters those out so the operator only sees
+ * per-claim acks; the `AckDrawer` panel renders them with the
+ * originating Batch instead.
+ *
+ * `claimState` is a derived join (the 999/277CA row carries the
+ * current `Claim.state` so the drawer can render the
+ * `ClaimStateBadge` inline without a second round-trip). For
+ * TA1 batch-level rows with `claimId === null`, this is `"n/a"`.
+ *
+ * `ak2Index` is populated only for `"999"` rows — 277CA and TA1
+ * don't have AK2 segments. `setControlNumber` is populated for
+ * 999/277CA rows (the value the upstream ack actually carried,
+ * regardless of which join path resolved the link — spec D10).
+ */
+export interface ClaimAck {
+  id: number;
+  claimId: string | null;
+  batchId: string | null;
+  ackId: number;
+  ackKind: ClaimAckKind;
+  ak2Index: number | null;
+  setControlNumber: string | null;
+  setAcceptRejectCode: string | null;
+  linkedAt: string;
+  linkedBy: "auto" | "manual";
+  claimState?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -710,6 +773,15 @@ export interface ClaimDetail {
    * composite.
    */
   lineReconciliation?: ClaimDetailLineReconciliation[];
+  /**
+   * SP28: compact form of the claim's `claim_acks` rows. Each entry
+   * has `ack_id`, `ack_kind`, `set_accept_reject_code`, `parsed_at`
+   * (no `claim_state` join — the drawer can use this for the
+   * initial panel render and rely on the live-tail for the full
+   * per-row payload via `useClaimAcks`). Empty array when the claim
+   * has no acks.
+   */
+  ackLinks?: ClaimAck[];
 }
 
 // ---------------------------------------------------------------------------