@shipstatic/types 0.7.4 → 0.7.6

package/README.md

@@ -1,6 +1,6 @@
 # @shipstatic/types
 
-Shared TypeScript types for the Shipstatic platform.
+Shared TypeScript types for the ShipStatic platform.
 
 Single source of truth for types used across API, SDK, CLI, and web applications.
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * @file Shared TypeScript types, constants, and utilities for the ShipStatic platform.
  * This package is the single source of truth for all shared data structures.
  */
 /**
@@ -272,7 +272,7 @@ export interface AccountOverrides {
     totalSize?: number;
 }
 /**
- * All possible error types in the Shipstatic platform
+ * All possible error types in the ShipStatic platform
  * Names are developer-friendly while wire format stays consistent
  */
 export declare enum ErrorType {
@@ -389,12 +389,34 @@ export declare const BLOCKED_EXTENSIONS: ReadonlySet<string>;
  */
 export declare function isBlockedExtension(filename: string): boolean;
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export declare const UNSAFE_FILENAME_CHARS: RegExp;
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export declare function hasUnsafeChars(filename: string): boolean;
+/**
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export declare const UNBUILT_PROJECT_MARKERS: ReadonlySet<string>;
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true
@@ -802,24 +824,24 @@ export interface UploadedFile {
  * Check if a domain is a platform domain (subdomain of our platform).
  * Platform domains are free and don't require DNS verification.
  *
- * @example isPlatformDomain("www.shipstatic.dev", "shipstatic.dev") → true
- * @example isPlatformDomain("example.com", "shipstatic.dev") → false
+ * @example isPlatformDomain("www.shipstatic.com", "shipstatic.com") → true
+ * @example isPlatformDomain("example.com", "shipstatic.com") → false
  */
 export declare function isPlatformDomain(domain: string, platformDomain: string): boolean;
 /**
  * Check if a domain is a custom domain (not a platform subdomain).
  * Custom domains are billable and require DNS verification.
  *
- * @example isCustomDomain("example.com", "shipstatic.dev") → true
- * @example isCustomDomain("www.shipstatic.dev", "shipstatic.dev") → false
+ * @example isCustomDomain("example.com", "shipstatic.com") → true
+ * @example isCustomDomain("www.shipstatic.com", "shipstatic.com") → false
  */
 export declare function isCustomDomain(domain: string, platformDomain: string): boolean;
 /**
  * Extract subdomain from a platform domain.
  * Returns null if not a platform domain.
  *
- * @example extractSubdomain("www.shipstatic.dev", "shipstatic.dev") → "www"
- * @example extractSubdomain("example.com", "shipstatic.dev") → null
+ * @example extractSubdomain("www.shipstatic.com", "shipstatic.com") → "www"
+ * @example extractSubdomain("example.com", "shipstatic.com") → null
  */
 export declare function extractSubdomain(domain: string, platformDomain: string): string | null;
 /**

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * @file Shared TypeScript types, constants, and utilities for the ShipStatic platform.
  * This package is the single source of truth for all shared data structures.
  */
 // =============================================================================
@@ -50,7 +50,7 @@ export const AccountPlan = {
 // ERROR SYSTEM
 // =============================================================================
 /**
- * All possible error types in the Shipstatic platform
+ * All possible error types in the ShipStatic platform
  * Names are developer-friendly while wire format stays consistent
  */
 export var ErrorType;
@@ -250,10 +250,37 @@ export function isBlockedExtension(filename) {
     return BLOCKED_EXTENSIONS.has(ext);
 }
 // =============================================================================
+// FILENAME CHARACTER VALIDATION
+// =============================================================================
+/**
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export function hasUnsafeChars(filename) {
+    return UNSAFE_FILENAME_CHARS.test(filename);
+}
+// =============================================================================
 // UNBUILT PROJECT MARKERS
 // =============================================================================
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export const UNBUILT_PROJECT_MARKERS = new Set([
@@ -261,7 +288,7 @@ export const UNBUILT_PROJECT_MARKERS = new Set([
     'package.json',
 ]);
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true
@@ -384,8 +411,8 @@ export const FileValidationStatus = {
  * Check if a domain is a platform domain (subdomain of our platform).
  * Platform domains are free and don't require DNS verification.
  *
- * @example isPlatformDomain("www.shipstatic.dev", "shipstatic.dev") → true
- * @example isPlatformDomain("example.com", "shipstatic.dev") → false
+ * @example isPlatformDomain("www.shipstatic.com", "shipstatic.com") → true
+ * @example isPlatformDomain("example.com", "shipstatic.com") → false
  */
 export function isPlatformDomain(domain, platformDomain) {
     return domain.endsWith(`.${platformDomain}`);
@@ -394,8 +421,8 @@ export function isPlatformDomain(domain, platformDomain) {
  * Check if a domain is a custom domain (not a platform subdomain).
  * Custom domains are billable and require DNS verification.
  *
- * @example isCustomDomain("example.com", "shipstatic.dev") → true
- * @example isCustomDomain("www.shipstatic.dev", "shipstatic.dev") → false
+ * @example isCustomDomain("example.com", "shipstatic.com") → true
+ * @example isCustomDomain("www.shipstatic.com", "shipstatic.com") → false
  */
 export function isCustomDomain(domain, platformDomain) {
     return !isPlatformDomain(domain, platformDomain);
@@ -404,8 +431,8 @@ export function isCustomDomain(domain, platformDomain) {
  * Extract subdomain from a platform domain.
  * Returns null if not a platform domain.
  *
- * @example extractSubdomain("www.shipstatic.dev", "shipstatic.dev") → "www"
- * @example extractSubdomain("example.com", "shipstatic.dev") → null
+ * @example extractSubdomain("www.shipstatic.com", "shipstatic.com") → "www"
+ * @example extractSubdomain("example.com", "shipstatic.com") → null
  */
 export function extractSubdomain(domain, platformDomain) {
     if (!isPlatformDomain(domain, platformDomain)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.7.4",
-  "description": "Shared types for Shipstatic platform",
+  "version": "0.7.6",
+  "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @file Shared TypeScript types, constants, and utilities for the Shipstatic platform.
+ * @file Shared TypeScript types, constants, and utilities for the ShipStatic platform.
  * This package is the single source of truth for all shared data structures.
  */
 
@@ -315,7 +315,7 @@ export interface AccountOverrides {
 // =============================================================================
 
 /**
- * All possible error types in the Shipstatic platform
+ * All possible error types in the ShipStatic platform
  * Names are developer-friendly while wire format stays consistent
  */
 export enum ErrorType {
@@ -571,12 +571,42 @@ export function isBlockedExtension(filename: string): boolean {
   return BLOCKED_EXTENSIONS.has(ext);
 }
 
+// =============================================================================
+// FILENAME CHARACTER VALIDATION
+// =============================================================================
+
+/**
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+export const UNSAFE_FILENAME_CHARS = /[\x00-\x1f\x7f#?%\\<>"]/;
+
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+export function hasUnsafeChars(filename: string): boolean {
+  return UNSAFE_FILENAME_CHARS.test(filename);
+}
+
 // =============================================================================
 // UNBUILT PROJECT MARKERS
 // =============================================================================
 
 /**
- * Directory names that indicate an unbuilt project was uploaded instead of build output.
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
  * Used for early detection in CLI, browser, and server validation.
  */
 export const UNBUILT_PROJECT_MARKERS: ReadonlySet<string> = new Set([
@@ -585,7 +615,7 @@ export const UNBUILT_PROJECT_MARKERS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Check if a file path contains an unbuilt project marker directory.
+ * Check if a file path contains an unbuilt project marker.
  *
  * @example
  * hasUnbuiltMarker('node_modules/react/index.js')  // true
@@ -1201,8 +1231,8 @@ export interface UploadedFile {
  * Check if a domain is a platform domain (subdomain of our platform).
  * Platform domains are free and don't require DNS verification.
  *
- * @example isPlatformDomain("www.shipstatic.dev", "shipstatic.dev") → true
- * @example isPlatformDomain("example.com", "shipstatic.dev") → false
+ * @example isPlatformDomain("www.shipstatic.com", "shipstatic.com") → true
+ * @example isPlatformDomain("example.com", "shipstatic.com") → false
  */
 export function isPlatformDomain(domain: string, platformDomain: string): boolean {
   return domain.endsWith(`.${platformDomain}`);
@@ -1212,8 +1242,8 @@ export function isPlatformDomain(domain: string, platformDomain: string): boolea
  * Check if a domain is a custom domain (not a platform subdomain).
  * Custom domains are billable and require DNS verification.
  *
- * @example isCustomDomain("example.com", "shipstatic.dev") → true
- * @example isCustomDomain("www.shipstatic.dev", "shipstatic.dev") → false
+ * @example isCustomDomain("example.com", "shipstatic.com") → true
+ * @example isCustomDomain("www.shipstatic.com", "shipstatic.com") → false
  */
 export function isCustomDomain(domain: string, platformDomain: string): boolean {
   return !isPlatformDomain(domain, platformDomain);
@@ -1223,8 +1253,8 @@ export function isCustomDomain(domain: string, platformDomain: string): boolean
  * Extract subdomain from a platform domain.
  * Returns null if not a platform domain.
  *
- * @example extractSubdomain("www.shipstatic.dev", "shipstatic.dev") → "www"
- * @example extractSubdomain("example.com", "shipstatic.dev") → null
+ * @example extractSubdomain("www.shipstatic.com", "shipstatic.com") → "www"
+ * @example extractSubdomain("example.com", "shipstatic.com") → null
  */
 export function extractSubdomain(domain: string, platformDomain: string): string | null {
   if (!isPlatformDomain(domain, platformDomain)) {