@shipstatic/types 0.8.10 → 0.9.1

package/README.md

@@ -21,7 +21,7 @@ npm install @shipstatic/types
 ```typescript
 import type {
   Deployment, DeploymentListResponse,
-  Domain, DomainListResponse, DnsRecord, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse,
+  Domain, DomainSetResult, DomainListResponse, DnsRecord, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse,
   Token, TokenListItem, TokenListResponse, TokenCreateResponse,
   Account, AccountUsage, AccountOverrides,
   StaticFile
@@ -62,7 +62,7 @@ import {
 
 ```typescript
 import type {
-  ConfigResponse,
+  PlatformLimits,        // plan-based caps from /config (file size, file count, total size)
   BillingStatus,
   CheckoutSession,
   ActivityListResponse,
@@ -80,8 +80,6 @@ import type {
   DomainResource,
   AccountResource,
   TokenResource,
-  BillingResource,
-  KeysResource,
 } from '@shipstatic/types';
 ```
 
@@ -138,8 +136,8 @@ import {
 ```typescript
 import {
   DEFAULT_API,
-  API_KEY_PREFIX,
-  DEPLOY_TOKEN_PREFIX,
+  API_KEY,         // { PREFIX, HEX_LENGTH, TOTAL_LENGTH, HINT_LENGTH }
+  DEPLOY_TOKEN,    // { PREFIX, HEX_LENGTH, TOTAL_LENGTH }
   DEPLOYMENT_CONFIG_FILENAME,
 } from '@shipstatic/types';
 ```

package/dist/index.d.ts

@@ -94,6 +94,20 @@ export interface Domain {
     /** Total deployment links */
     links: number;
 }
+/**
+ * Return shape of `domains.set()` — `Domain` plus an SDK-derived flag indicating
+ * whether the underlying `PUT /domains/:name` created the record (HTTP 201) or
+ * updated an existing one (HTTP 200).
+ *
+ * `isCreate` is not part of the wire format — the API returns a plain `Domain`
+ * body. The SDK derives the flag from the HTTP status code so callers (notably
+ * the CLI) can format different output for the create vs repoint paths without
+ * a second round-trip.
+ */
+export interface DomainSetResult extends Domain {
+    /** `true` when this call created a new domain; `false` when it updated an existing one. */
+    isCreate: boolean;
+}
 /**
  * Response for listing domains
  */
@@ -282,31 +296,37 @@ export interface AccountOverrides {
     totalSize?: number;
 }
 /**
- * All possible error types in the ShipStatic platform
- * Names are developer-friendly while wire format stays consistent
+ * All possible error types in the ShipStatic platform.
+ *
+ * Developer-friendly key names map to stable wire-format string values.
+ * Both the value and the type are exported under the same name so callers
+ * can use `ErrorType.Validation` (value comparison) and `: ErrorType` (type
+ * annotation) without ceremony — matching the pattern other status objects
+ * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
-export declare enum ErrorType {
+export declare const ErrorType: {
     /** Validation failed (400) */
-    Validation = "validation_failed",
+    readonly Validation: "validation_failed";
     /** Resource not found (404) */
-    NotFound = "not_found",
+    readonly NotFound: "not_found";
     /** Rate limit exceeded (429) */
-    RateLimit = "rate_limit_exceeded",
+    readonly RateLimit: "rate_limit_exceeded";
     /** Authentication required (401) */
-    Authentication = "authentication_failed",
+    readonly Authentication: "authentication_failed";
     /** Business logic error (400) */
-    Business = "business_logic_error",
-    /** API server error (500) - renamed from Internal for clarity */
-    Api = "internal_server_error",
+    readonly Business: "business_logic_error";
+    /** API server error (500) */
+    readonly Api: "internal_server_error";
     /** Network/connection error */
-    Network = "network_error",
+    readonly Network: "network_error";
     /** Operation was cancelled */
-    Cancelled = "operation_cancelled",
+    readonly Cancelled: "operation_cancelled";
     /** File operation error */
-    File = "file_error",
+    readonly File: "file_error";
     /** Configuration error */
-    Config = "config_error"
-}
+    readonly Config: "config_error";
+};
+export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
 /**
  * Standard error response format used everywhere
  */
@@ -366,12 +386,22 @@ export declare class ShipError extends Error {
  */
 export declare function isShipError(error: unknown): error is ShipError;
 /**
- * Dynamic platform configuration returned by the /config endpoint.
- * Contains plan-based limits that vary by account.
+ * Plan-based platform limits returned by the `/config` endpoint.
+ *
+ * The SDK fetches these once on first API call to drive client-side
+ * file-size / file-count / total-size validation that mirrors what the API
+ * would enforce server-side. Limits vary by account plan.
+ *
+ * Distinct from `ResolvedConfig` (which carries the *client's* credentials
+ * and API URL after defaulting); this one carries the *platform's* posted
+ * caps for the current account.
  */
-export interface ConfigResponse {
+export interface PlatformLimits {
+    /** Maximum size in bytes for a single file. */
     maxFileSize: number;
+    /** Maximum number of files in a single deployment. */
     maxFilesCount: number;
+    /** Maximum total size in bytes across all files in a deployment. */
     maxTotalSize: number;
 }
 /**
@@ -443,13 +473,32 @@ export interface PingResponse {
     /** Optional timestamp */
     timestamp?: number;
 }
-export declare const API_KEY_PREFIX = "ship-";
-export declare const API_KEY_HEX_LENGTH = 64;
-export declare const API_KEY_TOTAL_LENGTH: number;
-export declare const API_KEY_HINT_LENGTH = 4;
-export declare const DEPLOY_TOKEN_PREFIX = "token-";
-export declare const DEPLOY_TOKEN_HEX_LENGTH = 64;
-export declare const DEPLOY_TOKEN_TOTAL_LENGTH: number;
+/**
+ * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export declare const API_KEY: {
+    /** Prefix that identifies an API key. */
+    readonly PREFIX: "ship-";
+    /** Number of hex characters following the prefix. */
+    readonly HEX_LENGTH: 64;
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
+    readonly TOTAL_LENGTH: 69;
+    /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
+    readonly HINT_LENGTH: 4;
+};
+/**
+ * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export declare const DEPLOY_TOKEN: {
+    /** Prefix that identifies a deploy token. */
+    readonly PREFIX: "token-";
+    /** Number of hex characters following the prefix. */
+    readonly HEX_LENGTH: 64;
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
+    readonly TOTAL_LENGTH: 70;
+};
 export declare const AuthMethod: {
     readonly JWT: "jwt";
     readonly API_KEY: "apiKey";
@@ -536,23 +585,21 @@ export interface StaticFile {
     size: number;
 }
 /**
- * Standard platform configuration format used by all clients
- */
-export interface PlatformConfig {
-    apiUrl?: string;
-    deployToken?: string;
-    apiKey?: string;
-}
-/**
- * Resolved configuration with required apiUrl.
- * This is the normalized config after merging options, env, and config files.
+ * Resolved client configuration with `apiUrl` defaulted.
+ *
+ * Produced by the SDK after layering its credential sources (constructor
+ * options on top of `SHIP_*` env vars in Node; constructor options only in
+ * Browser) and applying the `DEFAULT_API` fallback. File-based sources
+ * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
+ * are merged in *before* construction — by the time a `ResolvedConfig`
+ * exists, every source has already collapsed into the constructor argument.
  */
 export interface ResolvedConfig {
-    /** API URL (always present after resolution, defaults to DEFAULT_API) */
+    /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
     apiUrl: string;
-    /** API key for authenticated deployments */
+    /** API key for authenticated deployments. */
     apiKey?: string;
-    /** Deploy token for single-use deployments */
+    /** Deploy token for single-use deployments. */
     deployToken?: string;
 }
 /**
@@ -572,10 +619,14 @@ export interface ProgressInfo {
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
- * Deploy input type - environment-specific
+ * Universal deploy input — the union of every shape the SDK accepts.
+ *
+ * - **Browser**: `File[]` (typically from `<input type="file">` or drag-and-drop)
+ * - **Node**: `string | string[]` (file or directory path(s) on disk; directories are walked)
  *
- * Browser: File[] - array of File objects
- * Node.js: string | string[] - file/directory paths
+ * Each platform's SDK narrows its `deploy()` signature to the relevant shape
+ * and rejects anything else at runtime. Use the structural types directly
+ * (`File[]`, `string | string[]`) when writing platform-specific code.
  */
 export type DeployInput = File[] | string | string[];
 /**
@@ -623,7 +674,7 @@ export interface DomainResource {
     set: (name: string, options?: {
         deployment?: string;
         labels?: string[];
-    }) => Promise<Domain>;
+    }) => Promise<DomainSetResult>;
     list: () => Promise<DomainListResponse>;
     get: (name: string) => Promise<Domain>;
     remove: (name: string) => Promise<void>;
@@ -680,32 +731,6 @@ export interface CheckoutSession {
     /** URL to redirect user to Creem checkout page */
     url: string;
 }
-/**
- * Billing resource interface - the contract all implementations must follow
- *
- * IMPOSSIBLE SIMPLICITY: No sync() method needed!
- * Webhooks are the single source of truth. Frontend just polls status().
- */
-export interface BillingResource {
-    /**
-     * Create a checkout session
-     * @returns Checkout session with URL to redirect user
-     */
-    checkout: () => Promise<CheckoutSession>;
-    /**
-     * Get current billing status
-     * @returns Billing status and usage information
-     */
-    status: () => Promise<BillingStatus>;
-}
-/**
- * Keys resource interface - the contract all implementations must follow
- */
-export interface KeysResource {
-    create: () => Promise<{
-        apiKey: string;
-    }>;
-}
 /**
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}

package/dist/index.js

@@ -50,34 +50,40 @@ export const AccountPlan = {
 // ERROR SYSTEM
 // =============================================================================
 /**
- * All possible error types in the ShipStatic platform
- * Names are developer-friendly while wire format stays consistent
+ * All possible error types in the ShipStatic platform.
+ *
+ * Developer-friendly key names map to stable wire-format string values.
+ * Both the value and the type are exported under the same name so callers
+ * can use `ErrorType.Validation` (value comparison) and `: ErrorType` (type
+ * annotation) without ceremony — matching the pattern other status objects
+ * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
-export var ErrorType;
-(function (ErrorType) {
+export const ErrorType = {
     /** Validation failed (400) */
-    ErrorType["Validation"] = "validation_failed";
+    Validation: 'validation_failed',
     /** Resource not found (404) */
-    ErrorType["NotFound"] = "not_found";
+    NotFound: 'not_found',
     /** Rate limit exceeded (429) */
-    ErrorType["RateLimit"] = "rate_limit_exceeded";
+    RateLimit: 'rate_limit_exceeded',
     /** Authentication required (401) */
-    ErrorType["Authentication"] = "authentication_failed";
+    Authentication: 'authentication_failed',
     /** Business logic error (400) */
-    ErrorType["Business"] = "business_logic_error";
-    /** API server error (500) - renamed from Internal for clarity */
-    ErrorType["Api"] = "internal_server_error";
+    Business: 'business_logic_error',
+    /** API server error (500) */
+    Api: 'internal_server_error',
     /** Network/connection error */
-    ErrorType["Network"] = "network_error";
+    Network: 'network_error',
     /** Operation was cancelled */
-    ErrorType["Cancelled"] = "operation_cancelled";
+    Cancelled: 'operation_cancelled',
     /** File operation error */
-    ErrorType["File"] = "file_error";
+    File: 'file_error',
     /** Configuration error */
-    ErrorType["Config"] = "config_error";
-})(ErrorType || (ErrorType = {}));
+    Config: 'config_error',
+};
 /**
- * Categorizes error types for better type checking
+ * Categorizes error types for the `isClientError` / `isNetworkError` /
+ * `isAuthError` helpers. Each `Set` is typed against the wider `ErrorType`
+ * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
     client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
@@ -299,15 +305,32 @@ export function hasUnbuiltMarker(filePath) {
     const segments = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
     return segments.some(s => UNBUILT_PROJECT_MARKERS.has(s));
 }
-// API Key Configuration
-export const API_KEY_PREFIX = 'ship-';
-export const API_KEY_HEX_LENGTH = 64;
-export const API_KEY_TOTAL_LENGTH = API_KEY_PREFIX.length + API_KEY_HEX_LENGTH; // 69
-export const API_KEY_HINT_LENGTH = 4;
-// Deploy Token Configuration
-export const DEPLOY_TOKEN_PREFIX = 'token-';
-export const DEPLOY_TOKEN_HEX_LENGTH = 64;
-export const DEPLOY_TOKEN_TOTAL_LENGTH = DEPLOY_TOKEN_PREFIX.length + DEPLOY_TOKEN_HEX_LENGTH; // 70
+/**
+ * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export const API_KEY = {
+    /** Prefix that identifies an API key. */
+    PREFIX: 'ship-',
+    /** Number of hex characters following the prefix. */
+    HEX_LENGTH: 64,
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
+    TOTAL_LENGTH: 69,
+    /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
+    HINT_LENGTH: 4,
+};
+/**
+ * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export const DEPLOY_TOKEN = {
+    /** Prefix that identifies a deploy token. */
+    PREFIX: 'token-',
+    /** Number of hex characters following the prefix. */
+    HEX_LENGTH: 64,
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
+    TOTAL_LENGTH: 70,
+};
 // Authentication Method Constants
 export const AuthMethod = {
     JWT: 'jwt',
@@ -327,30 +350,30 @@ export const SPA_DEFAULT_CONFIG = { rewrites: [{ source: '/(.*)', destination: '
  * Validate API key format
  */
 export function validateApiKey(apiKey) {
-    if (!apiKey.startsWith(API_KEY_PREFIX)) {
-        throw ShipError.validation(`API key must start with "${API_KEY_PREFIX}"`);
+    if (!apiKey.startsWith(API_KEY.PREFIX)) {
+        throw ShipError.validation(`API key must start with "${API_KEY.PREFIX}"`);
     }
-    if (apiKey.length !== API_KEY_TOTAL_LENGTH) {
-        throw ShipError.validation(`API key must be ${API_KEY_TOTAL_LENGTH} characters total (${API_KEY_PREFIX} + ${API_KEY_HEX_LENGTH} hex chars)`);
+    if (apiKey.length !== API_KEY.TOTAL_LENGTH) {
+        throw ShipError.validation(`API key must be ${API_KEY.TOTAL_LENGTH} characters total (${API_KEY.PREFIX} + ${API_KEY.HEX_LENGTH} hex chars)`);
     }
-    const hexPart = apiKey.slice(API_KEY_PREFIX.length);
+    const hexPart = apiKey.slice(API_KEY.PREFIX.length);
     if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-        throw ShipError.validation(`API key must contain ${API_KEY_HEX_LENGTH} hexadecimal characters after "${API_KEY_PREFIX}" prefix`);
+        throw ShipError.validation(`API key must contain ${API_KEY.HEX_LENGTH} hexadecimal characters after "${API_KEY.PREFIX}" prefix`);
     }
 }
 /**
  * Validate deploy token format
  */
 export function validateDeployToken(deployToken) {
-    if (!deployToken.startsWith(DEPLOY_TOKEN_PREFIX)) {
-        throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN_PREFIX}"`);
+    if (!deployToken.startsWith(DEPLOY_TOKEN.PREFIX)) {
+        throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN.PREFIX}"`);
     }
-    if (deployToken.length !== DEPLOY_TOKEN_TOTAL_LENGTH) {
-        throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN_TOTAL_LENGTH} characters total (${DEPLOY_TOKEN_PREFIX} + ${DEPLOY_TOKEN_HEX_LENGTH} hex chars)`);
+    if (deployToken.length !== DEPLOY_TOKEN.TOTAL_LENGTH) {
+        throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN.TOTAL_LENGTH} characters total (${DEPLOY_TOKEN.PREFIX} + ${DEPLOY_TOKEN.HEX_LENGTH} hex chars)`);
     }
-    const hexPart = deployToken.slice(DEPLOY_TOKEN_PREFIX.length);
+    const hexPart = deployToken.slice(DEPLOY_TOKEN.PREFIX.length);
     if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-        throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN_HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN_PREFIX}" prefix`);
+        throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN.HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN.PREFIX}" prefix`);
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.8.10",
+  "version": "0.9.1",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -112,6 +112,21 @@ export interface Domain {
   links: number;
 }
 
+/**
+ * Return shape of `domains.set()` — `Domain` plus an SDK-derived flag indicating
+ * whether the underlying `PUT /domains/:name` created the record (HTTP 201) or
+ * updated an existing one (HTTP 200).
+ *
+ * `isCreate` is not part of the wire format — the API returns a plain `Domain`
+ * body. The SDK derives the flag from the HTTP status code so callers (notably
+ * the CLI) can format different output for the create vs repoint paths without
+ * a second round-trip.
+ */
+export interface DomainSetResult extends Domain {
+  /** `true` when this call created a new domain; `false` when it updated an existing one. */
+  isCreate: boolean;
+}
+
 /**
  * Response for listing domains
  */
@@ -326,39 +341,48 @@ export interface AccountOverrides {
 // =============================================================================
 
 /**
- * All possible error types in the ShipStatic platform
- * Names are developer-friendly while wire format stays consistent
+ * All possible error types in the ShipStatic platform.
+ *
+ * Developer-friendly key names map to stable wire-format string values.
+ * Both the value and the type are exported under the same name so callers
+ * can use `ErrorType.Validation` (value comparison) and `: ErrorType` (type
+ * annotation) without ceremony — matching the pattern other status objects
+ * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
-export enum ErrorType {
+export const ErrorType = {
   /** Validation failed (400) */
-  Validation = "validation_failed",
+  Validation: 'validation_failed',
   /** Resource not found (404) */
-  NotFound = "not_found",
+  NotFound: 'not_found',
   /** Rate limit exceeded (429) */
-  RateLimit = "rate_limit_exceeded",
+  RateLimit: 'rate_limit_exceeded',
   /** Authentication required (401) */
-  Authentication = "authentication_failed",
+  Authentication: 'authentication_failed',
   /** Business logic error (400) */
-  Business = "business_logic_error",
-  /** API server error (500) - renamed from Internal for clarity */
-  Api = "internal_server_error",
+  Business: 'business_logic_error',
+  /** API server error (500) */
+  Api: 'internal_server_error',
   /** Network/connection error */
-  Network = "network_error",
+  Network: 'network_error',
   /** Operation was cancelled */
-  Cancelled = "operation_cancelled",
+  Cancelled: 'operation_cancelled',
   /** File operation error */
-  File = "file_error",
+  File: 'file_error',
   /** Configuration error */
-  Config = "config_error"
-}
+  Config: 'config_error',
+} as const;
+
+export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
 
 /**
- * Categorizes error types for better type checking
+ * Categorizes error types for the `isClientError` / `isNetworkError` /
+ * `isAuthError` helpers. Each `Set` is typed against the wider `ErrorType`
+ * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
-  client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
-  network: new Set([ErrorType.Network]),
-  auth: new Set([ErrorType.Authentication]),
+  client: new Set<ErrorType>([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
+  network: new Set<ErrorType>([ErrorType.Network]),
+  auth: new Set<ErrorType>([ErrorType.Authentication]),
 } as const;
 
 /**
@@ -521,12 +545,22 @@ export function isShipError(error: unknown): error is ShipError {
 // =============================================================================
 
 /**
- * Dynamic platform configuration returned by the /config endpoint.
- * Contains plan-based limits that vary by account.
+ * Plan-based platform limits returned by the `/config` endpoint.
+ *
+ * The SDK fetches these once on first API call to drive client-side
+ * file-size / file-count / total-size validation that mirrors what the API
+ * would enforce server-side. Limits vary by account plan.
+ *
+ * Distinct from `ResolvedConfig` (which carries the *client's* credentials
+ * and API URL after defaulting); this one carries the *platform's* posted
+ * caps for the current account.
  */
-export interface ConfigResponse {
+export interface PlatformLimits {
+  /** Maximum size in bytes for a single file. */
   maxFileSize: number;
+  /** Maximum number of files in a single deployment. */
   maxFilesCount: number;
+  /** Maximum total size in bytes across all files in a deployment. */
   maxTotalSize: number;
 }
 
@@ -652,16 +686,33 @@ export interface PingResponse {
   timestamp?: number;
 }
 
-// API Key Configuration
-export const API_KEY_PREFIX = 'ship-';
-export const API_KEY_HEX_LENGTH = 64;
-export const API_KEY_TOTAL_LENGTH = API_KEY_PREFIX.length + API_KEY_HEX_LENGTH; // 69
-export const API_KEY_HINT_LENGTH = 4;
+/**
+ * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export const API_KEY = {
+  /** Prefix that identifies an API key. */
+  PREFIX: 'ship-',
+  /** Number of hex characters following the prefix. */
+  HEX_LENGTH: 64,
+  /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
+  TOTAL_LENGTH: 69,
+  /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
+  HINT_LENGTH: 4,
+} as const;
 
-// Deploy Token Configuration
-export const DEPLOY_TOKEN_PREFIX = 'token-';
-export const DEPLOY_TOKEN_HEX_LENGTH = 64;
-export const DEPLOY_TOKEN_TOTAL_LENGTH = DEPLOY_TOKEN_PREFIX.length + DEPLOY_TOKEN_HEX_LENGTH; // 70
+/**
+ * Shape constants for deploy tokens (`token-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+export const DEPLOY_TOKEN = {
+  /** Prefix that identifies a deploy token. */
+  PREFIX: 'token-',
+  /** Number of hex characters following the prefix. */
+  HEX_LENGTH: 64,
+  /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 70`). */
+  TOTAL_LENGTH: 70,
+} as const;
 
 // Authentication Method Constants
 export const AuthMethod = {
@@ -688,17 +739,17 @@ export const SPA_DEFAULT_CONFIG = { rewrites: [{ source: '/(.*)', destination: '
  * Validate API key format
  */
 export function validateApiKey(apiKey: string): void {
-  if (!apiKey.startsWith(API_KEY_PREFIX)) {
-    throw ShipError.validation(`API key must start with "${API_KEY_PREFIX}"`);
+  if (!apiKey.startsWith(API_KEY.PREFIX)) {
+    throw ShipError.validation(`API key must start with "${API_KEY.PREFIX}"`);
   }
 
-  if (apiKey.length !== API_KEY_TOTAL_LENGTH) {
-    throw ShipError.validation(`API key must be ${API_KEY_TOTAL_LENGTH} characters total (${API_KEY_PREFIX} + ${API_KEY_HEX_LENGTH} hex chars)`);
+  if (apiKey.length !== API_KEY.TOTAL_LENGTH) {
+    throw ShipError.validation(`API key must be ${API_KEY.TOTAL_LENGTH} characters total (${API_KEY.PREFIX} + ${API_KEY.HEX_LENGTH} hex chars)`);
   }
 
-  const hexPart = apiKey.slice(API_KEY_PREFIX.length);
+  const hexPart = apiKey.slice(API_KEY.PREFIX.length);
   if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-    throw ShipError.validation(`API key must contain ${API_KEY_HEX_LENGTH} hexadecimal characters after "${API_KEY_PREFIX}" prefix`);
+    throw ShipError.validation(`API key must contain ${API_KEY.HEX_LENGTH} hexadecimal characters after "${API_KEY.PREFIX}" prefix`);
   }
 }
 
@@ -706,17 +757,17 @@ export function validateApiKey(apiKey: string): void {
  * Validate deploy token format
  */
 export function validateDeployToken(deployToken: string): void {
-  if (!deployToken.startsWith(DEPLOY_TOKEN_PREFIX)) {
-    throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN_PREFIX}"`);
+  if (!deployToken.startsWith(DEPLOY_TOKEN.PREFIX)) {
+    throw ShipError.validation(`Deploy token must start with "${DEPLOY_TOKEN.PREFIX}"`);
   }
 
-  if (deployToken.length !== DEPLOY_TOKEN_TOTAL_LENGTH) {
-    throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN_TOTAL_LENGTH} characters total (${DEPLOY_TOKEN_PREFIX} + ${DEPLOY_TOKEN_HEX_LENGTH} hex chars)`);
+  if (deployToken.length !== DEPLOY_TOKEN.TOTAL_LENGTH) {
+    throw ShipError.validation(`Deploy token must be ${DEPLOY_TOKEN.TOTAL_LENGTH} characters total (${DEPLOY_TOKEN.PREFIX} + ${DEPLOY_TOKEN.HEX_LENGTH} hex chars)`);
   }
 
-  const hexPart = deployToken.slice(DEPLOY_TOKEN_PREFIX.length);
+  const hexPart = deployToken.slice(DEPLOY_TOKEN.PREFIX.length);
   if (!/^[a-f0-9]{64}$/i.test(hexPart)) {
-    throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN_HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN_PREFIX}" prefix`);
+    throw ShipError.validation(`Deploy token must contain ${DEPLOY_TOKEN.HEX_LENGTH} hexadecimal characters after "${DEPLOY_TOKEN.PREFIX}" prefix`);
   }
 }
 
@@ -822,24 +873,21 @@ export interface StaticFile {
 // =============================================================================
 
 /**
- * Standard platform configuration format used by all clients
- */
-export interface PlatformConfig {
-  apiUrl?: string;
-  deployToken?: string;
-  apiKey?: string;
-}
-
-/**
- * Resolved configuration with required apiUrl.
- * This is the normalized config after merging options, env, and config files.
+ * Resolved client configuration with `apiUrl` defaulted.
+ *
+ * Produced by the SDK after layering its credential sources (constructor
+ * options on top of `SHIP_*` env vars in Node; constructor options only in
+ * Browser) and applying the `DEFAULT_API` fallback. File-based sources
+ * (`.shiprc`, `package.json` `"ship"` key) are the CLI's responsibility and
+ * are merged in *before* construction — by the time a `ResolvedConfig`
+ * exists, every source has already collapsed into the constructor argument.
  */
 export interface ResolvedConfig {
-  /** API URL (always present after resolution, defaults to DEFAULT_API) */
+  /** API URL — always present after resolution, defaults to `DEFAULT_API`. */
   apiUrl: string;
-  /** API key for authenticated deployments */
+  /** API key for authenticated deployments. */
   apiKey?: string;
-  /** Deploy token for single-use deployments */
+  /** Deploy token for single-use deployments. */
   deployToken?: string;
 }
 
@@ -874,10 +922,14 @@ export const DEFAULT_API = 'https://api.shipstatic.com';
 // =============================================================================
 
 /**
- * Deploy input type - environment-specific
+ * Universal deploy input — the union of every shape the SDK accepts.
  *
- * Browser: File[] - array of File objects
- * Node.js: string | string[] - file/directory paths
+ * - **Browser**: `File[]` (typically from `<input type="file">` or drag-and-drop)
+ * - **Node**: `string | string[]` (file or directory path(s) on disk; directories are walked)
+ *
+ * Each platform's SDK narrows its `deploy()` signature to the relevant shape
+ * and rejects anything else at runtime. Use the structural types directly
+ * (`File[]`, `string | string[]`) when writing platform-specific code.
  */
 export type DeployInput = File[] | string | string[];
 
@@ -923,7 +975,7 @@ export interface DeploymentResource {
  * Domain resource interface - the contract all implementations must follow
  */
 export interface DomainResource {
-  set: (name: string, options?: { deployment?: string; labels?: string[] }) => Promise<Domain>;
+  set: (name: string, options?: { deployment?: string; labels?: string[] }) => Promise<DomainSetResult>;
   list: () => Promise<DomainListResponse>;
   get: (name: string) => Promise<Domain>;
   remove: (name: string) => Promise<void>;
@@ -982,34 +1034,6 @@ export interface CheckoutSession {
   url: string;
 }
 
-/**
- * Billing resource interface - the contract all implementations must follow
- *
- * IMPOSSIBLE SIMPLICITY: No sync() method needed!
- * Webhooks are the single source of truth. Frontend just polls status().
- */
-export interface BillingResource {
-  /**
-   * Create a checkout session
-   * @returns Checkout session with URL to redirect user
-   */
-  checkout: () => Promise<CheckoutSession>;
-
-  /**
-   * Get current billing status
-   * @returns Billing status and usage information
-   */
-  status: () => Promise<BillingStatus>;
-}
-
-
-/**
- * Keys resource interface - the contract all implementations must follow
- */
-export interface KeysResource {
-  create: () => Promise<{ apiKey: string }>;
-}
-
 // =============================================================================
 // ACTIVITY TYPES
 // =============================================================================