platform-types 1.10.713 → 1.10.714

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/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.714",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",