platform-types 1.10.701 → 1.10.703

package/dist/basket.d.ts

@@ -63,9 +63,9 @@ declare global {
     }
 }
 /**
- * Domain refusals from POST /baskets: legacy replacement, named cart actions,
- * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
- * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ * Domain refusals from POST /baskets (replacement, named actions and park/resume)
+ * and GET /baskets?mode=review. Check GATING_ERROR_CODES separately for middleware
+ * and role refusals. Other GET modes and storefront-only refusals remain separate.
  *
  * Coupon and promotion reasons are forwarded from evaluateCoupon and
  * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
@@ -74,6 +74,6 @@ declare global {
  * priceHandler.resolveLineStamp. The legacy loose body also reaches the shared
  * foreign-index-key guard; its owned terminalId is validated before that guard.
  */
-export declare const BASKET_ERROR_CODES: readonly ["VALIDATION_FAILED", "FOREIGN_INDEX_KEY_ATTRIBUTE", "CART_TARGET_REQUIRED", "CART_NOT_FOUND", "CART_NOT_PARKED", "CART_ALREADY_PARKED", "TERMINAL_INDEX_UNAVAILABLE", "PRODUCT_NOT_FOUND", "PRODUCT_COST_UNKNOWN", "UNIT_QUANTITY_NOT_WHOLE", "BASKET_VERSION_CONFLICT", "BASKET_LINE_LIMIT", "BASKET_SIZE_LIMIT", "UNKNOWN_LINE", "INVALID_PRICE", "LINE_DISCOUNT_NOT_ALLOWED", "LINE_DISCOUNT_EXCEEDS_MAX", "FX_CONVERSION_UNAVAILABLE", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_EXPIRED", "COUPON_EXHAUSTED", "COUPON_MIN_SUBTOTAL", "COUPON_REQUIRES_CUSTOMER", "COUPON_BUDGET_EXHAUSTED", "COUPON_RATE_LIMITED", "COUPON_CURRENCY_MISMATCH", "PROMOTION_NOT_FOUND", "PROMOTION_NOT_ACTIVE", "PROMOTION_NOT_STARTED", "PROMOTION_EXPIRED", "PROMOTION_NOT_CART_APPLICABLE"];
+export declare const BASKET_ERROR_CODES: readonly ["VALIDATION_FAILED", "FOREIGN_INDEX_KEY_ATTRIBUTE", "CART_TARGET_REQUIRED", "CART_NOT_FOUND", "CART_REVIEW_INCOMPLETE", "CART_REVIEW_UNAVAILABLE", "CART_NOT_PARKED", "CART_ALREADY_PARKED", "TERMINAL_INDEX_UNAVAILABLE", "PRODUCT_NOT_FOUND", "PRODUCT_COST_UNKNOWN", "UNIT_QUANTITY_NOT_WHOLE", "BASKET_VERSION_CONFLICT", "BASKET_LINE_LIMIT", "BASKET_SIZE_LIMIT", "UNKNOWN_LINE", "INVALID_PRICE", "LINE_DISCOUNT_NOT_ALLOWED", "LINE_DISCOUNT_EXCEEDS_MAX", "FX_CONVERSION_UNAVAILABLE", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_EXPIRED", "COUPON_EXHAUSTED", "COUPON_MIN_SUBTOTAL", "COUPON_REQUIRES_CUSTOMER", "COUPON_BUDGET_EXHAUSTED", "COUPON_RATE_LIMITED", "COUPON_CURRENCY_MISMATCH", "PROMOTION_NOT_FOUND", "PROMOTION_NOT_ACTIVE", "PROMOTION_NOT_STARTED", "PROMOTION_EXPIRED", "PROMOTION_NOT_CART_APPLICABLE"];
 export type BasketErrorCode = (typeof BASKET_ERROR_CODES)[number];
 export {};

package/dist/basket.js

@@ -1,7 +1,7 @@
 /**
- * Domain refusals from POST /baskets: legacy replacement, named cart actions,
- * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
- * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ * Domain refusals from POST /baskets (replacement, named actions and park/resume)
+ * and GET /baskets?mode=review. Check GATING_ERROR_CODES separately for middleware
+ * and role refusals. Other GET modes and storefront-only refusals remain separate.
  *
  * Coupon and promotion reasons are forwarded from evaluateCoupon and
  * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
@@ -15,6 +15,8 @@ export const BASKET_ERROR_CODES = [
     'FOREIGN_INDEX_KEY_ATTRIBUTE',
     'CART_TARGET_REQUIRED',
     'CART_NOT_FOUND',
+    'CART_REVIEW_INCOMPLETE',
+    'CART_REVIEW_UNAVAILABLE',
     'CART_NOT_PARKED',
     'CART_ALREADY_PARKED',
     'TERMINAL_INDEX_UNAVAILABLE',

package/dist/cart.d.ts

@@ -1,4 +1,24 @@
 declare global {
+    interface OperatorCartReviewRequest {
+        mode: 'review';
+        customerId: string;
+        cartId?: string;
+    }
+    interface OperatorCartReviewCart extends Omit<Cart, 'customer'> {
+        customer?: Partial<Pick<Customer, 'customerId' | 'fullName'>>;
+    }
+    type OperatorCartReviewData = OperatorCartReviewCart | null;
+    /**
+     * Completed discovery returns null; an exact missing cart is a refusal.
+     * Discovery over several customer carts is never ambiguous: it returns the
+     * cart a customer-targeted write resolves (a terminal-less cart before a
+     * till's ticket, newest within each group, a new-partition row before a
+     * legacy one).
+     */
+    interface OperatorCartReviewResponse {
+        message: string;
+        data: OperatorCartReviewData;
+    }
     /**
      * A cart, keyed by its OWN minted id rather than by the customer.
      *

package/dist/cjs/basket.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BASKET_ERROR_CODES = void 0;
 /**
- * Domain refusals from POST /baskets: legacy replacement, named cart actions,
- * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
- * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ * Domain refusals from POST /baskets (replacement, named actions and park/resume)
+ * and GET /baskets?mode=review. Check GATING_ERROR_CODES separately for middleware
+ * and role refusals. Other GET modes and storefront-only refusals remain separate.
  *
  * Coupon and promotion reasons are forwarded from evaluateCoupon and
  * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
@@ -18,6 +18,8 @@ exports.BASKET_ERROR_CODES = [
     'FOREIGN_INDEX_KEY_ATTRIBUTE',
     'CART_TARGET_REQUIRED',
     'CART_NOT_FOUND',
+    'CART_REVIEW_INCOMPLETE',
+    'CART_REVIEW_UNAVAILABLE',
     'CART_NOT_PARKED',
     'CART_ALREADY_PARKED',
     'TERMINAL_INDEX_UNAVAILABLE',

package/dist/cjs/subscription.js

@@ -8,8 +8,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -24,7 +27,7 @@
  *   enabled:false until they do.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEATURE_KEYS = exports.PLAN_TIERS = void 0;
+exports.FEATURE_KEYS = exports.isPaidPlanTier = exports.PAID_PLAN_TIERS = exports.PLAN_TIERS = void 0;
 /*
  * Runtime tuples for the unions above.
  *
@@ -44,6 +47,15 @@ exports.FEATURE_KEYS = exports.PLAN_TIERS = void 0;
 const exhaustiveTuple = () => (tuple) => tuple;
 /** Every plan tier, in rank order (lowest first). */
 exports.PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+exports.PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+const isPaidPlanTier = (value) => typeof value === 'string' && exports.PAID_PLAN_TIERS.includes(value);
+exports.isPaidPlanTier = isPaidPlanTier;
 /**
  * Every gated feature key.
  *

package/dist/subscription.d.ts

@@ -7,8 +7,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -24,10 +27,15 @@
  */
 declare global {
     type PlanTier = 'basico' | 'emprendedor' | 'profesional' | 'avanzado';
+    /** A tier that bills — every `PlanTier` but the free `basico`. Enumerated by `PAID_PLAN_TIERS`. */
+    type PaidPlanTier = Exclude<PlanTier, 'basico'>;
     /**
      * Lifecycle status of a tenant's subscription.
      *
-     * - `trialing` — new paid-tier signup in their 30-day Stripe trial.
+     * - `trialing` — a trial on a paid tier: a new store trials on the
+     *   `trialTier` platform global with `trialEndsAt` set `trialDays` days out
+     *   (`PlanCatalogue.trial`) — a date not yet enforced for a store without a
+     *   payment provider — and a Stripe checkout adds its own fixed 30-day trial.
      * - `active` — paid subscription, period current.
      * - `past_due` — payment failed, in the 7-day grace window.
      * - `readonly` — grace elapsed, writes blocked, tenant can still read.
@@ -319,13 +327,24 @@ declare global {
     }
     /**
      * `data` of `GET /public/plans` and `GET /subscription/plans` — both return
-     * the same `{ plans, groups }`: the plans plus the feature groups their rows
-     * render under.
+     * the same `{ plans, groups, trial }`: the plans, the feature groups their
+     * rows render under, and the trial a new store starts on.
      */
     interface PlanCatalogue {
         plans: Plan[];
         /** Every group a `features[].group` can name, with its label and sort position. */
         groups: PlanFeatureGroup[];
+        /**
+         * What a store registered now starts on: `tier` — a paid tier — in status
+         * `trialing`, with `trialEndsAt` set `days` days out. That date is not yet
+         * enforced for a store without a payment provider. Resolved from the platform globals
+         * `trialTier` / `trialDays` — `profesional` / `30` when unset or invalid —
+         * so it is always present.
+         */
+        trial: {
+            tier: PaidPlanTier;
+            days: number;
+        };
     }
     /**
      * One audit row per MANAGER-driven plan mutation (`POST` / `PATCH
@@ -422,17 +441,35 @@ declare global {
     /** A single usage entry as returned by GET /subscription. */
     interface SubscriptionUsageEntry {
         key: FeatureKey;
-        /** Period in YYYYMM format; `null` for lifetime caps (maxProducts/maxCustomers/maxUsers). */
+        /**
+         * Period in YYYYMM format for a monthly counter; `null` for a cap that never
+         * resets — the lifetime caps (maxProducts/maxCustomers/maxUsers) and the
+         * row-counted ones (webhooks, maxWarehouses: active rows, as their caps count).
+         */
         period: string | null;
         current: number;
-        /** `null` for unlimited tiers (no cap). */
+        /**
+         * The resolved ceiling: `-1` is the unlimited sentinel, and `null` means
+         * the plan declares no ceiling for this key.
+         */
         limit: number | null;
-        /** `null` when `limit` is unlimited/uncapped. */
+        /** `limit - current`, floored at zero; `null` whenever `limit` is `-1` or `null`. */
         remaining: number | null;
     }
     /**
-     * Full subscription snapshot pushed to the frontend on subscription/entitlement
-     * changes. Flat shape — matches GET /subscription wire format directly.
+     * Full subscription snapshot. Three producers emit it:
+     *
+     * - `GET /subscription` — the full `usage[]`, including the row-counted
+     *   `webhooks` / `maxWarehouses` meters. The two are present together or
+     *   absent together: both are absent when the row count failed in this pass,
+     *   and absent is not zero;
+     * - the `GET /store` subscription embed — WITHOUT those two meters (monthly
+     *   and lifetime only) and without `provider`;
+     * - the reply of the MANAGER `PUT /platform/stores/{storeId}/subscription` —
+     *   built by the same assembly as `GET /subscription`, meters included.
+     *
+     * The WebSocket only nudges a refetch on subscription/entitlement changes; it
+     * never carries this payload.
      */
     interface SubscriptionSyncPayload {
         planTier: PlanTier;
@@ -738,6 +775,14 @@ export type BillingProviderName = SubscriptionProvider;
 export type InvoiceSummary = globalThis.InvoiceSummary;
 /** Every plan tier, in rank order (lowest first). */
 export declare const PLAN_TIERS: readonly ["basico", "emprendedor", "profesional", "avanzado"];
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+export declare const PAID_PLAN_TIERS: readonly ["emprendedor", "profesional", "avanzado"];
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+export declare const isPaidPlanTier: (value: unknown) => value is PaidPlanTier;
 /**
  * Every gated feature key.
  *

package/dist/subscription.js

@@ -7,8 +7,11 @@
  *
  * Notes:
  * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0):
- *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
- *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; courtesy
+ *   BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. A new store starts trialing on
+ *   the `trialTier` platform global, with `trialEndsAt` set `trialDays` days out
+ *   (see `PlanCatalogue.trial`); that date is not yet enforced for a store
+ *   without a payment provider. A Stripe checkout adds its own fixed 30-day
+ *   trial, which does not follow those globals (ADR-0010). Courtesy
  *   gifts (formerly the Founders cohort) are now a one-off ops action via
  *   `gift-subscription` that sets `freeUntil` on the SUBSCRIPTION row.
  * - `freeUntil` lives on every Subscription independent of status. It is the
@@ -41,6 +44,14 @@
 const exhaustiveTuple = () => (tuple) => tuple;
 /** Every plan tier, in rank order (lowest first). */
 export const PLAN_TIERS = exhaustiveTuple()(['basico', 'emprendedor', 'profesional', 'avanzado']);
+/**
+ * Every paid tier, in rank order (lowest first) — `PLAN_TIERS` without the free
+ * `basico`. The one list of "tiers that bill": the trial-tier vocabulary, the
+ * grace sweep's tier fan-out and the provider plan seeders all read it.
+ */
+export const PAID_PLAN_TIERS = exhaustiveTuple()(['emprendedor', 'profesional', 'avanzado']);
+/** Whether `value` names a paid tier — narrows an untyped read (a stored row, a global) to `PaidPlanTier`. */
+export const isPaidPlanTier = (value) => typeof value === 'string' && PAID_PLAN_TIERS.includes(value);
 /**
  * Every gated feature key.
  *

package/package.json

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