@shipstatic/types 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -25,19 +25,17 @@ export interface Deployment {
     /** Current deployment status */
     status: DeploymentStatusType;
     /** Whether deployment has configuration */
-    readonly config?: boolean;
-    /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-    labels?: string[];
-    /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli') */
-    readonly via?: string;
+    readonly config: boolean;
+    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+    labels: string[];
+    /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+    readonly via: string | null;
     /** The deployment URL */
     readonly url: string;
     /** Unix timestamp (seconds) when deployment was created */
     readonly created: number;
-    /** Unix timestamp (seconds) when deployment expires */
-    expires?: number;
-    /** Short-lived JWT token for claiming this deployment (only present for public deployments) */
-    claimToken?: string;
+    /** Unix timestamp (seconds) when deployment expires, null if never */
+    expires: number | null;
 }
 /**
  * Response for listing deployments
@@ -45,10 +43,10 @@ export interface Deployment {
 export interface DeploymentListResponse {
     /** Array of deployments */
     deployments: Deployment[];
-    /** Optional cursor for pagination */
-    cursor?: string;
-    /** Total number of deployments if available */
-    total?: number;
+    /** Cursor for pagination, null if no more pages */
+    cursor: string | null;
+    /** Total number of deployments */
+    total: number;
 }
 /**
  * Domain status constants
@@ -75,18 +73,16 @@ export interface Domain {
     deployment: string | null;
     /** Current domain status */
     status: DomainStatusType;
-    /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-    labels?: string[];
+    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+    labels: string[];
     /** The domain URL - internal (subdomain) or external (custom domain) */
     readonly url: string;
     /** Unix timestamp (seconds) when domain was created */
     readonly created: number;
-    /** Whether this was a create (201) or update (200) operation */
-    readonly isCreate?: boolean;
-    /** When deployment was last linked (Unix timestamp, null if never) */
-    linked?: number;
+    /** When deployment was last linked (Unix timestamp), null if never linked */
+    linked: number | null;
     /** Total deployment links */
-    links?: number;
+    links: number;
 }
 /**
  * Response for listing domains
@@ -94,10 +90,10 @@ export interface Domain {
 export interface DomainListResponse {
     /** Array of domains */
     domains: Domain[];
-    /** Optional cursor for pagination */
-    cursor?: string;
-    /** Total number of domains if available */
-    total?: number;
+    /** Cursor for pagination, null if no more pages */
+    cursor: string | null;
+    /** Total number of domains */
+    total: number;
 }
 /**
  * DNS record types supported for domain configuration
@@ -118,8 +114,8 @@ export interface DnsRecord {
  * DNS provider information for a domain
  */
 export interface DnsProvider {
-    /** Provider name (e.g., "Cloudflare", "GoDaddy") */
-    name?: string;
+    /** Provider name (e.g., "Cloudflare", "GoDaddy"), null if unknown */
+    name: string | null;
 }
 /**
  * Response for domain DNS provider lookup
@@ -149,23 +145,12 @@ export interface DomainRecordsResponse {
 export interface DomainValidateResponse {
     /** Whether the domain is valid */
     valid: boolean;
-    /** Normalized domain name (only present when valid) */
-    normalized?: string;
-    /** Whether the domain is available (only present when valid) */
-    available?: boolean;
-    /** Error message (only present when invalid) */
-    error?: string;
-}
-/**
- * Response for deployment removal
- */
-export interface DeploymentRemoveResponse {
-    /** Operation success status */
-    success: boolean;
-    /** The deployment ID */
-    deployment: string;
-    /** Human-readable message */
-    message?: string;
+    /** Normalized domain name, null when invalid */
+    normalized: string | null;
+    /** Whether the domain is available, null when invalid */
+    available: boolean | null;
+    /** Error message, null when valid */
+    error: string | null;
 }
 /**
  * Deployment token for automated deployments
@@ -175,25 +160,41 @@ export interface Token {
     readonly token: string;
     /** The account this token belongs to */
     readonly account: string;
-    /** Optional IP address locking for security */
-    readonly ip?: string;
-    /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-    labels?: string[];
+    /** IP address locking for security, null if not locked */
+    readonly ip: string | null;
+    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+    labels: string[];
     /** Unix timestamp (seconds) when token was created */
     readonly created: number;
-    /** Unix timestamp (seconds) when token expires, or null for never */
-    readonly expires?: number;
-    /** Unix timestamp (seconds) when token was last used */
-    readonly used?: number;
+    /** Unix timestamp (seconds) when token expires, null for never */
+    readonly expires: number | null;
+    /** Unix timestamp (seconds) when token was last used, null if never used */
+    readonly used: number | null;
+}
+/**
+ * Token as returned by the list endpoint.
+ * Security-redacted: shows truncated prefix instead of full hash, omits account.
+ */
+export interface TokenListItem {
+    /** Truncated token prefix for identification (e.g., "hash12345678...") */
+    readonly token: string;
+    /** Labels for categorization and filtering. Always present, empty array when none. */
+    labels: string[];
+    /** Unix timestamp (seconds) when token was created */
+    readonly created: number;
+    /** Unix timestamp (seconds) when token expires, null for never */
+    readonly expires: number | null;
+    /** Unix timestamp (seconds) when token was last used, null if never used */
+    readonly used: number | null;
 }
 /**
  * Response for listing tokens
  */
 export interface TokenListResponse {
-    /** Array of tokens */
-    tokens: Token[];
-    /** Total count of tokens */
-    count?: number;
+    /** Array of tokens (security-redacted for list display) */
+    tokens: TokenListItem[];
+    /** Total number of tokens */
+    total: number;
 }
 /**
  * Response for token creation
@@ -201,10 +202,10 @@ export interface TokenListResponse {
 export interface TokenCreateResponse {
     /** The actual token value (only returned on creation) */
     token: string;
-    /** Unix timestamp (seconds) when token expires, or null for never */
-    expires?: number;
-    /** Success message */
-    message?: string;
+    /** Labels for categorization and filtering. Always present, empty array when none. */
+    labels: string[];
+    /** Unix timestamp (seconds) when token expires, null for never */
+    expires: number | null;
 }
 /**
  * Account plan constants
@@ -226,18 +227,18 @@ export type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
 export interface Account {
     /** User email address */
     readonly email: string;
-    /** User display name */
-    readonly name: string;
-    /** User profile picture URL */
-    readonly picture?: string;
+    /** User display name, null if not set */
+    readonly name: string | null;
+    /** User profile picture URL, null if not set */
+    readonly picture: string | null;
     /** Account plan status */
     readonly plan: AccountPlanType;
     /** Unix timestamp (seconds) when account was created */
     readonly created: number;
-    /** Unix timestamp (seconds) when account was activated (first deployment) */
-    readonly activated?: number;
-    /** Last 4 characters of the API key for identification (null when no key generated) */
-    readonly hint?: string;
+    /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
+    readonly activated: number | null;
+    /** Last 4 characters of the API key for identification, null when no key generated */
+    readonly hint: string | null;
 }
 /**
  * Account-specific configuration overrides
@@ -433,15 +434,6 @@ export declare const ALLOWED_MIME_TYPES: readonly ["text/html", "text/css", "tex
  * isAllowedMimeType('application/wasm') // false (not allowed)
  */
 export declare function isAllowedMimeType(mimeType: string): boolean;
-/**
- * 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
  */
@@ -653,14 +645,14 @@ export interface TokenResource {
 export interface BillingStatus {
     /** Creem billing ID, or null if no active billing */
     billing: string | null;
-    /** Number of billing units (1 unit = 1 custom domain) */
-    units?: number;
-    /** Number of custom domains currently in use */
-    usage?: number;
-    /** Billing status from Creem (active, trialing, canceled, etc.) */
-    status?: string;
-    /** Link to Creem customer portal for billing management */
-    portal?: string | null;
+    /** Number of billing units (1 unit = 1 custom domain), null if no billing */
+    units: number | null;
+    /** Number of custom domains currently in use, null if no billing */
+    usage: number | null;
+    /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
+    status: string | null;
+    /** Link to Creem customer portal for billing management, null if unavailable */
+    portal: string | null;
 }
 /**
  * Checkout session response from POST /billing/checkout
@@ -786,17 +778,6 @@ export interface ValidationIssue {
     /** Display-ready message explaining the issue */
     message: string;
 }
-/**
- * Legacy validation error structure
- *
- * @deprecated Use ValidationIssue[] from FileValidationResult instead
- */
-export interface ValidationError {
-    error: string;
-    details: string;
-    errors: string[];
-    isClientError: true;
-}
 /**
  * Minimal file interface required for validation
  */
@@ -804,7 +785,7 @@ export interface ValidatableFile {
     name: string;
     size: number;
     type: string;
-    status?: string;
+    status?: FileValidationStatusType;
     statusMessage?: string;
 }
 /**
@@ -919,10 +900,10 @@ export declare const LABEL_PATTERN: RegExp;
 export declare function serializeLabels(labels: string[] | undefined): string | null;
 /**
  * Deserialize labels from JSON string to array.
- * Returns undefined for null/empty strings.
+ * Always returns an array — empty array for null/empty/invalid input.
  *
  * @example deserializeLabels('["web","production"]') → ['web', 'production']
- * @example deserializeLabels(null) → undefined
- * @example deserializeLabels('') → undefined
+ * @example deserializeLabels(null) → []
+ * @example deserializeLabels('') → []
  */
-export declare function deserializeLabels(labelsJson: string | null): string[] | undefined;
+export declare function deserializeLabels(labelsJson: string | null): string[];

package/dist/index.js

@@ -605,20 +605,20 @@ export function serializeLabels(labels) {
 }
 /**
  * Deserialize labels from JSON string to array.
- * Returns undefined for null/empty strings.
+ * Always returns an array — empty array for null/empty/invalid input.
  *
  * @example deserializeLabels('["web","production"]') → ['web', 'production']
- * @example deserializeLabels(null) → undefined
- * @example deserializeLabels('') → undefined
+ * @example deserializeLabels(null) → []
+ * @example deserializeLabels('') → []
  */
 export function deserializeLabels(labelsJson) {
     if (!labelsJson)
-        return undefined;
+        return [];
     try {
         const parsed = JSON.parse(labelsJson);
-        return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined;
+        return Array.isArray(parsed) ? parsed : [];
     }
     catch {
-        return undefined;
+        return [];
     }
 }

package/package.json

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

package/src/index.ts

@@ -32,19 +32,17 @@ export interface Deployment {
   /** Current deployment status */
   status: DeploymentStatusType; // Mutable - can be updated
   /** Whether deployment has configuration */
-  readonly config?: boolean;
-  /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-  labels?: string[];
-  /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli') */
-  readonly via?: string;
+  readonly config: boolean;
+  /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+  labels: string[];
+  /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+  readonly via: string | null;
   /** The deployment URL */
   readonly url: string;
   /** Unix timestamp (seconds) when deployment was created */
   readonly created: number;
-  /** Unix timestamp (seconds) when deployment expires */
-  expires?: number; // Mutable - can be updated
-  /** Short-lived JWT token for claiming this deployment (only present for public deployments) */
-  claimToken?: string; // Mutable - can be updated
+  /** Unix timestamp (seconds) when deployment expires, null if never */
+  expires: number | null; // Mutable - can be updated
 }
 
 
@@ -54,10 +52,10 @@ export interface Deployment {
 export interface DeploymentListResponse {
   /** Array of deployments */
   deployments: Deployment[];
-  /** Optional cursor for pagination */
-  cursor?: string;
-  /** Total number of deployments if available */
-  total?: number;
+  /** Cursor for pagination, null if no more pages */
+  cursor: string | null;
+  /** Total number of deployments */
+  total: number;
 }
 
 // =============================================================================
@@ -91,18 +89,16 @@ export interface Domain {
   deployment: string | null; // Mutable - can be updated to point to different deployment
   /** Current domain status */
   status: DomainStatusType; // Mutable - can be updated
-  /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-  labels?: string[];
+  /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+  labels: string[];
   /** The domain URL - internal (subdomain) or external (custom domain) */
   readonly url: string;
   /** Unix timestamp (seconds) when domain was created */
   readonly created: number;
-  /** Whether this was a create (201) or update (200) operation */
-  readonly isCreate?: boolean;
-  /** When deployment was last linked (Unix timestamp, null if never) */
-  linked?: number;
+  /** When deployment was last linked (Unix timestamp), null if never linked */
+  linked: number | null;
   /** Total deployment links */
-  links?: number;
+  links: number;
 }
 
 /**
@@ -111,10 +107,10 @@ export interface Domain {
 export interface DomainListResponse {
   /** Array of domains */
   domains: Domain[];
-  /** Optional cursor for pagination */
-  cursor?: string;
-  /** Total number of domains if available */
-  total?: number;
+  /** Cursor for pagination, null if no more pages */
+  cursor: string | null;
+  /** Total number of domains */
+  total: number;
 }
 
 /**
@@ -138,8 +134,8 @@ export interface DnsRecord {
  * DNS provider information for a domain
  */
 export interface DnsProvider {
-  /** Provider name (e.g., "Cloudflare", "GoDaddy") */
-  name?: string;
+  /** Provider name (e.g., "Cloudflare", "GoDaddy"), null if unknown */
+  name: string | null;
 }
 
 /**
@@ -170,24 +166,12 @@ export interface DomainRecordsResponse {
 export interface DomainValidateResponse {
   /** Whether the domain is valid */
   valid: boolean;
-  /** Normalized domain name (only present when valid) */
-  normalized?: string;
-  /** Whether the domain is available (only present when valid) */
-  available?: boolean;
-  /** Error message (only present when invalid) */
-  error?: string;
-}
-
-/**
- * Response for deployment removal
- */
-export interface DeploymentRemoveResponse {
-  /** Operation success status */
-  success: boolean;
-  /** The deployment ID */
-  deployment: string;
-  /** Human-readable message */
-  message?: string;
+  /** Normalized domain name, null when invalid */
+  normalized: string | null;
+  /** Whether the domain is available, null when invalid */
+  available: boolean | null;
+  /** Error message, null when valid */
+  error: string | null;
 }
 
 // =============================================================================
@@ -202,26 +186,43 @@ export interface Token {
   readonly token: string;
   /** The account this token belongs to */
   readonly account: string;
-  /** Optional IP address locking for security */
-  readonly ip?: string;
-  /** Optional array of labels for categorization and filtering (lowercase, alphanumeric with separators) */
-  labels?: string[];
+  /** IP address locking for security, null if not locked */
+  readonly ip: string | null;
+  /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+  labels: string[];
   /** Unix timestamp (seconds) when token was created */
   readonly created: number;
-  /** Unix timestamp (seconds) when token expires, or null for never */
-  readonly expires?: number;
-  /** Unix timestamp (seconds) when token was last used */
-  readonly used?: number;
+  /** Unix timestamp (seconds) when token expires, null for never */
+  readonly expires: number | null;
+  /** Unix timestamp (seconds) when token was last used, null if never used */
+  readonly used: number | null;
+}
+
+/**
+ * Token as returned by the list endpoint.
+ * Security-redacted: shows truncated prefix instead of full hash, omits account.
+ */
+export interface TokenListItem {
+  /** Truncated token prefix for identification (e.g., "hash12345678...") */
+  readonly token: string;
+  /** Labels for categorization and filtering. Always present, empty array when none. */
+  labels: string[];
+  /** Unix timestamp (seconds) when token was created */
+  readonly created: number;
+  /** Unix timestamp (seconds) when token expires, null for never */
+  readonly expires: number | null;
+  /** Unix timestamp (seconds) when token was last used, null if never used */
+  readonly used: number | null;
 }
 
 /**
  * Response for listing tokens
  */
 export interface TokenListResponse {
-  /** Array of tokens */
-  tokens: Token[];
-  /** Total count of tokens */
-  count?: number;
+  /** Array of tokens (security-redacted for list display) */
+  tokens: TokenListItem[];
+  /** Total number of tokens */
+  total: number;
 }
 
 /**
@@ -230,10 +231,10 @@ export interface TokenListResponse {
 export interface TokenCreateResponse {
   /** The actual token value (only returned on creation) */
   token: string;
-  /** Unix timestamp (seconds) when token expires, or null for never */
-  expires?: number;
-  /** Success message */
-  message?: string;
+  /** Labels for categorization and filtering. Always present, empty array when none. */
+  labels: string[];
+  /** Unix timestamp (seconds) when token expires, null for never */
+  expires: number | null;
 }
 
 // =============================================================================
@@ -262,18 +263,18 @@ export type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
 export interface Account {
   /** User email address */
   readonly email: string;
-  /** User display name */
-  readonly name: string;
-  /** User profile picture URL */
-  readonly picture?: string;
+  /** User display name, null if not set */
+  readonly name: string | null;
+  /** User profile picture URL, null if not set */
+  readonly picture: string | null;
   /** Account plan status */
   readonly plan: AccountPlanType;
   /** Unix timestamp (seconds) when account was created */
   readonly created: number;
-  /** Unix timestamp (seconds) when account was activated (first deployment) */
-  readonly activated?: number;
-  /** Last 4 characters of the API key for identification (null when no key generated) */
-  readonly hint?: string;
+  /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
+  readonly activated: number | null;
+  /** Last 4 characters of the API key for identification, null when no key generated */
+  readonly hint: string | null;
 }
 
 /**
@@ -755,16 +756,6 @@ export function isAllowedMimeType(mimeType: string): boolean {
 // 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
  */
@@ -1071,14 +1062,14 @@ export interface TokenResource {
 export interface BillingStatus {
   /** Creem billing ID, or null if no active billing */
   billing: string | null;
-  /** Number of billing units (1 unit = 1 custom domain) */
-  units?: number;
-  /** Number of custom domains currently in use */
-  usage?: number;
-  /** Billing status from Creem (active, trialing, canceled, etc.) */
-  status?: string;
-  /** Link to Creem customer portal for billing management */
-  portal?: string | null;
+  /** Number of billing units (1 unit = 1 custom domain), null if no billing */
+  units: number | null;
+  /** Number of custom domains currently in use, null if no billing */
+  usage: number | null;
+  /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
+  status: string | null;
+  /** Link to Creem customer portal for billing management, null if unavailable */
+  portal: string | null;
 }
 
 
@@ -1293,18 +1284,6 @@ export interface ValidationIssue {
   message: string;
 }
 
-/**
- * Legacy validation error structure
- *
- * @deprecated Use ValidationIssue[] from FileValidationResult instead
- */
-export interface ValidationError {
-  error: string;
-  details: string;
-  errors: string[];
-  isClientError: true;
-}
-
 /**
  * Minimal file interface required for validation
  */
@@ -1312,7 +1291,7 @@ export interface ValidatableFile {
   name: string;
   size: number;
   type: string;
-  status?: string;
+  status?: FileValidationStatusType;
   statusMessage?: string;
 }
 
@@ -1467,18 +1446,18 @@ export function serializeLabels(labels: string[] | undefined): string | null {
 
 /**
  * Deserialize labels from JSON string to array.
- * Returns undefined for null/empty strings.
+ * Always returns an array — empty array for null/empty/invalid input.
  *
  * @example deserializeLabels('["web","production"]') → ['web', 'production']
- * @example deserializeLabels(null) → undefined
- * @example deserializeLabels('') → undefined
+ * @example deserializeLabels(null) → []
+ * @example deserializeLabels('') → []
  */
-export function deserializeLabels(labelsJson: string | null): string[] | undefined {
-  if (!labelsJson) return undefined;
+export function deserializeLabels(labelsJson: string | null): string[] {
+  if (!labelsJson) return [];
   try {
     const parsed = JSON.parse(labelsJson);
-    return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined;
+    return Array.isArray(parsed) ? parsed : [];
   } catch {
-    return undefined;
+    return [];
   }
 }