platform-types 1.10.834 → 1.10.835

package/dist/auth.d.ts

@@ -186,6 +186,46 @@ declare global {
          */
         storeContact?: TenantRegisterStoreContactInput;
     }
+    /**
+     * `POST /auth { mode: 'register-social' }` on the OPERATOR host — register a
+     * store whose founder signs in with Google or Apple and has NO password. Field
+     * for field what `registerSocialSchema` (`stacks/lambdas/auth/_registerSocial.ts`)
+     * accepts as INPUT, beside `mode`; the tie is compile-time,
+     * `AssertTenantSocialRegisterInputMatchesSchema`.
+     *
+     * The business fields are {@link TenantRegisterInput}'s, same bounds, minus
+     * `email` and `password`: the founder's email is ALWAYS the verified token's,
+     * and an `email` or `password` in the body is stripped, never read. The 200 is
+     * the body `mode: 'register'` answers, with `emailVerified: true`, and no
+     * verification code is mailed.
+     *
+     * ⚠️ Apple Hide My Email: a relay login is allowed, but then
+     * `storeContact.email` is REQUIRED and must itself not be a relay — see
+     * {@link TENANT_SOCIAL_REGISTER_ERROR_CODES}.
+     */
+    type TenantSocialRegisterInput = Omit<TenantRegisterInput, 'email' | 'password'> & {
+        /** A Firebase ID token from a Google or Apple sign-in, exactly as {@link Social.accessToken}. */
+        accessToken: string;
+    };
+    /**
+     * `POST /auth/verify-password` — re-authentication before a sensitive
+     * operation. EXACTLY ONE proof:
+     * - `password` — every account that has one;
+     * - `idToken` — a FRESH Firebase ID token (signed in within the last 5
+     *   minutes) from a provider the account was registered with, whose verified
+     *   email is the account's. Accepted ONLY on an account with no password;
+     *   see {@link STAFF_REAUTH_ERROR_CODES}.
+     * `totpCode` is the second factor, when the account has one, on either proof.
+     */
+    type StaffReauthInput = {
+        password: string;
+        idToken?: never;
+        totpCode?: string;
+    } | {
+        idToken: string;
+        password?: never;
+        totpCode?: string;
+    };
     /** {@link TenantRegisterInput.storeContact} — at least one key. */
     interface TenantRegisterStoreContactInput {
         /** EXACTLY 10 characters. */
@@ -1615,6 +1655,41 @@ export type SocialBridgeErrorCode = (typeof SOCIAL_BRIDGE_ERROR_CODES)[number];
  */
 export declare const CUSTOMER_SOCIAL_REGISTER_ERROR_CODES: readonly ["EMAIL_TAKEN_BY_ANOTHER_ACCOUNT", "CUSTOMER_ID_ALLOCATION_EXHAUSTED", "SIGN_IN_IDENTITY_UNVERIFIED", "INVALID_ID_TOKEN", "SIGN_IN_PROVIDER_UNSUPPORTED"];
 export type CustomerSocialRegisterErrorCode = (typeof CUSTOMER_SOCIAL_REGISTER_ERROR_CODES)[number];
+/**
+ * `body.error` codes `POST /auth { mode: 'register-social' }` on the OPERATOR
+ * host can refuse with, beside the ordinary `400` validation refusal:
+ *
+ * - `INVALID_ID_TOKEN` · 401 — the token is expired or malformed; get a fresh one.
+ * - `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — the provider has not verified the
+ *   email, or the token carries none.
+ * - `SIGN_IN_PROVIDER_UNSUPPORTED` · 400 — a provider other than Google or Apple.
+ * - `STORE_CONTACT_EMAIL_REQUIRED` · 400 — the login is an Apple relay address
+ *   and the body carries no `storeContact.email`, or a relay one.
+ * - `EMAIL_IN_USE` · 400 and `CUIT_SHARED` · 409 — exactly as `mode: 'register'`.
+ */
+export declare const TENANT_SOCIAL_REGISTER_ERROR_CODES: readonly ["INVALID_ID_TOKEN", "SIGN_IN_IDENTITY_UNVERIFIED", "SIGN_IN_PROVIDER_UNSUPPORTED", "STORE_CONTACT_EMAIL_REQUIRED", "EMAIL_IN_USE", "CUIT_SHARED"];
+export type TenantSocialRegisterErrorCode = (typeof TENANT_SOCIAL_REGISTER_ERROR_CODES)[number];
+/**
+ * `body.error` codes `POST /auth/verify-password` answers for the PROOF itself
+ * (the `password` / `idToken` choice), beside the identity, lockout and
+ * second-factor codes it shared before:
+ *
+ * - `WRONG_CREDENTIALS` · 401 — the password did not match.
+ * - `PASSWORD_NOT_SET` · 409 — a `password` was sent for an account that has
+ *   none (a founder registered with Google or Apple). The body carries
+ *   `providers`, the providers to re-authenticate with through `idToken`; or set
+ *   a password through recovery. Nothing is counted against the account.
+ * - `PASSWORD_REQUIRED` · 400 — an `idToken` was sent for an account that HAS a
+ *   password; it must re-authenticate with the password.
+ * - `INVALID_ID_TOKEN` · 401 / `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — as on
+ *   `register-social`.
+ * - `REAUTH_IDENTITY_MISMATCH` · 401 — the token's email is not the account's,
+ *   or its provider is not one the account was registered with.
+ * - `REAUTH_NOT_RECENT` · 401 — the provider sign-in behind the token is older
+ *   than 5 minutes; sign in with the provider again.
+ */
+export declare const STAFF_REAUTH_ERROR_CODES: readonly ["WRONG_CREDENTIALS", "PASSWORD_NOT_SET", "PASSWORD_REQUIRED", "INVALID_ID_TOKEN", "SIGN_IN_IDENTITY_UNVERIFIED", "REAUTH_IDENTITY_MISMATCH", "REAUTH_NOT_RECENT"];
+export type StaffReauthErrorCode = (typeof STAFF_REAUTH_ERROR_CODES)[number];
 /**
  * `body.error` codes the operator refresh/session leg can refuse with —
  * `POST /auth { mode: 'refresh' }` and the body-transport ingress it shares with

package/dist/auth.js

@@ -163,6 +163,54 @@ export const CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = [
     'INVALID_ID_TOKEN',
     'SIGN_IN_PROVIDER_UNSUPPORTED',
 ];
+/**
+ * `body.error` codes `POST /auth { mode: 'register-social' }` on the OPERATOR
+ * host can refuse with, beside the ordinary `400` validation refusal:
+ *
+ * - `INVALID_ID_TOKEN` · 401 — the token is expired or malformed; get a fresh one.
+ * - `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — the provider has not verified the
+ *   email, or the token carries none.
+ * - `SIGN_IN_PROVIDER_UNSUPPORTED` · 400 — a provider other than Google or Apple.
+ * - `STORE_CONTACT_EMAIL_REQUIRED` · 400 — the login is an Apple relay address
+ *   and the body carries no `storeContact.email`, or a relay one.
+ * - `EMAIL_IN_USE` · 400 and `CUIT_SHARED` · 409 — exactly as `mode: 'register'`.
+ */
+export const TENANT_SOCIAL_REGISTER_ERROR_CODES = [
+    'INVALID_ID_TOKEN',
+    'SIGN_IN_IDENTITY_UNVERIFIED',
+    'SIGN_IN_PROVIDER_UNSUPPORTED',
+    'STORE_CONTACT_EMAIL_REQUIRED',
+    'EMAIL_IN_USE',
+    'CUIT_SHARED',
+];
+/**
+ * `body.error` codes `POST /auth/verify-password` answers for the PROOF itself
+ * (the `password` / `idToken` choice), beside the identity, lockout and
+ * second-factor codes it shared before:
+ *
+ * - `WRONG_CREDENTIALS` · 401 — the password did not match.
+ * - `PASSWORD_NOT_SET` · 409 — a `password` was sent for an account that has
+ *   none (a founder registered with Google or Apple). The body carries
+ *   `providers`, the providers to re-authenticate with through `idToken`; or set
+ *   a password through recovery. Nothing is counted against the account.
+ * - `PASSWORD_REQUIRED` · 400 — an `idToken` was sent for an account that HAS a
+ *   password; it must re-authenticate with the password.
+ * - `INVALID_ID_TOKEN` · 401 / `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — as on
+ *   `register-social`.
+ * - `REAUTH_IDENTITY_MISMATCH` · 401 — the token's email is not the account's,
+ *   or its provider is not one the account was registered with.
+ * - `REAUTH_NOT_RECENT` · 401 — the provider sign-in behind the token is older
+ *   than 5 minutes; sign in with the provider again.
+ */
+export const STAFF_REAUTH_ERROR_CODES = [
+    'WRONG_CREDENTIALS',
+    'PASSWORD_NOT_SET',
+    'PASSWORD_REQUIRED',
+    'INVALID_ID_TOKEN',
+    'SIGN_IN_IDENTITY_UNVERIFIED',
+    'REAUTH_IDENTITY_MISMATCH',
+    'REAUTH_NOT_RECENT',
+];
 /**
  * `body.error` codes the operator refresh/session leg can refuse with —
  * `POST /auth { mode: 'refresh' }` and the body-transport ingress it shares with

package/dist/cjs/auth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CUSTOMER_OTP_LIMITS = exports.CUSTOMER_OTP_ERROR_CODES = exports.STAFF_ACCOUNT_DELETION_ERROR_CODES = exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
+exports.CUSTOMER_OTP_LIMITS = exports.CUSTOMER_OTP_ERROR_CODES = exports.STAFF_ACCOUNT_DELETION_ERROR_CODES = exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.STAFF_REAUTH_ERROR_CODES = exports.TENANT_SOCIAL_REGISTER_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
 /**
  * `body.error` codes the sign-in-method paths can refuse with.
  *
@@ -166,6 +166,54 @@ exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = [
     'INVALID_ID_TOKEN',
     'SIGN_IN_PROVIDER_UNSUPPORTED',
 ];
+/**
+ * `body.error` codes `POST /auth { mode: 'register-social' }` on the OPERATOR
+ * host can refuse with, beside the ordinary `400` validation refusal:
+ *
+ * - `INVALID_ID_TOKEN` · 401 — the token is expired or malformed; get a fresh one.
+ * - `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — the provider has not verified the
+ *   email, or the token carries none.
+ * - `SIGN_IN_PROVIDER_UNSUPPORTED` · 400 — a provider other than Google or Apple.
+ * - `STORE_CONTACT_EMAIL_REQUIRED` · 400 — the login is an Apple relay address
+ *   and the body carries no `storeContact.email`, or a relay one.
+ * - `EMAIL_IN_USE` · 400 and `CUIT_SHARED` · 409 — exactly as `mode: 'register'`.
+ */
+exports.TENANT_SOCIAL_REGISTER_ERROR_CODES = [
+    'INVALID_ID_TOKEN',
+    'SIGN_IN_IDENTITY_UNVERIFIED',
+    'SIGN_IN_PROVIDER_UNSUPPORTED',
+    'STORE_CONTACT_EMAIL_REQUIRED',
+    'EMAIL_IN_USE',
+    'CUIT_SHARED',
+];
+/**
+ * `body.error` codes `POST /auth/verify-password` answers for the PROOF itself
+ * (the `password` / `idToken` choice), beside the identity, lockout and
+ * second-factor codes it shared before:
+ *
+ * - `WRONG_CREDENTIALS` · 401 — the password did not match.
+ * - `PASSWORD_NOT_SET` · 409 — a `password` was sent for an account that has
+ *   none (a founder registered with Google or Apple). The body carries
+ *   `providers`, the providers to re-authenticate with through `idToken`; or set
+ *   a password through recovery. Nothing is counted against the account.
+ * - `PASSWORD_REQUIRED` · 400 — an `idToken` was sent for an account that HAS a
+ *   password; it must re-authenticate with the password.
+ * - `INVALID_ID_TOKEN` · 401 / `SIGN_IN_IDENTITY_UNVERIFIED` · 401 — as on
+ *   `register-social`.
+ * - `REAUTH_IDENTITY_MISMATCH` · 401 — the token's email is not the account's,
+ *   or its provider is not one the account was registered with.
+ * - `REAUTH_NOT_RECENT` · 401 — the provider sign-in behind the token is older
+ *   than 5 minutes; sign in with the provider again.
+ */
+exports.STAFF_REAUTH_ERROR_CODES = [
+    'WRONG_CREDENTIALS',
+    'PASSWORD_NOT_SET',
+    'PASSWORD_REQUIRED',
+    'INVALID_ID_TOKEN',
+    'SIGN_IN_IDENTITY_UNVERIFIED',
+    'REAUTH_IDENTITY_MISMATCH',
+    'REAUTH_NOT_RECENT',
+];
 /**
  * `body.error` codes the operator refresh/session leg can refuse with —
  * `POST /auth { mode: 'refresh' }` and the body-transport ingress it shares with

package/dist/cjs/marketing.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARKETING_COPY_VARIANTS_MAX = exports.MARKETING_COPY_VARIANTS_MIN = exports.MARKETING_COPY_FACT_MAX_CHARS = exports.MARKETING_COPY_FACTS_MAX = exports.MARKETING_COPY_FACTS_MIN = exports.MARKETING_COPY_GOAL_MAX_CHARS = exports.ABANDONED_CART_SNAPSHOT_NAME_MAX = exports.ABANDONED_CART_SNAPSHOT_MAX_LINES = exports.CART_APPLICABLE_PROMOTION_TYPES = exports.PROMOTION_TYPES = exports.AUTOMATION_RULE_STATUSES = exports.AUTOMATION_SEND_STATUSES = exports.ATTRIBUTION_WINDOW_HOURS = exports.RFM_SEGMENT_LABELS = exports.AUTOMATION_TRIGGERS = void 0;
+exports.MARKETING_COPY_VARIANTS_MAX = exports.MARKETING_COPY_VARIANTS_MIN = exports.MARKETING_COPY_FACT_MAX_CHARS = exports.MARKETING_COPY_FACTS_MAX = exports.MARKETING_COPY_FACTS_MIN = exports.MARKETING_COPY_GOAL_MAX_CHARS = exports.ABANDONED_CART_SNAPSHOT_NAME_MAX = exports.ABANDONED_CART_SNAPSHOT_MAX_LINES = exports.CART_APPLICABLE_PROMOTION_TYPES = exports.PROMOTION_TYPES = exports.AUTOMATION_RULE_STATUSES = exports.AUTOMATION_SEND_STATUSES = exports.ATTRIBUTION_WINDOW_HOURS = exports.RFM_SEGMENT_LABELS = exports.CAMPAIGN_ERROR_CODES = exports.CAMPAIGN_CLIENT_STATUSES = exports.AUTOMATION_TRIGGERS = void 0;
 /**
  * Runtime source for {@link AutomationTrigger}, the api’s Zod enum and the
  * configuration picker. Derive them from this tuple; a separate union plus
@@ -11,6 +11,32 @@ exports.MARKETING_COPY_VARIANTS_MAX = exports.MARKETING_COPY_VARIANTS_MIN = expo
  * consumers such as Record<AutomationTrigger, …>; handle it in the same change.
  */
 exports.AUTOMATION_TRIGGERS = ['ABANDONED_CART', 'REORDER_DUE'];
+/**
+ * The {@link CampaignStatus} values a client may write on `POST /campaigns`.
+ * Any other status is a 409 `CAMPAIGN_ILLEGAL_TRANSITION`; a client `sentAt` is
+ * a 400 `VALIDATION_FAILED`.
+ */
+exports.CAMPAIGN_CLIENT_STATUSES = [
+    'draft',
+    'scheduled',
+    'cancelled',
+];
+/**
+ * Refusals of the campaign status machine on `POST /campaigns`.
+ *
+ * - `CAMPAIGN_NOT_EDITABLE` · 409 — the campaign is `'sending'`, `'sent'` or
+ *   `'cancelled'`, and the request changes no status.
+ * - `CAMPAIGN_ILLEGAL_TRANSITION` · 409 — the request (create or update) asks
+ *   for a server-owned status (`'sending'` / `'sent'`), or asks a `'sending'`,
+ *   `'sent'` or `'cancelled'` campaign for a different status.
+ * - `CAMPAIGN_STATUS_CONFLICT` · 409 — the status changed between the read and
+ *   the write (usually the scheduler claiming it); re-read and retry.
+ */
+exports.CAMPAIGN_ERROR_CODES = [
+    'CAMPAIGN_NOT_EDITABLE',
+    'CAMPAIGN_ILLEGAL_TRANSITION',
+    'CAMPAIGN_STATUS_CONFLICT',
+];
 /**
  * {@link RfmSegmentLabel} as a runtime value, so `isSegmentRuleValid`
  * (`stacks/services/segments.ts`) and the nightly scoring pass

package/dist/cjs/purchaseWithdrawal.js

@@ -100,9 +100,10 @@ exports.PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
  *   on) on an order that already has an open shopper return request
  *   (`requested`, `authorized` or `received`); `data.rmaId` names it. One open
  *   shopper request per order.
- * - `too-many-lines` — a shopper return request (either flow) naming, or
- *   resolving to, more lines than one return request may hold; `data.max` is
- *   the bound.
+ * - `too-many-lines` — a withdrawal naming more lines than
+ *   {@link PURCHASE_WITHDRAWAL_LINES_MAX}, or a shopper return request (either
+ *   flow) naming, or resolving to, more lines than one return request may hold;
+ *   `data.max` is the bound.
  */
 exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'order-cancelled',
@@ -131,8 +132,14 @@ exports.PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
 exports.PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 exports.PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
-/** The most lines one request may name. */
-exports.PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/**
+ * The most lines one request may name. It is held to the worst case a single
+ * bound `Return` can carry: a withdrawal's hand-off RMA approves every line,
+ * and its `Return` must name exactly those lines, while the Return's
+ * transaction item budget fits 48 lines when every line restocks into a
+ * depósito as well as the store total. A larger withdrawal could never settle.
+ */
+exports.PURCHASE_WITHDRAWAL_LINES_MAX = 48;
 /** Calendar days of the withdrawal window after the later of delivery and purchase. */
 exports.PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
 /** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */

package/dist/cjs/terminal.js

@@ -90,6 +90,10 @@ exports.TERMINAL_ENROLMENT_ERROR_CODES = [
  * - `INVALID_PIN_FORMAT` · 400 — `POST /terminal/pin`: not 4–6 digits.
  * - `WRONG_CREDENTIALS` · 400 — `POST /terminal/pin`: the re-verified password
  *   did not match.
+ * - `PASSWORD_NOT_SET` · 409 — `POST /terminal/activation` and `POST
+ *   /terminal/pin`: the employee (a founder registered with Google or Apple) has
+ *   no password. The body carries `providers`, the recorded sign-in providers, as
+ *   `POST /auth/verify-password` does. Nothing is counted against the account.
  * - `IDEMPOTENCY_KEY_REUSE` · 422 / `IDEMPOTENCY_IN_PROGRESS` · 409 /
  *   `INVALID_IDEMPOTENCY_KEY` · 400 — the `Idempotency-Key` header's own
  *   refusals on `POST /terminal/operators`. A MISSING header is
@@ -126,6 +130,7 @@ exports.TERMINAL_SESSION_ERROR_CODES = [
     'ROLE_NOT_ALLOWED',
     'INVALID_PIN_FORMAT',
     'WRONG_CREDENTIALS',
+    'PASSWORD_NOT_SET',
     'IDEMPOTENCY_KEY_REUSE',
     'IDEMPOTENCY_IN_PROGRESS',
     'INVALID_IDEMPOTENCY_KEY',

package/dist/customer.d.ts

@@ -56,8 +56,13 @@ declare global {
     interface ChannelConsentStamp {
         /** ms epoch of the grant or withdrawal this stamp describes. */
         ts: number;
-        source: 'ui' | 'import' | 'api' | 'storefront';
-        /** Absent when the write had no request-level IP (a CSV import, a job). */
+        /**
+         * Who set the value. `'complaint'` is the SES events worker withdrawing
+         * `email` after the recipient marked a message as spam; it is only ever a
+         * withdrawal.
+         */
+        source: 'ui' | 'import' | 'api' | 'storefront' | 'complaint';
+        /** Absent when the write had no request-level IP (a CSV import, a job, a complaint). */
         ip?: string;
     }
     interface CustomerMarketing {

package/dist/marketing.d.ts

@@ -9,6 +9,21 @@ declare global {
      * cheap, and having shipped a promise is not.
      */
     type CampaignChannel = 'email';
+    /**
+     * Where a campaign is in its life. The api enforces the transitions:
+     *
+     * - `'draft'` → `'scheduled'` | `'cancelled'`
+     * - `'scheduled'` → `'draft'` | `'cancelled'`, or `'sending'` by the scheduler's claim
+     * - `'sending'` → `'sent'` once every recipient settled, or back to `'scheduled'`
+     *   only on the scheduler's own fan-out retry
+     * - `'sent'` and `'cancelled'` are terminal.
+     *
+     * ⚠️ A client may write only {@link CAMPAIGN_CLIENT_STATUSES}. `'sending'`,
+     * `'sent'` and `sentAt` are server-owned, and a campaign that is `'sending'`,
+     * `'sent'` or `'cancelled'` cannot be edited at all — the refusals are
+     * {@link CAMPAIGN_ERROR_CODES}. A sent campaign is never sent again; to send
+     * the same content twice, create a new campaign.
+     */
     type CampaignStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'cancelled';
     interface Campaign {
         storeId: string;
@@ -18,8 +33,14 @@ declare global {
         status: CampaignStatus;
         templateId?: string;
         segmentId?: string;
+        /**
+         * ⚠️ UNUSED. Stored as the client sent it and returned on reads, but no
+         * code reads it: the send does not apply, mention or link a promotion.
+         * Do not build on it as if a campaign carried a discount.
+         */
         promotionId?: string;
         scheduledAt?: number;
+        /** Unix MILLISECONDS. Server-owned: written only when the campaign reaches `'sent'`. */
         sentAt?: number;
         /**
          * Aggregate send counters, maintained by an atomic DynamoDB `ADD` as the
@@ -65,6 +86,16 @@ declare global {
          * bound the scheduler stops reverting and asks for an operator.
          */
         sendAttempts?: number;
+        /**
+         * Server-owned. Present while recipients HELD by the email kill switch
+         * (`'failed'` / `EMAIL_SENDING_DISABLED`) await a re-enqueue: the send
+         * worker `ADD`s 1 on every hold, and the scheduler removes it once it has
+         * re-enqueued every held recipient after the switch is back on.
+         *
+         * ⚠️ A MARKER, not a recipient count: a recipient held twice counts twice.
+         * Read it as "held recipients are still owed a delivery", nothing more.
+         */
+        sendHolds?: number;
         createdAt: number;
         updatedAt?: number;
     }
@@ -73,12 +104,14 @@ declare global {
      *
      * `'queued'` — accepted for delivery, not yet handed to the transport.
      * `'sent'` — the transport ACCEPTED it; acceptance is never proof of inbox
-     * placement. `'failed'` — the transport refused or errored. `'skipped'` — the
-     * segment matched the recipient but the send was withheld at send time: the
-     * recipient was not eligible (no marketing consent for the channel, no
-     * address, a suppressed address, a customer that no longer exists), the
-     * campaign was cancelled, or the store had its Marketing module switched off
-     * (`reason: 'MODULE_OFF'`). `CampaignRecipient.reason` carries which.
+     * placement. `'failed'` — the transport refused or errored, or the platform
+     * had email sending switched off (`reason: 'EMAIL_SENDING_DISABLED'`, held for
+     * a re-enqueue once sending is back on, and counted nowhere until it settles). `'skipped'` — the segment
+     * matched the recipient but the send was withheld at send time: the recipient
+     * was not eligible (no marketing consent for the channel, no address, a
+     * suppressed address, a customer that no longer exists or that the store
+     * disabled), the campaign was cancelled, or the store had its Marketing module
+     * switched off (`reason: 'MODULE_OFF'`). `CampaignRecipient.reason` carries which.
      *
      * ⚠️ `'skipped'` is a REFUSAL that was honoured, not a delivery problem:
      * never retry it, and never roll it into a failure rate. A `'MODULE_OFF'`
@@ -477,12 +510,15 @@ declare global {
      * a per-customer frequency cap. The configuration record for automated
      * marketing — abandoned-cart recovery first.
      *
-     * ⚠️ **Nothing consumes these rows yet.** This is the entity, its CRUD and
-     * its published contract, shipped INERT on purpose so the configuration
-     * screen has something to write to. The consumer that receives the signal,
-     * evaluates the rule and enqueues a send is a separate slice, and so is the
-     * storage the cap below is counted against. A rule created today is a stored
-     * intention, not an armed sender.
+     * ⚠️ **An `'active'` rule is an ARMED SENDER.** `cartSweep` (`ABANDONED_CART`)
+     * and `reorderDueCron` (`REORDER_DUE`) arm an {@link AutomationSend} for
+     * every active rule matching the trigger; the `automation-due` cron re-reads
+     * the rule, its template, the cap and consent when the delay ends, and the
+     * `automation-send` worker mails it. An archived template sends nothing.
+     * Automations are a `marketing` (Avanzado) feature: `/automation-rules` and
+     * `/templates` answer 403 `PLAN_UPGRADE_REQUIRED` without it, and both
+     * unattended lanes settle a store's due sends `'skipped'`
+     * `AUTOMATION_NOT_ENTITLED`.
      *
      * ⚠️ **No `channel`.** The bound `Template` already carries one, and a
      * second copy is a second answer — the same argument
@@ -554,8 +590,12 @@ declare global {
      * `'queued'` — accepted, not yet handed to a transport. `'sent'` — handed
      * over. `'failed'` — the transport refused or errored. `'skipped'` — the rule
      * matched but the send was withheld, by the frequency cap, by a live
-     * consent re-check, or because the store had its Marketing module switched
-     * off (`reason: 'MODULE_OFF'`, a store choice rather than a customer's).
+     * consent re-check, because the store had its Marketing module switched
+     * off (`reason: 'MODULE_OFF'`, a store choice rather than a customer's),
+     * because its plan does not carry `marketing`
+     * (`reason: 'AUTOMATION_NOT_ENTITLED'`), or because the rule's template was
+     * archived (`reason: 'AUTOMATION_TEMPLATE_ARCHIVED'`). A `'skipped'` row
+     * does not count against the frequency cap.
      *
      * Deliberately the same four values as {@link CampaignRecipientStatus}, and
      * deliberately a SEPARATE type rather than an alias: the two vocabularies
@@ -870,8 +910,18 @@ declare global {
         due: number;
         /** Sends handed to the transport queue. */
         enqueued: number;
-        /** Due rows withheld, each with its own recorded reason. */
+        /**
+         * Due rows withheld, each with its own recorded reason — including a
+         * store whose plan lacks `marketing` (`AUTOMATION_NOT_ENTITLED`).
+         */
         skipped: number;
+        /**
+         * Due rows whose evaluation or settle threw. Left queued, so the next run
+         * picks them up again; one deduped ERROR row per rule names them.
+         */
+        failed: number;
+        /** Tenants whose drain threw. Isolated: the rest of the tick still ran. */
+        storesFailed: number;
         /**
          * The pass reached the end of its work rather than stopping on its own
          * clock reserve. ⚠️ `false` is NORMAL under load and is not an error — it
@@ -1067,6 +1117,25 @@ declare global {
  * consumers such as Record<AutomationTrigger, …>; handle it in the same change.
  */
 export declare const AUTOMATION_TRIGGERS: readonly ["ABANDONED_CART", "REORDER_DUE"];
+/**
+ * The {@link CampaignStatus} values a client may write on `POST /campaigns`.
+ * Any other status is a 409 `CAMPAIGN_ILLEGAL_TRANSITION`; a client `sentAt` is
+ * a 400 `VALIDATION_FAILED`.
+ */
+export declare const CAMPAIGN_CLIENT_STATUSES: readonly ["draft", "scheduled", "cancelled"];
+/**
+ * Refusals of the campaign status machine on `POST /campaigns`.
+ *
+ * - `CAMPAIGN_NOT_EDITABLE` · 409 — the campaign is `'sending'`, `'sent'` or
+ *   `'cancelled'`, and the request changes no status.
+ * - `CAMPAIGN_ILLEGAL_TRANSITION` · 409 — the request (create or update) asks
+ *   for a server-owned status (`'sending'` / `'sent'`), or asks a `'sending'`,
+ *   `'sent'` or `'cancelled'` campaign for a different status.
+ * - `CAMPAIGN_STATUS_CONFLICT` · 409 — the status changed between the read and
+ *   the write (usually the scheduler claiming it); re-read and retry.
+ */
+export declare const CAMPAIGN_ERROR_CODES: readonly ["CAMPAIGN_NOT_EDITABLE", "CAMPAIGN_ILLEGAL_TRANSITION", "CAMPAIGN_STATUS_CONFLICT"];
+export type CampaignErrorCode = (typeof CAMPAIGN_ERROR_CODES)[number];
 /**
  * {@link RfmSegmentLabel} as a runtime value, so `isSegmentRuleValid`
  * (`stacks/services/segments.ts`) and the nightly scoring pass

package/dist/marketing.js

@@ -8,6 +8,32 @@
  * consumers such as Record<AutomationTrigger, …>; handle it in the same change.
  */
 export const AUTOMATION_TRIGGERS = ['ABANDONED_CART', 'REORDER_DUE'];
+/**
+ * The {@link CampaignStatus} values a client may write on `POST /campaigns`.
+ * Any other status is a 409 `CAMPAIGN_ILLEGAL_TRANSITION`; a client `sentAt` is
+ * a 400 `VALIDATION_FAILED`.
+ */
+export const CAMPAIGN_CLIENT_STATUSES = [
+    'draft',
+    'scheduled',
+    'cancelled',
+];
+/**
+ * Refusals of the campaign status machine on `POST /campaigns`.
+ *
+ * - `CAMPAIGN_NOT_EDITABLE` · 409 — the campaign is `'sending'`, `'sent'` or
+ *   `'cancelled'`, and the request changes no status.
+ * - `CAMPAIGN_ILLEGAL_TRANSITION` · 409 — the request (create or update) asks
+ *   for a server-owned status (`'sending'` / `'sent'`), or asks a `'sending'`,
+ *   `'sent'` or `'cancelled'` campaign for a different status.
+ * - `CAMPAIGN_STATUS_CONFLICT` · 409 — the status changed between the read and
+ *   the write (usually the scheduler claiming it); re-read and retry.
+ */
+export const CAMPAIGN_ERROR_CODES = [
+    'CAMPAIGN_NOT_EDITABLE',
+    'CAMPAIGN_ILLEGAL_TRANSITION',
+    'CAMPAIGN_STATUS_CONFLICT',
+];
 /**
  * {@link RfmSegmentLabel} as a runtime value, so `isSegmentRuleValid`
  * (`stacks/services/segments.ts`) and the nightly scoring pass

package/dist/order.d.ts

@@ -1236,6 +1236,18 @@ declare global {
         printedAt?: number;
         /** BE-minted pointer to the most recent print dispatch. Last-write-wins on reprint. */
         printJobId?: string;
+        /**
+         * A snapshot of each factura issued on this order, located by `invoiceId`.
+         * Two print fields mirror the invoice row and mean the same thing there:
+         * - `invoicePrinted`: stamped `true` when `POST /invoices { mode: 'print' }`
+         *   dispatches a job — optimistic, not evidence the job printed;
+         * - `printedAt`: server ms epoch, stamped when the agent's `ACK_PRINTED`
+         *   correlates to the invoice row's CURRENT `printJobId`. Removed by every
+         *   dispatch, so it is absent until that job is confirmed.
+         * Both are written right after the invoice row's own stamp and announced on an
+         * operator-only `orders` frame carrying `{ orderId, invoices }`. An entry for a
+         * factura printed before the order copy was kept carries neither.
+         */
         invoices?: Partial<Invoice>[];
         /**
          * Bounded, embedded projections of this order's returns, capped at 50.

package/dist/purchaseWithdrawal.d.ts

@@ -82,9 +82,10 @@ export declare const PURCHASE_WITHDRAWAL_ACTION_MODES: readonly ["accept", "decl
  *   on) on an order that already has an open shopper return request
  *   (`requested`, `authorized` or `received`); `data.rmaId` names it. One open
  *   shopper request per order.
- * - `too-many-lines` — a shopper return request (either flow) naming, or
- *   resolving to, more lines than one return request may hold; `data.max` is
- *   the bound.
+ * - `too-many-lines` — a withdrawal naming more lines than
+ *   {@link PURCHASE_WITHDRAWAL_LINES_MAX}, or a shopper return request (either
+ *   flow) naming, or resolving to, more lines than one return request may hold;
+ *   `data.max` is the bound.
  */
 export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-cancelled", "no-customer", "partial-before-fulfilment", "line-not-on-order", "line-unavailable", "nothing-to-withdraw", "not-delivered", "return-request-open", "too-many-lines"];
 /**
@@ -103,8 +104,14 @@ export declare const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS: readonly ["order-ca
 export declare const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES: readonly ["in-progress", "uncertain", "stranded"];
 /** The longest decline or relay `note`, in characters after trimming. */
 export declare const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
-/** The most lines one request may name. */
-export declare const PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/**
+ * The most lines one request may name. It is held to the worst case a single
+ * bound `Return` can carry: a withdrawal's hand-off RMA approves every line,
+ * and its `Return` must name exactly those lines, while the Return's
+ * transaction item budget fits 48 lines when every line restocks into a
+ * depósito as well as the store total. A larger withdrawal could never settle.
+ */
+export declare const PURCHASE_WITHDRAWAL_LINES_MAX = 48;
 /** Calendar days of the withdrawal window after the later of delivery and purchase. */
 export declare const PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
 /** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */
@@ -450,7 +457,7 @@ declare global {
         orderItemIndex?: number;
         /** The open shopper return request, for `return-request-open`. */
         rmaId?: string;
-        /** The most lines one return request may hold, for `too-many-lines`. */
+        /** The bound a `too-many-lines` request exceeded: a withdrawal's, or a return request's. */
         max?: number;
     }
     /** One of {@link PURCHASE_WITHDRAWAL_LIST_FILTERS}. */

package/dist/purchaseWithdrawal.js

@@ -97,9 +97,10 @@ export const PURCHASE_WITHDRAWAL_ACTION_MODES = ['accept', 'decline', 'relay'];
  *   on) on an order that already has an open shopper return request
  *   (`requested`, `authorized` or `received`); `data.rmaId` names it. One open
  *   shopper request per order.
- * - `too-many-lines` — a shopper return request (either flow) naming, or
- *   resolving to, more lines than one return request may hold; `data.max` is
- *   the bound.
+ * - `too-many-lines` — a withdrawal naming more lines than
+ *   {@link PURCHASE_WITHDRAWAL_LINES_MAX}, or a shopper return request (either
+ *   flow) naming, or resolving to, more lines than one return request may hold;
+ *   `data.max` is the bound.
  */
 export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
     'order-cancelled',
@@ -128,8 +129,14 @@ export const PURCHASE_WITHDRAWAL_INELIGIBLE_REASONS = [
 export const PURCHASE_WITHDRAWAL_FISCAL_IN_FLIGHT_CAUSES = ['in-progress', 'uncertain', 'stranded'];
 /** The longest decline or relay `note`, in characters after trimming. */
 export const PURCHASE_WITHDRAWAL_NOTE_MAX = 500;
-/** The most lines one request may name. */
-export const PURCHASE_WITHDRAWAL_LINES_MAX = 100;
+/**
+ * The most lines one request may name. It is held to the worst case a single
+ * bound `Return` can carry: a withdrawal's hand-off RMA approves every line,
+ * and its `Return` must name exactly those lines, while the Return's
+ * transaction item budget fits 48 lines when every line restocks into a
+ * depósito as well as the store total. A larger withdrawal could never settle.
+ */
+export const PURCHASE_WITHDRAWAL_LINES_MAX = 48;
 /** Calendar days of the withdrawal window after the later of delivery and purchase. */
 export const PURCHASE_WITHDRAWAL_WINDOW_DAYS = 10;
 /** The matrix row {@link PurchaseWithdrawal.windowClosesAt} is computed from. */

package/dist/terminal.d.ts

@@ -587,6 +587,10 @@ export type TerminalEnrolmentErrorCode = (typeof TERMINAL_ENROLMENT_ERROR_CODES)
  * - `INVALID_PIN_FORMAT` · 400 — `POST /terminal/pin`: not 4–6 digits.
  * - `WRONG_CREDENTIALS` · 400 — `POST /terminal/pin`: the re-verified password
  *   did not match.
+ * - `PASSWORD_NOT_SET` · 409 — `POST /terminal/activation` and `POST
+ *   /terminal/pin`: the employee (a founder registered with Google or Apple) has
+ *   no password. The body carries `providers`, the recorded sign-in providers, as
+ *   `POST /auth/verify-password` does. Nothing is counted against the account.
  * - `IDEMPOTENCY_KEY_REUSE` · 422 / `IDEMPOTENCY_IN_PROGRESS` · 409 /
  *   `INVALID_IDEMPOTENCY_KEY` · 400 — the `Idempotency-Key` header's own
  *   refusals on `POST /terminal/operators`. A MISSING header is
@@ -610,7 +614,7 @@ export type TerminalEnrolmentErrorCode = (typeof TERMINAL_ENROLMENT_ERROR_CODES)
  * wrapper refused (`IDEMPOTENCY_KEY_REUSE` and the rest) exactly like a wrong
  * PIN: a key reused with another PIN is not a free guess.
  */
-export declare const TERMINAL_SESSION_ERROR_CODES: readonly ["TERMINAL_NOT_PAIRED", "SHIFT_NOT_OPEN", "TERMINAL_ACTIVATION_SESSION_INVALID", "TERMINAL_ACTIVATION_SESSION_MISMATCH", "TERMINAL_ACTIVATION_CLEANUP_FAILED", "TERMINAL_NOT_ACTIVATED", "INVALID_PIN", "ACCOUNT_LOCKED", "PIN_LOCKED", "ROLE_NOT_ALLOWED", "INVALID_PIN_FORMAT", "WRONG_CREDENTIALS", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "INVALID_IDEMPOTENCY_KEY", "IMPERSONATION_TERMINAL_FORBIDDEN", "VALIDATION_FAILED", "IDEMPOTENCY_LOCK_CONTENTION", "OPERATOR_TOKEN_FORBIDDEN", "INVALID_CURSOR", "OPERATOR_SESSION_STALE", "TERMINAL_LOCK_FORBIDDEN", "TERMINAL_LOCK_UNAVAILABLE"];
+export declare const TERMINAL_SESSION_ERROR_CODES: readonly ["TERMINAL_NOT_PAIRED", "SHIFT_NOT_OPEN", "TERMINAL_ACTIVATION_SESSION_INVALID", "TERMINAL_ACTIVATION_SESSION_MISMATCH", "TERMINAL_ACTIVATION_CLEANUP_FAILED", "TERMINAL_NOT_ACTIVATED", "INVALID_PIN", "ACCOUNT_LOCKED", "PIN_LOCKED", "ROLE_NOT_ALLOWED", "INVALID_PIN_FORMAT", "WRONG_CREDENTIALS", "PASSWORD_NOT_SET", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "INVALID_IDEMPOTENCY_KEY", "IMPERSONATION_TERMINAL_FORBIDDEN", "VALIDATION_FAILED", "IDEMPOTENCY_LOCK_CONTENTION", "OPERATOR_TOKEN_FORBIDDEN", "INVALID_CURSOR", "OPERATOR_SESSION_STALE", "TERMINAL_LOCK_FORBIDDEN", "TERMINAL_LOCK_UNAVAILABLE"];
 export type TerminalSessionErrorCode = (typeof TERMINAL_SESSION_ERROR_CODES)[number];
 /** The device kinds a pairing code can pair (`TerminalPairingCodeRequest.kind`). */
 export declare const TERMINAL_PAIRING_KINDS: readonly ["terminal", "print-agent"];

package/dist/terminal.js

@@ -87,6 +87,10 @@ export const TERMINAL_ENROLMENT_ERROR_CODES = [
  * - `INVALID_PIN_FORMAT` · 400 — `POST /terminal/pin`: not 4–6 digits.
  * - `WRONG_CREDENTIALS` · 400 — `POST /terminal/pin`: the re-verified password
  *   did not match.
+ * - `PASSWORD_NOT_SET` · 409 — `POST /terminal/activation` and `POST
+ *   /terminal/pin`: the employee (a founder registered with Google or Apple) has
+ *   no password. The body carries `providers`, the recorded sign-in providers, as
+ *   `POST /auth/verify-password` does. Nothing is counted against the account.
  * - `IDEMPOTENCY_KEY_REUSE` · 422 / `IDEMPOTENCY_IN_PROGRESS` · 409 /
  *   `INVALID_IDEMPOTENCY_KEY` · 400 — the `Idempotency-Key` header's own
  *   refusals on `POST /terminal/operators`. A MISSING header is
@@ -123,6 +127,7 @@ export const TERMINAL_SESSION_ERROR_CODES = [
     'ROLE_NOT_ALLOWED',
     'INVALID_PIN_FORMAT',
     'WRONG_CREDENTIALS',
+    'PASSWORD_NOT_SET',
     'IDEMPOTENCY_KEY_REUSE',
     'IDEMPOTENCY_IN_PROGRESS',
     'INVALID_IDEMPOTENCY_KEY',

package/dist/userActivity.d.ts

@@ -104,7 +104,8 @@ declare global {
         channel: 'adds' | 'email' | 'phone' | 'sms' | 'whatsapp';
         from: boolean | null;
         to: boolean;
-        source: 'ui' | 'import' | 'api' | 'storefront';
+        /** `'complaint'`: a spam complaint withdrew `email` (`to: false`, no `ip`). */
+        source: 'ui' | 'import' | 'api' | 'storefront' | 'complaint';
         /**
          * ⚠️ PII — absent when the write had no request-level IP. Stored only: every
          * reader withholds it (both timeline reads, socket frames, the audit export
@@ -125,7 +126,7 @@ declare global {
     }
     /** Rows written for a customer's own action. Kept separate from {@link UserActivityEvent}. */
     type CustomerActivityEvent = CustomerConsentUpdatedEvent;
-    /** A staff CSV import set consent on a customer row, on the customer's word. */
+    /** A staff CSV import CLEARED consent on a customer row (an import never grants; a `true` cell is dropped). */
     interface CustomerConsentImportedEvent extends UserActivityEventBase {
         event: 'Customer Consent Imported';
         customer_id: string;

package/package.json

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