@shipstatic/types 0.9.0 → 0.9.2

package/README.md

@@ -46,6 +46,20 @@ if (error.isClientError()) { /* Business | Config | File | Validation */ }
 if (error.isAuthError()) { /* handle auth */ }
 ```
 
+**HTTP client integration.** Both producer and consumer sides of the wire have first-class helpers, so every HTTP client across the platform reconstructs the same `ShipError` shape:
+
+```typescript
+// Producer side (API workers): serialize a ShipError to JSON
+return c.json(error.toResponse(), error.status ?? 500);
+
+// Consumer side (SDK, web app): rehydrate from any error Response
+if (!response.ok) {
+  throw await ShipError.fromHttpResponse(response, 'Get account failed');
+}
+```
+
+`fromHttpResponse` derives the error type from HTTP status (401 → `Authentication`, 429 → `RateLimit`, else → `Api`), preserving the body's `message`, `error`, and `details` best-effort. The optional second arg is a fallback message used when the body has nothing usable.
+
 ### Status Constants
 
 ```typescript
@@ -62,7 +76,7 @@ import {
 
 ```typescript
 import type {
-  ConfigResponse,
+  PlatformLimits,        // plan-based caps from /limits (file size, file count, total size)
   BillingStatus,
   CheckoutSession,
   ActivityListResponse,
@@ -80,8 +94,6 @@ import type {
   DomainResource,
   AccountResource,
   TokenResource,
-  BillingResource,
-  KeysResource,
 } from '@shipstatic/types';
 ```
 
@@ -138,8 +150,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

@@ -296,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
  */
@@ -344,8 +350,20 @@ export declare class ShipError extends Error {
     constructor(type: ErrorType, message: string, status?: number | undefined, details?: any | undefined);
     /** Convert to wire format */
     toResponse(): ErrorResponse;
-    /** Create from wire format */
-    static fromResponse(response: ErrorResponse): ShipError;
+    /**
+     * Construct a `ShipError` from an HTTP error response.
+     *
+     * Best-effort body parse for `{ message, error?, details? }`. Message
+     * resolution: `body.message` → `body.error` → `fallbackMessage` →
+     * `Request failed with status N`. Status drives the error type — same
+     * convention used by the SDK and web console — so `error.status === 429`
+     * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+     * body's `error` field claims.
+     *
+     * Async because it reads the response body. Returns rather than throws so
+     * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
+     */
+    static fromHttpResponse(response: Response, fallbackMessage?: string): Promise<ShipError>;
     static validation(message: string, details?: any): ShipError;
     static notFound(resource: string, id?: string): ShipError;
     static rateLimit(message?: string): ShipError;
@@ -380,12 +398,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;
 }
 /**
@@ -457,13 +485,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";
@@ -584,26 +631,16 @@ export interface ProgressInfo {
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
- * Browser-specific deploy input — an array of `File` objects (typically from
- * `<input type="file">` or drag-and-drop). The Browser SDK rejects any other
- * shape at runtime.
- */
-export type BrowserDeployInput = File[];
-/**
- * Node-specific deploy input — file or directory path(s) on disk. A single
- * path or an array of paths; directories are walked recursively. The Node
- * SDK rejects any other shape at runtime.
- */
-export type NodeDeployInput = string | string[];
-/**
- * Universal deploy input — the union of every platform's accepted shape.
+ * 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)
  *
- * Prefer the platform-specific aliases (`BrowserDeployInput` /
- * `NodeDeployInput`) when writing platform-specific code; `DeployInput` is
- * the right type only for code that genuinely needs to accept either. Each
- * platform's SDK validates at runtime and throws on the wrong shape.
+ * 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 = BrowserDeployInput | NodeDeployInput;
+export type DeployInput = File[] | string | string[];
 /**
  * Options for deployment creation at the API contract level.
  * SDK implementations may extend with additional options (timeout, signal, callbacks, etc.).
@@ -706,32 +743,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]),
@@ -111,9 +117,49 @@ export class ShipError extends Error {
             details
         };
     }
-    /** Create from wire format */
-    static fromResponse(response) {
-        return new ShipError(response.error, response.message, response.status, response.details);
+    /**
+     * Construct a `ShipError` from an HTTP error response.
+     *
+     * Best-effort body parse for `{ message, error?, details? }`. Message
+     * resolution: `body.message` → `body.error` → `fallbackMessage` →
+     * `Request failed with status N`. Status drives the error type — same
+     * convention used by the SDK and web console — so `error.status === 429`
+     * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+     * body's `error` field claims.
+     *
+     * Async because it reads the response body. Returns rather than throws so
+     * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
+     */
+    static async fromHttpResponse(response, fallbackMessage) {
+        let message;
+        let details;
+        try {
+            const contentType = response.headers.get('content-type');
+            if (contentType?.includes('application/json')) {
+                const json = await response.json();
+                if (json && typeof json === 'object') {
+                    const obj = json;
+                    if (typeof obj.message === 'string')
+                        message = obj.message;
+                    else if (typeof obj.error === 'string')
+                        message = obj.error;
+                    details = obj.details;
+                }
+            }
+            else {
+                const text = await response.text();
+                if (text)
+                    message = text;
+            }
+        }
+        catch {
+            // Body unreadable; fall through to fallback.
+        }
+        message = message || fallbackMessage || `Request failed with status ${response.status}`;
+        const type = response.status === 401 ? ErrorType.Authentication :
+            response.status === 429 ? ErrorType.RateLimit :
+                ErrorType.Api;
+        return new ShipError(type, message, response.status, details);
     }
     // Factory methods for common errors
     static validation(message, details) {
@@ -299,15 +345,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 +390,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.9.0",
+  "version": "0.9.2",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -341,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;
 
 /**
@@ -419,9 +428,52 @@ export class ShipError extends Error {
     };
   }
 
-  /** Create from wire format */
-  static fromResponse(response: ErrorResponse): ShipError {
-    return new ShipError(response.error, response.message, response.status, response.details);
+  /**
+   * Construct a `ShipError` from an HTTP error response.
+   *
+   * Best-effort body parse for `{ message, error?, details? }`. Message
+   * resolution: `body.message` → `body.error` → `fallbackMessage` →
+   * `Request failed with status N`. Status drives the error type — same
+   * convention used by the SDK and web console — so `error.status === 429`
+   * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+   * body's `error` field claims.
+   *
+   * Async because it reads the response body. Returns rather than throws so
+   * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
+   */
+  static async fromHttpResponse(
+    response: Response,
+    fallbackMessage?: string,
+  ): Promise<ShipError> {
+    let message: string | undefined;
+    let details: unknown;
+
+    try {
+      const contentType = response.headers.get('content-type');
+      if (contentType?.includes('application/json')) {
+        const json: unknown = await response.json();
+        if (json && typeof json === 'object') {
+          const obj = json as Record<string, unknown>;
+          if (typeof obj.message === 'string') message = obj.message;
+          else if (typeof obj.error === 'string') message = obj.error;
+          details = obj.details;
+        }
+      } else {
+        const text = await response.text();
+        if (text) message = text;
+      }
+    } catch {
+      // Body unreadable; fall through to fallback.
+    }
+
+    message = message || fallbackMessage || `Request failed with status ${response.status}`;
+
+    const type =
+      response.status === 401 ? ErrorType.Authentication :
+      response.status === 429 ? ErrorType.RateLimit :
+      ErrorType.Api;
+
+    return new ShipError(type, message, response.status, details);
   }
 
   // Factory methods for common errors
@@ -536,12 +588,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;
 }
 
@@ -667,16 +729,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 = {
@@ -703,17 +782,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`);
   }
 }
 
@@ -721,17 +800,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`);
   }
 }
 
@@ -886,28 +965,16 @@ export const DEFAULT_API = 'https://api.shipstatic.com';
 // =============================================================================
 
 /**
- * Browser-specific deploy input — an array of `File` objects (typically from
- * `<input type="file">` or drag-and-drop). The Browser SDK rejects any other
- * shape at runtime.
- */
-export type BrowserDeployInput = File[];
-
-/**
- * Node-specific deploy input — file or directory path(s) on disk. A single
- * path or an array of paths; directories are walked recursively. The Node
- * SDK rejects any other shape at runtime.
- */
-export type NodeDeployInput = string | string[];
-
-/**
- * Universal deploy input — the union of every platform's accepted shape.
+ * 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)
  *
- * Prefer the platform-specific aliases (`BrowserDeployInput` /
- * `NodeDeployInput`) when writing platform-specific code; `DeployInput` is
- * the right type only for code that genuinely needs to accept either. Each
- * platform's SDK validates at runtime and throws on the wrong shape.
+ * 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 = BrowserDeployInput | NodeDeployInput;
+export type DeployInput = File[] | string | string[];
 
 /**
  * Options for deployment creation at the API contract level.
@@ -1010,34 +1077,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
 // =============================================================================