@insurance-broker/api-client 5.8.0 → 5.10.0

package/dist/schema.d.ts

@@ -45,7 +45,7 @@ export interface paths {
          *
          *     **What a key does not do**: it assumes the retrying client owns it. Two people at two desks recording the same instalment invent two keys, and both charges are raised (ADR-0042 §19).
          *
-         *     **Two different things answer `409` here.** A key collision is settled — retrying it can only fail again — and carries no `retryable` marker. The group's concurrency conflict is the other one and says it is retryable. Branch on that, not on the status.
+         *     **Two different things answer `409` here.** A key collision is settled — retrying it can only fail again — carries no `retryable` marker, and is typed `urn:brokerplatform:problem:idempotency-key-reused` (#593). The group's concurrency conflict is the other one, `urn:brokerplatform:problem:concurrency-conflict`, and says it is retryable. Branch on the `type`, not on the status.
          */
         post: operations["RaiseObligation"];
         delete?: never;
@@ -91,7 +91,7 @@ export interface paths {
          * Withdraw an obligation raised in error
          * @description Records that the charge should never have existed. **This is not a write-off**: writing off records that a real debt will not be collected, which is a decision with money behind it and a reason attached, and it arrives in step 9.7. Collapsing the two would make "how much did this broker forgive" unanswerable.
          *
-         *     Cancelling starts the record's retention clock (ADR-0038 §2), so it is refused a second time rather than silently re-stamped — re-stamping would move the anchor of a record that concluded earlier.
+         *     Cancelling starts the record's retention clock (ADR-0038 §2), so it is refused a second time rather than silently re-stamped — re-stamping would move the anchor of a record that concluded earlier. That refusal is `409` `urn:brokerplatform:problem:obligation-concluded` (#593), the type recording a payment against a concluded charge answers, and it is not retryable. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`.
          */
         post: operations["CancelObligation"];
         delete?: never;
@@ -119,7 +119,9 @@ export interface paths {
          *
          *     **It is why an obligation nobody will chase is not kept for ever.** An unsettled charge has no retention anchor and is therefore kept (ADR-0038 section 2); writing one off is the event that starts its clock.
          *
-         *     Refused on a charge that has already concluded — a settled one was paid and a cancelled one was never owed — rather than silently re-stamping an anchor.
+         *     Refused on a charge that has already concluded — a settled one was paid and a cancelled one was never owed — rather than silently re-stamping an anchor. That refusal is `409` `urn:brokerplatform:problem:obligation-concluded` (#593), and it is not retryable. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`.
+         *
+         *     A missing or over-long reason is `400` on `Reason`, the member's own name, which is the platform's majority convention; WorkflowComms' device and preference routes are the known exception (#613). It was `reason` until client 5.10.0 (#593).
          */
         post: operations["WriteOffObligation"];
         delete?: never;
@@ -159,7 +161,7 @@ export interface paths {
          *
          *     **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.
+         *     **The key collision `409` is settled**: retrying it can only fail again, it carries no `retryable` marker, and it is typed `urn:brokerplatform:problem:idempotency-key-reused` (#593).
          */
         post: operations["DraftInvoice"];
         delete?: never;
@@ -185,7 +187,7 @@ export interface paths {
          *
          *     There is **no ordinal field**. The position is derived from the lines already present.
          *
-         *     Refused once the invoice is issued: issue is a one-way door.
+         *     Refused once the invoice is issued: issue is a one-way door. That refusal, and the same one for a discarded invoice, is `409` `urn:brokerplatform:problem:invoice-not-a-draft` (#593), which is not retryable. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`.
          */
         post: operations["AddInvoiceLine"];
         delete?: never;
@@ -210,6 +212,8 @@ export interface paths {
          *     An invoice with **no lines is refused**: that would be a demand for nothing. A broker charging nil says so with a zero-rated line.
          *
          *     Issuing twice is a `409`, and it is not retryable: the invoice is already issued and reading it back is the resolution.
+         *
+         *     **Each `409` carries a `type`** (#593): `urn:brokerplatform:problem:invoice-not-a-draft` (already issued or discarded; read it back), `urn:brokerplatform:problem:invoice-has-no-lines` (still a draft; add a line and issue again), and the platform's `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`.
          */
         post: operations["IssueInvoice"];
         delete?: never;
@@ -245,11 +249,15 @@ export interface paths {
          *
          *     Refused against a **draft** invoice: a draft was never demanded of anybody, so it is discarded rather than credited.
          *
+         *     **Each `409` carries a `type`** (#593): `urn:brokerplatform:problem:invoice-not-issued` (a draft or a discarded invoice), `urn:brokerplatform:problem:credit-note-exceeds-invoice` (credit less, counting the notes already issued) and `urn:brokerplatform:problem:idempotency-key-reused`. None is retryable.
+         *
+         *     **Validation keys are the members' own names** — `Reason`, `Lines`, `IdempotencyKey` — which is the platform's majority convention; WorkflowComms' device and preference routes are the known exception (#613). They were camel-cased until client 5.10.0 (#593).
+         *
          *     **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.
+         *     **The key collision `409` is settled**: retrying it can only fail again, it carries no `retryable` marker, and it is typed `urn:brokerplatform:problem:idempotency-key-reused` (#593).
          */
         post: operations["IssueCreditNote"];
         delete?: never;
@@ -271,7 +279,7 @@ export interface paths {
          * Abandon a draft that should never have been raised
          * @description Records that this demand was never made — the customer never saw it and owes nothing on account of it. **Only a draft may be discarded.** An issued invoice that should not have been issued is corrected by a credit note, because the customer has seen the demand and BR-010 will not have it silently withdrawn.
          *
-         *     Discarding starts the record's retention clock (ADR-0038 section 2), so it is refused a second time rather than silently re-stamped.
+         *     Discarding starts the record's retention clock (ADR-0038 section 2), so it is refused a second time rather than silently re-stamped. Refusing an invoice that is not a draft is `409` `urn:brokerplatform:problem:invoice-not-a-draft` (#593), which is not retryable. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`.
          */
         post: operations["DiscardInvoice"];
         delete?: never;
@@ -323,7 +331,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;
@@ -367,13 +377,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;
@@ -452,6 +464,10 @@ export interface paths {
          *     **Approval is an act and not a status.** The payment's status set is untouched: collapsing the two would make *"recorded but not yet approved"* and *"the money is definitely there"* the same value.
          *
          *     There is no un-approval. A payment approved in error is corrected by a reversal, which is step 9.7's, for the reason BR-010 gives about every financially significant record.
+         *
+         *     **A reversed payment cannot be approved** (#604): the reversal records that the money did not arrive, so there is nothing to take responsibility for.
+         *
+         *     **Each `409` carries a `type`**: `urn:brokerplatform:problem:payment-already-approved`, `urn:brokerplatform:problem:payment-already-reversed`, `urn:brokerplatform:problem:payment-self-approval` (a colleague must approve it), `urn:brokerplatform:problem:payment-approval-unevidenced` (file evidence and wait for the scan), and the platform's `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`. Only the last is worth retrying as it stands.
          */
         post: operations["ApprovePayment"];
         delete?: never;
@@ -542,6 +558,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;
@@ -581,7 +599,7 @@ export interface paths {
          *
          *     **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.
+         *     **The key collision `409` is settled**: retrying it can only fail again, it carries no `retryable` marker, and it is typed `urn:brokerplatform:problem:idempotency-key-reused` (#593).
          */
         post: operations["ProduceStatement"];
         delete?: never;
@@ -805,7 +823,7 @@ export interface paths {
          * Add a way this broker's customers pay
          * @description #530. `code` is a stable identifier — lower-case letters, digits and hyphens, at most 40 characters — unique within this broker and never changed. `label` is what customers read, at most 80 characters, and can be changed later.
          *
-         *     **A code is never reused**, even after its method is retired, because payments recorded against the method carry it as their `source`. A code already taken is `409`.
+         *     **A code is never reused**, even after its method is retired, because payments recorded against the method carry it as their `source`. A code already taken is `409` `urn:brokerplatform:problem:payment-method-code-taken` (#604), which is not retryable: choose another code.
          */
         post: operations["CreatePaymentMethod"];
         delete?: never;
@@ -867,7 +885,7 @@ export interface paths {
         put?: never;
         /**
          * Stop a payment method being chosen for new payments
-         * @description #530. **One-way.** A retired method cannot be chosen when recording a payment, keeps labelling the payments already recorded against it, and keeps its code, which is never given to another method. Retiring one already retired is `409`. A `409` can also be the platform's concurrency conflict, with `retryable: true`, when another write changed the method after it was read.
+         * @description #530. **One-way.** A retired method cannot be chosen when recording a payment, keeps labelling the payments already recorded against it, and keeps its code, which is never given to another method. Retiring one already retired is `409` `urn:brokerplatform:problem:payment-method-retired` (#604), which is not retryable: the method is already retired. A `409` can also be the platform's concurrency conflict, `urn:brokerplatform:problem:concurrency-conflict` with `retryable: true`, when another write changed the method after it was read.
          */
         post: operations["RetirePaymentMethod"];
         delete?: never;
@@ -917,7 +935,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;
@@ -963,7 +983,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.
          *
@@ -7801,7 +7821,7 @@ export interface components {
             coverStart: null | string;
             /** Format: date */
             coverEnd: null | string;
-            status: string;
+            status: components["schemas"]["InvoiceStatus"];
             /** Format: date-time */
             draftedAtUtc: string;
             /** Format: date-time */
@@ -7812,6 +7832,8 @@ export interface components {
             retentionAnchorAtUtc: null | string;
             lines: components["schemas"]["InvoiceLineResponse"][];
         };
+        /** @enum {string} */
+        InvoiceStatus: "Draft" | "Issued" | "Discarded";
         InvoiceSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -7828,7 +7850,7 @@ export interface components {
             coverStart: null | string;
             /** Format: date */
             coverEnd: null | string;
-            status: string;
+            status: components["schemas"]["InvoiceStatus"];
             /** Format: date-time */
             draftedAtUtc: string;
             /** Format: date-time */
@@ -8035,13 +8057,15 @@ export interface components {
             /** Format: date */
             dueOn: string;
             description: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
             /** Format: date-time */
             raisedAtUtc: string;
             /** Format: date-time */
             retentionAnchorAtUtc: null | string;
             writeOffReason: null | string;
         };
+        /** @enum {string} */
+        ObligationStatus: "Outstanding" | "Cancelled" | "Settled" | "WrittenOff";
         ObligationSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -8061,7 +8085,7 @@ export interface components {
             /** Format: date */
             dueOn: string;
             description: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
         };
         OfferedFormResponse: {
             /** Format: uuid */
@@ -8214,10 +8238,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;
@@ -8237,7 +8263,7 @@ export interface components {
             /** Format: date-time */
             uploadedAtUtc: string;
             uploadedBySubjectId: string;
-            scanVerdict: string;
+            scanVerdict: components["schemas"]["ScanVerdict"];
             /** Format: date-time */
             scannedAtUtc: null | string;
         };
@@ -8288,7 +8314,7 @@ export interface components {
             currency: string;
             source: string;
             externalReference: string;
-            status: string;
+            status: components["schemas"]["PaymentStatus"];
             recordedBySubjectId: string;
             /** Format: date-time */
             postedAtUtc: string;
@@ -8297,6 +8323,7 @@ export interface components {
             approvedAtUtc: null | string;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PaymentReversalResponse: {
             /** Format: uuid */
@@ -8349,6 +8376,8 @@ export interface components {
             /** Format: int32 */
             notYetCorrectable: number;
         };
+        /** @enum {string} */
+        PaymentStatus: "Posted";
         PaymentSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -8361,7 +8390,7 @@ export interface components {
             currency: string;
             source: string;
             externalReference: string;
-            status: string;
+            status: components["schemas"]["PaymentStatus"];
             /** Format: date-time */
             postedAtUtc: string;
             /** Format: date-time */
@@ -8369,6 +8398,7 @@ export interface components {
             reversed: boolean;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PlacedMemberResponse: {
             /** Format: uuid */
@@ -9276,6 +9306,8 @@ export interface components {
             email: null | string;
             phone: null | string;
         };
+        /** @enum {string} */
+        ScanVerdict: "Quarantined" | "Clean" | "Infected" | "Unscannable";
         ServiceLocationResponse: {
             /** Format: uuid */
             id: string;
@@ -9386,7 +9418,7 @@ export interface components {
             dueOn: string;
             /** Format: date-time */
             raisedAtUtc: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
         };
         StatementPage: {
             items: components["schemas"]["StatementSummaryResponse"][];
@@ -10488,6 +10520,7 @@ export interface operations {
             query?: {
                 customerId?: string;
                 obligationId?: string;
+                awaitingApproval?: boolean;
                 cursor?: string;
                 limit?: number | string;
             };
@@ -10801,6 +10834,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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insurance-broker/api-client",
-  "version": "5.8.0",
+  "version": "5.10.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,