@shipstatic/ship 3.6.1 → 3.7.0

package/dist/index.d.cts

@@ -222,6 +222,9 @@ interface DeploymentListResponse extends ListResponse {
  *
  * No prose either (`message`): an acknowledgement is data, and each surface
  * composes its own copy.
+ *
+ * It states where the deployment IS, not what the call did: a repeat finds
+ * the row already `deleting` and answers this same object again, at 202.
  */
 interface DeploymentDeleteResponse {
     /** The deployment hostname that was marked for removal */
@@ -546,6 +549,40 @@ declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
     /** How long a stored 201 stays replayable. */
     readonly WINDOW_SECONDS: number;
 };
+/**
+ * The most one deploy request may carry, and the framing a client counts
+ * toward it. A deployment larger than one request arrives in several: a
+ * declaration with its {@link DEPLOY_FIELDS.MANIFEST}, then
+ * {@link API_PATHS.DEPLOYMENT_FILES} for the rest.
+ *
+ * Framing, not plan policy, which is why it is static rather than delivered
+ * by `/limits`: a client splitting at a smaller number is always correct.
+ *
+ * **`MAX_BYTES` is a one-way door.** This package is bundled into every
+ * published client, so an installed client keeps its cap forever. Raising it
+ * is free (an older client splits smaller, which is always valid); lowering
+ * it turns every installed client's largest request into a refusal.
+ *
+ * 64 MiB because it holds the largest file any plan allows (50 MiB) with its
+ * framing, keeps a request inside the API's memory, finishes within the
+ * SDK's request timeout at 2.5 Mbit/s, and sits under the edge's 100 MiB
+ * request limit. Measured on the development environment at the boundary
+ * (2026-10-18), a request of exactly 64 MiB, one 50 MiB file and 14 MiB of
+ * others, stored in under half a second of CPU, sent with or without a
+ * `Content-Length`, alone or two at once. What a request costs when its
+ * files are rewritten is the API's to bound, and it does so per file.
+ */
+declare const DEPLOY_REQUEST_CONSTRAINTS: {
+    /** The most one deploy request may carry, as `Content-Length` counts it. */
+    readonly MAX_BYTES: number;
+    /**
+     * The most multipart framing one part adds beyond its bytes and its name,
+     * and the body's closing delimiter at most the same. A ceiling by the
+     * multipart standard (a boundary is at most 70 characters), not a
+     * measurement.
+     */
+    readonly PART_OVERHEAD: 256;
+};
 /**
  * Normalize a `via` value from any transport — trimmed, lowercased, and a
  * member of {@link DeploymentVia}, or `undefined`.
@@ -1130,6 +1167,8 @@ declare const API_PATHS: {
     readonly DEPLOYMENTS: "/deployments";
     readonly DEPLOYMENT: (deployment: string) => string;
     readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
+    /** Fills a declared deployment with more of its files. */
+    readonly DEPLOYMENT_FILES: (deployment: string) => string;
     readonly DOMAINS: "/domains";
     readonly DOMAIN: (domain: string) => string;
     readonly DOMAIN_VERIFY: (domain: string) => string;
@@ -1170,8 +1209,11 @@ declare const API_PATHS: {
 declare const DEPLOY_FIELDS: {
     /** One entry per file — read with `getAll`. */
     readonly FILES: "files[]";
-    /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
-    readonly CHECKSUMS: "checksums";
+    /**
+     * JSON array of {@link ManifestEntry}, one per file of the deployment: its
+     * declaration. Optional; a request without one is the whole deployment.
+     */
+    readonly MANIFEST: "manifest";
     /** JSON array of label strings. */
     readonly LABELS: "labels";
     /** The deploying surface's {@link DeploymentVia} member. */
@@ -1201,6 +1243,19 @@ declare const DEPLOY_FIELDS: {
     /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
     readonly CAPTCHA: "captcha";
 };
+/**
+ * One file of a deployment's declaration ({@link DEPLOY_FIELDS.MANIFEST}).
+ * The wire shape both ends share and nothing more: the API owns what makes a
+ * manifest valid, and a client builds one from files it has already checked.
+ */
+interface ManifestEntry {
+    /** The deploy path, relative to the deployment root, no leading slash. */
+    path: string;
+    /** The file's size in bytes. */
+    size: number;
+    /** The MD5 of the file's bytes, 32 lowercase hex characters. */
+    md5: string;
+}
 /**
  * The JSON deploy body's file grammar: the OTHER body both deploy doors
  * accept, beside the multipart one {@link DEPLOY_FIELDS} names. A JSON caller
@@ -2189,14 +2244,16 @@ interface Journey {
  * them.
  *
  * ```ts
- * doors.login({ token, next: '/claim/abc' })
- * // '/login/<token>?next=%2Fclaim%2Fabc'
+ * doors.login.link({ token, next: '/claim/abc' })
+ * // '/login/link/<token>?next=%2Fclaim%2Fabc'
  * ```
  */
 declare const doors: {
-    readonly login: ({ token, next }?: Journey & {
-        readonly token?: string;
-    }) => string;
+    readonly login: (({ next }?: Journey) => string) & {
+        link: ({ token, next }: Journey & {
+            readonly token: string;
+        }) => string;
+    };
     readonly register: ({ next }?: Journey) => string;
     readonly logout: ({ next }?: Journey) => string;
     readonly invitation: (invitation: string) => string;
@@ -2218,7 +2275,7 @@ declare function accountOfPath(path: string): string | null;
  * The door a path names, or null for an account place or the operator
  * partition. Every question about doors reads this one answer: which page is
  * an auth page, which errand a destination carries, what a vendor must not
- * see. `/login/<token>` is the login door, as `/invitation/<id>` is the
+ * see. `/login/link/<token>` is the login door, as `/invitation/<id>` is the
  * invitation door: a door's object is the rest of its path.
  */
 declare function doorOf(path: string): DoorSegment | null;
@@ -2439,8 +2496,9 @@ interface DeploymentUploadOptions {
      * commit sha, a uuid minted before the first try — never one minted fresh
      * on each retry, which would defeat the point.
      *
-     * The replay is per-caller, and it stores successes only: a failed deploy
-     * retries fresh under the same key.
+     * A key replays within the account that sent it; an anonymous key is
+     * ignored, and each anonymous deploy is a new deployment. Only successes
+     * replay: a failed deploy retries fresh under the same key.
      */
     idempotencyKey?: string;
 }
@@ -3100,9 +3158,9 @@ interface DeployBodyContext {
      */
     via?: DeploymentViaType;
     /**
-     * Optional plaintext password to protect the deployment.
-     * Length: `PASSWORD_CONSTRAINTS.MIN_LENGTH` to `PASSWORD_CONSTRAINTS.MAX_LENGTH`
-     * characters. Whitespace is preserved verbatim — significant.
+     * Optional plaintext password to protect the deployment, already through
+     * `validatePassword`, which trims it: the body sends the value the rule
+     * judged, and the API trims and judges it the same way.
      */
     password?: string;
     /**
@@ -3321,6 +3379,11 @@ declare class SimpleEvents {
     emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
 }
 
+/**
+ * The slowest upload a deploy request is sized for, in bits a second. Stated
+ * here, beside the one ceiling this client derives from it.
+ */
+declare const UPLOAD_FLOOR_BITS_PER_SECOND = 2500000;
 interface ApiHttpOptions extends ShipClientOptions {
     /** Resolves the credential slot per request — async so token providers can mint/refresh. */
     getAuthHeaders: () => Record<string, string> | Promise<Record<string, string>>;
@@ -3358,23 +3421,26 @@ interface DeployTransport {
  */
 interface Transport {
     request<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<T>;
-    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string): Promise<RequestResult<T>>;
+    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<RequestResult<T>>;
     readonly deploy: DeployTransport;
 }
 /**
  * A request as THIS client composes one.
  *
- * Identical to `RequestInit` but for the headers, which are narrowed from the
- * DOM's three-shaped `HeadersInit` to the one shape every call site here
- * actually builds. That narrowing is load-bearing twice over: `mergeHeaders`
- * used to reach its record through an `as` cast, and `hasIdempotencyKey` used
- * to walk all three shapes to find a key that only ever arrives in one of
- * them. Narrowing at RUNTIME instead would have turned an unreachable case
- * into a SILENT no-retry — a deploy that quietly stopped replaying because
- * someone handed the transport a `Headers`. Here that is a compile error.
+ * `RequestInit`, with the headers narrowed from the DOM's three-shaped
+ * `HeadersInit` to the one shape every call site here builds (so
+ * `mergeHeaders` composes a record without a cast), and one field of its
+ * own: `idempotent`, which the resource that knows the request is safe to
+ * repeat sets, and the retry rule reads. The transport never infers it.
  */
 type ShipRequestInit = Omit<RequestInit, 'headers'> & {
     headers?: Record<string, string>;
+    /**
+     * The request may be sent twice with the same effect: a fill (every fill
+     * is safe to repeat), or a declaration carrying an `Idempotency-Key`, which
+     * the API answers with the deployment the key names.
+     */
+    idempotent?: boolean;
 };
 declare class ApiHttp extends SimpleEvents implements Transport {
     private readonly apiUrl;
@@ -3425,14 +3491,6 @@ declare class ApiHttp extends SimpleEvents implements Transport {
      * is one that may be sent twice.
      */
     private isRetryable;
-    /**
-     * Did this request carry the header that makes a repeat safe?
-     *
-     * Case-insensitively, because HTTP field names are — the CLI's env tier and
-     * the SDK option both spell it canonically, but a caller composing headers
-     * by hand is entitled not to.
-     */
-    private hasIdempotencyKey;
     /**
      * One attempt: headers, timeout signal, the `request`/`response` events, and
      * error normalization.
@@ -3456,7 +3514,7 @@ declare class ApiHttp extends SimpleEvents implements Transport {
      * the answer: a domain upsert says create-or-update in its 201/200 and
      * nowhere else in the response.
      */
-    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string): Promise<RequestResult<T>>;
+    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<RequestResult<T>>;
     private mergeHeaders;
     private createTimeoutSignal;
     private safeClone;
@@ -3916,7 +3974,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  * @file The Node half of the deploy pipeline: finding files on a filesystem.
  *
  * Everything after the finding is shared (`shared/core/deploy-files.ts`) —
- * path optimization, junk filtering, the platform's rules, the checksums.
+ * path optimization, junk filtering, the platform's rules, the digests.
  * What is genuinely Node here is a directory walk with symlink-cycle
  * protection, a content path computed against the upload root, and the fact
  * that a Node user can point at a project folder and mean `dist/`.
@@ -3987,6 +4045,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, AccountUsage, 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, DoorSegment, 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, 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, USAGE_KIND, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, countPhrase, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doorOf, doors, errandOf, excessOver, extractSubdomain, filterJunk, fitPhrase, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, placesTaken, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateLabel, validateLabels, 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, AccountUsage, 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_REQUEST_CONSTRAINTS, 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, DoorSegment, 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, ManifestEntry, 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, 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, UPLOAD_FLOOR_BITS_PER_SECOND, USAGE_KIND, USER_VISIBLE_EVENTS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, countPhrase, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, doorOf, doors, errandOf, excessOver, extractSubdomain, filterJunk, fitPhrase, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, placesTaken, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateLabel, validateLabels, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };
 }
 export = Ship;

package/dist/index.d.ts

@@ -222,6 +222,9 @@ interface DeploymentListResponse extends ListResponse {
  *
  * No prose either (`message`): an acknowledgement is data, and each surface
  * composes its own copy.
+ *
+ * It states where the deployment IS, not what the call did: a repeat finds
+ * the row already `deleting` and answers this same object again, at 202.
  */
 interface DeploymentDeleteResponse {
     /** The deployment hostname that was marked for removal */
@@ -546,6 +549,40 @@ declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
     /** How long a stored 201 stays replayable. */
     readonly WINDOW_SECONDS: number;
 };
+/**
+ * The most one deploy request may carry, and the framing a client counts
+ * toward it. A deployment larger than one request arrives in several: a
+ * declaration with its {@link DEPLOY_FIELDS.MANIFEST}, then
+ * {@link API_PATHS.DEPLOYMENT_FILES} for the rest.
+ *
+ * Framing, not plan policy, which is why it is static rather than delivered
+ * by `/limits`: a client splitting at a smaller number is always correct.
+ *
+ * **`MAX_BYTES` is a one-way door.** This package is bundled into every
+ * published client, so an installed client keeps its cap forever. Raising it
+ * is free (an older client splits smaller, which is always valid); lowering
+ * it turns every installed client's largest request into a refusal.
+ *
+ * 64 MiB because it holds the largest file any plan allows (50 MiB) with its
+ * framing, keeps a request inside the API's memory, finishes within the
+ * SDK's request timeout at 2.5 Mbit/s, and sits under the edge's 100 MiB
+ * request limit. Measured on the development environment at the boundary
+ * (2026-10-18), a request of exactly 64 MiB, one 50 MiB file and 14 MiB of
+ * others, stored in under half a second of CPU, sent with or without a
+ * `Content-Length`, alone or two at once. What a request costs when its
+ * files are rewritten is the API's to bound, and it does so per file.
+ */
+declare const DEPLOY_REQUEST_CONSTRAINTS: {
+    /** The most one deploy request may carry, as `Content-Length` counts it. */
+    readonly MAX_BYTES: number;
+    /**
+     * The most multipart framing one part adds beyond its bytes and its name,
+     * and the body's closing delimiter at most the same. A ceiling by the
+     * multipart standard (a boundary is at most 70 characters), not a
+     * measurement.
+     */
+    readonly PART_OVERHEAD: 256;
+};
 /**
  * Normalize a `via` value from any transport — trimmed, lowercased, and a
  * member of {@link DeploymentVia}, or `undefined`.
@@ -1130,6 +1167,8 @@ declare const API_PATHS: {
     readonly DEPLOYMENTS: "/deployments";
     readonly DEPLOYMENT: (deployment: string) => string;
     readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
+    /** Fills a declared deployment with more of its files. */
+    readonly DEPLOYMENT_FILES: (deployment: string) => string;
     readonly DOMAINS: "/domains";
     readonly DOMAIN: (domain: string) => string;
     readonly DOMAIN_VERIFY: (domain: string) => string;
@@ -1170,8 +1209,11 @@ declare const API_PATHS: {
 declare const DEPLOY_FIELDS: {
     /** One entry per file — read with `getAll`. */
     readonly FILES: "files[]";
-    /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
-    readonly CHECKSUMS: "checksums";
+    /**
+     * JSON array of {@link ManifestEntry}, one per file of the deployment: its
+     * declaration. Optional; a request without one is the whole deployment.
+     */
+    readonly MANIFEST: "manifest";
     /** JSON array of label strings. */
     readonly LABELS: "labels";
     /** The deploying surface's {@link DeploymentVia} member. */
@@ -1201,6 +1243,19 @@ declare const DEPLOY_FIELDS: {
     /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
     readonly CAPTCHA: "captcha";
 };
+/**
+ * One file of a deployment's declaration ({@link DEPLOY_FIELDS.MANIFEST}).
+ * The wire shape both ends share and nothing more: the API owns what makes a
+ * manifest valid, and a client builds one from files it has already checked.
+ */
+interface ManifestEntry {
+    /** The deploy path, relative to the deployment root, no leading slash. */
+    path: string;
+    /** The file's size in bytes. */
+    size: number;
+    /** The MD5 of the file's bytes, 32 lowercase hex characters. */
+    md5: string;
+}
 /**
  * The JSON deploy body's file grammar: the OTHER body both deploy doors
  * accept, beside the multipart one {@link DEPLOY_FIELDS} names. A JSON caller
@@ -2189,14 +2244,16 @@ interface Journey {
  * them.
  *
  * ```ts
- * doors.login({ token, next: '/claim/abc' })
- * // '/login/<token>?next=%2Fclaim%2Fabc'
+ * doors.login.link({ token, next: '/claim/abc' })
+ * // '/login/link/<token>?next=%2Fclaim%2Fabc'
  * ```
  */
 declare const doors: {
-    readonly login: ({ token, next }?: Journey & {
-        readonly token?: string;
-    }) => string;
+    readonly login: (({ next }?: Journey) => string) & {
+        link: ({ token, next }: Journey & {
+            readonly token: string;
+        }) => string;
+    };
     readonly register: ({ next }?: Journey) => string;
     readonly logout: ({ next }?: Journey) => string;
     readonly invitation: (invitation: string) => string;
@@ -2218,7 +2275,7 @@ declare function accountOfPath(path: string): string | null;
  * The door a path names, or null for an account place or the operator
  * partition. Every question about doors reads this one answer: which page is
  * an auth page, which errand a destination carries, what a vendor must not
- * see. `/login/<token>` is the login door, as `/invitation/<id>` is the
+ * see. `/login/link/<token>` is the login door, as `/invitation/<id>` is the
  * invitation door: a door's object is the rest of its path.
  */
 declare function doorOf(path: string): DoorSegment | null;
@@ -2439,8 +2496,9 @@ interface DeploymentUploadOptions {
      * commit sha, a uuid minted before the first try — never one minted fresh
      * on each retry, which would defeat the point.
      *
-     * The replay is per-caller, and it stores successes only: a failed deploy
-     * retries fresh under the same key.
+     * A key replays within the account that sent it; an anonymous key is
+     * ignored, and each anonymous deploy is a new deployment. Only successes
+     * replay: a failed deploy retries fresh under the same key.
      */
     idempotencyKey?: string;
 }
@@ -3100,9 +3158,9 @@ interface DeployBodyContext {
      */
     via?: DeploymentViaType;
     /**
-     * Optional plaintext password to protect the deployment.
-     * Length: `PASSWORD_CONSTRAINTS.MIN_LENGTH` to `PASSWORD_CONSTRAINTS.MAX_LENGTH`
-     * characters. Whitespace is preserved verbatim — significant.
+     * Optional plaintext password to protect the deployment, already through
+     * `validatePassword`, which trims it: the body sends the value the rule
+     * judged, and the API trims and judges it the same way.
      */
     password?: string;
     /**
@@ -3321,6 +3379,11 @@ declare class SimpleEvents {
     emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
 }
 
+/**
+ * The slowest upload a deploy request is sized for, in bits a second. Stated
+ * here, beside the one ceiling this client derives from it.
+ */
+declare const UPLOAD_FLOOR_BITS_PER_SECOND = 2500000;
 interface ApiHttpOptions extends ShipClientOptions {
     /** Resolves the credential slot per request — async so token providers can mint/refresh. */
     getAuthHeaders: () => Record<string, string> | Promise<Record<string, string>>;
@@ -3358,23 +3421,26 @@ interface DeployTransport {
  */
 interface Transport {
     request<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<T>;
-    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string): Promise<RequestResult<T>>;
+    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<RequestResult<T>>;
     readonly deploy: DeployTransport;
 }
 /**
  * A request as THIS client composes one.
  *
- * Identical to `RequestInit` but for the headers, which are narrowed from the
- * DOM's three-shaped `HeadersInit` to the one shape every call site here
- * actually builds. That narrowing is load-bearing twice over: `mergeHeaders`
- * used to reach its record through an `as` cast, and `hasIdempotencyKey` used
- * to walk all three shapes to find a key that only ever arrives in one of
- * them. Narrowing at RUNTIME instead would have turned an unreachable case
- * into a SILENT no-retry — a deploy that quietly stopped replaying because
- * someone handed the transport a `Headers`. Here that is a compile error.
+ * `RequestInit`, with the headers narrowed from the DOM's three-shaped
+ * `HeadersInit` to the one shape every call site here builds (so
+ * `mergeHeaders` composes a record without a cast), and one field of its
+ * own: `idempotent`, which the resource that knows the request is safe to
+ * repeat sets, and the retry rule reads. The transport never infers it.
  */
 type ShipRequestInit = Omit<RequestInit, 'headers'> & {
     headers?: Record<string, string>;
+    /**
+     * The request may be sent twice with the same effect: a fill (every fill
+     * is safe to repeat), or a declaration carrying an `Idempotency-Key`, which
+     * the API answers with the deployment the key names.
+     */
+    idempotent?: boolean;
 };
 declare class ApiHttp extends SimpleEvents implements Transport {
     private readonly apiUrl;
@@ -3425,14 +3491,6 @@ declare class ApiHttp extends SimpleEvents implements Transport {
      * is one that may be sent twice.
      */
     private isRetryable;
-    /**
-     * Did this request carry the header that makes a repeat safe?
-     *
-     * Case-insensitively, because HTTP field names are — the CLI's env tier and
-     * the SDK option both spell it canonically, but a caller composing headers
-     * by hand is entitled not to.
-     */
-    private hasIdempotencyKey;
     /**
      * One attempt: headers, timeout signal, the `request`/`response` events, and
      * error normalization.
@@ -3456,7 +3514,7 @@ declare class ApiHttp extends SimpleEvents implements Transport {
      * the answer: a domain upsert says create-or-update in its 201/200 and
      * nowhere else in the response.
      */
-    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string): Promise<RequestResult<T>>;
+    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<RequestResult<T>>;
     private mergeHeaders;
     private createTimeoutSignal;
     private safeClone;
@@ -3916,7 +3974,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  * @file The Node half of the deploy pipeline: finding files on a filesystem.
  *
  * Everything after the finding is shared (`shared/core/deploy-files.ts`) —
- * path optimization, junk filtering, the platform's rules, the checksums.
+ * path optimization, junk filtering, the platform's rules, the digests.
  * What is genuinely Node here is a directory walk with symlink-cycle
  * protection, a content path computed against the upload root, and the fact
  * that a Node user can point at a project folder and mean `dist/`.
@@ -3986,4 +4044,4 @@ declare class Ship extends Ship$1 {
     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 AccountUsage, 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 DoorSegment, 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, 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, USAGE_KIND, USER_VISIBLE_EVENTS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, countPhrase, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, doorOf, doors, errandOf, excessOver, extractSubdomain, filterJunk, fitPhrase, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, placesTaken, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateLabel, validateLabels, 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 AccountUsage, 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_REQUEST_CONSTRAINTS, 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 DoorSegment, 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, type ManifestEntry, 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, 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, UPLOAD_FLOOR_BITS_PER_SECOND, USAGE_KIND, USER_VISIBLE_EVENTS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, accountOfPath, allValidFilesReady, assertShipJsonSyntax, billingReturnOf, calculateMD5, classifyToken, consolePaths, countPhrase, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, doorOf, doors, errandOf, excessOver, extractSubdomain, filterJunk, fitPhrase, formatDuration, formatFileSize, formatTimeRemaining, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isClaimPath, isCustomDomain, isDeployment, isPlatformDomain, isShipError, isUpgradePath, normalizeVia, optimizeDeployPaths, personName, personShortName, placesTaken, pluralize, processFilesForNode, readBearerValue, serializeLabels, validateApiKey, validateApiUrl, validateBuildCommand, validateCaller, validateDeployCount, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validateLabel, validateLabels, validateOAuthToken, validateOutputDir, validatePassword, validateToken, validateTtl };