@signstack/cli 0.1.1

package/dist/libs/signstack/base/src/lib/models/shareable-link.d.ts

@@ -0,0 +1,215 @@
+import { ListResp } from './base';
+/**
+ * Shareable links for published blueprints (Task 91).
+ *
+ * A namespace user mints a public, unguessable URL that opens a branded,
+ * anonymous form. The customer fills only the fields they know; the creator
+ * has hardcoded the rest (e.g. Company Address, Company Tax Id), which render
+ * pre-filled and read-only. On submit, a workflow is created from the published
+ * blueprint and the customer is dropped into the existing signing experience.
+ *
+ * See `sharable-blueprint-plan.md` for the full design.
+ */
+/**
+ * Per-namespace cap on shareable links. Bounds the storage / enumeration
+ * surface of a publicly-reachable resource. Enforced at create time; Studio
+ * uses it to disable the "Create link" button at the cap. Mirrors
+ * `MAX_WEBHOOKS_PER_NAMESPACE`.
+ */
+export declare const MAX_SHAREABLE_LINKS_PER_NAMESPACE = 50;
+export declare enum ShareableLinkSourceType {
+    Blueprint = "blueprint",
+    Listing = "listing"
+}
+/**
+ * Source the link targets — a same-namespace blueprint OR a marketplace listing,
+ * told apart by `type`. `key`/`version` apply to both (the blueprint's or the
+ * listing's), mirroring the blueprint|listing split used by workflow creation.
+ */
+export interface ShareableLinkSource {
+    type: ShareableLinkSourceType;
+    key: string;
+    version: string;
+}
+export interface CreateShareableLinkReq {
+    source: ShareableLinkSource;
+    /**
+     * inputKey -> hardcoded value. Same shape as `CreateWorkflowReq.data`: usually
+     * a (full or partial) data object, but a top-level scalar input maps to a bare
+     * scalar. Every field present is rendered read-only on the public form — the
+     * customer can only fill the fields left blank.
+     */
+    prefill?: Record<string, any>;
+    /** Required. Shown as the heading on the public form (and in the creator's list). */
+    title: string;
+    /** Optional blurb shown under the title on the public page. May be multi-line. */
+    description?: string;
+    /** ISO date string; omit for "never expires". */
+    expiresAt?: string;
+    /** Hard ceiling on total submissions; omit for unlimited. */
+    maxSubmissions?: number;
+}
+/**
+ * Body of `POST /shareable-links/generate-metadata` — asks the AI to draft a
+ * customer-facing title + description for a link from its source blueprint.
+ */
+export interface GenerateShareableLinkMetadataReq {
+    source: ShareableLinkSource;
+}
+export interface GenerateShareableLinkMetadataResp {
+    /** Suggested heading for the public form. May be empty if generation failed. */
+    title: string;
+    /** Suggested blurb under the title. May be empty. */
+    description: string;
+}
+export interface UpdateShareableLinkReq {
+    /** inputKey -> hardcoded value (object, or a bare scalar for scalar inputs). */
+    prefill?: Record<string, any>;
+    /** Required title. Omit to leave unchanged; cannot be blanked. */
+    title?: string;
+    /** Public description. Send '' to clear; omit to leave unchanged. */
+    description?: string;
+    /** Kill-switch. `false` => public resolve/submit return 410. */
+    enabled?: boolean;
+    /** `null` clears the expiry. */
+    expiresAt?: string | null;
+    /** `null` clears the cap. */
+    maxSubmissions?: number | null;
+}
+/**
+ * Full shareable link — returned by the authenticated management endpoints.
+ * The optimistic-locking handle is on the `ETag` HTTP response header — pass it
+ * back as `If-Match` on the next `PATCH` / `DELETE`.
+ */
+export interface ShareableLinkResp {
+    /** Prefixed lowercase ULID, e.g. `sl_01jv8m7qfj6xj9gkz7a4s2h8e`. This IS the public URL token. */
+    id: string;
+    /** Absolute public URL incl. scheme, built server-side from the request host. */
+    url: string;
+    source: ShareableLinkSource;
+    /** inputKey -> hardcoded value (object, or a bare scalar for scalar inputs). */
+    prefill: Record<string, any>;
+    /** Required. Heading shown on the public form and in the creator's list. */
+    title: string;
+    /** Optional, possibly multi-line, shown under the title on the public page. */
+    description?: string;
+    enabled: boolean;
+    expiresAt?: string;
+    maxSubmissions?: number;
+    submissionCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * List item — carries `_eTag` per item since list responses cannot multiplex
+ * the single-valued `ETag` header. Pass back as `If-Match` on a subsequent
+ * `PATCH` / `DELETE`.
+ */
+export interface ShareableLinkListItem extends ShareableLinkResp {
+    _eTag: string;
+}
+export type ListShareableLinksResp = ListResp<ShareableLinkListItem>;
+/**
+ * Minimal namespace brand for the public page. Deliberately excludes
+ * `contactEmail`, `senderEmail*`, `phone`, `address`, `logoFileId`, `mode`,
+ * timestamps, ids — anything that is PII or internal config. See plan §7.7.
+ */
+export interface PublicNamespaceBrand {
+    /** company ?? senderName ?? org equivalents ?? platform default. */
+    name: string;
+    /** First https logo URL up the namespace→org chain ?? platform default. Never `gs://`. */
+    logoUrl: string;
+}
+/** Render-only projection of a JSON Schema property (no internal descriptions/expressions). */
+export interface PublicSchemaProperty {
+    type: string;
+    title?: string;
+    format?: string;
+    enum?: Array<string | number>;
+    /** Nested objects are supported. */
+    properties?: Record<string, PublicSchemaProperty>;
+    /** For object properties: the keys of its required children (drives required validation). */
+    required?: string[];
+    /** For array properties: the per-item schema (drives the `ss-repeat` rows). */
+    items?: PublicSchemaProperty;
+    /** Number: inclusive minimum / maximum. */
+    minimum?: number;
+    maximum?: number;
+    /** Number: exclusive minimum / maximum. */
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    /** Number: value must be a multiple of this (also sets the input step). */
+    multipleOf?: number;
+    /** String: min / max length. */
+    minLength?: number;
+    maxLength?: number;
+    /** String: regex the value must match. */
+    pattern?: string;
+    /** Array: min / max number of items. */
+    minItems?: number;
+    maxItems?: number;
+}
+/** Object-input projection: the common case (kept for clarity / back-compat). */
+export interface PublicInputSchema {
+    type: 'object';
+    title?: string;
+    required?: string[];
+    properties: Record<string, PublicSchemaProperty>;
+}
+export interface PublicShareableLinkInput {
+    /** Blueprint `Input.key`. */
+    key: string;
+    name?: string;
+    description?: string;
+    /** Pre-evaluated literal — expression-required is resolved server-side. */
+    required: boolean;
+    /**
+     * Render-only schema projection (NOT the raw `schemaDefinition`). Usually an
+     * object (`PublicInputSchema`), but a top-level **scalar** input projects to a
+     * bare `PublicSchemaProperty` (e.g. `{ type: 'string', format: 'email' }`) and
+     * renders as a single field.
+     */
+    schema: PublicSchemaProperty;
+}
+/** Response of the public `GET /shareable-links/:id` resolve endpoint. */
+export interface ResolveShareableLinkResp {
+    brand: PublicNamespaceBrand;
+    /** The link's title — the heading shown on the public form. */
+    title: string;
+    /** Optional, possibly multi-line description shown under the title. */
+    description?: string;
+    inputs: PublicShareableLinkInput[];
+    /**
+     * inputKey -> hardcoded value (object, or a bare scalar for scalar inputs).
+     * Every field present is pre-filled and rendered read-only on the public form;
+     * the customer fills only the rest.
+     */
+    prefill: Record<string, any>;
+}
+/** Body of the public `POST /shareable-links/:id/submit` endpoint. */
+export interface SubmitShareableLinkReq {
+    /**
+     * User-entered value per inputKey (an object, or a bare scalar for scalar
+     * inputs). Hardcoded fields are re-applied server-side, so anything sent for
+     * them is ignored. Each participant's name and email are carried by these
+     * inputs (the blueprint maps them via its `participant.name`/`email`
+     * expressions) — the public form never collects participant identity separately.
+     */
+    data: Record<string, any>;
+    /** Client-generated per attempt — a double-click guard, NOT a rate limit. */
+    idempotencyKey: string;
+}
+export interface SubmitShareableLinkResp {
+    /**
+     * Whether the workflow has any signing step. `true` => the workflow has
+     * emailed a signing link to each participant at the address carried in the
+     * submitted inputs (they sign from the email — never in-browser, since a
+     * public link can't prove email ownership). `false` => the blueprint is
+     * form/automation-only (or `includeIf` pruned every step), so the submission
+     * is already complete with nothing to sign.
+     *
+     * Signing tokens are deliberately NOT returned: exposing one would let the
+     * submitter sign without opening the email, bypassing the ownership check.
+     */
+    requiresSigning: boolean;
+}

package/dist/libs/signstack/base/src/lib/models/shareable-link.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShareableLinkSourceType = exports.MAX_SHAREABLE_LINKS_PER_NAMESPACE = void 0;
+/**
+ * Shareable links for published blueprints (Task 91).
+ *
+ * A namespace user mints a public, unguessable URL that opens a branded,
+ * anonymous form. The customer fills only the fields they know; the creator
+ * has hardcoded the rest (e.g. Company Address, Company Tax Id), which render
+ * pre-filled and read-only. On submit, a workflow is created from the published
+ * blueprint and the customer is dropped into the existing signing experience.
+ *
+ * See `sharable-blueprint-plan.md` for the full design.
+ */
+/**
+ * Per-namespace cap on shareable links. Bounds the storage / enumeration
+ * surface of a publicly-reachable resource. Enforced at create time; Studio
+ * uses it to disable the "Create link" button at the cap. Mirrors
+ * `MAX_WEBHOOKS_PER_NAMESPACE`.
+ */
+exports.MAX_SHAREABLE_LINKS_PER_NAMESPACE = 50;
+var ShareableLinkSourceType;
+(function (ShareableLinkSourceType) {
+    ShareableLinkSourceType["Blueprint"] = "blueprint";
+    ShareableLinkSourceType["Listing"] = "listing";
+})(ShareableLinkSourceType || (exports.ShareableLinkSourceType = ShareableLinkSourceType = {}));
+//# sourceMappingURL=shareable-link.js.map

package/dist/libs/signstack/base/src/lib/models/shareable-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shareable-link.js","sourceRoot":"","sources":["../../../../../../../../../libs/signstack/base/src/lib/models/shareable-link.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG,EAAE,CAAC;AAEpD,IAAY,uBAGX;AAHD,WAAY,uBAAuB;IACjC,kDAAuB,CAAA;IACvB,8CAAmB,CAAA;AACrB,CAAC,EAHW,uBAAuB,uCAAvB,uBAAuB,QAGlC"}

package/dist/libs/signstack/base/src/lib/models/subscription.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Subscription / billing shared types.
+ *
+ * Money is always integer cents — never floats. Currency formatting happens
+ * in the FE display layer.
+ *
+ * IDs:
+ * - Internal subscription doc id is prefixed `bsub_…` (billing subscription)
+ *   to avoid colliding with Stripe's own `sub_…` ids. Stripe's id lives in
+ *   `stripeSubscriptionId`.
+ * - Internal usage-period doc id is prefixed `up_…`.
+ * - Internal usage-event doc id is prefixed `ue_…`.
+ */
+export declare enum PlanCode {
+    Free = "free",
+    Pro = "pro"
+}
+/**
+ * 1:1 mirror of Stripe's subscription status enum. **All values are intentional**
+ * even though only a subset drives bespoke code paths — the schema's Mongoose
+ * `enum` validator rejects writes with unknown values, so every status Stripe
+ * may emit must be listed here or the corresponding webhook update crashes
+ * mid-write and the local doc drifts.
+ *
+ * Three categories (see the grouped sections below):
+ *
+ *  1. **Active states** — `isSubscriptionActive()` returns true; the org can
+ *     create Live workflows. Includes `past_due` because we honour the grace
+ *     period before locking access.
+ *
+ *  2. **Terminal states** — `applySubscriptionUpdate` flips the org back to
+ *     the Free baseline via `transitionToFree`.
+ *
+ *  3. **Pass-through states** — accepted by the schema so webhooks don't
+ *     crash, but no bespoke handler. Stripe is the system of record; if any
+ *     of these starts mattering to a feature, add the handler then.
+ *
+ * Reference: https://stripe.com/docs/api/subscriptions/object#subscription_object-status
+ */
+export declare enum SubscriptionStatus {
+    Active = "active",
+    /** Pro user with a failed payment. Stripe retries on its retry schedule
+     *  (configured in the Dashboard) and auto-cancels if retries exhaust;
+     *  we keep access active during this window. */
+    PastDue = "past_due",
+    /** Reserved — we don't ship trials today, but the access gate already
+     *  treats this as active so adding trials is purely a Stripe-side change. */
+    Trialing = "trialing",
+    /** User canceled (immediate or via Customer Portal). */
+    Canceled = "canceled",
+    /** First-invoice payment never cleared within Stripe's ~23h window. */
+    IncompleteExpired = "incomplete_expired",
+    /** Initial state for every Stripe-created sub before the first payment
+     *  attempt resolves — typically flips to `active` within seconds via the
+     *  follow-up `customer.subscription.updated` event. */
+    Incomplete = "incomplete",
+    /** Stripe-emitted after retries exhaust mid-cycle. We don't act on this
+     *  directly — the next `past_due → cancel` cycle (or operator action)
+     *  resolves the sub. */
+    Unpaid = "unpaid",
+    /** Customer Portal pause. We don't expose pause as a product feature, so
+     *  the doc just mirrors Stripe and the org keeps its current access until
+     *  Stripe transitions it to a real terminal state. */
+    Paused = "paused"
+}
+export declare enum UsageBillingCategory {
+    /** Counted against the plan's included quota. */
+    Included = "included",
+    /** Charged as overage via Stripe metered Price. */
+    Overage = "overage"
+}
+/**
+ * Plan catalog — one row per offered plan. Mutated only via deploy / admin
+ * scripts. Read every request (cached in-memory by `SubscriptionPlanService`).
+ */
+export interface SubscriptionPlan {
+    planCode: PlanCode;
+    displayName: string;
+    description: string;
+    isActive: boolean;
+    /** Workflows included in the base subscription per billing period. */
+    includedWorkflows: number;
+    /**
+     * Hard-cap for plans without an overage Price (e.g. Free). `null` = no hard
+     * cap (Pro relies on overage charges instead of blocking).
+     */
+    hardLimitWorkflows: number | null;
+    /** Stripe Price ID for the recurring base fee. `null` for Free. */
+    stripeBasePriceId: string | null;
+    /** Stripe Price ID for the metered overage. `null` if no overage. */
+    stripeOveragePriceId: string | null;
+    /**
+     * Stripe Billing Meter `event_name` that this plan's overage Price is
+     * linked to. Required for reporting on Stripe accounts that use the new
+     * Billing Meters API (which is the default for accounts created after
+     * mid-2024). The reporter POSTs `billing.meterEvents.create({ event_name,
+     * payload: { stripe_customer_id, value }, identifier })` against this
+     * name. `null` for plans with no overage or for legacy accounts still on
+     * the deprecated `subscriptionItems.createUsageRecord` API (we don't ship
+     * a code path for the legacy API anymore).
+     */
+    stripeOverageMeterEventName: string | null;
+    /** Cents per overage unit — display only. Stripe is source of truth for charging. */
+    overageUnitAmountCents: number | null;
+    /** Cents for base recurring fee — display only. */
+    baseAmountCents: number | null;
+    currency: string;
+    /** Sort order for the pricing page. */
+    displayOrder: number;
+}
+/**
+ * Discount currently attached to a subscription (or customer-level, applied to
+ * a subscription). Sourced from Stripe's `subscription.discounts[]` snapshot
+ * on every `customer.subscription.*` webhook — `undefined` here means no
+ * active discount on this subscription right now.
+ *
+ * Exactly one of `percentOff` / `amountOffCents` is set, mirroring Stripe's
+ * `coupon` shape.
+ *
+ * `label` is FE-ready ("20% off" / "$5.00 off") so the UI doesn't reimplement
+ * the formatting.
+ */
+export interface DiscountSummary {
+    /** Stripe coupon id (`co_…`). */
+    couponId: string;
+    /**
+     * Customer-facing promo code text (e.g. `LAUNCH20`) when the discount came
+     * from a `promotion_code` redemption at Checkout. `undefined` when the
+     * coupon was attached directly (Dashboard / API), since direct attachments
+     * don't go through a promotion_code.
+     */
+    promoCode?: string;
+    /** Pre-formatted human label, e.g. "20% off" or "$5.00 off". */
+    label: string;
+    /** Percent off (1-100). Set when the coupon is percentage-based. */
+    percentOff?: number;
+    /** Cents off the invoice subtotal. Set when the coupon is amount-based. */
+    amountOffCents?: number;
+    /** Coupon duration semantics — controls when Stripe auto-removes. */
+    duration: 'once' | 'repeating' | 'forever';
+    /** Months remaining for `repeating` duration. `undefined` for `once`/`forever`. */
+    durationInMonths?: number;
+    /**
+     * Hard end timestamp from Stripe (set for `once`/`repeating`). `undefined`
+     * for `forever` — that one only ends if explicitly removed.
+     */
+    endsAt?: string;
+}
+/**
+ * Per-org current subscription state — denormalized cache of Stripe state.
+ * Stripe webhooks are the only mutator after initial seeding.
+ */
+export interface SubscriptionResp {
+    /** Internal id, prefix `bsub_`. */
+    id: string;
+    orgId: string;
+    planCode: PlanCode;
+    status: SubscriptionStatus;
+    /** UTC period boundaries — for Free, derived from calendar month. */
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    /** Set when user clicks "cancel" — resolves at period end. */
+    cancelAtPeriodEnd?: boolean;
+    canceledAt?: string;
+    pastDueSince?: string;
+    /** Cached for fast reads — Stripe is authoritative. */
+    stripeCustomerId?: string;
+    stripeSubscriptionId?: string;
+    stripeBasePriceId?: string;
+    stripeOveragePriceId?: string;
+    /** Cached plan snapshot — useful for FE rendering without a join. */
+    plan?: Pick<SubscriptionPlan, 'planCode' | 'displayName' | 'includedWorkflows' | 'hardLimitWorkflows' | 'overageUnitAmountCents' | 'baseAmountCents' | 'currency'>;
+    /**
+     * Active discount on this subscription — present when the user redeemed a
+     * promo code at Checkout, or when a coupon was attached customer-level.
+     * `undefined` for full-price subscriptions.
+     */
+    discount?: DiscountSummary;
+}
+export interface ListPlansResp {
+    data: SubscriptionPlan[];
+}
+export interface UsageResp {
+    orgId: string;
+    planCode: PlanCode;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    includedQuota: number;
+    includedUsed: number;
+    overageUsed: number;
+    /** Remaining included slots — `null` if plan has no hard cap. */
+    remainingIncluded: number | null;
+    /** True if next workflow create will be billed as overage. */
+    nextIsOverage: boolean;
+}
+export interface InvoiceListItem {
+    /** Stripe invoice id (`in_…`). */
+    id: string;
+    status: string;
+    amountDueCents: number;
+    amountPaidCents: number;
+    currency: string;
+    hostedInvoiceUrl?: string;
+    invoicePdfUrl?: string;
+    periodStart?: string;
+    periodEnd?: string;
+    paidAt?: string;
+    /**
+     * Invoice subtotal **before** any discount (cents). Populated whenever the
+     * invoice carries a `total_discount_amounts > 0` — used by the FE to show
+     * a "Subtotal / Discount / Total" breakdown. `undefined` on discount-free
+     * invoices (the FE just shows the single total).
+     */
+    subtotalAmountCents?: number;
+    /** Total discount applied across all line items (cents, positive number). */
+    discountAmountCents?: number;
+    /** Pre-formatted label, e.g. "20% off (LAUNCH20)". */
+    discountLabel?: string;
+}
+export interface InvoiceListResp {
+    data: InvoiceListItem[];
+    nextCursor?: string;
+}
+export interface StartCheckoutReq {
+    planCode: PlanCode;
+}
+export interface StartCheckoutResp {
+    checkoutUrl: string;
+    sessionId: string;
+}
+export interface OpenPortalResp {
+    portalUrl: string;
+}
+/**
+ * Returned with HTTP 403 when a Free org tries to create a 4th workflow.
+ * The FE intercepts this code and renders the upgrade modal directly from
+ * the response — no extra round-trip needed.
+ */
+export interface QuotaExceededErrorBody {
+    code: 'quota_exceeded';
+    message: string;
+    currentPlan: PlanCode;
+    limit: number;
+    used: number;
+    upgradeUrl: string;
+}
+export declare const QUOTA_EXCEEDED_ERROR_CODE = "quota_exceeded";
+/**
+ * Returned with HTTP 403 when an org tries to create a Live workflow but
+ * their subscription is in a terminal / pending state (canceled, incomplete,
+ * unpaid, paused, …). Distinct from `quota_exceeded` because the user
+ * remediation is different — they need to update billing or re-subscribe,
+ * not just stay under the cap.
+ */
+export interface SubscriptionInactiveErrorBody {
+    code: 'subscription_inactive';
+    message: string;
+    currentPlan: PlanCode;
+    status: SubscriptionStatus;
+    upgradeUrl: string;
+}
+export declare const SUBSCRIPTION_INACTIVE_ERROR_CODE = "subscription_inactive";
+/**
+ * Statuses that grant Live workflow access. Used both server-side (gate in
+ * `UsageMeterService.checkQuota`) and client-side (UI hides the upgrade
+ * warning when this returns true).
+ *
+ *  - `active`     — Free (always active) and Pro (paid + current)
+ *  - `trialing`   — would apply once trials are introduced (additive, no
+ *                   schema change)
+ *  - `past_due`   — Pro user with a failed payment. We deliberately keep
+ *                   access during Stripe's retry window so the user can
+ *                   fix their card without losing service. Stripe's
+ *                   Dashboard-configured retry rules eventually cancel
+ *                   the sub after retries exhaust, and the
+ *                   `customer.subscription.deleted` webhook downgrades
+ *                   the org back to Free.
+ */
+export declare function isSubscriptionActive(status: SubscriptionStatus): boolean;

package/dist/libs/signstack/base/src/lib/models/subscription.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Subscription / billing shared types.
+ *
+ * Money is always integer cents — never floats. Currency formatting happens
+ * in the FE display layer.
+ *
+ * IDs:
+ * - Internal subscription doc id is prefixed `bsub_…` (billing subscription)
+ *   to avoid colliding with Stripe's own `sub_…` ids. Stripe's id lives in
+ *   `stripeSubscriptionId`.
+ * - Internal usage-period doc id is prefixed `up_…`.
+ * - Internal usage-event doc id is prefixed `ue_…`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBSCRIPTION_INACTIVE_ERROR_CODE = exports.QUOTA_EXCEEDED_ERROR_CODE = exports.UsageBillingCategory = exports.SubscriptionStatus = exports.PlanCode = void 0;
+exports.isSubscriptionActive = isSubscriptionActive;
+var PlanCode;
+(function (PlanCode) {
+    PlanCode["Free"] = "free";
+    PlanCode["Pro"] = "pro";
+})(PlanCode || (exports.PlanCode = PlanCode = {}));
+/**
+ * 1:1 mirror of Stripe's subscription status enum. **All values are intentional**
+ * even though only a subset drives bespoke code paths — the schema's Mongoose
+ * `enum` validator rejects writes with unknown values, so every status Stripe
+ * may emit must be listed here or the corresponding webhook update crashes
+ * mid-write and the local doc drifts.
+ *
+ * Three categories (see the grouped sections below):
+ *
+ *  1. **Active states** — `isSubscriptionActive()` returns true; the org can
+ *     create Live workflows. Includes `past_due` because we honour the grace
+ *     period before locking access.
+ *
+ *  2. **Terminal states** — `applySubscriptionUpdate` flips the org back to
+ *     the Free baseline via `transitionToFree`.
+ *
+ *  3. **Pass-through states** — accepted by the schema so webhooks don't
+ *     crash, but no bespoke handler. Stripe is the system of record; if any
+ *     of these starts mattering to a feature, add the handler then.
+ *
+ * Reference: https://stripe.com/docs/api/subscriptions/object#subscription_object-status
+ */
+var SubscriptionStatus;
+(function (SubscriptionStatus) {
+    // ─── Active states — grant Live workflow access ──────────────────────────
+    SubscriptionStatus["Active"] = "active";
+    /** Pro user with a failed payment. Stripe retries on its retry schedule
+     *  (configured in the Dashboard) and auto-cancels if retries exhaust;
+     *  we keep access active during this window. */
+    SubscriptionStatus["PastDue"] = "past_due";
+    /** Reserved — we don't ship trials today, but the access gate already
+     *  treats this as active so adding trials is purely a Stripe-side change. */
+    SubscriptionStatus["Trialing"] = "trialing";
+    // ─── Terminal states — trigger transition back to Free ───────────────────
+    /** User canceled (immediate or via Customer Portal). */
+    SubscriptionStatus["Canceled"] = "canceled";
+    /** First-invoice payment never cleared within Stripe's ~23h window. */
+    SubscriptionStatus["IncompleteExpired"] = "incomplete_expired";
+    // ─── Pass-through states — accepted, no bespoke handling ─────────────────
+    /** Initial state for every Stripe-created sub before the first payment
+     *  attempt resolves — typically flips to `active` within seconds via the
+     *  follow-up `customer.subscription.updated` event. */
+    SubscriptionStatus["Incomplete"] = "incomplete";
+    /** Stripe-emitted after retries exhaust mid-cycle. We don't act on this
+     *  directly — the next `past_due → cancel` cycle (or operator action)
+     *  resolves the sub. */
+    SubscriptionStatus["Unpaid"] = "unpaid";
+    /** Customer Portal pause. We don't expose pause as a product feature, so
+     *  the doc just mirrors Stripe and the org keeps its current access until
+     *  Stripe transitions it to a real terminal state. */
+    SubscriptionStatus["Paused"] = "paused";
+})(SubscriptionStatus || (exports.SubscriptionStatus = SubscriptionStatus = {}));
+var UsageBillingCategory;
+(function (UsageBillingCategory) {
+    /** Counted against the plan's included quota. */
+    UsageBillingCategory["Included"] = "included";
+    /** Charged as overage via Stripe metered Price. */
+    UsageBillingCategory["Overage"] = "overage";
+})(UsageBillingCategory || (exports.UsageBillingCategory = UsageBillingCategory = {}));
+exports.QUOTA_EXCEEDED_ERROR_CODE = 'quota_exceeded';
+exports.SUBSCRIPTION_INACTIVE_ERROR_CODE = 'subscription_inactive';
+/**
+ * Statuses that grant Live workflow access. Used both server-side (gate in
+ * `UsageMeterService.checkQuota`) and client-side (UI hides the upgrade
+ * warning when this returns true).
+ *
+ *  - `active`     — Free (always active) and Pro (paid + current)
+ *  - `trialing`   — would apply once trials are introduced (additive, no
+ *                   schema change)
+ *  - `past_due`   — Pro user with a failed payment. We deliberately keep
+ *                   access during Stripe's retry window so the user can
+ *                   fix their card without losing service. Stripe's
+ *                   Dashboard-configured retry rules eventually cancel
+ *                   the sub after retries exhaust, and the
+ *                   `customer.subscription.deleted` webhook downgrades
+ *                   the org back to Free.
+ */
+function isSubscriptionActive(status) {
+    return (status === SubscriptionStatus.Active ||
+        status === SubscriptionStatus.Trialing ||
+        status === SubscriptionStatus.PastDue);
+}
+//# sourceMappingURL=subscription.js.map

package/dist/libs/signstack/base/src/lib/models/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../../../../../../../../../libs/signstack/base/src/lib/models/subscription.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA2TH,oDAMC;AA/TD,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,uBAAW,CAAA;AACb,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,IAAY,kBA8BX;AA9BD,WAAY,kBAAkB;IAC5B,4EAA4E;IAC5E,uCAAiB,CAAA;IACjB;;oDAEgD;IAChD,0CAAoB,CAAA;IACpB;iFAC6E;IAC7E,2CAAqB,CAAA;IAErB,4EAA4E;IAC5E,wDAAwD;IACxD,2CAAqB,CAAA;IACrB,uEAAuE;IACvE,8DAAwC,CAAA;IAExC,4EAA4E;IAC5E;;2DAEuD;IACvD,+CAAyB,CAAA;IACzB;;4BAEwB;IACxB,uCAAiB,CAAA;IACjB;;0DAEsD;IACtD,uCAAiB,CAAA;AACnB,CAAC,EA9BW,kBAAkB,kCAAlB,kBAAkB,QA8B7B;AAED,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,iDAAiD;IACjD,6CAAqB,CAAA;IACrB,mDAAmD;IACnD,2CAAmB,CAAA;AACrB,CAAC,EALW,oBAAoB,oCAApB,oBAAoB,QAK/B;AAsNY,QAAA,yBAAyB,GAAG,gBAAgB,CAAC;AAiB7C,QAAA,gCAAgC,GAAG,uBAAuB,CAAC;AAExE;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAAC,MAA0B;IAC7D,OAAO,CACL,MAAM,KAAK,kBAAkB,CAAC,MAAM;QACpC,MAAM,KAAK,kBAAkB,CAAC,QAAQ;QACtC,MAAM,KAAK,kBAAkB,CAAC,OAAO,CACtC,CAAC;AACJ,CAAC"}