@shipstatic/ship 3.4.0-beta.2 → 3.4.0-beta.21

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.
  *
@@ -1824,15 +1846,17 @@ declare const SPA_DEFAULT_CONFIG: {
  * "100KB". `INDEX_FILE` is the selection rule (the file whose content rides
  * `SPACheckRequest.index`), restated by every client that builds the request.
  *
- * Neither member is a validation boundary: a client over the cap simply
- * skips the pre-flight, because the server answers an oversized index
- * `isSPA: false` anyway. A consumer that cannot import this (n8n) needs no
- * size copy at all — outcome parity is the server's, not the client's.
+ * Neither member is a validation boundary: a client over the cap skips the
+ * pre-flight and answers "no" itself, which is the answer the server gives an
+ * oversized index. Every client holds the cap, in bytes: the server's own
+ * route refuses a body over the JSON intake cap, so a client that asked about
+ * any index would fail a deploy whose upload succeeds. The n8n node, which
+ * cannot import this, restates the number under its contract fence.
  */
 declare const SPA_CHECK_CONSTRAINTS: {
     /** The file whose content is the check's subject. */
     readonly INDEX_FILE: "index.html";
-    /** Skip the pre-flight above this size — the server would answer false. */
+    /** Skip the pre-flight above this many UTF-8 bytes: the server answers no. */
     readonly MAX_INDEX_BYTES: number;
 };
 /**
@@ -1957,28 +1981,19 @@ interface SPACheckRequest {
     index: string;
 }
 /**
- * Response from SPA check endpoint
- */
-/**
- * Which of the classifier's tiers reached the verdict, and why. Named rather
- * than inline so the API's own `checkSPA` can return `SPACheckResponse`
- * instead of restating its shape.
- */
-interface SPACheckDebug {
-    /** Which tier made the detection */
-    tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
-    /** The reason for the detection result */
-    reason: string;
-}
-/**
- * A report: it answers a question and carries only the answer (`CLAUDE.md`,
- * "A report answers a question").
+ * The `/spa-check` answer: whether the upload is a single-page app, and the
+ * one sentence saying why it was or was not detected.
+ *
+ * `reason` is there so anyone can ask the open route about an upload and
+ * read the answer. It is human-readable text under the message authoring law:
+ * clients branch on `isSPA`, never on the sentence, so its wording is not a
+ * contract.
  */
 interface SPACheckResponse {
-    /** Whether the project is detected as a Single Page Application */
+    /** Whether the upload is detected as a single-page app */
     isSPA: boolean;
-    /** Debugging information about detection */
-    debug: SPACheckDebug;
+    /** Why it was or was not detected, for a person to read */
+    reason: string;
 }
 /**
  * Represents a file that has been processed and is ready for deploy.
@@ -2014,10 +2029,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 +2053,7 @@ declare const SECTIONS: {
         readonly owner: true;
     };
     readonly success: {
-        readonly owner: false;
+        readonly owner: true;
     };
     readonly 'api-key': {
         readonly owner: true;
@@ -2484,11 +2501,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 +2790,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 +2936,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;
@@ -3391,9 +3429,12 @@ declare abstract class Ship$1 {
     /**
      * 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.
+     * 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;
     /**
@@ -3500,6 +3541,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;
@@ -3628,35 +3672,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. */
@@ -3708,6 +3757,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.
@@ -3797,6 +3855,6 @@ declare class Ship extends Ship$1 {
 }
 
 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, 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;