@insurance-broker/api-client 5.6.0 → 5.8.0

package/dist/schema.d.ts

@@ -66,6 +66,8 @@ export interface paths {
          * @description PAY-002. Another broker's obligation and another customer's are invisible here rather than refused: the tenant and owner query filters remove them before the read runs, so all three cases answer the same `404` (ADR-0008, ADR-0030).
          *
          *     There is **no overdue field**. Whether an obligation is overdue is a comparison between its due date and the clock, and step 9.10's lists compute it at read time and return the day they measured against — ADR-0035 §4's rule, which forbids storing a status a date comparison answers.
+         *
+         *     **`paid` and `balance` are computed as the response is written** (#595), by the same rule as the list. `paid` is read a moment after the charge itself, so a payment that lands in between can show in `paid` and `balance` before `status` reflects it; read again and the two agree. `balance` is not always `amount` less `paid`: a cancelled charge is owed nothing, so money paid against one leaves the customer in credit, and a written-off charge is owed what actually arrived and no more.
          */
         get: operations["GetObligation"];
         put?: never;
@@ -133,7 +135,15 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * List what this broker has invoiced, newest first
+         * @description ADR-0042 section 8, ADR-0031. Every invoice this broker has drafted — drafts, issued invoices and discarded drafts — **most recently drafted first**, ordered by `draftedAtUtc` and then `id`, both descending, and paged by cursor. The drafting instant is the key because it never changes: an invoice keeps its place in the walk when it is issued or discarded.
+         *
+         *     `customerId`, `policyId` and `status` (`Draft`, `Issued`, `Discarded`) narrow the list and combine. **None of them is authorisation**: the broker whose invoices these are comes from the session, and naming another broker's customer selects nothing rather than refusing.
+         *
+         *     A row carries no lines; `GET /invoices/{id}` returns one invoice with its lines. There is no total and no count: `nextCursor` is null at the end of the walk (ADR-0031 section 4). A cursor this endpoint did not issue is a `400`.
+         */
+        get: operations["ListInvoices"];
         put?: never;
         /**
          * Open a draft invoice against a policy
@@ -142,6 +152,14 @@ export interface paths {
          *     The **currency is not a field** — it is the policy's own, so BR-008's pair travels from one source. The **payer is not a field** either: an invoice is addressed to whoever owns the policy.
          *
          *     A draft has **no total**. The total is fixed once, at issue, from the lines.
+         *
+         *     A replay answers the invoice **as it is now**, lines and status included: a draft that has since gained lines, been issued or been discarded is still the one invoice the key drafted, so its body can differ from the first response's, `status` included.
+         *
+         *     **`idempotencyKey` is optional, and it is what makes a retry after a lost response safe.** Without one, every request writes a new invoice. With one, a repeat carrying a key already used **answers the original invoice with the same `201 Created` and the same `Location`** and writes nothing; a repeat carrying that key with a **different** policy is a `409` and writes nothing. The key is trimmed, at most 200 characters, blank is no key, and it belongs to this broker alone.
+         *
+         *     **A key is honoured for 30 days from the moment the invoice was written, and then stops being honoured** — after that the same key is one this platform has never seen. Mint a fresh key per intended invoice; do not recycle one.
+         *
+         *     **The key collision `409` is settled**: retrying it can only fail again, and it carries no `retryable` marker.
          */
         post: operations["DraftInvoice"];
         delete?: never;
@@ -226,6 +244,12 @@ export interface paths {
          *     **It may not credit more than the invoice demanded**, counting what earlier credit notes already credit. Crediting past the demand is a payment out rather than a correction, and a refund is its own record (WRK-004, Phase 2).
          *
          *     Refused against a **draft** invoice: a draft was never demanded of anybody, so it is discarded rather than credited.
+         *
+         *     **A retried credit note without a key credits the customer twice**, so send one. **`idempotencyKey` is optional, and it is what makes a retry after a lost response safe.** Without one, every request writes a new credit note. With one, a repeat carrying a key already used **answers the original credit note with the same `201 Created` and the same `Location`** and writes nothing; a repeat carrying that key with a **different** invoice, reason or set of lines is a `409` and writes nothing. The key is trimmed, at most 200 characters, blank is no key, and it belongs to this broker alone.
+         *
+         *     **A key is honoured for 30 days from the moment the credit note was written, and then stops being honoured** — after that the same key is one this platform has never seen. Mint a fresh key per intended credit note; do not recycle one.
+         *
+         *     **The key collision `409` is settled**: retrying it can only fail again, and it carries no `retryable` marker.
          */
         post: operations["IssueCreditNote"];
         delete?: never;
@@ -552,6 +576,12 @@ export interface paths {
          *     **One currency per statement.** A charge carries its own currency, and a balance in two of them is not a number. A customer owing in two currencies gets two statements.
          *
          *     **Nothing about money is stored on the row.** There is no balance column: every figure is derived from the obligations and payments the statement renders, bounded by its period and by the instant it was produced.
+         *
+         *     **`idempotencyKey` is optional, and it is what makes a retry after a lost response safe.** Without one, every request produces a statement. With one, a repeat carrying a key already used **answers the original statement with the same `201 Created` and the same `Location`** and produces nothing; a repeat carrying that key with a **different** customer, currency or period is a `409` and produces nothing. The key is trimmed, at most 200 characters, blank is no key, and it belongs to this broker alone.
+         *
+         *     **A key is honoured for 30 days from the moment the statement was produced, and then stops being honoured** — after that the same key is one this platform has never seen. Mint a fresh key per intended statement; do not recycle one.
+         *
+         *     **The key collision `409` is settled**: retrying it can only fail again, and it carries no `retryable` marker.
          */
         post: operations["ProduceStatement"];
         delete?: never;
@@ -7209,6 +7239,7 @@ export interface components {
         DraftInvoiceRequest: {
             /** Format: uuid */
             policyId: string;
+            idempotencyKey?: null | string;
         };
         EmergencyContactDetailsResponse: {
             providerName: string;
@@ -7750,6 +7781,10 @@ export interface components {
             amount: number | string;
             currency: string;
         };
+        InvoicePage: {
+            items: components["schemas"]["InvoiceSummaryResponse"][];
+            nextCursor: null | string;
+        };
         InvoiceResponse: {
             /** Format: uuid */
             id: string;
@@ -7777,9 +7812,36 @@ export interface components {
             retentionAnchorAtUtc: null | string;
             lines: components["schemas"]["InvoiceLineResponse"][];
         };
+        InvoiceSummaryResponse: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            customerId: string;
+            /** Format: uuid */
+            policyId: string;
+            /** Format: uuid */
+            productId: string;
+            /** Format: double */
+            premiumAmount: number | string;
+            currency: string;
+            /** Format: date */
+            coverStart: null | string;
+            /** Format: date */
+            coverEnd: null | string;
+            status: string;
+            /** Format: date-time */
+            draftedAtUtc: string;
+            /** Format: date-time */
+            issuedAtUtc: null | string;
+            /** Format: double */
+            totalAmount: null | number | string;
+            /** Format: date-time */
+            retentionAnchorAtUtc: null | string;
+        };
         IssueCreditNoteRequest: {
             reason: string;
             lines: components["schemas"]["CreditNoteLineRequest"][];
+            idempotencyKey?: null | string;
         };
         IssuedCustomerInvitationResponse: {
             /** Format: uuid */
@@ -7965,6 +8027,10 @@ export interface components {
             productId: string;
             /** Format: double */
             amount: number | string;
+            /** Format: double */
+            paid: number | string;
+            /** Format: double */
+            balance: number | string;
             currency: string;
             /** Format: date */
             dueOn: string;
@@ -8564,6 +8630,7 @@ export interface components {
             periodStart: string;
             /** Format: date */
             periodEnd: string;
+            idempotencyKey?: null | string;
         };
         ProductCategoryResponse: {
             /** Format: uuid */
@@ -10023,6 +10090,41 @@ export interface operations {
             };
         };
     };
+    ListInvoices: {
+        parameters: {
+            query?: {
+                customerId?: string;
+                policyId?: string;
+                status?: string;
+                cursor?: string;
+                limit?: number | string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InvoicePage"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["HttpValidationProblemDetails"];
+                };
+            };
+        };
+    };
     DraftInvoice: {
         parameters: {
             query?: never;
@@ -10054,6 +10156,15 @@ export interface operations {
                     "application/problem+json": components["schemas"]["HttpValidationProblemDetails"];
                 };
             };
+            /** @description Conflict. A type of urn:brokerplatform:problem:concurrency-conflict means someone else changed the record first and nothing was written: read it again and decide again. Any other type is a conflict this operation decided itself, and retrying it unchanged will not help. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ConcurrencyConflictProblem"] | components["schemas"]["ProblemDetails"];
+                };
+            };
         };
     };
     AddInvoiceLine: {
@@ -10765,6 +10876,15 @@ export interface operations {
                     "application/problem+json": components["schemas"]["HttpValidationProblemDetails"];
                 };
             };
+            /** @description Conflict. A type of urn:brokerplatform:problem:concurrency-conflict means someone else changed the record first and nothing was written: read it again and decide again. Any other type is a conflict this operation decided itself, and retrying it unchanged will not help. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ConcurrencyConflictProblem"] | components["schemas"]["ProblemDetails"];
+                };
+            };
             /** @description Too Many Requests (ADR-0050). This operation renders, produces or exports, and the caller's own budget for such work, or their organisation's, is spent. Nothing was done: no document, statement, export or receipt exists for this request. Wait the number of seconds in Retry-After (also in retryAfterSeconds) before trying again. */
             429: {
                 headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insurance-broker/api-client",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "description": "Generated TypeScript client for the Insurance Broker Platform API. Do not edit by hand: regenerate with scripts/update-api-contract.",
   "license": "UNLICENSED",
   "private": false,