@shipstatic/types 0.1.14 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
-# Shipstatic Types
+# @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.
+Shared TypeScript types, constants, and utilities for the Shipstatic platform. This package is the single source of truth for all shared data structures used across the API, SDK, and CLI.
 
 ## Overview
 
@@ -9,82 +9,146 @@ This package contains all shared types used between:
 - **Shipstatic SDK** (`/ship`) - Universal SDK for Node.js and Browser
 - **Shipstatic CLI** - Command-line interface
 
-## Core Types
+## Core Entities
 
-### Deployment Types
+### Deployment
 
 ```typescript
-// Core deployment object
 interface Deployment {
-  deployment: string;         // Deployment ID
-  files: number;             // Number of files
-  size: number;              // Total size in bytes
+  deployment: string;           // Deployment ID (e.g., "happy-cat-abc1234")
+  files: number;               // Number of files in deployment
+  size: number;                // Total size in bytes
+  status: 'pending' | 'success' | 'failed' | 'deleting';
+  config?: boolean;            // Whether deployment has ship.json
+  url: string;                 // Deployment URL
+  created: number;             // Unix timestamp (seconds)
+  expires?: number;            // Unix timestamp (seconds)
+  verified?: number;           // Unix timestamp (seconds) when verified
+}
+```
+
+### Alias
+
+```typescript
+interface Alias {
+  alias: string;               // Alias name (subdomain or custom domain)
+  deployment: string;          // Target deployment ID
   status: 'pending' | 'success' | 'failed';
-  created: number;           // Unix timestamp
-  expires?: number;          // Unix timestamp
-  verified?: number;         // Unix timestamp
+  url: string;                 // Alias URL
+  created: number;             // Unix timestamp (seconds)
+  confirmed?: number;          // Unix timestamp (seconds) when confirmed
+  isCreate?: boolean;          // Present in set operations only
 }
+```
 
-// Successful deployment response
-interface DeploySuccessResponse {
-  success: true;
-  deployment: string;
-  expires: number;
-  files: number;
-  size: number;
+### Account
+
+```typescript
+interface Account {
+  email: string;               // User email address
+  name: string;                // User display name
+  picture?: string;            // Profile picture URL
+  plan: 'free' | 'active' | 'suspended';  // Account plan status
+  created: number;             // Unix timestamp (seconds)
+  subscribed?: number;         // Unix timestamp (seconds) when plan started
+  suspended?: number;          // Unix timestamp (seconds) when suspended
 }
+```
 
-// Deployment list response
-interface DeploymentListResponse {
-  deployments: Deployment[];
-  cursor?: string;
-  total?: number;
+### Static File
+
+```typescript
+interface StaticFile {
+  content: File | Buffer | Blob;  // File content
+  path: string;                   // Server path (e.g., "assets/style.css")
+  filePath?: string;              // Original filesystem path (Node.js)
+  md5?: string;                   // MD5 hash of content
+  size: number;                   // File size in bytes
 }
 ```
 
-### Alias Types
+## API Response Types
+
+### Success Responses
 
 ```typescript
-// Core alias object
-interface Alias {
-  alias: string;             // Alias name
-  deployment: string;        // Target deployment ID
-  status: 'pending' | 'success' | 'failed';
-  created: number;           // Unix timestamp
-  confirmed?: number;        // Unix timestamp
+interface DeploymentListResponse {
+  deployments: Deployment[];
+  cursor?: string;             // Pagination cursor
+  total?: number;              // Total count if available
 }
 
-// Alias list response
 interface AliasListResponse {
   aliases: Alias[];
   cursor?: string;
   total?: number;
 }
+
+interface SuccessResponse<T = any> {
+  success: true;
+  data: T;
+}
 ```
 
-### Account Types
+### Configuration
 
 ```typescript
-// Core account object
-interface Account {
-  email: string;
-  name: string;
-  picture?: string;
-  subscription: 'free' | 'active' | 'suspended';
-  created: number;           // Unix timestamp
-  subscribed?: number;       // Unix timestamp
-  suspended?: number;        // Unix timestamp
+interface ConfigResponse {
+  maxFileSize: number;         // Maximum file size in bytes
+  maxFilesCount: number;       // Maximum files per deployment
+  maxTotalSize: number;        // Maximum total deployment size
+}
+
+interface PlatformConfig {
+  apiUrl?: string;
+  deployToken?: string;
+  apiKey?: string;
 }
 ```
 
-### Platform Configuration
+### SPA Detection
 
 ```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
+interface SPACheckRequest {
+  files: string[];             // Array of file paths
+  index: string;               // Index file path
+}
+
+interface SPACheckResponse {
+  isSPA: boolean;              // Whether it's detected as SPA
+  debug: {
+    tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
+    reason: string;
+  };
+}
+```
+
+## Resource Interface Contracts
+
+These interfaces define the contracts that all SDK implementations must follow:
+
+```typescript
+interface DeploymentResource {
+  create: (input: DeployInput, options?: any) => Promise<Deployment>;
+  list: () => Promise<DeploymentListResponse>;
+  remove: (id: string) => Promise<void>;
+  get: (id: string) => Promise<Deployment>;
+}
+
+interface AliasResource {
+  set: (aliasName: string, deployment: string) => Promise<Alias>;
+  get: (aliasName: string) => Promise<Alias>;
+  list: () => Promise<AliasListResponse>;
+  remove: (aliasName: string) => Promise<void>;
+  check: (aliasName: string) => Promise<{ message: string }>;
+}
+
+interface AccountResource {
+  get: () => Promise<Account>;
+}
+
+interface KeysResource {
+  create: () => Promise<{ apiKey: string }>;
 }
 ```
 
@@ -93,7 +157,6 @@ interface ConfigResponse {
 ### Unified Error Handling
 
 ```typescript
-// All possible error types
 enum ErrorType {
   Validation = "validation_failed",
   NotFound = "not_found",
@@ -107,7 +170,6 @@ enum ErrorType {
   Config = "config_error"
 }
 
-// Standard error response format
 interface ErrorResponse {
   error: ErrorType;
   message: string;
@@ -115,7 +177,6 @@ interface ErrorResponse {
   details?: any;
 }
 
-// Unified error class for both API and SDK
 class ShipError extends Error {
   constructor(
     public readonly type: ErrorType,
@@ -128,72 +189,102 @@ class ShipError extends Error {
   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;
+  static business(message: string, status?: number): ShipError;
+  static network(message: string, cause?: Error): ShipError;
+  static api(message?: string, status?: number): ShipError;
   
   // Helper methods
   isClientError(): boolean;
   isNetworkError(): boolean;
   isAuthError(): boolean;
+  toResponse(): ErrorResponse;
 }
 ```
 
-## Platform Configuration
-
-### Shared Constants
+## Platform 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,
+// API configuration
+const DEFAULT_API = 'https://api.shipstatic.com';
+
+// Server configuration limits
+const serverConfig = {
+  maxFileSize: 10 * 1024 * 1024,        // 10MB
+  maxFilesCount: 1000,                  // Files per deployment
+  maxTotalSize: 100 * 1024 * 1024,      // 100MB total
+  deploymentExpiryHours: 168,           // 7 days
+  defaultLimit: 50,                     // Pagination default
+  maxLimit: 100,                        // Pagination maximum
 } 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;
+// API key format validation
+const API_KEY_PREFIX = 'ship-';
+const API_KEY_HEX_LENGTH = 64;
+const API_KEY_TOTAL_LENGTH = 69; // 'ship-' + 64 hex chars
 ```
 
-### Dynamic Configuration
+## Upload Types
+
+```typescript
+enum UploadStatus {
+  PENDING = 'pending',
+  SUCCESS = 'success',
+  FAILED = 'failed',
+  DELETING = 'deleting'
+}
 
-The platform provides dynamic configuration through the API's `/config` endpoint:
+interface UploadedFile {
+  key: string;                 // Storage key
+  etag: string;                // ETag from storage
+  size: number;                // File size in bytes
+  validated?: boolean;         // Whether file was validated
+}
 
-```json
-{
-  "maxFileSize": 10485760,     // 10MB
-  "maxFilesCount": 1000,       // Files per deployment  
-  "maxTotalSize": 104857600    // 100MB total
+interface RateLimitData {
+  count: number;               // Current request count
+  timestamp: number;           // Window start timestamp
 }
 ```
 
-**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
+## Validation Utilities
+
+```typescript
+// Validate API key format
+function validateApiKey(apiKey: string): void;
+
+// Validate deploy token format  
+function validateDeployToken(deployToken: string): void;
 
-## Usage
+// Validate API URL format
+function validateApiUrl(apiUrl: string): void;
 
-### In Ship API
+// Validate deployment subdomain format
+function validateSubdomain(input: string): boolean;
+```
+
+## URL Generation
 
 ```typescript
-import { serverConfig, ShipError, type ConfigResponse } from '@shipstatic/types';
+// Generate deployment URL
+function generateDeploymentUrl(deployment: string, sitesDomain?: string): string;
 
-// Use shared configuration constants
+// Generate alias URL (handles both subdomains and custom domains)
+function generateAliasUrl(alias: string, sitesDomain?: string): string;
+```
+
+## Usage Examples
+
+### In the API
+
+```typescript
+import { 
+  serverConfig, 
+  ShipError, 
+  type ConfigResponse,
+  type Deployment 
+} from '@shipstatic/types';
+
+// Use shared configuration
 const config: ConfigResponse = {
   maxFileSize: serverConfig.maxFileSize,
   maxFilesCount: serverConfig.maxFilesCount,
@@ -201,32 +292,45 @@ const config: ConfigResponse = {
 };
 
 // Use unified error handling
-throw ShipError.validation('File too large', { maxSize: serverConfig.maxFileSize });
+throw ShipError.validation('File too large', { 
+  maxSize: serverConfig.maxFileSize 
+});
 ```
 
-### In Ship SDK
+### In the SDK
 
 ```typescript
-import { ShipError, type ConfigResponse, type DeploySuccessResponse } from '@shipstatic/types';
+import { 
+  ShipError, 
+  type ConfigResponse, 
+  type DeploymentListResponse,
+  generateDeploymentUrl
+} from '@shipstatic/types';
 
-// Receive platform configuration
-const config: ConfigResponse = await api.getConfig();
+// Handle API responses
+const deployments: DeploymentListResponse = await api.listDeployments();
+
+// Generate URLs consistently
+const url = generateDeploymentUrl('happy-cat-abc1234');
 
 // Handle errors consistently
 try {
-  const result: DeploySuccessResponse = await deploy(files);
+  const result = await deploy(files);
 } catch (error) {
-  if (error instanceof ShipError) {
-    // Handle Ship-specific errors
+  if (error instanceof ShipError && error.isClientError()) {
+    // Handle client errors
   }
 }
 ```
 
 ## Installation
 
-This package is automatically installed as a dependency of the Ship SDK and API:
+This package is automatically installed as a dependency:
 
 ```bash
+# Included with Ship SDK
+npm install @shipstatic/ship
+
 # Direct installation (if needed)
 npm install @shipstatic/types
 ```
@@ -236,40 +340,34 @@ npm install @shipstatic/types
 ### 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
+- **Type safety** - Strict TypeScript with comprehensive validation
+- **Wire format compatibility** - Types match actual API contracts
 - **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
-```
+- **Platform contracts** - Resource interfaces define SDK behavior
 
 ### Type Organization
 
-All types are organized in a single `index.ts` file by category:
+All types are organized in a single `src/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
+1. **Core entities** - Deployment, Alias, Account objects
+2. **API responses** - Response wrappers and pagination
+3. **Resource contracts** - SDK interface definitions
+4. **Error system** - Unified ShipError class and error types
+5. **Platform configuration** - Shared constants and validation
+6. **Upload types** - File handling and status enums
+7. **Utility functions** - URL generation and validation
 
 ## 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
+- **Clear contracts** - Types define platform behavior
+- **Zero duplication** - Single source prevents drift
+- **Developer experience** - Predictable, well-documented interfaces
 - **Maintainability** - Easy to update types across entire platform
 
-**Result:** Type-safe development across the entire Ship platform with zero type drift between components.
+The result is type-safe development across the entire Shipstatic platform with guaranteed consistency between API, SDK, and CLI components.
 
 ---
 
-**Ship Types** - Shared types for the Ship platform 🚢
+**@shipstatic/types** - The foundation of type safety for Shipstatic 🚢

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * @file Shared types for Shipstatic platform
- * Simple, clean types that both API and SDK agree on
+ * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * This package is the single source of truth for all shared data structures.
  */
 /**
  * Core deployment object - used in both API responses and SDK
@@ -13,7 +13,7 @@ export interface Deployment {
     /** Total size of all files in bytes */
     size: number;
     /** Current deployment status */
-    status: 'pending' | 'success' | 'failed';
+    status: 'pending' | 'success' | 'failed' | 'deleting';
     /** Whether deployment has configuration */
     config?: boolean;
     /** The deployment URL */
@@ -22,6 +22,8 @@ export interface Deployment {
     created: number;
     /** Unix timestamp (seconds) when deployment expires */
     expires?: number;
+    /** Unix timestamp (seconds) when deployment was verified and ready */
+    verified?: number;
 }
 /**
  * Response for listing deployments
@@ -150,7 +152,7 @@ export declare class ShipError extends Error {
     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 authentication(message?: string, details?: any): ShipError;
     static business(message: string, status?: number): ShipError;
     static network(message: string, cause?: Error): ShipError;
     static cancelled(message: string): ShipError;
@@ -243,7 +245,7 @@ export declare function validateSubdomain(input: string): boolean;
 export interface SPACheckRequest {
     /** Array of file paths */
     files: string[];
-    /** Raw HTML content of index.html file */
+    /** HTML content of index.html file */
     index: string;
 }
 /**
@@ -252,4 +254,124 @@ export interface SPACheckRequest {
 export interface SPACheckResponse {
     /** Whether the project is detected as a Single Page Application */
     isSPA: boolean;
+    /** Debugging information about detection */
+    debug: {
+        /** Which tier made the detection: 'exclusions', 'inclusions', 'scoring', 'ai', or 'fallback' */
+        tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
+        /** The reason for the detection result */
+        reason: string;
+    };
+}
+/**
+ * Represents a file that has been processed and is ready for deploy.
+ * Used across the platform (API, SDK, CLI) for file operations.
+ */
+export interface StaticFile {
+    /**
+     * The content of the file.
+     * In Node.js, this is typically a `Buffer`.
+     * In the browser, this is typically a `File` or `Blob` object.
+     */
+    content: File | Buffer | Blob;
+    /**
+     * The desired path for the file on the server, relative to the deployment root.
+     * Should include the filename, e.g., `images/photo.jpg`.
+     */
+    path: string;
+    /**
+     * The original absolute file system path (primarily used in Node.js environments).
+     * This helps in debugging or associating the server path back to its source.
+     */
+    filePath?: string;
+    /**
+     * The MD5 hash (checksum) of the file's content.
+     * This is calculated by the SDK before deploy if not provided.
+     */
+    md5?: string;
+    /** The size of the file in bytes. */
+    size: number;
+}
+/**
+ * Standard platform configuration format used by all clients
+ */
+export interface PlatformConfig {
+    apiUrl?: string;
+    deployToken?: string;
+    apiKey?: string;
+}
+/** Default API URL if not otherwise configured. */
+export declare const DEFAULT_API = "https://api.shipstatic.com";
+/**
+ * Universal deploy input type for all environments.
+ * - File[] | FileList: Browser environments (file upload)
+ * - string: Node.js environments (file/directory path)
+ */
+export type DeployInput = File[] | FileList | string;
+/**
+ * Deployment resource interface - the contract all implementations must follow
+ */
+export interface DeploymentResource {
+    create: (input: DeployInput, options?: any) => Promise<Deployment>;
+    list: () => Promise<DeploymentListResponse>;
+    remove: (id: string) => Promise<void>;
+    get: (id: string) => Promise<Deployment>;
+}
+/**
+ * Alias resource interface - the contract all implementations must follow
+ */
+export interface AliasResource {
+    set: (aliasName: string, deployment: string) => Promise<Alias>;
+    get: (aliasName: string) => Promise<Alias>;
+    list: () => Promise<AliasListResponse>;
+    remove: (aliasName: string) => Promise<void>;
+    check: (aliasName: string) => Promise<{
+        message: string;
+    }>;
+}
+/**
+ * Account resource interface - the contract all implementations must follow
+ */
+export interface AccountResource {
+    get: () => Promise<Account>;
+}
+/**
+ * Keys resource interface - the contract all implementations must follow
+ */
+export interface KeysResource {
+    create: () => Promise<{
+        apiKey: string;
+    }>;
+}
+/**
+ * Represents a file that has been uploaded and stored
+ */
+export interface UploadedFile {
+    key: string;
+    etag: string;
+    size: number;
+    validated?: boolean;
+}
+/**
+ * Upload/deployment status enum
+ */
+export declare enum UploadStatus {
+    PENDING = "pending",
+    SUCCESS = "success",
+    FAILED = "failed",
+    DELETING = "deleting"
+}
+/**
+ * Rate limiting data structure
+ */
+export interface RateLimitData {
+    count: number;
+    timestamp: number;
 }
+/**
+ * Generate deployment URL from deployment ID and sites domain
+ */
+export declare function generateDeploymentUrl(deployment: string, sitesDomain?: string): string;
+/**
+ * Generate alias URL based on whether it's internal (subdomain) or external (custom domain)
+ */
+export declare function generateAliasUrl(alias: string, sitesDomain?: string): string;

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
- * @file Shared types for Shipstatic platform
- * Simple, clean types that both API and SDK agree on
+ * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * This package is the single source of truth for all shared data structures.
  */
 // =============================================================================
 // ERROR SYSTEM
@@ -58,11 +58,15 @@ export class ShipError extends Error {
     }
     /** Convert to wire format */
     toResponse() {
+        // For security, exclude internal details from authentication errors in API responses
+        const details = this.type === ErrorType.Authentication && this.details?.internal
+            ? undefined
+            : this.details;
         return {
             error: this.type,
             message: this.message,
             status: this.status,
-            details: this.details
+            details
         };
     }
     /** Create from wire format */
@@ -80,8 +84,8 @@ export class ShipError extends Error {
     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 authentication(message = "Authentication required", details) {
+        return new ShipError(ErrorType.Authentication, message, 401, details);
     }
     static business(message, status = 400) {
         return new ShipError(ErrorType.Business, message, status);
@@ -230,3 +234,40 @@ export function validateSubdomain(input) {
     // Deployment subdomain format: word-word-7chars (e.g. "happy-cat-abc1234")
     return /^[a-z]+-[a-z]+-[a-z0-9]{7}$/i.test(input);
 }
+// =============================================================================
+// PLATFORM CONSTANTS
+// =============================================================================
+/** Default API URL if not otherwise configured. */
+export const DEFAULT_API = 'https://api.shipstatic.com';
+/**
+ * Upload/deployment status enum
+ */
+export var UploadStatus;
+(function (UploadStatus) {
+    UploadStatus["PENDING"] = "pending";
+    UploadStatus["SUCCESS"] = "success";
+    UploadStatus["FAILED"] = "failed";
+    UploadStatus["DELETING"] = "deleting";
+})(UploadStatus || (UploadStatus = {}));
+// =============================================================================
+// URL GENERATION UTILITIES
+// =============================================================================
+/**
+ * Generate deployment URL from deployment ID and sites domain
+ */
+export function generateDeploymentUrl(deployment, sitesDomain) {
+    const domain = sitesDomain || 'statichost.com';
+    return `https://${deployment}.${domain}`;
+}
+/**
+ * Generate alias URL based on whether it's internal (subdomain) or external (custom domain)
+ */
+export function generateAliasUrl(alias, sitesDomain) {
+    // If alias contains dots, it's an external domain
+    if (alias.includes('.')) {
+        return `https://${alias}`;
+    }
+    // Otherwise it's an internal subdomain
+    const domain = sitesDomain || 'statichost.dev';
+    return `https://${alias}.${domain}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.1.14",
+  "version": "0.2.1",
   "description": "Shared types for Shipstatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,7 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
+    "@types/node": "^24.3.0",
     "typescript": "^5.8.3"
   },
   "scripts": {

package/src/index.ts

@@ -1,10 +1,10 @@
 /**
- * @file Shared types for Shipstatic platform
- * Simple, clean types that both API and SDK agree on
+ * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * This package is the single source of truth for all shared data structures.
  */
 
 // =============================================================================
-// DEPLOYMENT TYPES
+// I. CORE ENTITIES
 // =============================================================================
 
 /**
@@ -18,7 +18,7 @@ export interface Deployment {
   /** Total size of all files in bytes */
   size: number;
   /** Current deployment status */
-  status: 'pending' | 'success' | 'failed';
+  status: 'pending' | 'success' | 'failed' | 'deleting';
   /** Whether deployment has configuration */
   config?: boolean;
   /** The deployment URL */
@@ -27,6 +27,8 @@ export interface Deployment {
   created: number;
   /** Unix timestamp (seconds) when deployment expires */
   expires?: number;
+  /** Unix timestamp (seconds) when deployment was verified and ready */
+  verified?: number;
 }
 
 
@@ -187,11 +189,16 @@ export class ShipError extends Error {
 
   /** Convert to wire format */
   toResponse(): ErrorResponse {
+    // For security, exclude internal details from authentication errors in API responses
+    const details = this.type === ErrorType.Authentication && this.details?.internal 
+      ? undefined 
+      : this.details;
+      
     return {
       error: this.type,
       message: this.message,
       status: this.status,
-      details: this.details
+      details
     };
   }
 
@@ -214,8 +221,8 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.RateLimit, message, 429);
   }
 
-  static authentication(message: string = "Authentication required"): ShipError {
-    return new ShipError(ErrorType.Authentication, message, 401);
+  static authentication(message: string = "Authentication required", details?: any): ShipError {
+    return new ShipError(ErrorType.Authentication, message, 401, details);
   }
 
 
@@ -452,7 +459,7 @@ export function validateSubdomain(input: string): boolean {
 export interface SPACheckRequest {
   /** Array of file paths */
   files: string[];
-  /** Raw HTML content of index.html file */
+  /** HTML content of index.html file */
   index: string;
 }
 
@@ -462,4 +469,169 @@ export interface SPACheckRequest {
 export interface SPACheckResponse {
   /** Whether the project is detected as a Single Page Application */
   isSPA: boolean;
+  /** Debugging information about detection */
+  debug: {
+    /** Which tier made the detection: 'exclusions', 'inclusions', 'scoring', 'ai', or 'fallback' */
+    tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
+    /** The reason for the detection result */
+    reason: string;
+  };
+}
+
+// =============================================================================
+// STATIC FILE REPRESENTATION
+// =============================================================================
+
+/**
+ * Represents a file that has been processed and is ready for deploy.
+ * Used across the platform (API, SDK, CLI) for file operations.
+ */
+export interface StaticFile {
+  /**
+   * The content of the file.
+   * In Node.js, this is typically a `Buffer`.
+   * In the browser, this is typically a `File` or `Blob` object.
+   */
+  content: File | Buffer | Blob;
+  /**
+   * The desired path for the file on the server, relative to the deployment root.
+   * Should include the filename, e.g., `images/photo.jpg`.
+   */
+  path: string;
+  /**
+   * The original absolute file system path (primarily used in Node.js environments).
+   * This helps in debugging or associating the server path back to its source.
+   */
+  filePath?: string;
+  /**
+   * The MD5 hash (checksum) of the file's content.
+   * This is calculated by the SDK before deploy if not provided.
+   */
+  md5?: string;
+  /** The size of the file in bytes. */
+  size: number;
+}
+
+// =============================================================================
+// PLATFORM CONFIGURATION
+// =============================================================================
+
+/**
+ * Standard platform configuration format used by all clients
+ */
+export interface PlatformConfig {
+  apiUrl?: string;
+  deployToken?: string;
+  apiKey?: string;
+}
+
+// =============================================================================
+// PLATFORM CONSTANTS
+// =============================================================================
+
+/** Default API URL if not otherwise configured. */
+export const DEFAULT_API = 'https://api.shipstatic.com';
+
+// =============================================================================
+// RESOURCE INTERFACE CONTRACTS
+// =============================================================================
+
+/**
+ * Universal deploy input type for all environments.
+ * - File[] | FileList: Browser environments (file upload)
+ * - string: Node.js environments (file/directory path)
+ */
+export type DeployInput = File[] | FileList | string;
+
+/**
+ * Deployment resource interface - the contract all implementations must follow
+ */
+export interface DeploymentResource {
+  create: (input: DeployInput, options?: any) => Promise<Deployment>;
+  list: () => Promise<DeploymentListResponse>;
+  remove: (id: string) => Promise<void>;
+  get: (id: string) => Promise<Deployment>;
+}
+
+/**
+ * Alias resource interface - the contract all implementations must follow
+ */
+export interface AliasResource {
+  set: (aliasName: string, deployment: string) => Promise<Alias>;
+  get: (aliasName: string) => Promise<Alias>;
+  list: () => Promise<AliasListResponse>;
+  remove: (aliasName: string) => Promise<void>;
+  check: (aliasName: string) => Promise<{ message: string }>;
+}
+
+/**
+ * Account resource interface - the contract all implementations must follow
+ */
+export interface AccountResource {
+  get: () => Promise<Account>;
+}
+
+/**
+ * Keys resource interface - the contract all implementations must follow
+ */
+export interface KeysResource {
+  create: () => Promise<{ apiKey: string }>;
+}
+
+// =============================================================================
+// FILE UPLOAD TYPES
+// =============================================================================
+
+/**
+ * Represents a file that has been uploaded and stored
+ */
+export interface UploadedFile {
+  key: string;
+  etag: string;
+  size: number;
+  validated?: boolean;
+}
+
+/**
+ * Upload/deployment status enum
+ */
+export enum UploadStatus {
+  PENDING = 'pending',
+  SUCCESS = 'success',
+  FAILED = 'failed',
+  DELETING = 'deleting'
+}
+
+/**
+ * Rate limiting data structure
+ */
+export interface RateLimitData {
+  count: number;
+  timestamp: number;
+}
+
+// =============================================================================
+// URL GENERATION UTILITIES
+// =============================================================================
+
+/**
+ * Generate deployment URL from deployment ID and sites domain
+ */
+export function generateDeploymentUrl(deployment: string, sitesDomain?: string): string {
+  const domain = sitesDomain || 'statichost.com';
+  return `https://${deployment}.${domain}`;
+}
+
+/**
+ * Generate alias URL based on whether it's internal (subdomain) or external (custom domain)
+ */
+export function generateAliasUrl(alias: string, sitesDomain?: string): string {
+  // If alias contains dots, it's an external domain
+  if (alias.includes('.')) {
+    return `https://${alias}`;
+  }
+  
+  // Otherwise it's an internal subdomain
+  const domain = sitesDomain || 'statichost.dev';
+  return `https://${alias}.${domain}`;
 }