@w6w/sdk 0.5.0 → 0.9.8

package/dist/src/console/commerce.d.ts

@@ -0,0 +1,428 @@
+/**
+ * `client.console.commerce.*` — the checked-in plan catalog, and the caller's
+ * own resolved subscription.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and this task's contract. `@w6w/sdk`'s instance-state mechanism pin still
+ * applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **The public/guarded split is per METHOD, not per file, exactly like
+ * `console.auth`.** `plans()` is registered above the auth guard
+ * (`packages/server/packages/api/commerce/plans-route.ts`'s own doc comment:
+ * "PUBLIC: registered above the auth guard by `commerce/edge.ts`") and reads
+ * nothing from the request, so it passes `requireAuth: false` and the
+ * transport never even attempts to attach a bearer. `subscription()` derives
+ * the account from the JWT (`subscription-route.ts`'s own doc comment:
+ * "GUARDED") and uses the default, unconditional `requireAuth`.
+ *
+ * **Both responses carry an envelope key — unlike `console.dashboard`.** The
+ * server answers `c.json({ plans: … })` (`plans-route.ts`) and
+ * `c.json({ subscription: { plan, status, canUpgrade } })`
+ * (`subscription-route.ts`), so both methods here call this package's
+ * `unwrap()` helper rather than returning `res.body` verbatim.
+ *
+ * **`allowance()` (W-12) is the caller's own EFFECTIVE allowance, credits and
+ * current-month usage** — `GET /commerce/allowance`, AUTHENTICATED like
+ * `subscription()`, unwrapped from the `allowance` envelope. `credits.balance`
+ * is SIGNED and never clamped: negative means over by that many executions.
+ * Egress-pinned: never `reason`, `setBy`, `grantedBy`, `grants`, `override` or
+ * a `/stripe/i` key at any depth — those are operator/control-internal, not
+ * account-facing. Any non-200 (including a 424 `control_unavailable` or an old
+ * control's 404 `text/plain`) is treated as "unavailable" by callers.
+ *
+ * @module
+ */
+import type { HttpResponse, RequestOptions } from "../http.ts";
+/**
+ * The slice of `W6WClient` this namespace needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so the namespace stays
+ * independently constructible in a test and this module never imports the
+ * client back — mirrors `ReliabilityHost` in `./reliability.ts`.
+ */
+export interface CommerceHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/** A quota on some countable resource, as `PlanQuotas`' fields each carry one. */
+export type Quota = {
+    readonly kind: "unlimited";
+} | {
+    readonly kind: "custom";
+} | {
+    readonly kind: "capped";
+    readonly included: number;
+} | {
+    readonly kind: "metered";
+    readonly included: number;
+    readonly per: number;
+    readonly unitAmount: number;
+};
+/** The monitor-cadence limit: how often a health check may run. */
+export interface MonitorLimit {
+    readonly quota: Quota;
+    readonly minCadenceMinutes: number | "custom";
+}
+/** How long check-run bodies and metadata are retained. */
+export interface RetentionLimit {
+    readonly bodiesDays: number | "custom";
+    readonly metadataDays: number | "custom";
+}
+/** Every countable resource a plan bounds. */
+export interface PlanQuotas {
+    readonly runs: Quota;
+    /** Concurrent runs — the server's own `parallelExecutions` dimension. */
+    readonly parallelExecutions: Quota;
+    readonly monitors: MonitorLimit;
+    readonly retention: RetentionLimit;
+    readonly projects: Quota;
+    readonly seats: Quota;
+}
+/** Whether a plan may self-host, and the annual surcharge if so. */
+export interface SelfHostLicence {
+    readonly available: boolean;
+    readonly annualSurcharge: number | null;
+}
+/** The feature toggles a plan grants. */
+export interface PlanCapabilities {
+    readonly catalogImport: boolean;
+    readonly privateRegistry: boolean;
+    readonly implSwapAndConfig: boolean;
+    readonly versionPinsAndBlocks: boolean;
+    readonly egressCaptureExport: boolean;
+    readonly embeddedWhiteLabel: boolean;
+    readonly sso: boolean;
+    readonly auditLog: boolean;
+    readonly rbac: boolean;
+    readonly dataResidency: boolean;
+    readonly selfHostLicence: SelfHostLicence;
+}
+/** A plan's support tier. */
+export type SupportLevel = "community" | "email" | "email-1-business-day" | "sla-named-contact-dpa";
+/** Everything a plan bounds or grants: quotas, capabilities, and support level. */
+export interface PlanLimits {
+    readonly quotas: PlanQuotas;
+    readonly capabilities: PlanCapabilities;
+    readonly support: SupportLevel;
+}
+/** Which cadence a {@link PlanPricePoint} recurs on. */
+export type BillingInterval = "month" | "year";
+/**
+ * One published price point. `unitAmount` is integer cents charged per ONE
+ * `interval` — an annual point's amount is what is charged once a year, NOT a
+ * monthly equivalent, so `$500/yr` arrives as `50000` beside a monthly `5000`.
+ *
+ * Both figures are authored server-side and neither is derived from the other.
+ * A client may compute a saving percentage from the pair for DISPLAY; nothing
+ * should reconstruct a price from one and a rate.
+ */
+export interface PlanPricePoint {
+    readonly unitAmount: number;
+    readonly interval: BillingInterval;
+}
+/**
+ * The `price` arm of a plan — exactly what `plans-route.ts`'s `toWirePlan`
+ * allowlists. Never `productId`/`lookupKey`/`metered`: the rail (Stripe) is an
+ * implementation detail and the product id / lookup key are server
+ * configuration, not published pricing.
+ *
+ * Only the `billable` arm carries price data. `none` (Free) and
+ * `contact-sales` (Enterprise) carry no amount, no interval and no currency.
+ */
+export type PlanPrice = {
+    readonly kind: "none";
+} | {
+    readonly kind: "contact-sales";
+} | {
+    readonly kind: "billable";
+    readonly currency: "usd";
+    readonly monthly: PlanPricePoint;
+    /** `null` when the plan is offered monthly only. */
+    readonly annual: PlanPricePoint | null;
+};
+/** One entry in the checked-in plan catalog, as `GET /commerce/plans` returns it. */
+export interface Plan {
+    /** `"free" | "team" | "business" | "enterprise"` today, typed `string` on the wire. */
+    readonly key: string;
+    readonly name: string;
+    readonly description: string;
+    readonly rank: number;
+    readonly retired: boolean;
+    /** Whether an upgrade INTO this plan must go through sales rather than self-serve checkout — true only for `enterprise` today. Optional/forward-compatible on this SDK copy: absent means false. */
+    readonly topTier?: boolean;
+    readonly features: readonly string[];
+    readonly limits: PlanLimits;
+    readonly price: PlanPrice;
+}
+/**
+ * The caller's resolved subscription, as `GET /commerce/subscription`
+ * returns it. `status` is the SUBSCRIPTION's status, never a vendor/HTTP
+ * status; `plan` is a catalog key, not a display name. Named
+ * `CommerceSubscription` rather than the bare `Subscription` — that name is
+ * already taken by `console/subscriptions.ts` (webhook-trigger
+ * subscriptions, an unrelated domain despite the shared word).
+ */
+export interface CommerceSubscription {
+    readonly plan: string;
+    readonly status: string;
+    readonly canUpgrade: boolean;
+}
+/**
+ * One entry in the caller's own invoice history, as `GET /commerce/invoices`
+ * returns it. `id` is OUR id (`commerce.invoice.id`), never a Stripe id;
+ * `status` is Stripe's own vocabulary, verbatim. Newest first, ordered
+ * server-side by `createdAt` — not `issuedAt`, which is nullable and
+ * therefore not a total order for a hand-entered SLA row.
+ */
+export interface Invoice {
+    readonly id: string;
+    readonly number: string | null;
+    readonly status: string;
+    readonly amountDueCents: number;
+    readonly amountPaidCents: number;
+    readonly currency: string;
+    readonly hostedInvoiceUrl: string | null;
+    readonly issuedAt: string | null;
+    readonly dueAt: string | null;
+    readonly createdAt: string;
+}
+/** Which cadence a checkout is for — mirrors `PlanPrice`'s own `BillingInterval`. */
+export type CheckoutInterval = "month" | "year";
+/** `client.console.commerce.checkout()`'s input. */
+export interface CheckoutInput {
+    readonly planKey: string;
+    readonly interval: CheckoutInterval;
+}
+/**
+ * `POST /commerce/checkout`'s response — a hosted Stripe payment page URL,
+ * and NOTHING else: never a raw Checkout Session id, price id or product id
+ * (the server's own D-3 rule — no Stripe id crosses the wire in either
+ * direction).
+ */
+export interface CheckoutResult {
+    readonly url: string;
+}
+/** `client.console.commerce.confirmCheckout()`'s input — the `checkout_session_id` the browser was redirected back with. */
+export interface ConfirmCheckoutInput {
+    readonly sessionId: string;
+}
+/**
+ * `POST /commerce/contact-sales`'s input. `account` is never sent by the
+ * caller — the server stamps it from the bearer's own principal.
+ */
+export interface ContactSalesInput {
+    readonly name: string;
+    readonly email: string;
+    readonly company?: string;
+    readonly message: string;
+}
+/** `POST /commerce/contact-sales`'s response. */
+export interface ContactSalesResult {
+    readonly id: string;
+}
+/** `client.console.commerce.previewSubscriptionChange()` / `.changeSubscription()`'s shared input. */
+export interface ChangeSubscriptionInput {
+    readonly planKey: string;
+    readonly interval: CheckoutInterval;
+}
+/**
+ * `POST /commerce/subscription/preview`'s response — what Stripe would
+ * charge (positive) or credit (negative) TODAY for this change, in integer
+ * cents. Never a raw Stripe invoice object; never rounded/clamped — a large
+ * negative value here is a large credit, expected when moving off a
+ * part-used ANNUAL plan (Stripe carries the excess forward to future
+ * invoices automatically — see the server's `SubscriptionChangeService`).
+ */
+export interface SubscriptionChangePreview {
+    readonly amountDueCents: number;
+    readonly currency: string;
+}
+/**
+ * `POST /commerce/subscription/change`'s response. `subscription` here is
+ * NARROWER than {@link CommerceSubscription} — no `canUpgrade` — the server
+ * has no reason to recompute it against the wire's own move; re-fetch
+ * `subscription()` if the caller needs it refreshed.
+ */
+export interface SubscriptionChangeResult {
+    readonly subscription: {
+        readonly plan: string;
+        readonly status: string;
+    };
+    readonly charge: SubscriptionChangePreview;
+}
+/**
+ * A metered/countable dimension's value as `GET /commerce/allowance` states
+ * it — a real number, or one of the catalog's two non-numeric arms. Mirrors
+ * the vocabulary of `PlanQuotas`' own `Quota.kind` but is deliberately flat
+ * (W-12): this endpoint reports one EFFECTIVE number per dimension, never a
+ * `{kind, included}` shape.
+ */
+export type AllowanceValue = number | "unlimited" | "custom";
+/**
+ * The caller's own accrued extra-usage balance (HITL-1 (b) — "extra
+ * executions", not a Stripe balance credit and not a comped plan). `balance`
+ * is SIGNED and never clamped: `granted - consumed`, so a negative value means
+ * the account is over by that many executions.
+ */
+export interface AccountAllowanceCredits {
+    readonly granted: number;
+    readonly consumed: number;
+    readonly balance: number;
+}
+/**
+ * The account's effective per-dimension limits for the current month — the
+ * override where the operator set one, the catalog value otherwise. Same 8
+ * dimensions `PlanQuotas`/`PlanLimits` bound, flattened to one
+ * {@link AllowanceValue} each; no `override`/`metered` field travels on this
+ * wire (that provenance is operator/control-internal, never account-facing —
+ * see this module's egress pin).
+ */
+export interface AccountAllowanceLimits {
+    readonly runs: AllowanceValue;
+    readonly parallelExecutions: AllowanceValue;
+    readonly monitors: AllowanceValue;
+    readonly monitorMinCadenceMinutes: AllowanceValue;
+    readonly retentionBodiesDays: AllowanceValue;
+    readonly retentionMetadataDays: AllowanceValue;
+    readonly projects: AllowanceValue;
+    readonly seats: AllowanceValue;
+}
+/**
+ * `GET /commerce/allowance`'s response (W-12) — the caller's own effective
+ * allowance, credits and current-month usage. `month` is the reporting month
+ * (`"YYYY-MM"`); `executions` is actual usage so far; `included` is the
+ * effective monthly allowance; `overage` is executions beyond `included`,
+ * reported but not consumed by this SDK's own callers (no enforcement,
+ * HITL-3).
+ */
+export interface AccountAllowance {
+    readonly month: string;
+    readonly executions: number;
+    readonly included: AllowanceValue;
+    readonly overage: number;
+    readonly credits: AccountAllowanceCredits;
+    readonly limits: AccountAllowanceLimits;
+    readonly customTerms: boolean;
+}
+/**
+ * The `console.commerce` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const plans = await client.console.commerce.plans();
+ * const { canUpgrade } = await client.console.commerce.subscription();
+ * ```
+ */
+export declare class CommerceApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: CommerceHost);
+    /**
+     * Fetch the checked-in plan catalog.
+     *
+     * PUBLIC — sends no bearer, even on a client that already holds one
+     * (`requireAuth: false`): the route reads nothing from the request and its
+     * output is byte-identical for every caller.
+     *
+     * @returns The catalog, unwrapped from the `plans` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    plans(): Promise<Plan[]>;
+    /**
+     * Fetch the caller's own resolved subscription.
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The subscription, unwrapped from the `subscription` envelope.
+     * @throws {ApiError} On any non-2xx, e.g. `409` when the resolved plan key
+     *   is not in the catalog or is ambiguous.
+     */
+    subscription(): Promise<CommerceSubscription>;
+    /**
+     * Fetch the caller's own invoice history, newest first.
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The invoices, unwrapped from the `invoices` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    invoices(): Promise<Invoice[]>;
+    /**
+     * Open a live Stripe Checkout Session for a billable plan/interval.
+     * AUTHENTICATED — the account is resolved server-side from the bearer.
+     *
+     * @returns The hosted payment page URL. Redirect the browser to it
+     *   (`window.location.href = url`); do not fetch it.
+     * @throws {ApiError} `409 plan_not_billable` for a `contact-sales`/`none`
+     *   plan or an interval the plan doesn't offer; `409 price_not_synced` if
+     *   the catalog says billable but Stripe has no matching active price yet;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    checkout(input: CheckoutInput): Promise<CheckoutResult>;
+    /**
+     * Confirm a Checkout Session on return from Stripe (the
+     * `checkout_session_id` query param `checkout()`'s success URL carries
+     * back). Verified against Stripe itself, never trusted from the URL alone
+     * — see the server's `CheckoutService` for what this deliberately does not
+     * cover (no webhook yet: a session completed after the tab closed is
+     * invisible to it).
+     *
+     * @returns The confirmed subscription.
+     * @throws {ApiError} `404 checkout_session_not_found`; `403
+     *   checkout_session_mismatch` if the session belongs to a different
+     *   account; `409 checkout_not_paid` if payment hasn't completed yet.
+     */
+    confirmCheckout(input: ConfirmCheckoutInput): Promise<CommerceSubscription>;
+    /**
+     * Submit an Enterprise "contact sales" lead. AUTHENTICATED — captured
+     * durably server-side regardless of whether outbound mail is configured
+     * (see the server's `ContactSalesService`).
+     */
+    contactSales(input: ContactSalesInput): Promise<ContactSalesResult>;
+    /**
+     * Preview what moving the CALLER'S OWN existing subscription to a
+     * different plan/interval would charge or credit TODAY, without applying
+     * anything. AUTHENTICATED.
+     *
+     * @throws {ApiError} `409 no_active_subscription` if the account has no
+     *   active Stripe subscription to change — use {@link checkout} instead;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    previewSubscriptionChange(input: ChangeSubscriptionInput): Promise<SubscriptionChangePreview>;
+    /**
+     * Apply the change {@link previewSubscriptionChange} previewed — moves the
+     * caller's existing Stripe subscription to the new plan/interval with
+     * proration, and charges/credits the net difference immediately.
+     * AUTHENTICATED.
+     *
+     * @throws {ApiError} `409 no_active_subscription` if the account has no
+     *   active Stripe subscription to change — use {@link checkout} instead;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    changeSubscription(input: ChangeSubscriptionInput): Promise<SubscriptionChangeResult>;
+    /**
+     * Fetch the caller's own effective allowance, credits and current-month
+     * usage (W-12).
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The allowance, unwrapped from the `allowance` envelope.
+     * @throws {ApiError} On any non-2xx, including `424 control_unavailable`
+     *   when the host cannot reach control — callers should treat ANY non-200
+     *   here as "unavailable", not just this one code.
+     */
+    allowance(): Promise<AccountAllowance>;
+}
+//# sourceMappingURL=commerce.d.ts.map

package/dist/src/console/commerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce.d.ts","sourceRoot":"","sources":["../../../src/console/commerce.ts"],"names":[],"mappings":"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"}

package/dist/src/console/commerce.js

@@ -0,0 +1,220 @@
+/**
+ * `client.console.commerce.*` — the checked-in plan catalog, and the caller's
+ * own resolved subscription.
+ *
+ * **Studio-internal, not the published partner contract.** This namespace
+ * lives under the `console` subpath export (`@w6w/sdk/console`), excluded from
+ * `endpoints.json` and from the root barrel (`mod.ts`) — see `docs/console.md`
+ * and this task's contract. `@w6w/sdk`'s instance-state mechanism pin still
+ * applies here exactly as it does to every other namespace
+ * (`docs/implementation.md` §MECHANISM PIN — instance state, never globals):
+ * this class holds no state of its own beyond the injected host, so two
+ * clients in one process never share a credential.
+ *
+ * **The public/guarded split is per METHOD, not per file, exactly like
+ * `console.auth`.** `plans()` is registered above the auth guard
+ * (`packages/server/packages/api/commerce/plans-route.ts`'s own doc comment:
+ * "PUBLIC: registered above the auth guard by `commerce/edge.ts`") and reads
+ * nothing from the request, so it passes `requireAuth: false` and the
+ * transport never even attempts to attach a bearer. `subscription()` derives
+ * the account from the JWT (`subscription-route.ts`'s own doc comment:
+ * "GUARDED") and uses the default, unconditional `requireAuth`.
+ *
+ * **Both responses carry an envelope key — unlike `console.dashboard`.** The
+ * server answers `c.json({ plans: … })` (`plans-route.ts`) and
+ * `c.json({ subscription: { plan, status, canUpgrade } })`
+ * (`subscription-route.ts`), so both methods here call this package's
+ * `unwrap()` helper rather than returning `res.body` verbatim.
+ *
+ * **`allowance()` (W-12) is the caller's own EFFECTIVE allowance, credits and
+ * current-month usage** — `GET /commerce/allowance`, AUTHENTICATED like
+ * `subscription()`, unwrapped from the `allowance` envelope. `credits.balance`
+ * is SIGNED and never clamped: negative means over by that many executions.
+ * Egress-pinned: never `reason`, `setBy`, `grantedBy`, `grants`, `override` or
+ * a `/stripe/i` key at any depth — those are operator/control-internal, not
+ * account-facing. Any non-200 (including a 424 `control_unavailable` or an old
+ * control's 404 `text/plain`) is treated as "unavailable" by callers.
+ *
+ * @module
+ */
+import { unwrap } from "../types.js";
+/**
+ * The `console.commerce` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const plans = await client.console.commerce.plans();
+ * const { canUpgrade } = await client.console.commerce.subscription();
+ * ```
+ */
+export class CommerceApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * Fetch the checked-in plan catalog.
+     *
+     * PUBLIC — sends no bearer, even on a client that already holds one
+     * (`requireAuth: false`): the route reads nothing from the request and its
+     * output is byte-identical for every caller.
+     *
+     * @returns The catalog, unwrapped from the `plans` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async plans() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/commerce/plans",
+            requireAuth: false,
+        });
+        return unwrap(res, "plans");
+    }
+    /**
+     * Fetch the caller's own resolved subscription.
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The subscription, unwrapped from the `subscription` envelope.
+     * @throws {ApiError} On any non-2xx, e.g. `409` when the resolved plan key
+     *   is not in the catalog or is ambiguous.
+     */
+    async subscription() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/commerce/subscription",
+        });
+        return unwrap(res, "subscription");
+    }
+    /**
+     * Fetch the caller's own invoice history, newest first.
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The invoices, unwrapped from the `invoices` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async invoices() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/commerce/invoices",
+        });
+        return unwrap(res, "invoices");
+    }
+    /**
+     * Open a live Stripe Checkout Session for a billable plan/interval.
+     * AUTHENTICATED — the account is resolved server-side from the bearer.
+     *
+     * @returns The hosted payment page URL. Redirect the browser to it
+     *   (`window.location.href = url`); do not fetch it.
+     * @throws {ApiError} `409 plan_not_billable` for a `contact-sales`/`none`
+     *   plan or an interval the plan doesn't offer; `409 price_not_synced` if
+     *   the catalog says billable but Stripe has no matching active price yet;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    async checkout(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/commerce/checkout",
+            body: input,
+        });
+        return unwrap(res, "checkout");
+    }
+    /**
+     * Confirm a Checkout Session on return from Stripe (the
+     * `checkout_session_id` query param `checkout()`'s success URL carries
+     * back). Verified against Stripe itself, never trusted from the URL alone
+     * — see the server's `CheckoutService` for what this deliberately does not
+     * cover (no webhook yet: a session completed after the tab closed is
+     * invisible to it).
+     *
+     * @returns The confirmed subscription.
+     * @throws {ApiError} `404 checkout_session_not_found`; `403
+     *   checkout_session_mismatch` if the session belongs to a different
+     *   account; `409 checkout_not_paid` if payment hasn't completed yet.
+     */
+    async confirmCheckout(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/commerce/checkout/confirm",
+            body: { sessionId: input.sessionId },
+        });
+        return unwrap(res, "subscription");
+    }
+    /**
+     * Submit an Enterprise "contact sales" lead. AUTHENTICATED — captured
+     * durably server-side regardless of whether outbound mail is configured
+     * (see the server's `ContactSalesService`).
+     */
+    async contactSales(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/commerce/contact-sales",
+            body: input,
+        });
+        return unwrap(res, "lead");
+    }
+    /**
+     * Preview what moving the CALLER'S OWN existing subscription to a
+     * different plan/interval would charge or credit TODAY, without applying
+     * anything. AUTHENTICATED.
+     *
+     * @throws {ApiError} `409 no_active_subscription` if the account has no
+     *   active Stripe subscription to change — use {@link checkout} instead;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    async previewSubscriptionChange(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/commerce/subscription/preview",
+            body: input,
+        });
+        return unwrap(res, "preview");
+    }
+    /**
+     * Apply the change {@link previewSubscriptionChange} previewed — moves the
+     * caller's existing Stripe subscription to the new plan/interval with
+     * proration, and charges/credits the net difference immediately.
+     * AUTHENTICATED.
+     *
+     * @throws {ApiError} `409 no_active_subscription` if the account has no
+     *   active Stripe subscription to change — use {@link checkout} instead;
+     *   `409 plan_not_self_serve` if the account's CURRENT plan is a top-tier
+     *   plan — an upgrade off it goes through sales, not self-serve checkout.
+     */
+    async changeSubscription(input) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/commerce/subscription/change",
+            body: input,
+        });
+        return res.body;
+    }
+    /**
+     * Fetch the caller's own effective allowance, credits and current-month
+     * usage (W-12).
+     *
+     * AUTHENTICATED — the default `requireAuth` applies: the account is
+     * derived server-side from the principal.
+     *
+     * @returns The allowance, unwrapped from the `allowance` envelope.
+     * @throws {ApiError} On any non-2xx, including `424 control_unavailable`
+     *   when the host cannot reach control — callers should treat ANY non-200
+     *   here as "unavailable", not just this one code.
+     */
+    async allowance() {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/commerce/allowance",
+        });
+        return unwrap(res, "allowance");
+    }
+}
+//# sourceMappingURL=commerce.js.map

package/dist/src/console/commerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commerce.js","sourceRoot":"","sources":["../../../src/console/commerce.ts"],"names":[],"mappings":"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"}

package/dist/src/console/dashboard.d.ts

@@ -72,6 +72,14 @@ export interface DashboardStats {
         summary: string | null;
         occurredAt: string;
         workflowId: string | null;
+        /** The Function's `fn_…` id; non-null only for `kind: "function"` rows. */
+        functionId: string | null;
+        /** Wall-clock duration in milliseconds; `null` when unknown. */
+        durationMs: number | null;
+        /** The owning project id; `null` when none. */
+        project: string | null;
+        /** The step's id within its workflow; non-null only on `kind: "workflow_step"` rows. */
+        stepId: string | null;
     }>;
 }
 /**