@insurance-broker/api-client 5.9.0 → 5.11.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. A typed source containing a control character is refused with `400` on `Source` (#601).
+         *     **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 character that does not print as text is refused with `400` on `Source`, and a reference with one on `ExternalReference` (#601): a control or format character (a direction override, a zero-width character), U+2028 or U+2029, a private-use or unassigned code point, or an unpaired surrogate. A payment stored with one before #601 is refused the same way when its text is sent again.
+         *
+         *     **A typed source is stored in Unicode normalisation form C** (#601), so a composed and a decomposed spelling of the same words are one source and the same money cannot be recorded once under each. The response carries the stored spelling. The reference is stored as sent.
          *
          *     **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.
          */
@@ -456,6 +466,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;
@@ -587,7 +601,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;
@@ -811,7 +825,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;
@@ -873,7 +887,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;
@@ -915,6 +929,8 @@ export interface paths {
          * Say which payment method the payments with a free-text source came through
          * @description #568. Every payment of this broker whose `source` is exactly the given text (after trimming, case as typed) and that names no payment method is given this method. Customers then see the method's label for those payments as `sourceLabel`. **The stored `source` is not changed**, and no amount or reference is.
          *
+         *     **The text is compared exactly, code point for code point, and is not normalised** (#601). Payments recorded since #601 hold their source in Unicode normalisation form C, which is what a keyboard produces; a source stored in another spelling before then is reached by sending it as `GET /payment-methods/free-text-sources` lists it. A control character is refused with `400` on `Source`; any other character recording refuses (a format character, a line separator, a private-use or unassigned code point) is accepted here, because a source stored with one before #601 is the one most worth mapping to a method.
+         *
          *     **A mapping never moves a payment between methods.** Payments with this source that already name this method are counted in `alreadyMapped`, and those naming another method in `mappedToAnotherMethod`; neither is changed.
          *
          *     **A payment whose reference the method already holds is skipped** and listed in `skipped` with the payment that holds it, because mapping it would put the same reference against the method twice. The method holds a reference through a payment recorded against it, one mapped to it, or a free-text payment typed exactly as its code: the last is cautious, because such a payment is in the method's duplicate space under §5's index. `skippedCount` is the full count and `skipped` lists at most 200, earliest first. The rest are still mapped.
@@ -947,6 +963,8 @@ export interface paths {
          * Undo a mapping: show the payments with a free-text source as typed again
          * @description #588. Every payment of this broker whose `source` is exactly the given text (after trimming, case as typed) and that **a mapping** gave this method goes back to naming no method. Customers see the source as typed again, and the source returns to `GET /payment-methods/free-text-sources`. No amount, source or reference changes.
          *
+         *     **The text is compared exactly, code point for code point, and is not normalised** (#601), as the mapping route compares it. A control character is refused with `400` on `Source`; any other character recording refuses (a format character, a line separator, a private-use or unassigned code point) is accepted here, so a source stored with one before #601 stays reachable.
+         *
          *     **A payment recorded against this method is never changed**: its method is part of what was recorded. Such payments with this text (possible only when the text is the method's own code) are counted in `recordedAgainstMethod`. A payment recorded against the wrong method is corrected by a reversal. A payment that names this method through a mapping not marked as one (made by an API instance from before #588, possible only when the text is not the method's code) is counted in `notYetCorrectable` and left alone: map the source to this method again, which marks it, and then undo.
          *
          *     **Idempotent.** Repeating the request answers `unmapped: 0` and records nothing. A retired method can be unmapped from. A statement already produced keeps the wording it was produced with. A `409` is the platform's concurrency conflict, with `retryable: true`, when another write changed one of the payments while this ran.
@@ -971,6 +989,8 @@ 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.
          *
+         *     **The text is compared exactly, code point for code point, and is not normalised** (#601), as the mapping route compares it. A control character is refused with `400` on `Source`; any other character recording refuses (a format character, a line separator, a private-use or unassigned code point) is accepted here, so a source stored with one before #601 stays reachable.
+         *
          *     `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.
@@ -7809,7 +7829,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 */
@@ -7820,6 +7840,8 @@ export interface components {
             retentionAnchorAtUtc: null | string;
             lines: components["schemas"]["InvoiceLineResponse"][];
         };
+        /** @enum {string} */
+        InvoiceStatus: "Draft" | "Issued" | "Discarded";
         InvoiceSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -7836,7 +7858,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 */
@@ -8043,13 +8065,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;
@@ -8069,7 +8093,7 @@ export interface components {
             /** Format: date */
             dueOn: string;
             description: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
         };
         OfferedFormResponse: {
             /** Format: uuid */
@@ -9402,7 +9426,7 @@ export interface components {
             dueOn: string;
             /** Format: date-time */
             raisedAtUtc: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
         };
         StatementPage: {
             items: components["schemas"]["StatementSummaryResponse"][];

package/package.json

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