@shipstatic/ship 2.0.0-beta.0 → 2.0.0-beta.2

package/dist/index.d.cts

@@ -11,7 +11,7 @@ declare const DeploymentStatus: {
     readonly FAILED: "failed";
     readonly DELETING: "deleting";
 };
-type DeploymentStatusType = typeof DeploymentStatus[keyof typeof DeploymentStatus];
+type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -74,7 +74,7 @@ declare const DomainStatus: {
     readonly SUCCESS: "success";
     readonly PAUSED: "paused";
 };
-type DomainStatusType = typeof DomainStatus[keyof typeof DomainStatus];
+type DomainStatusType = (typeof DomainStatus)[keyof typeof DomainStatus];
 /**
  * Core domain object - used in both API responses and SDK
  */
@@ -229,7 +229,7 @@ declare const AccountPlan: {
     readonly TERMINATING: "terminating";
     readonly TERMINATED: "terminated";
 };
-type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
+type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
  * Account usage metrics — always available regardless of billing provider.
  */
@@ -324,7 +324,7 @@ declare const ErrorType: {
     /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
     readonly Config: "config_error";
 };
-type ErrorType = typeof ErrorType[keyof typeof ErrorType];
+type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
 /**
  * Standard error response format used everywhere
  */
@@ -536,7 +536,7 @@ declare const AuthMethod: {
     readonly WEBHOOK: "webhook";
     readonly SYSTEM: "system";
 };
-type AuthMethodType = typeof AuthMethod[keyof typeof AuthMethod];
+type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 /**
  * Shape constants for API keys (`ship-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
@@ -595,7 +595,7 @@ declare const TokenKind: {
     readonly DEPLOY_TOKEN: "token";
     readonly OPAQUE: "opaque";
 };
-type TokenKindType = typeof TokenKind[keyof typeof TokenKind];
+type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
 /**
  * Classify a client token by shape. The single dispatch used by both sides
  * of the wire: API auth middleware (which population is this credential?)
@@ -621,7 +621,7 @@ declare const OAuthScope: {
     readonly DOMAINS_READ: "domains:read";
     readonly DOMAINS_WRITE: "domains:write";
 };
-type OAuthScopeType = typeof OAuthScope[keyof typeof OAuthScope];
+type OAuthScopeType = (typeof OAuthScope)[keyof typeof OAuthScope];
 declare const DEPLOYMENT_CONFIG_FILENAME = "ship.json";
 /** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
 declare const SPA_DEFAULT_CONFIG: {
@@ -924,7 +924,7 @@ declare const FileValidationStatus: {
     /** File passed validation and is ready for deployment */
     readonly READY: "ready";
 };
-type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
+type FileValidationStatusType = (typeof FileValidationStatus)[keyof typeof FileValidationStatus];
 /**
  * A validation issue with a display-ready message
  *
@@ -1376,7 +1376,7 @@ declare class ApiHttp extends SimpleEvents {
     getAccount(): Promise<AccountGetResponse>;
     getLimits(): Promise<PlatformLimits>;
     ping(): Promise<boolean>;
-    checkSPA(files: StaticFile[], options?: ApiDeployOptions): Promise<boolean>;
+    checkSPA(files: StaticFile[], _options?: ApiDeployOptions): Promise<boolean>;
 }
 
 /**
@@ -1518,91 +1518,6 @@ declare abstract class Ship$1 {
  */
 declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
 
-interface MD5Result {
-    md5: string;
-}
-declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
-
-/**
- * Utility functions for string manipulation.
- */
-/**
- * Simple utility to pluralize a word based on a count.
- * @param count The number to determine pluralization.
- * @param singular The singular form of the word.
- * @param plural The plural form of the word.
- * @param includeCount Whether to include the count in the returned string. Defaults to true.
- * @returns A string with the count and the correctly pluralized word.
- */
-declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
-
-/**
- * List of directory names considered as junk
- *
- * Files within these directories (at any level in the path hierarchy) will be excluded.
- * The comparison is case-insensitive for cross-platform compatibility.
- *
- * @internal
- */
-declare const JUNK_DIRECTORIES: readonly ["__MACOSX", ".Trashes", ".fseventsd", ".Spotlight-V100"];
-/**
- * Filters an array of file paths, removing those considered junk
- *
- * Throws if any path contains an unbuilt project marker (e.g. `node_modules`, `package.json`).
- * This check runs first because the dot-file filter below would strip paths like
- * `node_modules/.pnpm/...`, destroying the evidence.
- *
- * A path is filtered out if any of these conditions are met:
- * 1. The basename is identified as junk by the 'junk' package (e.g., .DS_Store, Thumbs.db)
- * 2. Any path segment starts with a dot (e.g., .env, .git, .htaccess)
- *    Exception: `.well-known` is allowed (RFC 8615 — ACME, security.txt, app links)
- * 3. Any path segment exceeds 255 characters (filesystem limit)
- * 4. Any directory segment in the path matches an entry in JUNK_DIRECTORIES (case-insensitive)
- *
- * All path separators are normalized to forward slashes for consistent cross-platform behavior.
- *
- * Dot files are filtered for security — they typically contain sensitive configuration
- * (.env, .git) or are not meant to be served publicly. This matches server-side filtering.
- *
- * @param filePaths - An array of file path strings to filter
- * @param options - Optional settings
- * @param options.allowUnbuilt - When true, skip the unbuilt project marker check (for server-processed uploads)
- * @returns A new array containing only non-junk file paths
- * @throws {ShipError} If any path contains an unbuilt project marker (unless allowUnbuilt is true)
- *
- * @example
- * ```typescript
- * import { filterJunk } from '@shipstatic/ship';
- *
- * // Filter an array of file paths
- * const paths = ['index.html', '.DS_Store', '.gitattributes', '__MACOSX/file.txt', 'app.js'];
- * const clean = filterJunk(paths);
- * // Result: ['index.html', 'app.js']
- * ```
- *
- * @example
- * ```typescript
- * // Use with browser File objects
- * import { filterJunk } from '@shipstatic/ship';
- *
- * const files: File[] = [...]; // From input or drag-drop
- *
- * // Extract paths from File objects
- * const filePaths = files.map(f => f.webkitRelativePath || f.name);
- *
- * // Filter out junk paths
- * const validPaths = new Set(filterJunk(filePaths));
- *
- * // Filter the original File array
- * const validFiles = files.filter(f =>
- *   validPaths.has(f.webkitRelativePath || f.name)
- * );
- * ```
- */
-declare function filterJunk(filePaths: string[], options?: {
-    allowUnbuilt?: boolean;
-}): string[];
-
 /**
  * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
  * Automatically strips common parent directories to create clean deployment URLs.
@@ -1727,6 +1642,85 @@ declare function getValidFiles<T extends ValidatableFile>(files: T[]): T[];
  */
 declare function allValidFilesReady<T extends ValidatableFile>(files: T[]): boolean;
 
+/**
+ * @file Utility for filtering out junk files and directories from file paths
+ *
+ * This module provides functionality to filter out common system junk files and directories
+ * from a list of file paths. It uses the 'junk' package to identify junk filenames and
+ * a custom list to filter out common junk directories.
+ */
+/**
+ * List of directory names considered as junk
+ *
+ * Files within these directories (at any level in the path hierarchy) will be excluded.
+ * The comparison is case-insensitive for cross-platform compatibility.
+ *
+ * @internal
+ */
+declare const JUNK_DIRECTORIES: readonly ["__MACOSX", ".Trashes", ".fseventsd", ".Spotlight-V100"];
+/**
+ * Filters an array of file paths, removing those considered junk
+ *
+ * Throws if any path contains an unbuilt project marker (e.g. `node_modules`, `package.json`).
+ * This check runs first because the dot-file filter below would strip paths like
+ * `node_modules/.pnpm/...`, destroying the evidence.
+ *
+ * A path is filtered out if any of these conditions are met:
+ * 1. The basename is identified as junk by the 'junk' package (e.g., .DS_Store, Thumbs.db)
+ * 2. Any path segment starts with a dot (e.g., .env, .git, .htaccess)
+ *    Exception: `.well-known` is allowed (RFC 8615 — ACME, security.txt, app links)
+ * 3. Any path segment exceeds 255 characters (filesystem limit)
+ * 4. Any directory segment in the path matches an entry in JUNK_DIRECTORIES (case-insensitive)
+ *
+ * All path separators are normalized to forward slashes for consistent cross-platform behavior.
+ *
+ * Dot files are filtered for security — they typically contain sensitive configuration
+ * (.env, .git) or are not meant to be served publicly. This matches server-side filtering.
+ *
+ * @param filePaths - An array of file path strings to filter
+ * @param options - Optional settings
+ * @param options.allowUnbuilt - When true, skip the unbuilt project marker check (for server-processed uploads)
+ * @returns A new array containing only non-junk file paths
+ * @throws {ShipError} If any path contains an unbuilt project marker (unless allowUnbuilt is true)
+ *
+ * @example
+ * ```typescript
+ * import { filterJunk } from '@shipstatic/ship';
+ *
+ * // Filter an array of file paths
+ * const paths = ['index.html', '.DS_Store', '.gitattributes', '__MACOSX/file.txt', 'app.js'];
+ * const clean = filterJunk(paths);
+ * // Result: ['index.html', 'app.js']
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with browser File objects
+ * import { filterJunk } from '@shipstatic/ship';
+ *
+ * const files: File[] = [...]; // From input or drag-drop
+ *
+ * // Extract paths from File objects
+ * const filePaths = files.map(f => f.webkitRelativePath || f.name);
+ *
+ * // Filter out junk paths
+ * const validPaths = new Set(filterJunk(filePaths));
+ *
+ * // Filter the original File array
+ * const validFiles = files.filter(f =>
+ *   validPaths.has(f.webkitRelativePath || f.name)
+ * );
+ * ```
+ */
+declare function filterJunk(filePaths: string[], options?: {
+    allowUnbuilt?: boolean;
+}): string[];
+
+interface MD5Result {
+    md5: string;
+}
+declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
+
 /**
  * Validate a deploy path for security concerns.
  * Rejects paths containing path traversal patterns or null bytes.
@@ -1755,6 +1749,24 @@ declare function validateDeployPath(deployPath: string, sourceIdentifier: string
  */
 declare function validateDeployFile(deployPath: string, sourceIdentifier: string): void;
 
+/**
+ * Utility functions for string manipulation.
+ */
+/**
+ * Simple utility to pluralize a word based on a count.
+ * @param count The number to determine pluralization.
+ * @param singular The singular form of the word.
+ * @param plural The plural form of the word.
+ * @param includeCount Whether to include the count in the returned string. Defaults to true.
+ * @returns A string with the count and the correctly pluralized word.
+ */
+declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
+
+/**
+ * @file Node.js-specific file utilities for the Ship SDK.
+ * Provides helpers for recursively discovering, filtering, and preparing files for deploy in Node.js.
+ */
+
 /**
  * Processes Node.js file and directory paths into an array of StaticFile objects ready for deploy.
  * Computes content paths relative to the upload root before filtering, so only the deployed

package/dist/index.d.ts

@@ -11,7 +11,7 @@ declare const DeploymentStatus: {
     readonly FAILED: "failed";
     readonly DELETING: "deleting";
 };
-type DeploymentStatusType = typeof DeploymentStatus[keyof typeof DeploymentStatus];
+type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -74,7 +74,7 @@ declare const DomainStatus: {
     readonly SUCCESS: "success";
     readonly PAUSED: "paused";
 };
-type DomainStatusType = typeof DomainStatus[keyof typeof DomainStatus];
+type DomainStatusType = (typeof DomainStatus)[keyof typeof DomainStatus];
 /**
  * Core domain object - used in both API responses and SDK
  */
@@ -229,7 +229,7 @@ declare const AccountPlan: {
     readonly TERMINATING: "terminating";
     readonly TERMINATED: "terminated";
 };
-type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
+type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
  * Account usage metrics — always available regardless of billing provider.
  */
@@ -324,7 +324,7 @@ declare const ErrorType: {
     /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
     readonly Config: "config_error";
 };
-type ErrorType = typeof ErrorType[keyof typeof ErrorType];
+type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
 /**
  * Standard error response format used everywhere
  */
@@ -536,7 +536,7 @@ declare const AuthMethod: {
     readonly WEBHOOK: "webhook";
     readonly SYSTEM: "system";
 };
-type AuthMethodType = typeof AuthMethod[keyof typeof AuthMethod];
+type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 /**
  * Shape constants for API keys (`ship-{64 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
@@ -595,7 +595,7 @@ declare const TokenKind: {
     readonly DEPLOY_TOKEN: "token";
     readonly OPAQUE: "opaque";
 };
-type TokenKindType = typeof TokenKind[keyof typeof TokenKind];
+type TokenKindType = (typeof TokenKind)[keyof typeof TokenKind];
 /**
  * Classify a client token by shape. The single dispatch used by both sides
  * of the wire: API auth middleware (which population is this credential?)
@@ -621,7 +621,7 @@ declare const OAuthScope: {
     readonly DOMAINS_READ: "domains:read";
     readonly DOMAINS_WRITE: "domains:write";
 };
-type OAuthScopeType = typeof OAuthScope[keyof typeof OAuthScope];
+type OAuthScopeType = (typeof OAuthScope)[keyof typeof OAuthScope];
 declare const DEPLOYMENT_CONFIG_FILENAME = "ship.json";
 /** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
 declare const SPA_DEFAULT_CONFIG: {
@@ -924,7 +924,7 @@ declare const FileValidationStatus: {
     /** File passed validation and is ready for deployment */
     readonly READY: "ready";
 };
-type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
+type FileValidationStatusType = (typeof FileValidationStatus)[keyof typeof FileValidationStatus];
 /**
  * A validation issue with a display-ready message
  *
@@ -1376,7 +1376,7 @@ declare class ApiHttp extends SimpleEvents {
     getAccount(): Promise<AccountGetResponse>;
     getLimits(): Promise<PlatformLimits>;
     ping(): Promise<boolean>;
-    checkSPA(files: StaticFile[], options?: ApiDeployOptions): Promise<boolean>;
+    checkSPA(files: StaticFile[], _options?: ApiDeployOptions): Promise<boolean>;
 }
 
 /**
@@ -1518,91 +1518,6 @@ declare abstract class Ship$1 {
  */
 declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
 
-interface MD5Result {
-    md5: string;
-}
-declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
-
-/**
- * Utility functions for string manipulation.
- */
-/**
- * Simple utility to pluralize a word based on a count.
- * @param count The number to determine pluralization.
- * @param singular The singular form of the word.
- * @param plural The plural form of the word.
- * @param includeCount Whether to include the count in the returned string. Defaults to true.
- * @returns A string with the count and the correctly pluralized word.
- */
-declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
-
-/**
- * List of directory names considered as junk
- *
- * Files within these directories (at any level in the path hierarchy) will be excluded.
- * The comparison is case-insensitive for cross-platform compatibility.
- *
- * @internal
- */
-declare const JUNK_DIRECTORIES: readonly ["__MACOSX", ".Trashes", ".fseventsd", ".Spotlight-V100"];
-/**
- * Filters an array of file paths, removing those considered junk
- *
- * Throws if any path contains an unbuilt project marker (e.g. `node_modules`, `package.json`).
- * This check runs first because the dot-file filter below would strip paths like
- * `node_modules/.pnpm/...`, destroying the evidence.
- *
- * A path is filtered out if any of these conditions are met:
- * 1. The basename is identified as junk by the 'junk' package (e.g., .DS_Store, Thumbs.db)
- * 2. Any path segment starts with a dot (e.g., .env, .git, .htaccess)
- *    Exception: `.well-known` is allowed (RFC 8615 — ACME, security.txt, app links)
- * 3. Any path segment exceeds 255 characters (filesystem limit)
- * 4. Any directory segment in the path matches an entry in JUNK_DIRECTORIES (case-insensitive)
- *
- * All path separators are normalized to forward slashes for consistent cross-platform behavior.
- *
- * Dot files are filtered for security — they typically contain sensitive configuration
- * (.env, .git) or are not meant to be served publicly. This matches server-side filtering.
- *
- * @param filePaths - An array of file path strings to filter
- * @param options - Optional settings
- * @param options.allowUnbuilt - When true, skip the unbuilt project marker check (for server-processed uploads)
- * @returns A new array containing only non-junk file paths
- * @throws {ShipError} If any path contains an unbuilt project marker (unless allowUnbuilt is true)
- *
- * @example
- * ```typescript
- * import { filterJunk } from '@shipstatic/ship';
- *
- * // Filter an array of file paths
- * const paths = ['index.html', '.DS_Store', '.gitattributes', '__MACOSX/file.txt', 'app.js'];
- * const clean = filterJunk(paths);
- * // Result: ['index.html', 'app.js']
- * ```
- *
- * @example
- * ```typescript
- * // Use with browser File objects
- * import { filterJunk } from '@shipstatic/ship';
- *
- * const files: File[] = [...]; // From input or drag-drop
- *
- * // Extract paths from File objects
- * const filePaths = files.map(f => f.webkitRelativePath || f.name);
- *
- * // Filter out junk paths
- * const validPaths = new Set(filterJunk(filePaths));
- *
- * // Filter the original File array
- * const validFiles = files.filter(f =>
- *   validPaths.has(f.webkitRelativePath || f.name)
- * );
- * ```
- */
-declare function filterJunk(filePaths: string[], options?: {
-    allowUnbuilt?: boolean;
-}): string[];
-
 /**
  * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
  * Automatically strips common parent directories to create clean deployment URLs.
@@ -1727,6 +1642,85 @@ declare function getValidFiles<T extends ValidatableFile>(files: T[]): T[];
  */
 declare function allValidFilesReady<T extends ValidatableFile>(files: T[]): boolean;
 
+/**
+ * @file Utility for filtering out junk files and directories from file paths
+ *
+ * This module provides functionality to filter out common system junk files and directories
+ * from a list of file paths. It uses the 'junk' package to identify junk filenames and
+ * a custom list to filter out common junk directories.
+ */
+/**
+ * List of directory names considered as junk
+ *
+ * Files within these directories (at any level in the path hierarchy) will be excluded.
+ * The comparison is case-insensitive for cross-platform compatibility.
+ *
+ * @internal
+ */
+declare const JUNK_DIRECTORIES: readonly ["__MACOSX", ".Trashes", ".fseventsd", ".Spotlight-V100"];
+/**
+ * Filters an array of file paths, removing those considered junk
+ *
+ * Throws if any path contains an unbuilt project marker (e.g. `node_modules`, `package.json`).
+ * This check runs first because the dot-file filter below would strip paths like
+ * `node_modules/.pnpm/...`, destroying the evidence.
+ *
+ * A path is filtered out if any of these conditions are met:
+ * 1. The basename is identified as junk by the 'junk' package (e.g., .DS_Store, Thumbs.db)
+ * 2. Any path segment starts with a dot (e.g., .env, .git, .htaccess)
+ *    Exception: `.well-known` is allowed (RFC 8615 — ACME, security.txt, app links)
+ * 3. Any path segment exceeds 255 characters (filesystem limit)
+ * 4. Any directory segment in the path matches an entry in JUNK_DIRECTORIES (case-insensitive)
+ *
+ * All path separators are normalized to forward slashes for consistent cross-platform behavior.
+ *
+ * Dot files are filtered for security — they typically contain sensitive configuration
+ * (.env, .git) or are not meant to be served publicly. This matches server-side filtering.
+ *
+ * @param filePaths - An array of file path strings to filter
+ * @param options - Optional settings
+ * @param options.allowUnbuilt - When true, skip the unbuilt project marker check (for server-processed uploads)
+ * @returns A new array containing only non-junk file paths
+ * @throws {ShipError} If any path contains an unbuilt project marker (unless allowUnbuilt is true)
+ *
+ * @example
+ * ```typescript
+ * import { filterJunk } from '@shipstatic/ship';
+ *
+ * // Filter an array of file paths
+ * const paths = ['index.html', '.DS_Store', '.gitattributes', '__MACOSX/file.txt', 'app.js'];
+ * const clean = filterJunk(paths);
+ * // Result: ['index.html', 'app.js']
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with browser File objects
+ * import { filterJunk } from '@shipstatic/ship';
+ *
+ * const files: File[] = [...]; // From input or drag-drop
+ *
+ * // Extract paths from File objects
+ * const filePaths = files.map(f => f.webkitRelativePath || f.name);
+ *
+ * // Filter out junk paths
+ * const validPaths = new Set(filterJunk(filePaths));
+ *
+ * // Filter the original File array
+ * const validFiles = files.filter(f =>
+ *   validPaths.has(f.webkitRelativePath || f.name)
+ * );
+ * ```
+ */
+declare function filterJunk(filePaths: string[], options?: {
+    allowUnbuilt?: boolean;
+}): string[];
+
+interface MD5Result {
+    md5: string;
+}
+declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
+
 /**
  * Validate a deploy path for security concerns.
  * Rejects paths containing path traversal patterns or null bytes.
@@ -1755,6 +1749,24 @@ declare function validateDeployPath(deployPath: string, sourceIdentifier: string
  */
 declare function validateDeployFile(deployPath: string, sourceIdentifier: string): void;
 
+/**
+ * Utility functions for string manipulation.
+ */
+/**
+ * Simple utility to pluralize a word based on a count.
+ * @param count The number to determine pluralization.
+ * @param singular The singular form of the word.
+ * @param plural The plural form of the word.
+ * @param includeCount Whether to include the count in the returned string. Defaults to true.
+ * @returns A string with the count and the correctly pluralized word.
+ */
+declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
+
+/**
+ * @file Node.js-specific file utilities for the Ship SDK.
+ * Provides helpers for recursively discovering, filtering, and preparing files for deploy in Node.js.
+ */
+
 /**
  * Processes Node.js file and directory paths into an array of StaticFile objects ready for deploy.
  * Computes content paths relative to the upload root before filtering, so only the deployed