@insurance-broker/api-client 5.8.0 → 5.9.0

package/dist/schema.d.ts

@@ -323,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;
@@ -367,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;
@@ -542,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;
@@ -917,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;
@@ -963,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.
          *
@@ -8214,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;
@@ -8237,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;
         };
@@ -8288,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;
@@ -8297,6 +8307,7 @@ export interface components {
             approvedAtUtc: null | string;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PaymentReversalResponse: {
             /** Format: uuid */
@@ -8349,6 +8360,8 @@ export interface components {
             /** Format: int32 */
             notYetCorrectable: number;
         };
+        /** @enum {string} */
+        PaymentStatus: "Posted";
         PaymentSummaryResponse: {
             /** Format: uuid */
             id: string;
@@ -8361,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 */
@@ -8369,6 +8382,7 @@ export interface components {
             reversed: boolean;
             /** Format: uuid */
             paymentMethodId: null | string;
+            paymentMethodWasMapped: boolean;
         };
         PlacedMemberResponse: {
             /** Format: uuid */
@@ -9276,6 +9290,8 @@ export interface components {
             email: null | string;
             phone: null | string;
         };
+        /** @enum {string} */
+        ScanVerdict: "Quarantined" | "Clean" | "Infected" | "Unscannable";
         ServiceLocationResponse: {
             /** Format: uuid */
             id: string;
@@ -10488,6 +10504,7 @@ export interface operations {
             query?: {
                 customerId?: string;
                 obligationId?: string;
+                awaitingApproval?: boolean;
                 cursor?: string;
                 limit?: number | string;
             };
@@ -10801,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: {

package/package.json

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