sinfactura-types 1.1.2 → 1.3.0

package/dist/subscription.d.ts

@@ -2,15 +2,17 @@
  * Subscription types — plan tiers, entitlements, feature matrix, subscription state.
  *
  * Ships app#710 (Chunk 1). Canonical decisions live in
- * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md.
+ * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md and
+ * sinfactura/app/docs/adr/0010-launch-trial-policy.md.
  *
  * Notes:
- * - Tier names are the 5 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0
- *   and api#802 — the launch lineup is BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO,
- *   plus FUNDADOR for the pre-launch cohort).
- * - `fundador` is BOTH a `PlanTier` (the cohort plan template seeded at api#802) and a
- *   pre-existing `SubscriptionStatus` value (kept for backward compat — the registration
- *   flow now sets status='active' on fundador subscriptions).
+ * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0
+ *   and api#802): BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
+ *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; 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
+ *   courtesy-gift cutoff; while `freeUntil > now` the BE suppresses billing.
  * - `FeatureKey` uses flat camelCase (not the dotted `reports.advanced` from the design kit).
  * - Monetary amounts are integers in minor units (ARS cents) to avoid float issues.
  * - Feature keys now match the BE wire format directly (renamed afip→afipInvoicing,
@@ -20,19 +22,21 @@
  *   enabled:false until they do.
  */
 declare global {
-    type PlanTier = 'basico' | 'emprendedor' | 'profesional' | 'avanzado' | 'fundador';
+    type PlanTier = 'basico' | 'emprendedor' | 'profesional' | 'avanzado';
     /**
      * Lifecycle status of a tenant's subscription.
      *
-     * - `trialing` — new signup in the 30-day PROFESIONAL trial (no payment method).
+     * - `trialing` — new paid-tier signup in their 30-day Stripe 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.
      * - `canceled` — tenant ended subscription; data retained per grace policy.
-     * - `fundador` — legacy pre-cohort status. Post-api#802, fundador subscriptions
-     *   carry `status: 'active'` and are identified via `planTier === 'fundador'`.
+     *
+     * Courtesy gifts (formerly the Founders cohort, ADR-0009) are no longer a
+     * status — they are represented by `Subscription.freeUntil` on top of any
+     * normal status. See ADR-0010.
      */
-    type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'readonly' | 'canceled' | 'fundador';
+    type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'readonly' | 'canceled';
     type BillingCycle = 'monthly' | 'annual';
     /**
      * Shape of a single entitlement on a (tier, feature) cell.
@@ -65,57 +69,122 @@ declare global {
     /** Resolved entitlements for a specific tenant (matrix + overrides applied). */
     type ResolvedEntitlements = Record<FeatureKey, Entitlement>;
     /**
-     * A sellable plan in the catalog. Seeded into DynamoDB by api#626 and
-     * served to the frontend via GET /subscription/plans.
+     * Implementation status of a feature on a plan row. Informational —
+     * gating still happens via `enabled` / `limit`. `'service'` rows
+     * (e.g. prioritySupport) are human-delivered but still gated like
+     * booleans.
+     */
+    type PlanFeatureStatus = 'live' | 'planned' | 'future' | 'service';
+    /**
+     * A single feature row in a Plan's `features[]` array. Matches the
+     * BE wire format from `GET /subscription/plans` exactly — boolean
+     * features carry `enabled`, numeric/metered carry `limit` (-1 =
+     * unlimited).
+     */
+    interface PlanFeature {
+        key: FeatureKey;
+        type: EntitlementType;
+        status: PlanFeatureStatus;
+        /** User-facing Spanish description. */
+        description: string;
+        /** Set on `boolean` features; `null` on numeric/metered. */
+        enabled: boolean | null;
+        /** Set on `numeric`/`metered` features; `null` on boolean. -1 = unlimited. */
+        limit: number | null;
+    }
+    /**
+     * A sellable plan in the catalog. Aligned with the BE wire format from
+     * `GET /subscription/plans` (api#859). Source of truth lives in
+     * DynamoDB (`PLAN#{tier}` partition), administered via `POST /sa/plans`
+     * + `PATCH /sa/plans/{tier}` (api#859).
+     *
+     * 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.
+     *
+     * **Breaking change vs 1.1.x:** the catalog Plan interface was reshaped
+     * to match the BE wire format. Renames & removals:
+     *   - `label` → `name`
+     *   - `blurb` → `description`
+     *   - `priceMonthly` → `priceMonthlyCents` (number | null)
+     *   - `priceAnnual` → `priceAnnualCents` (number | null)
+     *   - `currency` widened to `'ARS' | 'USD' | null`
+     *   - `entitlements: Record<FeatureKey, Entitlement>` → `features: PlanFeature[]`
+     *   - `isPublic` removed (use `isActive` for visibility gating)
+     *   - `stripeMonthlyPriceId` / `stripeAnnualPriceId` /
+     *     `mpPreApprovalPlanIdMonthly` / `mpPreApprovalPlanIdAnnual` removed
+     *     (BE-internal — not on the public wire format)
+     *   - `createdAt` / `updatedAt` removed (not on the public wire format)
      *
-     * Prices are integers in ARS cents (e.g. $40 000 = 4_000_000).
-     * `null` = "Contactar ventas" (AVANZADO, pre-unlock).
+     * Added per api#859:
+     *   - `displayOrder` (number)
+     *   - `color` (single hex string, FE derives `soft`/`border` shades)
+     *   - `isPopular` (now required, was optional)
      */
     interface Plan {
         tier: PlanTier;
-        /** Display label — "BÁSICO", "EMPRENDEDOR", "PROFESIONAL", "AVANZADO", "FUNDADOR". */
-        label: string;
-        /** Short marketing tagline (Spanish). */
-        blurb?: string;
-        /** Price in the plan's `currency` smallest unit for monthly billing. `null` = contactar. */
-        priceMonthly: number | null;
-        /** Price in the plan's `currency` smallest unit for annual billing (total / 12; ~20% discount). `null` = contactar. */
-        priceAnnual: number | null;
+        /** Display name in Spanish (e.g. "Profesional"). */
+        name: string;
+        /** Short marketing one-liner in Spanish. */
+        description: string;
         /**
-         * Currency the prices are denominated in. `'ARS'` at launch; `'USD'`
-         * is the migration target (api#841). Widened from the launch-only
-         * `'ARS'` literal in api#842 so the FE can render either currency
-         * without a type change once the platform flips.
+         * Whether the plan is shown on the pricing page and accepting new
+         * subscribers. Pre-launch / sales-led tiers (e.g. AVANZADO until ≥2
+         * Planned features ship) set this to `false` without deleting the row.
          */
-        currency: 'ARS' | 'USD';
+        isActive: boolean;
         /**
-         * Whether the plan is accepting new subscribers. Closed-cohort plans
-         * (e.g. Founders after 2026-05-31) set this to `false` without deleting
-         * the plan row.
+         * Anchor / recommended tier on the pricing page. The FE typically
+         * renders the "Más elegido" pill on the plan(s) flagged here. The
+         * BE does not enforce uniqueness — admins can flag any number of
+         * plans, but the canonical convention is exactly one.
          */
-        isActive: boolean;
-        /** Marked as the anchor / recommended tier on the pricing page. PROFESIONAL at launch. */
-        isPopular?: boolean;
+        isPopular: boolean;
+        /** Sort order on the pricing page (ascending). Ties allowed. */
+        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. */
+        priceAnnualCents: number | null;
+        /**
+         * Currency the prices are denominated in. `'ARS'` at launch; `'USD'`
+         * is the migration target (api#841). `null` on free / off-billing
+         * tiers (basico).
+         */
+        currency: 'ARS' | 'USD' | null;
         /**
-         * Visibility on the public pricing page. AVANZADO = `false` until
-         * ≥2 Planned features ship (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0).
+         * Single brand hex color (e.g. '#590d82'). The FE derives `soft`
+         * (light tint) and `border` shades via MUI's `alpha()` helper.
+         * `null` on plans created/seeded before the api#859 backfill.
          */
-        isPublic: boolean;
-        /** Stripe Price IDs once the plan is wired to Stripe Products (api#627). */
-        stripeMonthlyPriceId?: string;
-        stripeAnnualPriceId?: string;
+        color: string | null;
         /**
-         * MercadoPago PreApprovalPlan IDs — populated by the future
-         * `seed-mercadopago-plans` Lambda (api#843). Coexist with the Stripe
-         * IDs above on the same Plan row so both providers' state can live
-         * in one place; unused fields stay dormant.
+         * Per-feature configuration. Every `FeatureKey` appears exactly once.
+         * Boolean features carry `enabled`; numeric/metered carry `limit`.
          */
-        mpPreApprovalPlanIdMonthly?: string;
-        mpPreApprovalPlanIdAnnual?: string;
-        /** Per-tier entitlement configuration. */
-        entitlements: Record<FeatureKey, Entitlement>;
+        features: PlanFeature[];
+    }
+    /**
+     * One audit row per SUPER_ADMIN-driven plan mutation. Returned by
+     * `GET /sa/plans/{tier}/audit` (api#859). The same row shape is used
+     * for the sibling `STORE` audit partition (api#827).
+     *
+     * `before` and `after` carry only the fields that changed (diff slice),
+     * not the full row blob.
+     */
+    interface PlanAuditEntry {
+        entity: 'PLAN';
+        entityId: string;
+        timestamp: number;
+        actor: {
+            userId: string;
+            fullName: string;
+        };
+        action: string;
+        before: Record<string, unknown>;
+        after: Record<string, unknown>;
+        reason: string;
         createdAt: number;
-        updatedAt: number;
     }
     /**
      * A tenant's current subscription row. One per `tenantId`.
@@ -141,17 +210,13 @@ declare global {
         /** Set while `status === 'trialing'`. Unix ms. */
         trialEndsAt?: number;
         /**
-         * Founders cohort only — YYYY-MM-DD when the 12-month free PROFESIONAL
-         * entitlement window ends. Set on registration when `?mode=founders`
-         * is opted into and the cohort is open. String (not numeric ms) so it's
-         * human-readable in the DynamoDB console — matches api#802 verbatim.
+         * Courtesy-gift cutoff (ADR-0010) — YYYY-MM-DD up to which billing is
+         * suppressed regardless of `status`. String (not numeric ms) so it's
+         * human-readable in the DynamoDB console. Set/cleared via the
+         * `gift-subscription` super endpoint with an audit-logged reason.
          */
         freeUntil?: string;
-        /** Founders cohort only — YYYY-MM-DD when the post-free grace period ends. */
-        graceUntil?: string;
-        /** Founders cohort only — eligible for the perpetual founder discount after cutoff. */
-        founderDiscountEligible?: boolean;
-        /** Stripe identifiers (absent for trialing/fundador before checkout). */
+        /** Stripe identifiers (absent before first checkout). */
         stripeCustomerId?: string;
         stripeSubscriptionId?: string;
         /**
@@ -204,6 +269,7 @@ declare global {
         currentPeriodStart: number | null;
         currentPeriodEnd: number | null;
         trialEndsAt: number | null;
+        /** Courtesy-gift cutoff (ADR-0010). YYYY-MM-DD or omitted. */
         freeUntil?: string;
         cancelAt: number | null;
         canceledAt: number | null;

package/dist/subscription.js

@@ -2,15 +2,17 @@
  * Subscription types — plan tiers, entitlements, feature matrix, subscription state.
  *
  * Ships app#710 (Chunk 1). Canonical decisions live in
- * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md.
+ * sinfactura/app/docs/plans/SUBSCRIPTION_BUSINESS_DECISIONS.md and
+ * sinfactura/app/docs/adr/0010-launch-trial-policy.md.
  *
  * Notes:
- * - Tier names are the 5 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0
- *   and api#802 — the launch lineup is BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO,
- *   plus FUNDADOR for the pre-launch cohort).
- * - `fundador` is BOTH a `PlanTier` (the cohort plan template seeded at api#802) and a
- *   pre-existing `SubscriptionStatus` value (kept for backward compat — the registration
- *   flow now sets status='active' on fundador subscriptions).
+ * - Tier names are the 4 locked Spanish tiers (per SUBSCRIPTION_TIERS_BEST_PRACTICES §0
+ *   and api#802): BÁSICO, EMPRENDEDOR, PROFESIONAL, AVANZADO. The launch policy
+ *   (ADR-0010) gives every new paid subscription a 30-day Stripe trial; 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
+ *   courtesy-gift cutoff; while `freeUntil > now` the BE suppresses billing.
  * - `FeatureKey` uses flat camelCase (not the dotted `reports.advanced` from the design kit).
  * - Monetary amounts are integers in minor units (ARS cents) to avoid float issues.
  * - Feature keys now match the BE wire format directly (renamed afip→afipInvoicing,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sinfactura-types",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "main": "dist/index.js",
   "type": "module",
   "types": "./dist/index.d.ts",