@shipstatic/ship 2.2.0-beta.7 → 2.2.0-beta.9

package/dist/index.d.cts

@@ -671,6 +671,12 @@ declare const DEPLOY_FIELDS: {
     readonly VIA: "via";
     /** Plaintext password — the API hashes it server-side. */
     readonly PASSWORD: "password";
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant. The API
+     * computes and stores the expiry, so the wire carries no client clock.
+     * See {@link validateTtl}.
+     */
+    readonly TTL: "ttl";
     /** @internal Server-processing flag — first-party `/upload` only. */
     readonly BUILD: "build";
     /** @internal Server-processing flag — first-party `/upload` only. */
@@ -1259,6 +1265,47 @@ declare function validateApiUrl(apiUrl: string): void;
  * Example: "happy-cat-abc1234.shipstatic.com"
  */
 declare function isDeployment(input: string): boolean;
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+declare const TTL_CONSTRAINTS: {
+    /**
+     * Shortest requestable lifetime, in seconds. One rather than zero: a
+     * deployment that expires the instant it is created is not a shorter lease,
+     * it is a deploy that was never live, and `0` is how an unset variable
+     * arrives.
+     */
+    readonly MIN_SECONDS: 1;
+    /** Longest requestable lifetime, in seconds — one year. */
+    readonly MAX_SECONDS: number;
+};
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+declare function validateTtl(value: unknown): number | undefined;
 /**
  * Request payload for SPA check endpoint
  */
@@ -1391,6 +1438,27 @@ interface DeploymentUploadOptions {
      * into missing analytics rather than an error. See {@link DeploymentVia}.
      */
     via?: DeploymentViaType;
+    /**
+     * Seconds until this deployment expires; omit for one that never does.
+     *
+     * The platform reclaims it when the time is up — an ephemeral deployment,
+     * chosen by the deployer rather than by the identity. The same word and the
+     * same grammar as {@link TokenCreateOptions.ttl}, bounded by
+     * {@link TTL_CONSTRAINTS}.
+     *
+     * **Requires a credential.** An anonymous deploy has no deployer, and the
+     * platform owns anonymous lifetime as policy
+     * ({@link PUBLIC_DEPLOYMENT_TTL_SECONDS}) — so a ttl on one is refused
+     * rather than honoured or ignored.
+     *
+     * **A deployment carrying one cannot be linked to a domain.** A domain is a
+     * commitment and a deadline is its opposite; the API refuses the link, which
+     * is what keeps the reaper from tearing a live domain's target away.
+     *
+     * Immutable, like every other field of a deployment: to keep something
+     * longer, redeploy.
+     */
+    ttl?: number;
     /**
      * Optional password that protects this deployment.
      *
@@ -1829,14 +1897,6 @@ interface DeploymentOptions extends DeploymentUploadOptions {
     spaDetect?: boolean;
 }
 type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
-/**
- * Prepared request body for deployment.
- * Created by platform-specific code, consumed by HTTP client.
- */
-interface DeployBody {
-    body: FormData | ArrayBuffer;
-    headers: Record<string, string>;
-}
 /**
  * Context passed to the deploy body creator — everything that becomes a
  * form field alongside the files themselves.
@@ -1860,6 +1920,11 @@ interface DeployBodyContext {
      * characters. Whitespace is preserved verbatim — significant.
      */
     password?: string;
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant, bounded by
+     * `TTL_CONSTRAINTS`. The API stamps the expiry against its own clock.
+     */
+    ttl?: number;
     /** @internal Server-side processing flags. */
     flags?: {
         build?: boolean;
@@ -1869,11 +1934,6 @@ interface DeployBodyContext {
     /** @internal reCAPTCHA proof for the anonymous human deploy channel (/upload). */
     captcha?: string;
 }
-/**
- * Function that creates a deploy request body from files.
- * Implemented differently for Node.js and Browser.
- */
-type DeployBodyCreator = (files: StaticFile[], context?: DeployBodyContext) => Promise<DeployBody>;
 /** Standard `fetch` signature — the type of the `fetch` client option. */
 type Fetch = typeof fetch;
 /**
@@ -2071,28 +2131,72 @@ declare class SimpleEvents {
     emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
 }
 
-/**
- * @file HTTP client for Ship API.
- */
-
 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>>;
-    createDeployBody: DeployBodyCreator;
 }
-declare class ApiHttp extends SimpleEvents {
+interface RequestResult<T> {
+    data: T;
+    status: number;
+}
+/**
+ * The deploy's CARRIAGE — the two facts about a deploy that are transport's
+ * rather than the deployment resource's.
+ *
+ * The numbers are transport's because a budget for how long to wait on a wire
+ * is nothing else, and the endpoint is transport's because `deployEndpoint` is
+ * a client option that redirects the route. The CHOICE between the two
+ * ceilings is the resource's, because only it knows that `build`/`prerender`
+ * wait on work the server does after the upload lands.
+ */
+interface DeployTransport {
+    /** `/deployments`, or `/upload` where the `@internal` option redirects it. */
+    readonly endpoint: string;
+    /** The ordinary deploy ceiling. */
+    readonly timeout: number;
+    /** The ceiling when the server will also build. */
+    readonly buildTimeout: number;
+}
+/**
+ * What a resource may ask of the transport: carry this request, and tell me
+ * what came back.
+ *
+ * This interface is the whole seam. `resources.ts` states WHICH request — the
+ * path, the verb, the body, the response type — and hands it here; nothing
+ * above this line knows the base URL, the credential, the retry policy or the
+ * event vocabulary, and nothing below knows what a domain is.
+ */
+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>>;
+    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.
+ */
+type ShipRequestInit = Omit<RequestInit, 'headers'> & {
+    headers?: Record<string, string>;
+};
+declare class ApiHttp extends SimpleEvents implements Transport {
     private readonly apiUrl;
     private readonly getAuthHeadersCallback;
     private readonly session;
     private readonly caller;
     private readonly timeout;
     private readonly maxRetries;
-    private readonly deployTimeout;
-    private readonly deployBuildTimeout;
     private readonly fetch;
-    private readonly createDeployBody;
-    private readonly deployEndpoint;
     private globalHeaders;
+    /** @see DeployTransport — the carriage facts the deployment resource reads. */
+    readonly deploy: DeployTransport;
     constructor(options: ApiHttpOptions);
     /**
      * Set global headers included in every request.
@@ -2131,7 +2235,13 @@ declare class ApiHttp extends SimpleEvents {
      * is one that may be sent twice.
      */
     private isRetryable;
-    /** Did this request carry the header that makes a repeat safe? */
+    /**
+     * 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
@@ -2143,51 +2253,56 @@ declare class ApiHttp extends SimpleEvents {
      */
     private attemptOnce;
     /**
-     * Simple request - returns data only
+     * Send it; resolve what came back.
+     *
+     * Takes a PATH, not a URL: the base is this client's and nothing above needs
+     * to know it. Twenty-two call sites wrote `${this.apiUrl}${API_PATHS.X}` by
+     * hand before the endpoints moved out, which is twenty-two chances to
+     * assemble it differently.
      */
-    private request;
+    request<T>(path: string, options: ShipRequestInit, operationName: string, timeoutMs?: number): Promise<T>;
     /**
-     * Request with status - returns data and HTTP status code
+     * The same, plus the HTTP status — for the one operation where the status IS
+     * the answer: a domain upsert says create-or-update in its 201/200 and
+     * nowhere else in the response.
      */
-    private requestWithStatus;
+    requestWithStatus<T>(path: string, options: ShipRequestInit, operationName: string): Promise<RequestResult<T>>;
     private mergeHeaders;
     private createTimeoutSignal;
     private safeClone;
     private parseResponse;
-    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<DeploymentCreateResponse>;
-    listDeployments(options?: ListOptions): Promise<DeploymentListResponse>;
-    getDeployment(id: string): Promise<Deployment>;
-    updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
-    deleteDeployment(id: string): Promise<DeploymentDeleteResponse>;
-    setDomain(name: string, deployment?: string, labels?: string[]): Promise<DomainSetResult>;
-    listDomains(options?: ListOptions): Promise<DomainListResponse>;
-    getDomain(name: string): Promise<Domain>;
-    deleteDomain(name: string): Promise<DomainDeleteResponse>;
-    verifyDomain(name: string): Promise<DomainVerifyResponse>;
-    getDomainDns(name: string): Promise<DomainDnsResponse>;
-    getDomainRecords(name: string): Promise<DomainRecordsResponse>;
-    getDomainShare(name: string): Promise<DomainShareResponse>;
-    validateDomain(name: string): Promise<DomainValidateResponse>;
-    createToken(ttl?: number, labels?: string[]): Promise<TokenCreateResponse>;
-    listTokens(options?: ListOptions): Promise<TokenListResponse>;
-    deleteToken(token: string): Promise<TokenDeleteResponse>;
-    getToken(token: string): Promise<Token>;
-    getAccount(): Promise<AccountGetResponse>;
-    getLimits(): Promise<PlatformLimits>;
-    ping(): Promise<PingResponse>;
-    checkSPA(files: StaticFile[], _options?: ApiDeployOptions): Promise<boolean>;
 }
 
 /**
- * Ship SDK resource factory functions.
+ * @file The SDK's vocabulary — every request it can make, stated once.
+ *
+ * A resource method IS its endpoint: the path, the verb, the body, the
+ * response type. It hands that to the transport, which knows how to carry a
+ * request and nothing about what one means.
+ *
+ * **These were two layers until 2026-08-12.** `ApiHttp` carried eighteen
+ * endpoint methods and every factory below wrapped one of them 1:1 —
+ * `get: async (name) => getApi().getDomain(name)` — because this SDK mirrors
+ * the wire one method per endpoint BY DESIGN (see CLAUDE.md, "Recorded
+ * absences"). That design is exactly what made the second layer a restatement
+ * rather than an adapter: the two could not diverge without one of them being
+ * wrong. Folding DOWN rather than up is what keeps the public grouping and the
+ * transport separate, which was the whole point of having two files.
+ *
+ * The `*Resource` interfaces come from `@shipstatic/types` and did not move.
+ * They are the published contract; this file is how it is met.
  */
 
 /**
  * Shared context for all resource factories.
+ *
+ * A factory receives the callbacks it needs and nothing else — which is what
+ * lets `getApi()` be a THUNK rather than an instance: the transport is built
+ * once in the constructor, but reading it lazily is what keeps the resources
+ * constructible before it exists and swappable in tests.
  */
 interface ResourceContext {
-    getApi: () => ApiHttp;
-    ensureInit: () => Promise<void>;
+    getApi: () => Transport;
 }
 /**
  * Extended context for deployment resource.
@@ -2236,7 +2351,6 @@ declare abstract class Ship$1 {
     private credential;
     constructor(options?: ShipClientOptions);
     protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
-    protected abstract getDeployBodyCreator(): DeployBodyCreator;
     /**
      * Lazy initialization — fetches platform limits (file size / count caps) once,
      * on the first API call. Subsequent calls reuse the resolved promise.
@@ -2601,8 +2715,13 @@ declare function validateDeployFile(input: FileRuleInput, limits: PlatformLimits
 declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
 
 /**
- * @file Node.js-specific file utilities for the Ship SDK.
- * Provides helpers for recursively discovering, filtering, and preparing files for deploy in Node.js.
+ * @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.
+ * 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/`.
  */
 
 /**
@@ -2617,7 +2736,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  *   in rather than read from a module global so concurrent Ships against
  *   different API URLs cannot clobber each other's caps.
  * @returns Promise resolving to an array of StaticFile objects.
- * @throws {ShipClientError} If called outside Node.js or if fs/path modules fail.
+ * @throws {ShipError} If called outside Node.js or if fs/path modules fail.
  */
 declare function processFilesForNode(paths: string[], options?: DeploymentOptions, platformLimits?: PlatformLimits): Promise<StaticFile[]>;
 
@@ -2667,10 +2786,9 @@ declare class Ship extends Ship$1 {
      */
     deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
-    protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
 declare namespace Ship {
-  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountOverrides, AccountPlan, AccountPlanType, AccountResource, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingCancelResponse, BillingStatus, CALLER, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBody, DeployBodyContext, DeployBodyCreator, DeployFile, DeployInput, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, PlatformLimits, ResourceContext, SHIP_ENV, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, StaticFile, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken };
+  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountOverrides, AccountPlan, AccountPlanType, AccountResource, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BillingCancelResponse, BillingStatus, CALLER, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBodyContext, DeployFile, DeployInput, DeployTransport, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, PlatformLimits, RequestResult, ResourceContext, SHIP_ENV, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, ShipRequestInit, StaticFile, TTL_CONSTRAINTS, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, Transport, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken, validateTtl };
 }
 export = Ship;