@insurance-broker/api-client 5.9.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;
@@ -456,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;
@@ -587,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;
@@ -811,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;
@@ -873,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;
@@ -7809,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 */
@@ -7820,6 +7832,8 @@ export interface components {
             retentionAnchorAtUtc: null | string;
             lines: components["schemas"]["InvoiceLineResponse"][];
         };
+        /** @enum {string} */
+        InvoiceStatus: "Draft" | "Issued" | "Discarded";
         InvoiceSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -7836,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 */
@@ -8043,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;
@@ -8069,7 +8085,7 @@ export interface components {
             /** Format: date */
             dueOn: string;
             description: string;
-            status: string;
+            status: components["schemas"]["ObligationStatus"];
         };
         OfferedFormResponse: {
             /** Format: uuid */
@@ -9402,7 +9418,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.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,