@shipstatic/types 0.3.21 → 0.4.1

package/README.md

@@ -1,371 +1,87 @@
 # @shipstatic/types
 
-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.
+Shared TypeScript types for the Shipstatic platform.
 
-## Overview
+Single source of truth for types used across API, SDK, CLI, and web applications.
 
-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 Entities
-
-### Deployment
-
-```typescript
-interface Deployment {
-  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';
-  url: string;                 // Alias URL
-  created: number;             // Unix timestamp (seconds)
-  confirmed?: number;          // Unix timestamp (seconds) when confirmed
-  isCreate?: boolean;          // Present in set operations only
-}
-```
-
-### Account
-
-```typescript
-interface Account {
-  email: string;               // User email address
-  name: string;                // User display name
-  picture?: string;            // Profile picture URL
-  plan: 'free' | 'standard' | 'sponsored' | 'enterprise' | 'suspended' | 'terminating' | 'terminated';  // Account plan status
-  created: number;             // Unix timestamp (seconds)
-}
-```
-
-### 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
-}
-```
-
-## API Response Types
-
-### Success Responses
-
-```typescript
-interface DeploymentListResponse {
-  deployments: Deployment[];
-  cursor?: string;             // Pagination cursor
-  total?: number;              // Total count if available
-}
-
-interface AliasListResponse {
-  aliases: Alias[];
-  cursor?: string;
-  total?: number;
-}
-
-interface SuccessResponse<T = any> {
-  success: true;
-  data: T;
-}
-```
-
-### Configuration
-
-```typescript
-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;
-}
-```
-
-### SPA Detection
+## Installation
 
-```typescript
-interface SPACheckRequest {
-  files: string[];             // Array of file paths
-  index: string;               // Index file path
-}
+```bash
+# Included with Ship SDK
+npm install @shipstatic/ship
 
-interface SPACheckResponse {
-  isSPA: boolean;              // Whether it's detected as SPA
-  debug: {
-    tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
-    reason: string;
-  };
-}
+# Direct installation
+npm install @shipstatic/types
 ```
 
-## Resource Interface Contracts
+## What's Included
 
-These interfaces define the contracts that all SDK implementations must follow:
+### Core Entities
 
 ```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 }>;
-}
+import type { Deployment, Domain, Account, Token, StaticFile } from '@shipstatic/types';
 ```
 
-## Error System
-
-### Unified Error Handling
+### Error System
 
 ```typescript
-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"
-}
+import { ShipError, ErrorType } from '@shipstatic/types';
 
-interface ErrorResponse {
-  error: ErrorType;
-  message: string;
-  status?: number;
-  details?: any;
-}
+throw ShipError.validation('File too large');
+throw ShipError.notFound('Deployment', id);
 
-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 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;
-}
+if (error.isClientError()) { /* handle */ }
 ```
 
-## Platform Constants
+### API Response Types
 
 ```typescript
-// 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: 120,           // 5 days
-  defaultLimit: 50,                     // Pagination default
-  maxLimit: 100,                        // Pagination maximum
-} 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
+import type {
+  DeploymentListResponse,
+  DomainListResponse,
+  ConfigResponse,
+  BillingStatus
+} from '@shipstatic/types';
 ```
 
-## Upload Types
+### Resource Contracts
 
-```typescript
-enum UploadStatus {
-  PENDING = 'pending',
-  SUCCESS = 'success',
-  FAILED = 'failed',
-  DELETING = 'deleting'
-}
-
-interface UploadedFile {
-  key: string;                 // Storage key
-  etag: string;                // ETag from storage
-  size: number;                // File size in bytes
-  validated?: boolean;         // Whether file was validated
-}
-
-interface RateLimitData {
-  count: number;               // Current request count
-  timestamp: number;           // Window start timestamp
-}
-```
-
-## Validation Utilities
+SDK interface definitions:
 
 ```typescript
-// Validate API key format
-function validateApiKey(apiKey: string): void;
-
-// Validate deploy token format  
-function validateDeployToken(deployToken: string): void;
-
-// Validate API URL format
-function validateApiUrl(apiUrl: string): void;
-
-// Validate deployment subdomain format
-function validateSubdomain(input: string): boolean;
+import type { DeploymentResource, DomainResource, AccountResource } from '@shipstatic/types';
 ```
 
-## URL Generation
+### Validation Utilities
 
 ```typescript
-// Generate deployment URL
-function generateDeploymentUrl(deployment: string, sitesDomain?: string): string;
-
-// Generate alias URL (handles both subdomains and custom domains)
-function generateAliasUrl(alias: string, sitesDomain?: string): string;
+import { validateApiKey, validateDeployToken, validateSubdomain } from '@shipstatic/types';
 ```
 
-## Usage Examples
-
-### In the API
+### Constants
 
 ```typescript
-import { 
-  serverConfig, 
-  ShipError, 
-  type ConfigResponse,
-  type Deployment 
+import {
+  DEFAULT_API,
+  API_KEY_PREFIX,
+  DeploymentStatus,
+  DomainStatus,
+  AccountPlan
 } from '@shipstatic/types';
-
-// Use shared configuration
-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 the SDK
+## Usage
 
 ```typescript
-import { 
-  ShipError, 
-  type ConfigResponse, 
-  type DeploymentListResponse,
-  generateDeploymentUrl
-} from '@shipstatic/types';
-
-// Handle API responses
-const deployments: DeploymentListResponse = await api.listDeployments();
+import { ShipError, type Deployment, DeploymentStatus } from '@shipstatic/types';
 
-// Generate URLs consistently
-const url = generateDeploymentUrl('happy-cat-abc1234');
-
-// Handle errors consistently
-try {
-  const result = await deploy(files);
-} catch (error) {
-  if (error instanceof ShipError && error.isClientError()) {
-    // Handle client errors
+function processDeployment(deployment: Deployment) {
+  if (deployment.status === DeploymentStatus.FAILED) {
+    throw ShipError.business('Deployment failed');
   }
 }
 ```
 
-## Installation
-
-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
-```
-
-## Architecture
-
-### Design Principles
-
-- **Single source of truth** - All types defined once, used everywhere
-- **Type safety** - Strict TypeScript with comprehensive validation
-- **Wire format compatibility** - Types match actual API contracts
-- **Error consistency** - Unified error handling across all components
-- **Platform contracts** - Resource interfaces define SDK behavior
-
-### Type Organization
-
-All types are organized in a single `src/index.ts` file by category:
-
-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:
-
-- **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
-
-The result is type-safe development across the entire Shipstatic platform with guaranteed consistency between API, SDK, and CLI components.
-
----
+## License
 
-**@shipstatic/types** - The foundation of type safety for Shipstatic 🚢
+MIT

package/dist/index.d.ts

@@ -464,30 +464,47 @@ export declare const DEFAULT_API = "https://api.shipstatic.com";
  * Node.js: string | string[] - file/directory paths
  */
 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.).
+ */
+export interface DeploymentCreateOptions {
+    /** Optional tags for categorization and filtering */
+    tags?: string[];
+    /** Optional subdomain suggestion for the deployment */
+    subdomain?: string;
+    /** Client identifier (e.g., 'cli', 'sdk', 'web') */
+    via?: string;
+}
 /**
  * Deployment resource interface - the contract all implementations must follow
  */
 export interface DeploymentResource {
-    create: (input: DeployInput, options?: any) => Promise<Deployment>;
+    create: (input: DeployInput, options?: DeploymentCreateOptions) => Promise<Deployment>;
     list: () => Promise<DeploymentListResponse>;
-    remove: (id: string) => Promise<void>;
     get: (id: string) => Promise<Deployment>;
+    set: (id: string, options: {
+        tags: string[];
+    }) => Promise<Deployment>;
+    remove: (id: string) => Promise<void>;
 }
 /**
  * Domain resource interface - the contract all implementations must follow
  */
 export interface DomainResource {
-    set: (domainName: string, deployment?: string, tags?: string[]) => Promise<Domain>;
-    update: (domainName: string, tags: string[]) => Promise<Domain>;
-    get: (domainName: string) => Promise<Domain>;
+    set: (name: string, options?: {
+        deployment?: string;
+        tags?: string[];
+    }) => Promise<Domain>;
     list: () => Promise<DomainListResponse>;
-    remove: (domainName: string) => Promise<void>;
-    verify: (domainName: string) => Promise<{
+    get: (name: string) => Promise<Domain>;
+    remove: (name: string) => Promise<void>;
+    verify: (name: string) => Promise<{
         message: string;
     }>;
-    dns: (domainName: string) => Promise<DomainDnsResponse>;
-    records: (domainName: string) => Promise<DomainRecordsResponse>;
-    share: (domainName: string) => Promise<{
+    dns: (name: string) => Promise<DomainDnsResponse>;
+    records: (name: string) => Promise<DomainRecordsResponse>;
+    share: (name: string) => Promise<{
         domain: string;
         hash: string;
     }>;
@@ -502,7 +519,10 @@ export interface AccountResource {
  * Token resource interface - the contract all implementations must follow
  */
 export interface TokenResource {
-    create: (ttl?: number, tags?: string[]) => Promise<TokenCreateResponse>;
+    create: (options?: {
+        ttl?: number;
+        tags?: string[];
+    }) => Promise<TokenCreateResponse>;
     list: () => Promise<TokenListResponse>;
     remove: (token: string) => Promise<void>;
 }

package/package.json

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

package/src/index.ts

@@ -716,29 +716,42 @@ export const DEFAULT_API = 'https://api.shipstatic.com';
  */
 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.).
+ */
+export interface DeploymentCreateOptions {
+  /** Optional tags for categorization and filtering */
+  tags?: string[];
+  /** Optional subdomain suggestion for the deployment */
+  subdomain?: string;
+  /** Client identifier (e.g., 'cli', 'sdk', 'web') */
+  via?: string;
+}
+
 /**
  * Deployment resource interface - the contract all implementations must follow
  */
 export interface DeploymentResource {
-  create: (input: DeployInput, options?: any) => Promise<Deployment>;
+  create: (input: DeployInput, options?: DeploymentCreateOptions) => Promise<Deployment>;
   list: () => Promise<DeploymentListResponse>;
-  remove: (id: string) => Promise<void>;
   get: (id: string) => Promise<Deployment>;
+  set: (id: string, options: { tags: string[] }) => Promise<Deployment>;
+  remove: (id: string) => Promise<void>;
 }
 
 /**
  * Domain resource interface - the contract all implementations must follow
  */
 export interface DomainResource {
-  set: (domainName: string, deployment?: string, tags?: string[]) => Promise<Domain>;
-  update: (domainName: string, tags: string[]) => Promise<Domain>;
-  get: (domainName: string) => Promise<Domain>;
+  set: (name: string, options?: { deployment?: string; tags?: string[] }) => Promise<Domain>;
   list: () => Promise<DomainListResponse>;
-  remove: (domainName: string) => Promise<void>;
-  verify: (domainName: string) => Promise<{ message: string }>;
-  dns: (domainName: string) => Promise<DomainDnsResponse>;
-  records: (domainName: string) => Promise<DomainRecordsResponse>;
-  share: (domainName: string) => Promise<{ domain: string; hash: string }>;
+  get: (name: string) => Promise<Domain>;
+  remove: (name: string) => Promise<void>;
+  verify: (name: string) => Promise<{ message: string }>;
+  dns: (name: string) => Promise<DomainDnsResponse>;
+  records: (name: string) => Promise<DomainRecordsResponse>;
+  share: (name: string) => Promise<{ domain: string; hash: string }>;
 }
 
 /**
@@ -752,7 +765,7 @@ export interface AccountResource {
  * Token resource interface - the contract all implementations must follow
  */
 export interface TokenResource {
-  create: (ttl?: number, tags?: string[]) => Promise<TokenCreateResponse>;
+  create: (options?: { ttl?: number; tags?: string[] }) => Promise<TokenCreateResponse>;
   list: () => Promise<TokenListResponse>;
   remove: (token: string) => Promise<void>;
 }