@shipstatic/ship 3.4.0-beta.1 → 3.4.0-beta.10

package/dist/index.d.cts

@@ -724,7 +724,7 @@ type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
  * than the 403 uses.
  *
  * All three are counts plans SELL, and every plan publishes a number for each.
- * A platform subdomain (`my-app.shipstatic.com`) is among them: the namespace
+ * A platform domain (`my-app.shipstatic.com`) is among them: the namespace
  * is the platform's, so every plan bounds how many names one account may take
  * from it — which is not the address every deployment gets by construction
  * (`happy-cat-abc1234.shipstatic.com`), one per deployment and bounded by
@@ -734,8 +734,9 @@ type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
  * "unlimited" — so no consumer needs an "is it bounded?" branch. A cap of `0`
  * means the plan does not have the feature at all; a cap of `N` bounds
  * creation, and what an account already holds above a cap stays until a plan
- * TRANSITION fits it (excess paused, newest first — a domain is the only kind
- * that pauses).
+ * TRANSITION fits it: excess domains are paused, newest first, and members
+ * are paused together while the account holds more than its cap. Deployments
+ * never pause; above their cap they only block creation.
  *
  * 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
@@ -1266,11 +1267,12 @@ interface ErrorResponse {
 /**
  * `details` of an `ErrorType.Build` error: the evidence behind the verdict.
  *
- * The one `details` shape this file names, because it is the one a HUMAN
- * surface renders rather than a machine reads. The sentence in `message`
- * says what went wrong; the log is how the person fixing the project sees
- * where. A surface that builds shows both, the log as a block rather than
- * as prose.
+ * Named, like {@link PlanChangeRefusalDetails}, because a surface reads it:
+ * `ErrorResponse.details` stays `unknown`, and a shape a client narrows to is
+ * owned here rather than restated at its read site. The sentence in
+ * `message` says what went wrong; the log is how the person fixing the
+ * project sees where. A surface that builds shows both, the log as a block
+ * rather than as prose.
  */
 interface BuildFailureDetails {
     /**
@@ -1476,7 +1478,27 @@ interface PlatformLimits {
      * retire with it (tracked in root `backlog.md`).
      */
     readonly blockedExtensions?: readonly string[];
+    /**
+     * The way forward past each limit, in the API's own words, for the account
+     * that asked: `"Upgrade to Pro for more."` where a sold plan allows more,
+     * `"Please contact support if you need more."` where none does. The API
+     * writes it with the same function its own refusals use, so a client that
+     * refuses a file before uploading it appends this sentence to its refusal
+     * verbatim and says exactly what the server would have said. Which plans
+     * exist, which are sold and what an account's grant raises are the server's
+     * to know; a client never learns a plan name from this field, only a
+     * sentence. An anonymous caller is answered the free plan's sentence, as it
+     * is the free plan's numbers.
+     *
+     * **Optional, and the absence is load-bearing**, as `blockedExtensions`
+     * above: an API deployed before this field existed sends nothing, and a
+     * client then appends nothing. It hardens to required at the entity's next
+     * natural break, with the blocklist.
+     */
+    readonly suggestions?: Readonly<Record<PlatformLimitKey, string>>;
 }
+/** The three request limits, named as `PlatformLimits` names them. */
+type PlatformLimitKey = 'maxFileSize' | 'maxFilesCount' | 'maxTotalSize';
 /**
  * Whether a file is one the platform refuses to host.
  *
@@ -2014,10 +2036,12 @@ interface StaticFile {
  * console: under `/<account>/` and at the root.
  *
  * `owner` marks a section that means the person's OWN account: a bare path
- * into it opens the person's own account rather than the one entered last,
- * since a pricing link's `/upgrade/pro` and the published API-key link speak
- * about the reader's plan and key. Modals inside a section carry their own
- * owner rule in the console; this flag is the section's alone.
+ * into it opens the person's own account rather than the one entered last.
+ * A pricing link's `/upgrade/pro` and the published API-key link speak about
+ * the reader's plan and key, and `/success` is where a purchase lands: only
+ * an owner buys, and a person owns exactly one account. Modals inside a
+ * section carry their own owner rule in the console; this flag is the
+ * section's alone.
  */
 declare const SECTIONS: {
     readonly new: {
@@ -2036,7 +2060,7 @@ declare const SECTIONS: {
         readonly owner: true;
     };
     readonly success: {
-        readonly owner: false;
+        readonly owner: true;
     };
     readonly 'api-key': {
         readonly owner: true;
@@ -2484,11 +2508,29 @@ interface PlansResponse {
  * consent), and a billed account moving down gets a Stripe Subscription
  * Schedule that applies the change at period end. The answer says which
  * happened ({@link PlanChangeResponse}).
+ *
+ * A move down a tier is booked only by an account that fits it: until it
+ * does, the door refuses (400) with a sentence naming what to remove, and
+ * the same counts as {@link PlanChangeRefusalDetails}.
  */
 interface PlanChangeRequest {
     readonly plan: AccountPlanType;
     readonly interval: BillingInterval;
 }
+/**
+ * `details` of the change door's refusal of a move down a tier the account
+ * does not fit: the account holds more members, custom domains or platform
+ * domains than the destination allows.
+ *
+ * `excess` counts what to REMOVE before asking again, per kind, keyed like
+ * {@link Caps}; only the kinds over the destination's caps appear. The
+ * door's `message` names the same counts in a sentence, and that sentence is
+ * what a surface shows; the counts are for a client that acts on the
+ * refusal.
+ */
+interface PlanChangeRefusalDetails {
+    readonly excess: Partial<Caps>;
+}
 /**
  * The pending plan change — a Stripe Subscription Schedule, mirrored onto the
  * account. `at` is when it applies (the current period's end, Unix seconds).
@@ -2755,7 +2797,7 @@ interface UploadedFile {
  */
 declare function isPlatformDomain(domain: string, platformDomain: string): boolean;
 /**
- * Check if a domain is a custom domain (not a platform subdomain).
+ * Check if a domain is a custom domain (not a platform domain).
  * Custom domains are billable and require DNS verification.
  *
  * @example isCustomDomain("example.com", "shipstatic.com") → true
@@ -2901,8 +2943,11 @@ declare function validatePassword(value: unknown): string | undefined;
 interface DeploymentOptions extends DeploymentUploadOptions {
     /**
      * An AbortSignal to allow cancellation of the deploy operation. The one
-     * cancellation mechanism — abort the signal and the request rejects with
-     * a typed `Cancelled` error. Request timeouts are a client concern
+     * cancellation mechanism: it reaches every request the deploy makes (the
+     * limits it validates against, the SPA question and the upload itself),
+     * and aborting it rejects the deploy with a typed `Cancelled` error
+     * wherever it stands. A deploy the server had already committed stays
+     * committed. Request timeouts are a client concern
      * (`ShipClientOptions.timeout`), not a per-deploy one.
      */
     signal?: AbortSignal;
@@ -3366,17 +3411,9 @@ declare abstract class Ship$1 {
     readonly tokens: TokenResource;
     private readonly http;
     private readonly clientOptions;
-    private initPromise;
-    protected platformLimits: PlatformLimits | null;
     private credential;
     constructor(options?: ShipClientOptions);
-    protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
-    /**
-     * Lazy initialization — fetches platform limits (file size / count caps) once,
-     * on the first API call. Subsequent calls reuse the resolved promise.
-     */
-    protected ensureInitialized(): Promise<void>;
-    private fetchPlatformLimits;
+    protected abstract processInput(input: DeployInput, options: DeploymentOptions, limits: PlatformLimits): Promise<StaticFile[]>;
     /**
      * Ping the API server, resolving its answer: `{ success, timestamp }`, where
      * `timestamp` is the server clock in unix SECONDS.
@@ -3397,11 +3434,14 @@ declare abstract class Ship$1 {
      */
     whoami(): Promise<Account>;
     /**
-     * Get platform limits (max file size, file count, total size).
-     * Reuses the response fetched during initialization. Per-instance state —
-     * does not leak between concurrent Ships against different API URLs.
+     * Get the platform limits the server states now (max file size, file count,
+     * total size, and the blocked extensions). Asked every time and never held,
+     * since a plan move or an operator's grant changes them. A `signal` aborts
+     * the request, rejecting with the typed `Cancelled` error.
      */
-    getLimits(): Promise<PlatformLimits>;
+    getLimits(options?: {
+        signal?: AbortSignal;
+    }): Promise<PlatformLimits>;
     on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
@@ -3508,6 +3548,9 @@ declare function getENV(): ExecutionEnvironment;
  * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
  *
  * Additional checks: path traversal, reserved names, leading/trailing dots or spaces.
+ *
+ * The reason is a complete sentence naming the file, so every surface shows it
+ * as it is (`file-rules.ts` on why).
  */
 declare function validateFileName(filename: string): {
     valid: boolean;
@@ -3636,35 +3679,40 @@ declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>
  * @file One ordered table of deploy-file rules, and the single evaluation two
  * renderers share.
  *
- * **The defect this closes:** one rule was rendering as three sentences. A
- * file over the size cap said `File x is too large. Maximum allowed size is
- * 20MB.` from the deploy pipelines, `File size (21 MB) exceeds limit of 20 MB`
- * from `validateFiles`, and `File too large. Maximum 20971520 bytes allowed`
- * from the API — against the dual-validation doctrine that an error reads the
- * same wherever it was caught (root `CLAUDE.md`). Both pipelines also restated
- * the whole ordered check, so node/browser parity was a comment.
- *
  * **A rule states a predicate and a sentence; a renderer chooses only how to
  * DELIVER it.** That is the `SHAPES`-table move (`cli/formatters.ts`) applied
  * to validation: the throwing renderer raises the first broken rule, the
  * collecting renderer records it, and neither authors prose. Adding a rule is
- * a row, and both surfaces get it in the same position by construction.
- *
- * **Wording follows the API where a choice existed**, so the deferred Phase B
- * — promoting this table to `@shipstatic/types` with the API consuming it —
- * has less to move. Two deliberate deviations, recorded rather than silent:
- *
- * - **Sizes are formatted, not raw bytes.** The API says `20971520 bytes`;
- *   a browser upload UI showing that is worse for the person reading it, and
- *   the unit is the smaller half of the sentence to reconcile later.
- * - **The path is named.** The API has no path to name; the throwing renderer
- *   has nothing BUT the message, so dropping it would leave a CLI user asking
- *   which file.
+ * a row, and both surfaces get it in the same position by construction. One
+ * table is also what keeps a rule from reading three ways: the deploy
+ * pipelines, `validateFiles` and the API once each worded the size cap
+ * differently, against the dual-validation doctrine that an error reads the
+ * same wherever it is caught (root `CLAUDE.md`).
+ *
+ * **Every sentence is complete on its own.** The SDK is where a refusal is
+ * worded; drop, the console, the CLI and the MCPs show the sentence verbatim
+ * and add nothing, so a sentence names its file exactly once and states the
+ * limit, and reads without a prefix. The family is subject first: `File
+ * "<path>" <verdict>. Maximum <limit> allowed.`, and `File name "<path>" …`
+ * where the name is the subject. The two rules about the SET, the count and
+ * the total, name no path. A limit's sentence ends with the suggestion the
+ * API delivered for it (`withSuggestion`), so the whole reads `File "x" is
+ * too large. Maximum 20 MB allowed. Upgrade to Pro for more.`
+ *
+ * **The API words the same rules the same way, in the same order**
+ * (`cloudflare/api/src/lib/validation.ts`), so a refusal reads alike whether
+ * the SDK made it before uploading or the boundary made it after. Sizes are
+ * formatted on both sides, and the path is named on both. That is a
+ * restatement, and it is fenced from the API's side: a test there imports
+ * this package's `validateFiles` and compares every shared rule's sentence to
+ * `validateUpload`'s. The fence dies the day the table is promoted to
+ * `@shipstatic/types` and the API imports it (Phase B, `CLAUDE.md`).
  *
  * Out of scope, and left where they are: `validateDeployPath` (a rule about
  * the deploy PATH rather than the file, and pipelines-only), and
- * `validateFiles`' UI-tier pre-checks — empty, negative, count, unbuilt
- * marker, processing error — which have one holder each and no drift.
+ * `validateFiles`' UI-tier pre-checks (empty, negative, unbuilt marker,
+ * processing error), which have one holder each and no drift, and word their
+ * sentences by the same family.
  */
 
 /** What a rule is asked about: one file, and the deploy so far. */
@@ -3716,6 +3764,15 @@ declare function validateDeployPath(deployPath: string, sourceIdentifier: string
  * @throws {ShipError} The first broken rule's sentence
  */
 declare function validateDeployFile(input: FileRuleInput, limits: PlatformLimits): void;
+/**
+ * The throwing renderer of `COUNT_RULE`: the deploy's file count, judged over
+ * the files the pipeline will send.
+ *
+ * @param count - How many files the deploy carries
+ * @param limits - The platform's limits, from `/limits`
+ * @throws {ShipError} The count rule's sentence
+ */
+declare function validateDeployCount(count: number, limits: PlatformLimits): void;
 
 /**
  * Utility functions for string manipulation.
@@ -3747,10 +3804,10 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  *
  * @param paths - File or directory paths to scan and process.
  * @param options - Processing options (pathDetect, etc.).
- * @param platformLimits - Per-instance platform limits (file-size / count /
- *   total-size caps) from the originating Ship's `GET /limits` fetch. Passed
- *   in rather than read from a module global so concurrent Ships against
- *   different API URLs cannot clobber each other's caps.
+ * @param platformLimits - The platform limits (file-size / count /
+ *   total-size caps and the blocked extensions) the deploy read from
+ *   `GET /limits` at its start. Passed in, never held, so a validation always
+ *   meets the limits the server states now.
  * @returns Promise resolving to an array of StaticFile objects.
  * @throws {ShipError} If called outside Node.js or if fs/path modules fail.
  */
@@ -3801,10 +3858,10 @@ declare class Ship extends Ship$1 {
      * contract stays platform-neutral.
      */
     deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
-    protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
+    protected processInput(input: DeployInput, options: DeploymentOptions, limits: PlatformLimits): Promise<StaticFile[]>;
 }
 
 declare namespace Ship {
-  export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountAccess, AccountDeleteResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountRefusal, AccountRefusalType, AccountResource, AccountRole, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BUILD_SETTINGS, BillingInterval, BillingPortalSession, BillingSyncResponse, BuildFailureDetails, CALLER, Caps, ConsoleErrand, ConsolePaths, ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployFileEncoding, DeployFileSpec, 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, DomainVerification, DomainVerificationType, 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, PlanChangeRequest, PlanChangeResponse, PlanDestination, PlansResponse, PlatformLimits, RequestResult, ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, ScheduledChange, SettingsFragment, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doors, errandOf, extractSubdomain, filterJunk, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isInvitationPath, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
+  export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountAccess, AccountDeleteResponse, AccountKeyResponse, AccountPlan, AccountPlanType, AccountRefusal, AccountRefusalType, AccountResource, AccountRole, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BUILD_SETTINGS, BillingInterval, BillingPortalSession, BillingSyncResponse, BuildFailureDetails, CALLER, Caps, ConsoleErrand, ConsolePaths, ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployFileEncoding, DeployFileSpec, 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, DomainVerification, DomainVerificationType, 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, PlanChangeRefusalDetails, PlanChangeRequest, PlanChangeResponse, PlanDestination, PlansResponse, PlatformLimitKey, PlatformLimits, RequestResult, ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SIGN_IN_RETURN_PARAM, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, ScheduledChange, SettingsFragment, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doors, errandOf, extractSubdomain, filterJunk, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isInvitationPath, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
 }
 export = Ship;

package/dist/index.d.ts

@@ -724,7 +724,7 @@ type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
  * than the 403 uses.
  *
  * All three are counts plans SELL, and every plan publishes a number for each.
- * A platform subdomain (`my-app.shipstatic.com`) is among them: the namespace
+ * A platform domain (`my-app.shipstatic.com`) is among them: the namespace
  * is the platform's, so every plan bounds how many names one account may take
  * from it — which is not the address every deployment gets by construction
  * (`happy-cat-abc1234.shipstatic.com`), one per deployment and bounded by
@@ -734,8 +734,9 @@ type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
  * "unlimited" — so no consumer needs an "is it bounded?" branch. A cap of `0`
  * means the plan does not have the feature at all; a cap of `N` bounds
  * creation, and what an account already holds above a cap stays until a plan
- * TRANSITION fits it (excess paused, newest first — a domain is the only kind
- * that pauses).
+ * TRANSITION fits it: excess domains are paused, newest first, and members
+ * are paused together while the account holds more than its cap. Deployments
+ * never pause; above their cap they only block creation.
  *
  * 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
@@ -1266,11 +1267,12 @@ interface ErrorResponse {
 /**
  * `details` of an `ErrorType.Build` error: the evidence behind the verdict.
  *
- * The one `details` shape this file names, because it is the one a HUMAN
- * surface renders rather than a machine reads. The sentence in `message`
- * says what went wrong; the log is how the person fixing the project sees
- * where. A surface that builds shows both, the log as a block rather than
- * as prose.
+ * Named, like {@link PlanChangeRefusalDetails}, because a surface reads it:
+ * `ErrorResponse.details` stays `unknown`, and a shape a client narrows to is
+ * owned here rather than restated at its read site. The sentence in
+ * `message` says what went wrong; the log is how the person fixing the
+ * project sees where. A surface that builds shows both, the log as a block
+ * rather than as prose.
  */
 interface BuildFailureDetails {
     /**
@@ -1476,7 +1478,27 @@ interface PlatformLimits {
      * retire with it (tracked in root `backlog.md`).
      */
     readonly blockedExtensions?: readonly string[];
+    /**
+     * The way forward past each limit, in the API's own words, for the account
+     * that asked: `"Upgrade to Pro for more."` where a sold plan allows more,
+     * `"Please contact support if you need more."` where none does. The API
+     * writes it with the same function its own refusals use, so a client that
+     * refuses a file before uploading it appends this sentence to its refusal
+     * verbatim and says exactly what the server would have said. Which plans
+     * exist, which are sold and what an account's grant raises are the server's
+     * to know; a client never learns a plan name from this field, only a
+     * sentence. An anonymous caller is answered the free plan's sentence, as it
+     * is the free plan's numbers.
+     *
+     * **Optional, and the absence is load-bearing**, as `blockedExtensions`
+     * above: an API deployed before this field existed sends nothing, and a
+     * client then appends nothing. It hardens to required at the entity's next
+     * natural break, with the blocklist.
+     */
+    readonly suggestions?: Readonly<Record<PlatformLimitKey, string>>;
 }
+/** The three request limits, named as `PlatformLimits` names them. */
+type PlatformLimitKey = 'maxFileSize' | 'maxFilesCount' | 'maxTotalSize';
 /**
  * Whether a file is one the platform refuses to host.
  *
@@ -2014,10 +2036,12 @@ interface StaticFile {
  * console: under `/<account>/` and at the root.
  *
  * `owner` marks a section that means the person's OWN account: a bare path
- * into it opens the person's own account rather than the one entered last,
- * since a pricing link's `/upgrade/pro` and the published API-key link speak
- * about the reader's plan and key. Modals inside a section carry their own
- * owner rule in the console; this flag is the section's alone.
+ * into it opens the person's own account rather than the one entered last.
+ * A pricing link's `/upgrade/pro` and the published API-key link speak about
+ * the reader's plan and key, and `/success` is where a purchase lands: only
+ * an owner buys, and a person owns exactly one account. Modals inside a
+ * section carry their own owner rule in the console; this flag is the
+ * section's alone.
  */
 declare const SECTIONS: {
     readonly new: {
@@ -2036,7 +2060,7 @@ declare const SECTIONS: {
         readonly owner: true;
     };
     readonly success: {
-        readonly owner: false;
+        readonly owner: true;
     };
     readonly 'api-key': {
         readonly owner: true;
@@ -2484,11 +2508,29 @@ interface PlansResponse {
  * consent), and a billed account moving down gets a Stripe Subscription
  * Schedule that applies the change at period end. The answer says which
  * happened ({@link PlanChangeResponse}).
+ *
+ * A move down a tier is booked only by an account that fits it: until it
+ * does, the door refuses (400) with a sentence naming what to remove, and
+ * the same counts as {@link PlanChangeRefusalDetails}.
  */
 interface PlanChangeRequest {
     readonly plan: AccountPlanType;
     readonly interval: BillingInterval;
 }
+/**
+ * `details` of the change door's refusal of a move down a tier the account
+ * does not fit: the account holds more members, custom domains or platform
+ * domains than the destination allows.
+ *
+ * `excess` counts what to REMOVE before asking again, per kind, keyed like
+ * {@link Caps}; only the kinds over the destination's caps appear. The
+ * door's `message` names the same counts in a sentence, and that sentence is
+ * what a surface shows; the counts are for a client that acts on the
+ * refusal.
+ */
+interface PlanChangeRefusalDetails {
+    readonly excess: Partial<Caps>;
+}
 /**
  * The pending plan change — a Stripe Subscription Schedule, mirrored onto the
  * account. `at` is when it applies (the current period's end, Unix seconds).
@@ -2755,7 +2797,7 @@ interface UploadedFile {
  */
 declare function isPlatformDomain(domain: string, platformDomain: string): boolean;
 /**
- * Check if a domain is a custom domain (not a platform subdomain).
+ * Check if a domain is a custom domain (not a platform domain).
  * Custom domains are billable and require DNS verification.
  *
  * @example isCustomDomain("example.com", "shipstatic.com") → true
@@ -2901,8 +2943,11 @@ declare function validatePassword(value: unknown): string | undefined;
 interface DeploymentOptions extends DeploymentUploadOptions {
     /**
      * An AbortSignal to allow cancellation of the deploy operation. The one
-     * cancellation mechanism — abort the signal and the request rejects with
-     * a typed `Cancelled` error. Request timeouts are a client concern
+     * cancellation mechanism: it reaches every request the deploy makes (the
+     * limits it validates against, the SPA question and the upload itself),
+     * and aborting it rejects the deploy with a typed `Cancelled` error
+     * wherever it stands. A deploy the server had already committed stays
+     * committed. Request timeouts are a client concern
      * (`ShipClientOptions.timeout`), not a per-deploy one.
      */
     signal?: AbortSignal;
@@ -3366,17 +3411,9 @@ declare abstract class Ship$1 {
     readonly tokens: TokenResource;
     private readonly http;
     private readonly clientOptions;
-    private initPromise;
-    protected platformLimits: PlatformLimits | null;
     private credential;
     constructor(options?: ShipClientOptions);
-    protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
-    /**
-     * Lazy initialization — fetches platform limits (file size / count caps) once,
-     * on the first API call. Subsequent calls reuse the resolved promise.
-     */
-    protected ensureInitialized(): Promise<void>;
-    private fetchPlatformLimits;
+    protected abstract processInput(input: DeployInput, options: DeploymentOptions, limits: PlatformLimits): Promise<StaticFile[]>;
     /**
      * Ping the API server, resolving its answer: `{ success, timestamp }`, where
      * `timestamp` is the server clock in unix SECONDS.
@@ -3397,11 +3434,14 @@ declare abstract class Ship$1 {
      */
     whoami(): Promise<Account>;
     /**
-     * Get platform limits (max file size, file count, total size).
-     * Reuses the response fetched during initialization. Per-instance state —
-     * does not leak between concurrent Ships against different API URLs.
+     * Get the platform limits the server states now (max file size, file count,
+     * total size, and the blocked extensions). Asked every time and never held,
+     * since a plan move or an operator's grant changes them. A `signal` aborts
+     * the request, rejecting with the typed `Cancelled` error.
      */
-    getLimits(): Promise<PlatformLimits>;
+    getLimits(options?: {
+        signal?: AbortSignal;
+    }): Promise<PlatformLimits>;
     on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
@@ -3508,6 +3548,9 @@ declare function getENV(): ExecutionEnvironment;
  * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
  *
  * Additional checks: path traversal, reserved names, leading/trailing dots or spaces.
+ *
+ * The reason is a complete sentence naming the file, so every surface shows it
+ * as it is (`file-rules.ts` on why).
  */
 declare function validateFileName(filename: string): {
     valid: boolean;
@@ -3636,35 +3679,40 @@ declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>
  * @file One ordered table of deploy-file rules, and the single evaluation two
  * renderers share.
  *
- * **The defect this closes:** one rule was rendering as three sentences. A
- * file over the size cap said `File x is too large. Maximum allowed size is
- * 20MB.` from the deploy pipelines, `File size (21 MB) exceeds limit of 20 MB`
- * from `validateFiles`, and `File too large. Maximum 20971520 bytes allowed`
- * from the API — against the dual-validation doctrine that an error reads the
- * same wherever it was caught (root `CLAUDE.md`). Both pipelines also restated
- * the whole ordered check, so node/browser parity was a comment.
- *
  * **A rule states a predicate and a sentence; a renderer chooses only how to
  * DELIVER it.** That is the `SHAPES`-table move (`cli/formatters.ts`) applied
  * to validation: the throwing renderer raises the first broken rule, the
  * collecting renderer records it, and neither authors prose. Adding a rule is
- * a row, and both surfaces get it in the same position by construction.
- *
- * **Wording follows the API where a choice existed**, so the deferred Phase B
- * — promoting this table to `@shipstatic/types` with the API consuming it —
- * has less to move. Two deliberate deviations, recorded rather than silent:
- *
- * - **Sizes are formatted, not raw bytes.** The API says `20971520 bytes`;
- *   a browser upload UI showing that is worse for the person reading it, and
- *   the unit is the smaller half of the sentence to reconcile later.
- * - **The path is named.** The API has no path to name; the throwing renderer
- *   has nothing BUT the message, so dropping it would leave a CLI user asking
- *   which file.
+ * a row, and both surfaces get it in the same position by construction. One
+ * table is also what keeps a rule from reading three ways: the deploy
+ * pipelines, `validateFiles` and the API once each worded the size cap
+ * differently, against the dual-validation doctrine that an error reads the
+ * same wherever it is caught (root `CLAUDE.md`).
+ *
+ * **Every sentence is complete on its own.** The SDK is where a refusal is
+ * worded; drop, the console, the CLI and the MCPs show the sentence verbatim
+ * and add nothing, so a sentence names its file exactly once and states the
+ * limit, and reads without a prefix. The family is subject first: `File
+ * "<path>" <verdict>. Maximum <limit> allowed.`, and `File name "<path>" …`
+ * where the name is the subject. The two rules about the SET, the count and
+ * the total, name no path. A limit's sentence ends with the suggestion the
+ * API delivered for it (`withSuggestion`), so the whole reads `File "x" is
+ * too large. Maximum 20 MB allowed. Upgrade to Pro for more.`
+ *
+ * **The API words the same rules the same way, in the same order**
+ * (`cloudflare/api/src/lib/validation.ts`), so a refusal reads alike whether
+ * the SDK made it before uploading or the boundary made it after. Sizes are
+ * formatted on both sides, and the path is named on both. That is a
+ * restatement, and it is fenced from the API's side: a test there imports
+ * this package's `validateFiles` and compares every shared rule's sentence to
+ * `validateUpload`'s. The fence dies the day the table is promoted to
+ * `@shipstatic/types` and the API imports it (Phase B, `CLAUDE.md`).
  *
  * Out of scope, and left where they are: `validateDeployPath` (a rule about
  * the deploy PATH rather than the file, and pipelines-only), and
- * `validateFiles`' UI-tier pre-checks — empty, negative, count, unbuilt
- * marker, processing error — which have one holder each and no drift.
+ * `validateFiles`' UI-tier pre-checks (empty, negative, unbuilt marker,
+ * processing error), which have one holder each and no drift, and word their
+ * sentences by the same family.
  */
 
 /** What a rule is asked about: one file, and the deploy so far. */
@@ -3716,6 +3764,15 @@ declare function validateDeployPath(deployPath: string, sourceIdentifier: string
  * @throws {ShipError} The first broken rule's sentence
  */
 declare function validateDeployFile(input: FileRuleInput, limits: PlatformLimits): void;
+/**
+ * The throwing renderer of `COUNT_RULE`: the deploy's file count, judged over
+ * the files the pipeline will send.
+ *
+ * @param count - How many files the deploy carries
+ * @param limits - The platform's limits, from `/limits`
+ * @throws {ShipError} The count rule's sentence
+ */
+declare function validateDeployCount(count: number, limits: PlatformLimits): void;
 
 /**
  * Utility functions for string manipulation.
@@ -3747,10 +3804,10 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  *
  * @param paths - File or directory paths to scan and process.
  * @param options - Processing options (pathDetect, etc.).
- * @param platformLimits - Per-instance platform limits (file-size / count /
- *   total-size caps) from the originating Ship's `GET /limits` fetch. Passed
- *   in rather than read from a module global so concurrent Ships against
- *   different API URLs cannot clobber each other's caps.
+ * @param platformLimits - The platform limits (file-size / count /
+ *   total-size caps and the blocked extensions) the deploy read from
+ *   `GET /limits` at its start. Passed in, never held, so a validation always
+ *   meets the limits the server states now.
  * @returns Promise resolving to an array of StaticFile objects.
  * @throws {ShipError} If called outside Node.js or if fs/path modules fail.
  */
@@ -3801,7 +3858,7 @@ declare class Ship extends Ship$1 {
      * contract stays platform-neutral.
      */
     deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
-    protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
+    protected processInput(input: DeployInput, options: DeploymentOptions, limits: PlatformLimits): Promise<StaticFile[]>;
 }
 
-export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountAccess, type AccountDeleteResponse, type AccountKeyResponse, AccountPlan, type AccountPlanType, AccountRefusal, type AccountRefusalType, type AccountResource, type AccountRole, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BUILD_SETTINGS, type BillingInterval, type BillingPortalSession, type BillingSyncResponse, type BuildFailureDetails, CALLER, type Caps, type ConsoleErrand, type ConsolePaths, type ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, type DeployBodyContext, type DeployFile, type DeployFileEncoding, type DeployFileSpec, type DeployInput, type DeployTransport, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, DeploymentVia, type DeploymentViaType, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, DomainVerification, type DomainVerificationType, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, type PingResponse, type Plan, type PlanChangeRequest, type PlanChangeResponse, type PlanDestination, type PlansResponse, type PlatformLimits, type RequestResult, type ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SIGN_IN_RETURN_PARAM, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, type ScheduledChange, type SettingsFragment, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type ShipRequestInit, type StaticFile, TTL_CONSTRAINTS, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, type Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USER_VISIBLE_EVENTS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, doors, errandOf, extractSubdomain, filterJunk, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isInvitationPath, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
+export { ACCOUNT_HEADER, API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountAccess, type AccountDeleteResponse, type AccountKeyResponse, AccountPlan, type AccountPlanType, AccountRefusal, type AccountRefusalType, type AccountResource, type AccountRole, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BUILD_SETTINGS, type BillingInterval, type BillingPortalSession, type BillingSyncResponse, type BuildFailureDetails, CALLER, type Caps, type ConsoleErrand, type ConsolePaths, type ConsoleSection, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_FILE_GRAMMAR, DEPLOY_TOKEN, type DeployBodyContext, type DeployFile, type DeployFileEncoding, type DeployFileSpec, type DeployInput, type DeployTransport, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, DeploymentVia, type DeploymentViaType, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, DomainVerification, type DomainVerificationType, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, MY_API_KEY_URL, OAUTH_TOKEN, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, type PingResponse, type Plan, type PlanChangeRefusalDetails, type PlanChangeRequest, type PlanChangeResponse, type PlanDestination, type PlansResponse, type PlatformLimitKey, type PlatformLimits, type RequestResult, type ResourceContext, SECTIONS, SETUP_TROUBLESHOOTING_ANCHOR, SHIP_ENV, SHIP_VIA_ENV, SIGN_IN_RETURN_PARAM, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, type ScheduledChange, type SettingsFragment, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type ShipRequestInit, type StaticFile, TTL_CONSTRAINTS, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, type Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, USER_VISIBLE_EVENTS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, doors, errandOf, extractSubdomain, filterJunk, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isInvitationPath, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };