@shipstatic/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shipstatic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# Shipstatic Types
+
+Shared TypeScript types and constants for the Shipstatic platform. This package provides a single source of truth for types, errors, and configuration across the Shipstatic ecosystem.
+
+## Overview
+
+This package contains all shared types used between:
+- **Shipstatic API** (`/cloudflare/api`) - Backend API on Cloudflare Workers
+- **Shipstatic SDK** (`/ship`) - Universal SDK for Node.js and Browser
+- **Shipstatic CLI** - Command-line interface
+
+## Core Types
+
+### Deployment Types
+
+```typescript
+// Core deployment object
+interface Deployment {
+  deployment: string;         // Deployment ID
+  filesCount: number;         // Number of files
+  totalSize: number;          // Total size in bytes
+  status: 'pending' | 'success' | 'failed';
+  createdAt: number;          // Unix timestamp
+  expiresAt?: number;         // Unix timestamp
+  verifiedAt?: number;        // Unix timestamp
+}
+
+// Successful deployment response
+interface DeploySuccessResponse {
+  success: true;
+  deployment: string;
+  expiresAt: number;
+  filesCount: number;
+  totalSize: number;
+}
+
+// Deployment list response
+interface DeploymentListResponse {
+  deployments: Deployment[];
+  cursor?: string;
+  total?: number;
+}
+```
+
+### Alias Types
+
+```typescript
+// Core alias object
+interface Alias {
+  alias: string;             // Alias name
+  deploymentName: string;    // Target deployment name
+  status: 'pending' | 'success' | 'failed';
+  createdAt: number;         // Unix timestamp
+  confirmedAt?: number;      // Unix timestamp
+}
+
+// Alias list response
+interface AliasListResponse {
+  aliases: Alias[];
+  cursor?: string;
+  total?: number;
+}
+```
+
+### Account Types
+
+```typescript
+// Core account object
+interface Account {
+  email: string;
+  name: string;
+  picture?: string;
+  subscription: 'free' | 'active' | 'suspended';
+  createdAt: number;         // Unix timestamp
+  subscribedAt?: number;     // Unix timestamp
+  suspendedAt?: number;      // Unix timestamp
+}
+```
+
+### Platform Configuration
+
+```typescript
+// Dynamic platform configuration from API
+interface ConfigResponse {
+  maxFileSize: number;       // Maximum file size in bytes
+  maxFilesCount: number;     // Maximum files per deployment
+  maxTotalSize: number;      // Maximum total deployment size
+}
+```
+
+## Error System
+
+### Unified Error Handling
+
+```typescript
+// All possible error types
+enum ErrorType {
+  Validation = "validation_failed",
+  NotFound = "not_found",
+  RateLimit = "rate_limit_exceeded",
+  Authentication = "authentication_failed",
+  Business = "business_logic_error",
+  Api = "internal_server_error",
+  Network = "network_error",
+  Cancelled = "operation_cancelled",
+  File = "file_error",
+  Config = "config_error"
+}
+
+// Standard error response format
+interface ErrorResponse {
+  error: ErrorType;
+  message: string;
+  status?: number;
+  details?: any;
+}
+
+// Unified error class for both API and SDK
+class ShipError extends Error {
+  constructor(
+    public readonly type: ErrorType,
+    message: string,
+    public readonly status?: number,
+    public readonly details?: any
+  );
+
+  // Factory methods
+  static validation(message: string, details?: any): ShipError;
+  static notFound(resource: string, id?: string): ShipError;
+  static authentication(message?: string): ShipError;
+  static client(message: string, details?: any): ShipError;
+  
+  // Helper methods
+  isClientError(): boolean;
+  isNetworkError(): boolean;
+  isAuthError(): boolean;
+}
+```
+
+## Platform Configuration
+
+### Shared Constants
+
+```typescript
+// Server-side platform configuration
+export const serverConfig = {
+  /** Maximum individual file size in bytes (10MB) */
+  maxFileSize: 10 * 1024 * 1024,
+  /** Maximum number of files per deployment */
+  maxFilesCount: 1000,
+  /** Maximum total deployment size in bytes (100MB) */
+  maxTotalSize: 100 * 1024 * 1024,
+  /** Deployment expiry in hours */
+  deploymentExpiryHours: 168, // 7 days
+  /** Pagination limits */
+  defaultLimit: 50,
+  maxLimit: 100,
+} as const;
+
+// Client-side configuration - conservative defaults for SDK/CLI
+export const clientConfig = {
+  /** Conservative file size limit for client validation (5MB) */
+  maxFileSize: 5 * 1024 * 1024,
+  /** Conservative file count limit for client validation */
+  maxFilesCount: 100,
+  /** Conservative total size limit for client validation (25MB) */
+  maxTotalSize: 25 * 1024 * 1024,
+} as const;
+```
+
+### Dynamic Configuration
+
+The platform provides dynamic configuration through the API's `/config` endpoint:
+
+```json
+{
+  "maxFileSize": 10485760,     // 10MB
+  "maxFilesCount": 1000,       // Files per deployment  
+  "maxTotalSize": 104857600    // 100MB total
+}
+```
+
+**Benefits:**
+- **Single source of truth** - Configuration defined once in `serverConfig`
+- **Dynamic updates** - API can adjust limits without code changes
+- **SDK synchronization** - SDK automatically fetches current limits
+- **Type safety** - Shared `ConfigResponse` interface ensures consistency
+
+## Usage
+
+### In Ship API
+
+```typescript
+import { serverConfig, ShipError, type ConfigResponse } from '@shipstatic/types';
+
+// Use shared configuration constants
+const config: ConfigResponse = {
+  maxFileSize: serverConfig.maxFileSize,
+  maxFilesCount: serverConfig.maxFilesCount,
+  maxTotalSize: serverConfig.maxTotalSize,
+};
+
+// Use unified error handling
+throw ShipError.validation('File too large', { maxSize: serverConfig.maxFileSize });
+```
+
+### In Ship SDK
+
+```typescript
+import { ShipError, type ConfigResponse, type DeploySuccessResponse } from '@shipstatic/types';
+
+// Receive platform configuration
+const config: ConfigResponse = await api.getConfig();
+
+// Handle errors consistently
+try {
+  const result: DeploySuccessResponse = await deploy(files);
+} catch (error) {
+  if (error instanceof ShipError) {
+    // Handle Ship-specific errors
+  }
+}
+```
+
+## Installation
+
+This package is automatically installed as a dependency of the Ship SDK and API:
+
+```bash
+# Direct installation (if needed)
+npm install @shipstatic/types
+```
+
+## Architecture
+
+### Design Principles
+
+- **Single source of truth** - All types defined once, used everywhere
+- **Type safety** - Strict TypeScript with no `any` types
+- **Wire format compatibility** - Types match API request/response formats
+- **Error consistency** - Unified error handling across all components
+- **Configuration sharing** - Shared constants prevent drift
+
+### Package Structure
+
+```
+/types/src/
+└── index.ts              # All types and exports in single file
+```
+
+### Type Organization
+
+All types are organized in a single `index.ts` file by category:
+
+- **Core entities** - Deployment, Alias, Account objects
+- **API responses** - Success/error response wrappers  
+- **Configuration** - `serverConfig` and `clientConfig` with platform limits
+- **Error system** - Unified `ShipError` class with factory methods
+- **Common patterns** - Shared response formats and interfaces
+
+## Philosophy
+
+This package follows the **"Impossible Simplicity"** principle:
+
+- **Do more with less** - Maximum type safety with minimal complexity
+- **Single source of truth** - Types defined once, used everywhere
+- **Wire format compatibility** - Types match actual API contracts
+- **Developer experience** - Clear, predictable type interfaces
+- **Maintainability** - Easy to update types across entire platform
+
+**Result:** Type-safe development across the entire Ship platform with zero type drift between components.
+
+---
+
+**Ship Types** - Shared types for the Ship platform 🚢

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @file Shared types for Shipstatic platform
+ * Simple, clean types that both API and SDK agree on
+ */
+/**
+ * Core deployment object - used in both API responses and SDK
+ */
+export interface Deployment {
+    /** The deployment ID */
+    deployment: string;
+    /** Number of files in this deployment */
+    filesCount: number;
+    /** Total size of all files in bytes */
+    totalSize: number;
+    /** Current deployment status */
+    status: 'pending' | 'success' | 'failed';
+    /** Unix timestamp (seconds) when deployment was created */
+    createdAt: number;
+    /** Unix timestamp (seconds) when deployment expires */
+    expiresAt?: number;
+    /** Unix timestamp (seconds) when deployment was verified */
+    verifiedAt?: number;
+}
+/**
+ * Response for listing deployments
+ */
+export interface DeploymentListResponse {
+    /** Array of deployments */
+    deployments: Deployment[];
+    /** Optional cursor for pagination */
+    cursor?: string;
+    /** Total number of deployments if available */
+    total?: number;
+}
+/**
+ * Core alias object - used in both API responses and SDK
+ */
+export interface Alias {
+    /** The alias name */
+    alias: string;
+    /** The deployment name this alias points to */
+    deploymentName: string;
+    /** Current alias status */
+    status: 'pending' | 'success' | 'failed';
+    /** Unix timestamp (seconds) when alias was created */
+    createdAt: number;
+    /** Unix timestamp (seconds) when alias was confirmed */
+    confirmedAt?: number;
+}
+/**
+ * Response for listing aliases
+ */
+export interface AliasListResponse {
+    /** Array of aliases */
+    aliases: Alias[];
+    /** Optional cursor for pagination */
+    cursor?: string;
+    /** Total number of aliases if available */
+    total?: number;
+}
+/**
+ * Response for deployment removal
+ */
+export interface DeploymentRemoveResponse {
+    /** Operation success status */
+    success: boolean;
+    /** The deployment ID */
+    deployment: string;
+    /** Human-readable message */
+    message?: string;
+}
+/**
+ * Core account object - used in both API responses and SDK
+ */
+export interface Account {
+    /** User email address */
+    email: string;
+    /** User display name */
+    name: string;
+    /** User profile picture URL */
+    picture?: string;
+    /** Account subscription status */
+    subscription: 'free' | 'active' | 'suspended';
+    /** Unix timestamp (seconds) when account was created */
+    createdAt: number;
+    /** Unix timestamp (seconds) when subscription started */
+    subscribedAt?: number;
+    /** Unix timestamp (seconds) when account was suspended */
+    suspendedAt?: number;
+}
+/**
+ * All possible error types in the Shipstatic platform
+ * Names are developer-friendly while wire format stays consistent
+ */
+export declare enum ErrorType {
+    /** Validation failed (400) */
+    Validation = "validation_failed",
+    /** Resource not found (404) */
+    NotFound = "not_found",
+    /** Rate limit exceeded (429) */
+    RateLimit = "rate_limit_exceeded",
+    /** Authentication required (401) */
+    Authentication = "authentication_failed",
+    /** Business logic error (400) */
+    Business = "business_logic_error",
+    /** API server error (500) - renamed from Internal for clarity */
+    Api = "internal_server_error",
+    /** Network/connection error */
+    Network = "network_error",
+    /** Operation was cancelled */
+    Cancelled = "operation_cancelled",
+    /** File operation error */
+    File = "file_error",
+    /** Configuration error */
+    Config = "config_error"
+}
+/** @deprecated Use ErrorType instead. Kept for backward compatibility. */
+export declare const ShipErrorType: typeof ErrorType;
+/**
+ * Standard error response format used everywhere
+ */
+export interface ErrorResponse {
+    /** Error type identifier */
+    error: ErrorType;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code (API contexts) */
+    status?: number;
+    /** Optional additional error details */
+    details?: any;
+}
+/**
+ * Simple unified error class for both API and SDK
+ */
+export declare class ShipError extends Error {
+    readonly type: ErrorType;
+    readonly status?: number | undefined;
+    readonly details?: any | undefined;
+    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;
+    static validation(message: string, details?: any): ShipError;
+    static notFound(resource: string, id?: string): ShipError;
+    static rateLimit(message?: string): ShipError;
+    static authentication(message?: string): ShipError;
+    static business(message: string, status?: number): ShipError;
+    static network(message: string, cause?: Error): ShipError;
+    static cancelled(message: string): ShipError;
+    static file(message: string, filePath?: string): ShipError;
+    static config(message: string, details?: any): ShipError;
+    static api(message: string, status?: number, code?: string, data?: any): ShipError;
+    get filePath(): string | undefined;
+    get code(): string | undefined;
+    isClientError(): boolean;
+    isNetworkError(): boolean;
+    isAuthError(): boolean;
+    isValidationError(): boolean;
+    isFileError(): boolean;
+    isConfigError(): boolean;
+    isType(errorType: ErrorType): boolean;
+}
+/**
+ * Server-side platform configuration - enforced limits on the platform
+ */
+export declare const serverConfig: {
+    /** Maximum individual file size in bytes (10MB) */
+    readonly maxFileSize: number;
+    /** Maximum number of files per deployment */
+    readonly maxFilesCount: 1000;
+    /** Maximum total deployment size in bytes (100MB) */
+    readonly maxTotalSize: number;
+    /** Deployment expiry in hours */
+    readonly deploymentExpiryHours: 168;
+    /** Pagination limits */
+    readonly defaultLimit: 50;
+    readonly maxLimit: 100;
+};
+/**
+ * Platform configuration response from API
+ */
+export interface ConfigResponse {
+    /** Maximum individual file size in bytes */
+    maxFileSize: number;
+    /** Maximum number of files per deployment */
+    maxFilesCount: number;
+    /** Maximum total deployment size in bytes */
+    maxTotalSize: number;
+}
+/**
+ * Generic success response wrapper
+ */
+export interface SuccessResponse<T = any> {
+    /** Always true for success */
+    success: true;
+    /** Response data */
+    data: T;
+}
+/**
+ * Simple ping response for health checks
+ */
+export interface PingResponse {
+    /** Always true if service is healthy */
+    success: boolean;
+    /** Optional timestamp */
+    timestamp?: number;
+}
+export declare const API_KEY_PREFIX = "ship-";

package/dist/index.js

@@ -0,0 +1,152 @@
+/// <reference types="@cloudflare/workers-types" />
+// =============================================================================
+// ERROR SYSTEM
+// =============================================================================
+/**
+ * All possible error types in the Shipstatic platform
+ * Names are developer-friendly while wire format stays consistent
+ */
+export var ErrorType;
+(function (ErrorType) {
+    /** Validation failed (400) */
+    ErrorType["Validation"] = "validation_failed";
+    /** Resource not found (404) */
+    ErrorType["NotFound"] = "not_found";
+    /** Rate limit exceeded (429) */
+    ErrorType["RateLimit"] = "rate_limit_exceeded";
+    /** Authentication required (401) */
+    ErrorType["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";
+    /** Network/connection error */
+    ErrorType["Network"] = "network_error";
+    /** Operation was cancelled */
+    ErrorType["Cancelled"] = "operation_cancelled";
+    /** File operation error */
+    ErrorType["File"] = "file_error";
+    /** Configuration error */
+    ErrorType["Config"] = "config_error";
+})(ErrorType || (ErrorType = {}));
+/** @deprecated Use ErrorType instead. Kept for backward compatibility. */
+export const ShipErrorType = ErrorType;
+/**
+ * Categorizes error types for better type checking
+ */
+const ERROR_CATEGORIES = {
+    client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
+    network: new Set([ErrorType.Network]),
+    auth: new Set([ErrorType.Authentication]),
+};
+/**
+ * Simple unified error class for both API and SDK
+ */
+export class ShipError extends Error {
+    type;
+    status;
+    details;
+    constructor(type, message, status, details) {
+        super(message);
+        this.type = type;
+        this.status = status;
+        this.details = details;
+        this.name = 'ShipError';
+    }
+    /** Convert to wire format */
+    toResponse() {
+        return {
+            error: this.type,
+            message: this.message,
+            status: this.status,
+            details: this.details
+        };
+    }
+    /** Create from wire format */
+    static fromResponse(response) {
+        return new ShipError(response.error, response.message, response.status, response.details);
+    }
+    // Factory methods for common errors
+    static validation(message, details) {
+        return new ShipError(ErrorType.Validation, message, 400, details);
+    }
+    static notFound(resource, id) {
+        const message = id ? `${resource} ${id} not found` : `${resource} not found`;
+        return new ShipError(ErrorType.NotFound, message, 404);
+    }
+    static rateLimit(message = "Too many requests") {
+        return new ShipError(ErrorType.RateLimit, message, 429);
+    }
+    static authentication(message = "Authentication required") {
+        return new ShipError(ErrorType.Authentication, message, 401);
+    }
+    static business(message, status = 400) {
+        return new ShipError(ErrorType.Business, message, status);
+    }
+    static network(message, cause) {
+        return new ShipError(ErrorType.Network, message, undefined, { cause });
+    }
+    static cancelled(message) {
+        return new ShipError(ErrorType.Cancelled, message);
+    }
+    static file(message, filePath) {
+        return new ShipError(ErrorType.File, message, undefined, { filePath });
+    }
+    static config(message, details) {
+        return new ShipError(ErrorType.Config, message, undefined, details);
+    }
+    static api(message, status = 500, code, data) {
+        return new ShipError(ErrorType.Api, message, status, { code, data });
+    }
+    // Helper getters for accessing common detail properties
+    get filePath() {
+        return this.details?.filePath;
+    }
+    get code() {
+        return this.details?.code;
+    }
+    // Helper methods for error type checking using categorization
+    isClientError() {
+        return ERROR_CATEGORIES.client.has(this.type);
+    }
+    isNetworkError() {
+        return ERROR_CATEGORIES.network.has(this.type);
+    }
+    isAuthError() {
+        return ERROR_CATEGORIES.auth.has(this.type);
+    }
+    isValidationError() {
+        return this.type === ErrorType.Validation;
+    }
+    isFileError() {
+        return this.type === ErrorType.File;
+    }
+    isConfigError() {
+        return this.type === ErrorType.Config;
+    }
+    // Generic type checker
+    isType(errorType) {
+        return this.type === errorType;
+    }
+}
+// =============================================================================
+// CONFIGURATION CONSTANTS
+// =============================================================================
+/**
+ * Server-side platform configuration - enforced limits on the platform
+ */
+export const serverConfig = {
+    /** Maximum individual file size in bytes (10MB) */
+    maxFileSize: 10 * 1024 * 1024,
+    /** Maximum number of files per deployment */
+    maxFilesCount: 1000,
+    /** Maximum total deployment size in bytes (100MB) */
+    maxTotalSize: 100 * 1024 * 1024,
+    /** Deployment expiry in hours */
+    deploymentExpiryHours: 168, // 7 days
+    /** Pagination limits */
+    defaultLimit: 50,
+    maxLimit: 100,
+};
+// API Key Configuration
+export const API_KEY_PREFIX = 'ship-';

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@shipstatic/types",
+  "version": "0.1.0",
+  "description": "Shared types for Shipstatic platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "types",
+    "shipstatic"
+  ],
+  "author": "ShipStatic",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@cloudflare/workers-types": "^4.20241218.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,347 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * @file Shared types for Shipstatic platform
+ * Simple, clean types that both API and SDK agree on
+ */
+
+// =============================================================================
+// DEPLOYMENT TYPES
+// =============================================================================
+
+/**
+ * Core deployment object - used in both API responses and SDK
+ */
+export interface Deployment {
+  /** The deployment ID */
+  deployment: string;
+  /** Number of files in this deployment */
+  filesCount: number;
+  /** Total size of all files in bytes */
+  totalSize: number;
+  /** Current deployment status */
+  status: 'pending' | 'success' | 'failed';
+  /** Unix timestamp (seconds) when deployment was created */
+  createdAt: number;
+  /** Unix timestamp (seconds) when deployment expires */
+  expiresAt?: number;
+  /** Unix timestamp (seconds) when deployment was verified */
+  verifiedAt?: number;
+}
+
+
+/**
+ * Response for listing deployments
+ */
+export interface DeploymentListResponse {
+  /** Array of deployments */
+  deployments: Deployment[];
+  /** Optional cursor for pagination */
+  cursor?: string;
+  /** Total number of deployments if available */
+  total?: number;
+}
+
+// =============================================================================
+// ALIAS TYPES
+// =============================================================================
+
+/**
+ * Core alias object - used in both API responses and SDK
+ */
+export interface Alias {
+  /** The alias name */
+  alias: string;
+  /** The deployment name this alias points to */
+  deploymentName: string;
+  /** Current alias status */
+  status: 'pending' | 'success' | 'failed';
+  /** Unix timestamp (seconds) when alias was created */
+  createdAt: number;
+  /** Unix timestamp (seconds) when alias was confirmed */
+  confirmedAt?: number;
+}
+
+/**
+ * Response for listing aliases
+ */
+export interface AliasListResponse {
+  /** Array of aliases */
+  aliases: Alias[];
+  /** Optional cursor for pagination */
+  cursor?: string;
+  /** Total number of aliases if available */
+  total?: number;
+}
+
+/**
+ * Response for deployment removal
+ */
+export interface DeploymentRemoveResponse {
+  /** Operation success status */
+  success: boolean;
+  /** The deployment ID */
+  deployment: string;
+  /** Human-readable message */
+  message?: string;
+}
+
+// =============================================================================
+// ACCOUNT TYPES
+// =============================================================================
+
+/**
+ * Core account object - used in both API responses and SDK
+ */
+export interface Account {
+  /** User email address */
+  email: string;
+  /** User display name */
+  name: string;
+  /** User profile picture URL */
+  picture?: string;
+  /** Account subscription status */
+  subscription: 'free' | 'active' | 'suspended';
+  /** Unix timestamp (seconds) when account was created */
+  createdAt: number;
+  /** Unix timestamp (seconds) when subscription started */
+  subscribedAt?: number;
+  /** Unix timestamp (seconds) when account was suspended */
+  suspendedAt?: number;
+}
+
+// =============================================================================
+// ERROR SYSTEM
+// =============================================================================
+
+/**
+ * All possible error types in the Shipstatic platform
+ * Names are developer-friendly while wire format stays consistent
+ */
+export enum ErrorType {
+  /** Validation failed (400) */
+  Validation = "validation_failed",
+  /** Resource not found (404) */
+  NotFound = "not_found", 
+  /** Rate limit exceeded (429) */
+  RateLimit = "rate_limit_exceeded",
+  /** Authentication required (401) */
+  Authentication = "authentication_failed",
+  /** Business logic error (400) */
+  Business = "business_logic_error",
+  /** API server error (500) - renamed from Internal for clarity */
+  Api = "internal_server_error",
+  /** Network/connection error */
+  Network = "network_error",
+  /** Operation was cancelled */
+  Cancelled = "operation_cancelled",
+  /** File operation error */
+  File = "file_error",
+  /** Configuration error */
+  Config = "config_error"
+}
+
+/** @deprecated Use ErrorType instead. Kept for backward compatibility. */
+export const ShipErrorType = ErrorType;
+
+/**
+ * Categorizes error types for better type checking
+ */
+const ERROR_CATEGORIES = {
+  client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
+  network: new Set([ErrorType.Network]),
+  auth: new Set([ErrorType.Authentication]),
+} as const;
+
+/**
+ * Standard error response format used everywhere
+ */
+export interface ErrorResponse {
+  /** Error type identifier */
+  error: ErrorType;
+  /** Human-readable error message */
+  message: string;
+  /** HTTP status code (API contexts) */
+  status?: number;
+  /** Optional additional error details */
+  details?: any;
+}
+
+/**
+ * Simple unified error class for both API and SDK
+ */
+export class ShipError extends Error {
+  constructor(
+    public readonly type: ErrorType,
+    message: string,
+    public readonly status?: number,
+    public readonly details?: any
+  ) {
+    super(message);
+    this.name = 'ShipError';
+  }
+
+  /** Convert to wire format */
+  toResponse(): ErrorResponse {
+    return {
+      error: this.type,
+      message: this.message,
+      status: this.status,
+      details: this.details
+    };
+  }
+
+  /** Create from wire format */
+  static fromResponse(response: ErrorResponse): ShipError {
+    return new ShipError(response.error, response.message, response.status, response.details);
+  }
+
+  // Factory methods for common errors
+  static validation(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.Validation, message, 400, details);
+  }
+
+  static notFound(resource: string, id?: string): ShipError {
+    const message = id ? `${resource} ${id} not found` : `${resource} not found`;
+    return new ShipError(ErrorType.NotFound, message, 404);
+  }
+
+  static rateLimit(message: string = "Too many requests"): ShipError {
+    return new ShipError(ErrorType.RateLimit, message, 429);
+  }
+
+  static authentication(message: string = "Authentication required"): ShipError {
+    return new ShipError(ErrorType.Authentication, message, 401);
+  }
+
+
+  static business(message: string, status: number = 400): ShipError {
+    return new ShipError(ErrorType.Business, message, status);
+  }
+
+  static network(message: string, cause?: Error): ShipError {
+    return new ShipError(ErrorType.Network, message, undefined, { cause });
+  }
+
+  static cancelled(message: string): ShipError {
+    return new ShipError(ErrorType.Cancelled, message);
+  }
+
+  static file(message: string, filePath?: string): ShipError {
+    return new ShipError(ErrorType.File, message, undefined, { filePath });
+  }
+
+  static config(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.Config, message, undefined, details);
+  }
+
+  static api(message: string, status: number = 500, code?: string, data?: any): ShipError {
+    return new ShipError(ErrorType.Api, message, status, { code, data });
+  }
+
+  // Helper getters for accessing common detail properties
+  get filePath(): string | undefined {
+    return this.details?.filePath;
+  }
+
+  get code(): string | undefined {
+    return this.details?.code;
+  }
+
+  // Helper methods for error type checking using categorization
+  isClientError(): boolean {
+    return ERROR_CATEGORIES.client.has(this.type);
+  }
+
+  isNetworkError(): boolean {
+    return ERROR_CATEGORIES.network.has(this.type);
+  }
+
+  isAuthError(): boolean {
+    return ERROR_CATEGORIES.auth.has(this.type);
+  }
+
+  isValidationError(): boolean {
+    return this.type === ErrorType.Validation;
+  }
+
+  isFileError(): boolean {
+    return this.type === ErrorType.File;
+  }
+
+  isConfigError(): boolean {
+    return this.type === ErrorType.Config;
+  }
+
+  // Generic type checker
+  isType(errorType: ErrorType): boolean {
+    return this.type === errorType;
+  }
+}
+
+// =============================================================================
+// CONFIGURATION CONSTANTS
+// =============================================================================
+
+/**
+ * Server-side platform configuration - enforced limits on the platform
+ */
+export const serverConfig = {
+  /** Maximum individual file size in bytes (10MB) */
+  maxFileSize: 10 * 1024 * 1024,
+  /** Maximum number of files per deployment */
+  maxFilesCount: 1000,
+  /** Maximum total deployment size in bytes (100MB) */
+  maxTotalSize: 100 * 1024 * 1024,
+  /** Deployment expiry in hours */
+  deploymentExpiryHours: 168, // 7 days
+  /** Pagination limits */
+  defaultLimit: 50,
+  maxLimit: 100,
+} as const;
+
+
+
+// =============================================================================
+// CONFIG TYPES
+// =============================================================================
+
+/**
+ * Platform configuration response from API
+ */
+export interface ConfigResponse {
+  /** Maximum individual file size in bytes */
+  maxFileSize: number;
+  /** Maximum number of files per deployment */
+  maxFilesCount: number;
+  /** Maximum total deployment size in bytes */
+  maxTotalSize: number;
+}
+
+// =============================================================================
+// COMMON RESPONSE PATTERNS  
+// =============================================================================
+
+/**
+ * Generic success response wrapper
+ */
+export interface SuccessResponse<T = any> {
+  /** Always true for success */
+  success: true;
+  /** Response data */
+  data: T;
+}
+
+/**
+ * Simple ping response for health checks
+ */
+export interface PingResponse {
+  /** Always true if service is healthy */
+  success: boolean;
+  /** Optional timestamp */
+  timestamp?: number;
+}
+
+
+// API Key Configuration
+export const API_KEY_PREFIX = 'ship-';