platform-types 1.10.713 → 1.10.715

package/dist/cjs/delivery.js

@@ -1,2 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELIVERY_ERROR_CODES = void 0;
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+exports.DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/dist/cjs/invoice.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INVOICE_POST_VOUCHER_ERROR_CODES = void 0;
+exports.INVOICE_ISSUANCE_REFUSAL_RECOVERY = exports.INVOICE_ISSUANCE_REFUSAL_CODES = exports.INVOICE_POST_VOUCHER_ERROR_CODES = void 0;
 /**
  * The codes `POST /invoices` answers AFTER a voucher number was spent — ARCA
  * was asked, or a CAEA number was claimed — as a runtime value the app maps.
@@ -32,3 +32,44 @@ exports.INVOICE_POST_VOUCHER_ERROR_CODES = [
     'INVOICE_EXPORT_OUTCOME_UNKNOWN',
     'CAEA_COMMIT_FAILED_AFTER_CLAIM',
 ];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+exports.INVOICE_ISSUANCE_REFUSAL_CODES = [
+    'INVOICE_ISSUANCE_IN_PROGRESS',
+    'CAEA_CLAIM_AMBIGUOUS',
+    'INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH',
+    'INVOICE_ISSUANCE_OUTCOME_UNCERTAIN',
+];
+exports.INVOICE_ISSUANCE_REFUSAL_RECOVERY = {
+    INVOICE_ISSUANCE_IN_PROGRESS: 'retry',
+    CAEA_CLAIM_AMBIGUOUS: 'retry',
+    INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: 'resend-issued-body',
+    INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: 'reconcile',
+};

package/dist/delivery.d.ts

@@ -84,8 +84,9 @@ declare global {
     }
     /**
      * One append-only entry in a delivery's timeline. Never overwritten and never
-     * deleted: a correction is a NEW event, so a `'delivered'` later contradicted
-     * by a `'failed'` leaves both on the record.
+     * deleted. `'delivered'` and `'failed'` are TERMINAL: nothing is appended
+     * after either (`409 DELIVERY_TERMINAL`), and a failed delivery is
+     * re-dispatched as a new delivery through `POST /deliveries`.
      *
      * PK `DELIVERY#{storeId}#{deliveryId}`, SK `EVENT#{createdAt}#{eventId}` —
      * the storeId segment is load-bearing, exactly as it is for `CashEvent`:
@@ -108,6 +109,18 @@ declare global {
         proof?: DeliveryProofAsset[];
         /** Set only on a `'failed'` event. */
         failureReason?: DeliveryFailureReason;
+        /**
+         * The `Idempotency-Key` the actor appended this event under — what lets a
+         * client match its own attempt exactly instead of guessing from type, time
+         * or photo count.
+         *
+         * ⚠️ Actor-scoped on the wire: `GET /deliveries/{id}` returns it only when
+         * the reader is this event's `actorUserId` or an ADMIN-tier role, and omits
+         * it otherwise. Absent on an event appended WITHOUT a key (still accepted —
+         * see `DeliveryEventAppendRequest`), on one written before keys existed, and
+         * on the opening `'assigned'` event `POST /deliveries` writes.
+         */
+        idempotencyKey?: string;
     }
     /**
      * A `DeliveryProofAsset` carrying the read-time-only `downloadUrl` minted by
@@ -126,5 +139,125 @@ declare global {
     type DeliveryEventWithProofUrls = Omit<DeliveryEvent, 'proof'> & {
         proof?: DeliveryProofAssetWithUrl[];
     };
+    /**
+     * Body of `POST /deliveries/{id}/events`. The `Idempotency-Key` header is
+     * OPTIONAL for now and strongly recommended — the key, not the body, is what
+     * makes a retry safe. It becomes REQUIRED in a later change, once the courier
+     * app sends it.
+     *
+     * ⚠️ WITHOUT a key the append is NOT idempotent: every call writes a new
+     * event, so a resend after a lost response records the event twice. Same
+     * validation, assignee scoping and terminal refusal; no replay protection and
+     * no attempt lookup.
+     *
+     * WITH a key, resend the SAME key with the byte-identical body after a lost
+     * response: a committed attempt answers its original event
+     * (`Idempotent-Replayed: true`), a changed body under that key is
+     * `422 IDEMPOTENCY_KEY_REUSE`.
+     *
+     * A transient fault answers `tryCatch`'s generic `400 UNHANDLED_ERROR`. A
+     * same-key resend then replays the attempt if it committed, RE-RUNS only if
+     * DynamoDB cancelled its transaction (nothing applied), and otherwise answers
+     * `409 IDEMPOTENCY_KEY_FAILED` — the attempt may have stored proof or
+     * committed, so the key is sealed. On that 409, ask
+     * `GET /deliveries/{id}?idempotencyKey=` (`DeliveryEventAttemptLookup`) and
+     * mint a new key only when it answers `'not-committed'`.
+     *
+     * The server sets `actorUserId`, `createdAt`, `gps.receivedAt` and the proof
+     * object keys; none of them is accepted here.
+     *
+     * Held to its schema by `AssertDeliveryEventAppendRequestMatchesSchema`.
+     */
+    interface DeliveryEventAppendRequest {
+        type: DeliveryEventType;
+        /** ≤ 1000 characters. */
+        note?: string;
+        gps?: Omit<DeliveryGpsFix, 'receivedAt'>;
+        /**
+         * Inline base64 proof, at most 5 assets (`MAX_PROOF_ASSETS_PER_EVENT`). Stored
+         * under a name derived from the delivery, the key, the asset's position and
+         * its bytes, written create-only — a retry can never replace an object.
+         */
+        proof?: Array<{
+            kind: DeliveryProofAsset['kind'];
+            contentType: string;
+            data: string;
+        }>;
+        /** Only on a `'failed'` event — anything else is `400 VALIDATION_FAILED`. */
+        failureReason?: DeliveryFailureReason;
+    }
+    /**
+     * What `GET /deliveries/{id}?idempotencyKey=<key>` answers about the
+     * CALLER'S OWN attempt under that key on THAT delivery — the authoritative
+     * recovery read, unlike the bounded (`truncated`) timeline, which can never
+     * prove absence.
+     *
+     * - `'committed'` — the attempt's event exists; `event` is that exact
+     *   original. Never append again for it.
+     * - `'pending'` — a request under the key is still in flight. Re-ask after
+     *   `retryAfterMs`; nothing was fenced.
+     * - `'not-committed'` — nothing was appended under the key, and the key is
+     *   FENCED: a durable tombstone (written by this read, or an earlier one, at
+     *   `fencedAt`) makes every later commit under it refuse. Only now may the
+     *   client mint a NEW key for the same intent; the old key answers
+     *   `409 IDEMPOTENCY_KEY_FAILED` forever.
+     *
+     * ⚠️ This read can WRITE: when the key is neither committed nor in flight it
+     * writes the tombstone before answering `'not-committed'`, so asking is itself
+     * a decision to give the key up. A client that would rather keep it resends
+     * under the same key instead.
+     *
+     * Attempt evidence is durable (no TTL), so both `'committed'` and
+     * `'not-committed'` stay answerable for the life of the delivery.
+     *
+     * The lookup takes the append's own authority bar: on a delivery that names
+     * a platform courier, a caller who is neither that courier nor ADMIN-tier is
+     * `403 DELIVERY_NOT_ASSIGNED`, before anything is read or written. Under an
+     * impersonated support session it answers only from stored state, and is
+     * `403 IMPERSONATION_READONLY` (`op: 'delivery.attemptFence'`) exactly where
+     * answering would need the tombstone.
+     */
+    interface DeliveryEventAttemptLookup {
+        idempotencyKey: string;
+        verdict: 'committed' | 'pending' | 'not-committed';
+        /** Present only on `'committed'`. */
+        event?: DeliveryEventWithProofUrls;
+        /** Present only on `'pending'`. */
+        retryAfterMs?: number;
+        /** Present only on `'not-committed'` — ms epoch the tombstone was written. */
+        fencedAt?: number;
+    }
 }
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export declare const DELIVERY_ERROR_CODES: readonly ["DELIVERY_NOT_FOUND", "DELIVERY_NOT_ASSIGNED", "DELIVERY_TERMINAL", "INVALID_DELIVERY_ID", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "INVALID_CURSOR", "IMPERSONATION_READONLY", "INVALID_BASE64", "CONTENT_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE"];
+export type DeliveryErrorCode = (typeof DELIVERY_ERROR_CODES)[number];
 export {};

package/dist/delivery.js

@@ -1 +1,47 @@
-export {};
+/**
+ * Every refusal code the delivery handlers (`POST /deliveries`,
+ * `POST /deliveries/{id}/events`, `GET /deliveries`, `GET /deliveries/{id}`)
+ * put on the wire, beyond the platform-wide set (`VALIDATION_FAILED`,
+ * `ROLE_FORBIDDEN`, `tryCatch`'s generic `UNHANDLED_ERROR`). Pinned against
+ * the handler sources by `tests/unit/deliveryErrorCodesPublished.test.ts`.
+ *
+ * - `INVALID_DELIVERY_ID` · 400 — no delivery id in the path.
+ * - `DELIVERY_NOT_FOUND` · 404 — unknown id, or another tenant's.
+ * - `DELIVERY_NOT_ASSIGNED` · 403 — the delivery names a platform courier
+ *   (`courier.userId`) and the caller is neither that user nor ADMIN-tier.
+ * - `DELIVERY_TERMINAL` · 409 — the delivery is already `'delivered'` or
+ *   `'failed'`; a failed delivery is re-dispatched through `POST /deliveries`.
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — the key is not ≤200 chars of
+ *   `[A-Za-z0-9._:-]`.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — the key was used with a different body.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — the attempt under the key failed after it
+ *   may have written proof, or the attempt lookup fenced the key; ask the
+ *   lookup, then use a new key.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the same key is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — the key's marker could not be
+ *   claimed; retry under the SAME key.
+ * - `INVALID_CURSOR` · 400 — a `?mine=true` `startKey` that is malformed or
+ *   names another store's partition.
+ * - `IMPERSONATION_READONLY` · 403 — the attempt lookup, under a support
+ *   session, could answer only by fencing the key (`op: 'delivery.attemptFence'`).
+ * - `INVALID_BASE64` · 400, `CONTENT_TOO_LARGE` · 413,
+ *   `UNSUPPORTED_MEDIA_TYPE` · 415 — the inline proof payload was refused
+ *   before anything was stored.
+ */
+export const DELIVERY_ERROR_CODES = [
+    'DELIVERY_NOT_FOUND',
+    'DELIVERY_NOT_ASSIGNED',
+    'DELIVERY_TERMINAL',
+    'INVALID_DELIVERY_ID',
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_KEY_FAILED',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'INVALID_CURSOR',
+    'IMPERSONATION_READONLY',
+    // The proof payload gate (`deliveryAttachmentValidation.ts`).
+    'INVALID_BASE64',
+    'CONTENT_TOO_LARGE',
+    'UNSUPPORTED_MEDIA_TYPE',
+];

package/dist/invoice.d.ts

@@ -837,6 +837,86 @@ declare global {
         /** The fortnight's CAEA code the number was claimed under. */
         CAEA: string;
     }
+    /**
+     * `data` of a `409 INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` answer from
+     * `POST /invoices` (a factura): an earlier issuance of this order was
+     * interrupted once it may have spent a voucher number — a live or WSFEX
+     * submit was recorded, or the outage path (a CAEA stamp or a `pending_cae`
+     * degrade) began — and the server holds no evidence of its outcome: the
+     * order's `invoices[]` does not name the recorded invoice and no
+     * stranded-voucher row names it. ARCA may hold a voucher for it, or may hold
+     * nothing.
+     *
+     * ⚠️ **Never retry, and never resend the original body as proof.** An
+     * unchanged body, a refetched order with no voucher and an elapsed lock are
+     * not evidence the earlier attempt spent nothing. The order stays fenced
+     * until support reconciles the attempt at ARCA and releases it.
+     */
+    interface InvoiceIssuanceOutcomeUncertainErrorData {
+        orderId: string;
+        /** The server's id for the interrupted invoice. No order entry names it. */
+        invoiceId?: string;
+        /**
+         * How the interrupted attempt reached ARCA: `cae` (live FECAESolicitar),
+         * `export` (WSFEX FEXAuthorize) or `outage` (a CAEA stamp or a
+         * `pending_cae` degrade). Written with `invoiceId` and `submittedAt` by
+         * the same mark, so absent only on a row edited by hand.
+         */
+        path?: 'cae' | 'export' | 'outage';
+        /** Epoch ms the interrupted attempt was cleared to contact ARCA. */
+        submittedAt?: number;
+        /**
+         * The voucher the interrupted attempt spent or was about to spend. A
+         * `cae`/`export` answer always carries it — such a row with no recorded
+         * voucher proves no submit went out and is never refused. On `outage` it
+         * is the claimed CAEA number (`kind: 'caea'`) when that best-effort
+         * record landed, or a live submit's voucher (`kind: 'arca'`) when the
+         * outage branch fell through to it; absent, it proves nothing.
+         */
+        voucher?: {
+            /** `arca` — submitted to ARCA (CAE or WSFEX); `caea` — a claimed CAEA number. */
+            kind: 'arca' | 'caea';
+            /** ARCA `CbteTipo` — the voucher class. */
+            CbteTipo: number;
+            /** ARCA `PtoVta` — the punto de venta it went out under. */
+            PtoVta: number;
+            /** ARCA `CbteNro` — the number ARCA may or may not hold. */
+            CbteNro: number;
+            /**
+             * The submitted voucher's `CbteFch` (`yyyymmdd`), when the attempt
+             * recorded one. `fingerprintMatches` compares it too: a voucher found
+             * at the number under another date is not this one.
+             */
+            CbteFch?: string;
+            /**
+             * A live `FECAESolicitar` attempt's identifying fields, as submitted —
+             * compare a `FECompConsultar` answer at the number against these, never
+             * against a rebuild from the order. The receptor's `DocNro` is withheld:
+             * compare it against the order's `invoiceMethod`. Absent on a CAEA claim,
+             * a WSFEX attempt, and an attempt recorded before it was stored.
+             */
+            fingerprint?: InvoiceIssuanceAttemptFingerprint;
+        };
+    }
+    /**
+     * The fields `FECompConsultar` echoes that identify a submitted voucher, as
+     * the interrupted attempt sent them, minus the receptor's `DocNro` and the
+     * date (`CbteFch`, beside it). Amounts are in the voucher currency (`MonId`).
+     */
+    interface InvoiceIssuanceAttemptFingerprint {
+        /** ARCA `DocTipo` — the receptor's document type. */
+        DocTipo: number;
+        /** ARCA `MonId` — the voucher currency code. */
+        MonId: string;
+        /** ARCA `MonCotiz` — the rate the voucher was submitted at. */
+        MonCotiz: number;
+        ImpTotal: number;
+        ImpNeto: number;
+        ImpIVA: number;
+        ImpTotConc: number;
+        ImpOpEx: number;
+        ImpTrib: number;
+    }
 }
 /**
  * The codes `POST /invoices` answers AFTER a voucher number was spent — ARCA
@@ -866,4 +946,50 @@ declare global {
  */
 export declare const INVOICE_POST_VOUCHER_ERROR_CODES: readonly ["INVOICE_PERSIST_AFTER_CAE_FAILED", "INVOICE_EXPORT_OUTCOME_UNKNOWN", "CAEA_COMMIT_FAILED_AFTER_CLAIM"];
 export type InvoicePostVoucherErrorCode = (typeof INVOICE_POST_VOUCHER_ERROR_CODES)[number];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+export declare const INVOICE_ISSUANCE_REFUSAL_CODES: readonly ["INVOICE_ISSUANCE_IN_PROGRESS", "CAEA_CLAIM_AMBIGUOUS", "INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH", "INVOICE_ISSUANCE_OUTCOME_UNCERTAIN"];
+export type InvoiceIssuanceRefusalCode = (typeof INVOICE_ISSUANCE_REFUSAL_CODES)[number];
+/**
+ * What a client may do with each {@link InvoiceIssuanceRefusalCode}:
+ *
+ * - `retry` — resend the same body after a short wait;
+ * - `resend-issued-body` — only the body of the issuance the key is bound to
+ *   (or credit that voucher first); a corrected body is refused again;
+ * - `reconcile` — do not resend at all; the order is fenced until support acts.
+ */
+export type InvoiceIssuanceRecovery = 'retry' | 'resend-issued-body' | 'reconcile';
+export declare const INVOICE_ISSUANCE_REFUSAL_RECOVERY: {
+    readonly INVOICE_ISSUANCE_IN_PROGRESS: "retry";
+    readonly CAEA_CLAIM_AMBIGUOUS: "retry";
+    readonly INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: "resend-issued-body";
+    readonly INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: "reconcile";
+};
 export {};

package/dist/invoice.js

@@ -29,3 +29,44 @@ export const INVOICE_POST_VOUCHER_ERROR_CODES = [
     'INVOICE_EXPORT_OUTCOME_UNKNOWN',
     'CAEA_COMMIT_FAILED_AFTER_CLAIM',
 ];
+/**
+ * The codes `POST /invoices` answers when it REFUSED to start an issuance — or
+ * could not confirm it — before any voucher of this request was recorded, as a
+ * runtime value a client maps. Distinct from
+ * {@link INVOICE_POST_VOUCHER_ERROR_CODES}: each has its own recovery, given by
+ * {@link INVOICE_ISSUANCE_REFUSAL_RECOVERY}.
+ *
+ * - `INVOICE_ISSUANCE_IN_PROGRESS` · 409 — another issuance of this order is
+ *   live: the same request's idempotency lock, or another request holding the
+ *   order's factura issuance guard inside its horizon. Also answered after the
+ *   order read, when the guard's owner-conditioned pre-ARCA mark or attempt
+ *   record finds the guard taken over by a successor — before that request's
+ *   submit went on the wire, so it spent nothing. Retry the same body shortly.
+ * - `CAEA_CLAIM_AMBIGUOUS` · 503 — ARCA was down and the CAEA number claim could
+ *   not be confirmed: the claim may have landed (an operator row records it), no
+ *   invoice was recorded and nothing was sent to ARCA, and the request released
+ *   its idempotency record. Retry the same body shortly — a retry claims again,
+ *   so the worst case is one unused CAEA number, never a second voucher.
+ * - `INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH` · 409 — the request's key is bound to
+ *   an issuance with a different voucher-shaping body (or to a record from
+ *   before payload hashing, which matches nothing). It does NOT say a voucher
+ *   exists on the order. Resend only the body that was issued, or credit the
+ *   voucher first.
+ * - `INVOICE_ISSUANCE_OUTCOME_UNCERTAIN` · 409 — an earlier factura of this
+ *   order was interrupted once it may have spent a voucher number, with no
+ *   recorded outcome. `data`
+ *   is {@link InvoiceIssuanceOutcomeUncertainErrorData}. Never retry; support
+ *   reconciles.
+ */
+export const INVOICE_ISSUANCE_REFUSAL_CODES = [
+    'INVOICE_ISSUANCE_IN_PROGRESS',
+    'CAEA_CLAIM_AMBIGUOUS',
+    'INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH',
+    'INVOICE_ISSUANCE_OUTCOME_UNCERTAIN',
+];
+export const INVOICE_ISSUANCE_REFUSAL_RECOVERY = {
+    INVOICE_ISSUANCE_IN_PROGRESS: 'retry',
+    CAEA_CLAIM_AMBIGUOUS: 'retry',
+    INVOICE_IDEMPOTENCY_PAYLOAD_MISMATCH: 'resend-issued-body',
+    INVOICE_ISSUANCE_OUTCOME_UNCERTAIN: 'reconcile',
+};

package/dist/platform.d.ts

@@ -846,15 +846,15 @@ export interface TenantBillingRollupRow {
 }
 /**
  * @deprecated Nothing produces one any more. The copy↔entitlement consistency
- * check went with the free-text plan copy it checked, so the `warnings` array
- * on the `POST` / `PATCH /platform/billing/plans` replies is ALWAYS empty. The
- * type stays only so a consumer still naming it compiles; it will be removed
- * together with that array.
+ * check went with the free-text plan copy it checked, and the `warnings` array
+ * that carried its findings is gone from the `POST` / `PATCH
+ * /platform/billing/plans` replies. The type stays only for the archived check
+ * under `stacks/services/_retired/` and for a consumer still naming it.
  */
 export type CatalogWarningCode = 'NUMERIC_MISMATCH' | 'UNLIMITED_ADVERTISED_AS_CAPPED' | 'UNBACKED_CAPABILITY' | 'MISSING_FEATURE_ROW';
 /**
- * @deprecated See {@link CatalogWarningCode} — no writer emits one; the
- * `warnings` array that carried it is always empty.
+ * @deprecated See {@link CatalogWarningCode} — no writer emits one, and no
+ * reply carries a `warnings` array of them any more.
  */
 export interface CatalogWarning {
     code: CatalogWarningCode;
@@ -1053,7 +1053,10 @@ export interface PlatformMrrMetrics {
      * the safer direction for a number an operator acts on.
      */
     countedStatuses: SubscriptionStatus[];
-    /** `priceAnnualCents / annualDivisor` is one annual subscription's monthly contribution. */
+    /**
+     * `priceAnnualCents` is the yearly total charged once per year, so
+     * `priceAnnualCents / annualDivisor` is one annual subscription's monthly contribution.
+     */
     annualDivisor: number;
     /** Subscriptions in a counted status. The denominator for `excluded`. */
     countedSubscriptions: number;

package/dist/subscription.d.ts

@@ -249,7 +249,7 @@ declare global {
      *
      * Prices are integers in the `currency` smallest unit (centavos for ARS,
      * cents for USD). `null` = "Contactar ventas" (AVANZADO annual at launch
-     * is sales-led; basico/fundador are free) per spec §6.4.
+     * is sales-led; basico is free) per spec §6.4.
      *
      * **Breaking change vs 1.1.x:** the catalog Plan interface was reshaped
      * to match the BE wire format. Renames & removals:
@@ -293,7 +293,12 @@ declare global {
         displayOrder: number;
         /** Monthly price in `currency` smallest units. `null` = sales-led / free. */
         priceMonthlyCents: number | null;
-        /** Annual price in `currency` smallest units. `null` = sales-led / free. */
+        /**
+         * The YEARLY TOTAL, charged once per year, in `currency` smallest units —
+         * never a per-month figure. Divide by 12 for a monthly equivalent.
+         * Nothing enforces its ratio to `priceMonthlyCents`; the operator sets
+         * both. `null` = sales-led / free.
+         */
         priceAnnualCents: number | null;
         /**
          * Currency the prices are denominated in. `'ARS'` at launch; `'USD'`
@@ -313,14 +318,6 @@ declare global {
          * `limit`.
          */
         features: PlanFeature[];
-        /**
-         * @deprecated ALWAYS `[]`. The free-text card copy was retired: a plan
-         * card renders {@link Plan.highlights} instead, and no write accepts
-         * `bullets` any more (`POST`/`PATCH /platform/billing/plans` answer 400
-         * `VALIDATION_FAILED`). A value an old row still stores is ignored, never
-         * echoed. The key will be removed once the app's copy editor is gone.
-         */
-        bullets: string[];
         /**
          * Keys worth calling out on this tier's card: highlight-eligible keys with
          * status `live` or `service` whose grant improves on the next lower

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.713",
+	"version": "1.10.715",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",