@insurance-broker/api-client 5.7.0 → 5.9.0

package/dist/schema.d.ts

@@ -152,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;
@@ -236,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;
@@ -309,7 +323,9 @@ export interface paths {
          *
          *     The currency is **not** a field: it is the obligation's, held by a foreign key rather than by this handler. Nil is refused — a payment of nothing is nothing having arrived.
          *
-         *     **Name a payment method or type a source, exactly one** (#530). `paymentMethodId` is one of this broker's active payment methods: its code becomes the payment's `source`, and customers see the method's label. `source` alone is free text, as before, and customers see it as typed. Both, neither, a retired method or another broker's method are refused with `400` and nothing is recorded.
+         *     **Name a payment method or type a source, exactly one** (#530). `paymentMethodId` is one of this broker's active payment methods: its code becomes the payment's `source`, and customers see the method's label. `source` alone is free text, as before, and customers see it as typed. Both, neither, a retired method or another broker's method are refused with `400` and nothing is recorded. A typed source containing a control character is refused with `400` on `Source` (#601).
+         *
+         *     **Each `409` carries a `type`** (#593): `urn:brokerplatform:problem:payment-already-recorded` (the same money is already recorded; the problem names the payment), `urn:brokerplatform:problem:payment-reference-amount-conflict` (that reference is recorded for a different amount), `urn:brokerplatform:problem:obligation-concluded` (the charge is settled, cancelled or written off, so nothing can be paid against it; nothing is recorded), and the platform's `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`. Only the last is worth retrying.
          */
         post: operations["RecordPayment"];
         delete?: never;
@@ -353,13 +369,15 @@ export interface paths {
          * List the money this broker has recorded, most recent first
          * @description PAY-005. The payments this broker has recorded, ordered by when they posted, paged by cursor. A `customerId` or an `obligationId` narrows the list.
          *
+         *     **`awaitingApproval=true` is the approver's queue** (#593): only payments nobody has approved yet, that have not been reversed, and that the caller did not record - so it holds what this caller can approve, because nobody may approve a payment they recorded. The caller is the session's subject, so another approver's queue holds the payments this caller recorded. A payment with no clean evidence is still listed. It combines with the other filters and pages the same way. `false` or absent is no filter. A reversed payment is not in the queue, because the money it records did not arrive.
+         *
          *     **There is no `asOf` here, unlike `GET /obligations`.** Nothing in this list's predicate reads the clock - a payment posted at an instant the row records - so a member reporting when the page was measured would read as a freshness guarantee while guaranteeing nothing.
          *
          *     **A reversed payment stays on the list** and carries `reversed: true`. Money that arrived and was sent back is a fact a reconciliation has to see, and a reversal is its own record rather than an edit to this one (ADR-0042 section 8).
          *
          *     **Rows carry no subject identifiers.** Who recorded a payment and who approved it is the separation-of-duties record and it is on the payment itself, so a page-sized read cannot enumerate a broker's finance staff.
          *
-         *     **`customerId` and `obligationId` are filters and never authorisation.** The broker whose payments these are comes from the session.
+         *     **`customerId`, `obligationId` and `awaitingApproval` are filters and never authorisation.** The broker whose payments these are comes from the session.
          */
         get: operations["ListPayments"];
         put?: never;
@@ -528,6 +546,8 @@ export interface paths {
          *     **The type is taken from the file's own bytes, never from the part header.** A part declaring one thing and holding another is refused rather than believed.
          *
          *     **A payment cannot be approved until at least one of its files is `Clean`**, which is the other half of PAY-003 and the reason this route exists.
+         *
+         *     **A reversed payment takes no evidence** (#593): the money it records did not arrive, so there is nothing left to approve. The answer is `409` `urn:brokerplatform:problem:payment-already-reversed`, the type reversing it again answers, and it is not retryable. The body is not read.
          */
         post: operations["UploadPaymentEvidence"];
         delete?: never;
@@ -562,6 +582,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;
@@ -897,7 +923,9 @@ export interface paths {
          *
          *     **A mapping can be undone** with `POST /payment-methods/{id}/source-mappings/removal`, or pointed at another method with `POST /payment-methods/{id}/source-mappings/correction` (#588). A payment with this source that names this method through a mapping not marked as one (made by an API instance from before #588) is marked by this request, so it can then be corrected; it is counted in `alreadyMapped`.
          *
-         *     A retired method is `409`. A statement already produced keeps the wording it was produced with. A `409` can also be the platform's concurrency conflict, with `retryable: true`, when another write changed one of the payments while it was being mapped.
+         *     **`skipped` lists payments only when the caller also holds `billing.payments.read`** (#602). Without it, `skipped` is empty and `skippedCount` still says how many were skipped: the entries name payments and their references, which is payment data. So **a `skippedCount` above zero with an empty `skipped` means the skipped payments are not shown to this caller**, not that the list was lost; with `billing.payments.read`, `skipped` is never empty while `skippedCount` is above zero.
+         *
+         *     A retired method is `409` `urn:brokerplatform:problem:payment-method-retired`, which is not retryable: choose an active method. A statement already produced keeps the wording it was produced with. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`: another write changed one of the payments while it was being mapped, or a payment was recorded against the method under one of these payments' references while the mapping ran. Nothing was mapped; send it again, and a retry lists any payment it would now duplicate as skipped.
          */
         post: operations["MapFreeTextPaymentSource"];
         delete?: never;
@@ -943,7 +971,7 @@ export interface paths {
          * Correct a mapping: say the payments with a free-text source came through another method
          * @description #588. Every payment of this broker whose `source` is exactly the given text and that **a mapping** gave this method is given `paymentMethodId` instead, in one step. Customers then see that method's label. No amount, source or reference changes, and a payment recorded against this method is never moved (counted in `recordedAgainstMethod`). A payment mapped by an API instance from before #588 is counted in `notYetCorrectable` and left alone until the source is mapped to this method again.
          *
-         *     `paymentMethodId` must be another active method of this broker: the same method, an unknown or another broker's method is `400` on `PaymentMethodId`, and a retired one is `409`. The method in the route may be retired.
+         *     `paymentMethodId` must be another active method of this broker: the same method, an unknown or another broker's method is `400` on `PaymentMethodId`, and a retired one is `409` `urn:brokerplatform:problem:payment-method-retired`, which is not retryable. The method in the route may be retired.
          *
          *     **All or nothing.** If the target method already holds the reference of any of the payments (a payment recorded against it, one mapped to it, or a free-text payment typed exactly as its code), nothing is moved and the answer is `409` `urn:brokerplatform:problem:payment-source-remap-collision`, which is not retryable, with `collisionCount`. **`collisions` is present only when the caller also holds `billing.payments.read`**: up to 200 entries naming each payment, its reference and the payment holding it. Undo the mapping instead and map the source to the target: the mapping maps the rest and lists those it skips.
          *
@@ -7219,6 +7247,7 @@ export interface components {
         DraftInvoiceRequest: {
             /** Format: uuid */
             policyId: string;
+            idempotencyKey?: null | string;
         };
         EmergencyContactDetailsResponse: {
             providerName: string;
@@ -7820,6 +7849,7 @@ export interface components {
         IssueCreditNoteRequest: {
             reason: string;
             lines: components["schemas"]["CreditNoteLineRequest"][];
+            idempotencyKey?: null | string;
         };
         IssuedCustomerInvitationResponse: {
             /** Format: uuid */
@@ -8192,10 +8222,12 @@ export interface components {
             /** Format: double */
             existingAmount: null | number | string;
         };
+        /** @enum {string} */
+        PaymentEventKind: "Recorded" | "DuplicateRefused" | "ConflictingAmountRefused" | "EvidenceAttached" | "Approved" | "Reversed";
         PaymentEventResponse: {
             /** Format: uuid */
             id: string;
-            kind: string;
+            kind: components["schemas"]["PaymentEventKind"];
             /** Format: date-time */
             occurredAtUtc: string;
             actorSubjectId: string;
@@ -8215,7 +8247,7 @@ export interface components {
             /** Format: date-time */
             uploadedAtUtc: string;
             uploadedBySubjectId: string;
-            scanVerdict: string;
+            scanVerdict: components["schemas"]["ScanVerdict"];
             /** Format: date-time */
             scannedAtUtc: null | string;
         };
@@ -8266,7 +8298,7 @@ export interface components {
             currency: string;
             source: string;
             externalReference: string;
-            status: string;
+            status: components["schemas"]["PaymentStatus"];
             recordedBySubjectId: string;
             /** Format: date-time */
             postedAtUtc: string;
@@ -8275,6 +8307,7 @@ export interface components {
             approvedAtUtc: null | string;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PaymentReversalResponse: {
             /** Format: uuid */
@@ -8327,6 +8360,8 @@ export interface components {
             /** Format: int32 */
             notYetCorrectable: number;
         };
+        /** @enum {string} */
+        PaymentStatus: "Posted";
         PaymentSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -8339,7 +8374,7 @@ export interface components {
             currency: string;
             source: string;
             externalReference: string;
-            status: string;
+            status: components["schemas"]["PaymentStatus"];
             /** Format: date-time */
             postedAtUtc: string;
             /** Format: date-time */
@@ -8347,6 +8382,7 @@ export interface components {
             reversed: boolean;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PlacedMemberResponse: {
             /** Format: uuid */
@@ -8608,6 +8644,7 @@ export interface components {
             periodStart: string;
             /** Format: date */
             periodEnd: string;
+            idempotencyKey?: null | string;
         };
         ProductCategoryResponse: {
             /** Format: uuid */
@@ -9253,6 +9290,8 @@ export interface components {
             email: null | string;
             phone: null | string;
         };
+        /** @enum {string} */
+        ScanVerdict: "Quarantined" | "Clean" | "Infected" | "Unscannable";
         ServiceLocationResponse: {
             /** Format: uuid */
             id: string;
@@ -10133,6 +10172,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: {
@@ -10456,6 +10504,7 @@ export interface operations {
             query?: {
                 customerId?: string;
                 obligationId?: string;
+                awaitingApproval?: boolean;
                 cursor?: string;
                 limit?: number | string;
             };
@@ -10769,6 +10818,15 @@ export interface operations {
                 };
                 content?: never;
             };
+            /** @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 Payload Too Large */
             413: {
                 headers: {
@@ -10844,6 +10902,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.7.0",
+  "version": "5.9.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,