@shipstatic/ship 2.3.5 → 2.4.0-beta.1

package/dist/index.d.cts

@@ -510,48 +510,64 @@ interface TokenDeleteResponse {
     readonly token: string;
 }
 /**
- * Account plan constants
+ * Every plan an account can hold — the platform's whole plan vocabulary, in
+ * one place, and nothing about what a plan is WORTH.
+ *
+ * A plan is a TIER and nothing else. Whether an account may act is a separate
+ * fact (`Account.suspended`; deletion ends the session outright), so an
+ * account keeps its tier through suspension and into deletion.
+ *
+ * - **Free** — `free`.
+ * - **Billed** — `pro`. The one plan a customer can buy; the only plan Stripe
+ *   knows about, and the only one the platform never sets by hand — it is
+ *   derived from the Stripe subscription.
+ * - **Granted** — `scale`, `sponsored`. Paid plans the operator confers by
+ *   hand; no Stripe subscription, no Checkout, no Stripe object at all.
+ *
+ * The numbers each plan confers — caps, sizes — are POLICY and are delivered
+ * by the API (`GET /plans`, `GET /account`, `GET /limits`), never published
+ * here: a price or a cap in a published package is pinned to whatever version
+ * a client installed (`CLAUDE.md`, "Validation: format vs policy").
  */
 declare const AccountPlan: {
     readonly FREE: "free";
-    readonly STANDARD: "standard";
+    readonly PRO: "pro";
+    readonly SCALE: "scale";
     readonly SPONSORED: "sponsored";
-    readonly ENTERPRISE: "enterprise";
-    readonly SUSPENDED: "suspended";
-    readonly TERMINATING: "terminating";
-    readonly TERMINATED: "terminated";
 };
 type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
- * Account usage metrics — always available regardless of billing provider.
+ * The two things an account ACCUMULATES, and therefore the two things a plan
+ * caps. One word for the count and for the ceiling: `Account.usage` and
+ * `Account.caps` are the same shape, so a surface renders "2 of 3" by
+ * dividing one by the other and can never divide by a different denominator
+ * than the 403 uses.
+ *
+ * Both are counts paid plans SELL. A platform subdomain (`x.shipstatic.com`)
+ * is not among them: the platform owns the name, it costs nothing, and no
+ * plan bounds how many an account may hold.
  *
- * This is where a caller's own totals live. Lists answer pages and carry no
- * `total` (see {@link ListOptions}); a count is an aggregate over a
- * collection, so it belongs to the summary resource that owns the
- * collection. `GET /account` is that resource for one caller, `GET
- * /admin/stats` for the platform.
+ * Every cap carries a number on every plan — never `null`, never
+ * "unlimited" — so no consumer needs an "is it bounded?" branch.
  *
- * The counted dimensions are the ones the plan caps — deployments and
- * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
- * surface can render "3 of 10" without a second request.
+ * A count is an aggregate over a collection, so it lives on the summary
+ * resource that owns the collection: `GET /account` for one caller, `GET
+ * /admin/stats` platform-wide. Lists answer pages and carry no `total` (see
+ * {@link ListOptions}).
  */
-interface AccountUsage {
-    /** Number of active custom domains (excludes paused) */
-    customDomains: number;
+interface Caps {
     /**
-     * Deployments counted against the plan's deployment cap — every row
-     * whatever its status, because that is what the cap counts, so a surface
-     * renders "3 of 10" against the denominator the 403 divides by. (`GET
-     * /deployments` lists successful ones only; that is a different question
-     * asked of a different resource.) Optional by the additive-evolution law:
-     * an API predating this field omits it.
+     * Deployments — every row whatever its status, because that is what the cap
+     * counts. (`GET /deployments` lists successful ones only; that is a
+     * different question asked of a different resource.)
      */
-    deployments?: number;
+    readonly deployments: number;
     /**
-     * Domains counted against the plan's domain cap — every domain, platform
-     * and custom alike, unlike `customDomains`. Optional for the same reason.
+     * Hostnames the customer owns — every row, paused ones included. A paused
+     * domain still occupies its slot, so deleting one is what frees capacity.
+     * A downgraded account therefore reads honestly as "3 of 0".
      */
-    domains?: number;
+    readonly customDomains: number;
 }
 /**
  * Core account object - used in both API responses and SDK
@@ -564,10 +580,22 @@ interface Account {
     readonly name: string | null;
     /** User profile picture URL, null if not set */
     readonly picture: string | null;
-    /** Account plan status */
+    /** The account's tier. */
     readonly plan: AccountPlanType;
-    /** Account usage metrics (custom domains, etc.) */
-    readonly usage: AccountUsage;
+    /**
+     * True while the operator has suspended the account: reads and deletes
+     * still work, every write is refused. The plan is unchanged underneath.
+     */
+    readonly suspended: boolean;
+    /** What the account currently holds — see {@link Caps}. */
+    readonly usage: Caps;
+    /**
+     * What the account is allowed to hold — the same three keys as
+     * {@link usage}, so the pair divides. These are the account's EFFECTIVE
+     * caps: its plan's numbers, plus whatever the operator granted it
+     * individually.
+     */
+    readonly caps: Caps;
     /** Unix timestamp (seconds) when account was created */
     readonly created: number;
     /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
@@ -581,8 +609,16 @@ interface Account {
      * when present rather than forcing a lockstep SDK release.
      */
     readonly used?: number | null;
-    /** Grace period expiration (unix seconds), null if no grace period active */
-    readonly grace: number | null;
+    /**
+     * True while the Stripe subscription's status is `past_due` and Stripe is
+     * still retrying the card. The plan is unchanged — the account keeps
+     * everything it has — so this is a banner, not a gate.
+     *
+     * A BOOLEAN rather than the status string: one fact for the console to
+     * act on. Stripe's own status word is mirrored on the account row for the
+     * operator surface.
+     */
+    readonly overdue: boolean;
 }
 /**
  * Account as returned by `GET /account` — the entity plus how the request
@@ -606,10 +642,10 @@ interface AccountGetResponse extends Account {
  * {@link DeploymentDeleteResponse} for the law.
  */
 interface AccountDeleteResponse {
-    /** The account that was marked for termination */
+    /** The account whose deletion was accepted */
     readonly account: string;
-    /** The plan the account is in while cleanup runs */
-    readonly plan: AccountPlanType;
+    /** Unix timestamp (seconds) the deletion was requested; cleanup completes it */
+    readonly deleted: number;
 }
 /**
  * Response from `PUT /account/key` — the account's single API key, minted in
@@ -627,22 +663,6 @@ interface AccountKeyResponse {
     /** The raw API key (shown once at mint, then never again) */
     readonly secret: string;
 }
-/**
- * Account-specific configuration overrides
- * Allows per-account customization of limits without changing plan
- */
-interface AccountOverrides {
-    /** Override for maximum number of domains */
-    domains?: number;
-    /** Override for maximum number of deployments */
-    deployments?: number;
-    /** Override for maximum individual file size in bytes */
-    fileSize?: number;
-    /** Override for maximum number of files per deployment */
-    filesCount?: number;
-    /** Override for maximum total deployment size in bytes */
-    totalSize?: number;
-}
 /**
  * Every path the public API answers on, declared once.
  *
@@ -694,6 +714,7 @@ declare const API_PATHS: {
     readonly ACTIVITIES: "/activities";
     readonly LABELS: "/labels";
     readonly LIMITS: "/limits";
+    readonly PLANS: "/plans";
     readonly PING: "/ping";
     readonly SETUP: "/setup";
     readonly SPA_CHECK: "/spa-check";
@@ -1726,54 +1747,85 @@ interface TokenResource {
     delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
- * Billing status response from GET /billing/status
+ * How often a subscription renews. The platform sells one plan at two
+ * intervals, so this is the only thing a buyer chooses at checkout.
  *
- * Note: The user's `plan` comes from Account, not here.
- * This endpoint only returns billing-specific data (usage, portal, etc.)
+ * It never branches business logic — monthly and yearly confer identical
+ * caps. It exists to be displayed and to pick a price at checkout.
+ */
+type BillingInterval = 'month' | 'year';
+/**
+ * One row of the plan menu, answered by `GET /plans`.
  *
- * If `billing` is null, the user has no active billing.
+ * **Vocabulary here, values from the server.** The shape is a wire contract
+ * every surface agrees on; the numbers in it are policy the API owns and may
+ * change on a deploy (`CLAUDE.md`, "Validation: format vs policy"). That is
+ * why the public site and the console both READ this endpoint instead of
+ * carrying their own copy of the price list — a hand-copied plan table was
+ * the platform's longest-lived restatement.
  */
-interface BillingStatus {
-    /** Creem billing ID, or null if no active billing */
-    billing: string | null;
-    /** Number of billing units (1 unit = 1 custom domain), null if no billing */
-    units: number | null;
-    /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
-    status: string | null;
-    /** Link to Creem customer portal for billing management, null if unavailable */
-    portal: string | null;
+interface Plan {
+    /** Which plan this row describes. */
+    readonly plan: AccountPlanType;
+    /** Display name, as the marketing site and the console should print it. */
+    readonly name: string;
+    /**
+     * What it costs. A union rather than a nullable number, so "free" and
+     * "talk to us" are two different answers instead of two readings of the
+     * same `null`. Amounts are integer CENTS in USD, as the API's plan table
+     * states them and as Stripe's Prices are provisioned from it — the wire
+     * never carries a formatted price, because formatting is the reader's job.
+     */
+    readonly price: 'free' | 'contact' | {
+        readonly month: number;
+        readonly year: number;
+    };
+    /**
+     * The caps this plan publishes, or `null` where the menu deliberately says
+     * nothing (a plan sold by conversation publishes no numbers).
+     */
+    readonly caps: Caps | null;
 }
 /**
- * Acknowledgement of `POST /billing/cancel`.
+ * Response for `GET /plans` — the whole public menu, in display order.
  *
- * Cancelling leaves no billing entity to return, so it answers with the
- * account and the one field of the account the call changed — the plan it
- * landed on. See {@link DeploymentDeleteResponse} for the law.
+ * Public, unauthenticated and cacheable: it describes the product, not the
+ * caller. Plans the operator only ever grants by hand are absent — a menu
+ * lists what can be ordered.
  *
- * This read `{ success: true, message: 'Subscription canceled successfully…' }`
- * until 2026-07-29, an anonymous shape that `web/my` redeclared inline and
- * whose prose no surface ever displayed: both callers await the promise and
- * discard the body, then compose their own toast. The message was written,
- * serialized, and thrown away on every cancellation.
+ * An aggregate rather than a list: the registry is the bound, so there is no
+ * cursor (the {@link LabelsResponse} shape).
  */
-interface BillingCancelResponse {
-    /** The account whose subscription was cancelled */
-    readonly account: string;
-    /** The plan the account now holds — `free` on a successful cancellation */
-    readonly plan: AccountPlanType;
+interface PlansResponse {
+    readonly plans: readonly Plan[];
 }
 /**
- * Checkout session response from POST /billing/checkout
+ * A page Stripe hosts — a Checkout Session or a Customer Portal session — the
+ * answer of `POST /billing/checkout` and `POST /billing/portal` alike.
+ *
+ * One shape for both because both say the same thing: the platform is not
+ * where this happens, go here. There is nothing else to return — the
+ * outcome arrives later, as a Stripe webhook.
  */
-interface CheckoutSession {
-    /** URL to redirect user to Creem checkout page */
-    url: string;
+interface StripeSession {
+    /** Absolute URL to redirect the browser to. Single use, short-lived. */
+    readonly url: string;
+}
+/**
+ * The answer of `POST /billing/sync` — the account's plan after the platform
+ * re-read Stripe. The success page calls it once on arrival from Checkout,
+ * instead of polling for the webhook: a card payment is settled by the time
+ * Stripe redirects, so one read makes the plan current before anything
+ * renders.
+ */
+interface BillingSyncResponse {
+    readonly plan: AccountPlanType;
 }
 /**
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
  */
-type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'deployment.open' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
+type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'deployment.open' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.suspended.update' | 'admin.account.ref.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.impersonate';
 /**
  * Activity events visible to users in the dashboard
  */
@@ -2956,6 +3008,6 @@ declare class Ship extends Ship$1 {
 }
 
 declare namespace Ship {
-  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountOverrides, AccountPlan, AccountPlanType, AccountResource, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingCancelResponse, BillingStatus, CALLER, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, PlatformLimits, RequestResult, ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };
+  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountResource, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingInterval, BillingSyncResponse, CALLER, Caps, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, Plan, PlansResponse, PlatformLimits, RequestResult, ResourceContext, SHIP_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, StripeSession, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validatePassword, validateToken, validateTtl };
 }
 export = Ship;