@shipstatic/types 0.4.23 → 0.4.25

package/dist/index.d.ts

@@ -417,7 +417,7 @@ export interface ConfigResponse {
  * - Explicit allowlist (only approved formats, reject unknown)
  * ============================================================================
  */
-export declare const ALLOWED_MIME_TYPES: readonly ["text/html", "text/css", "text/plain", "text/markdown", "text/xml", "text/csv", "text/yaml", "text/vtt", "text/calendar", "text/javascript", "text/typescript", "text/tsx", "text/jsx", "text/x-scss", "text/x-sass", "text/less", "text/x-less", "text/stylus", "text/x-vue", "text/x-svelte", "image/", "audio/", "video/", "font/", "application/javascript", "application/ecmascript", "application/x-javascript", "application/wasm", "application/json", "application/ld+json", "application/manifest+json", "application/source-map", "application/xml", "application/xhtml+xml", "application/rss+xml", "application/atom+xml", "application/yaml", "application/toml", "application/pdf", "model/gltf+json", "model/gltf-binary", "application/mp4", "application/font-woff", "application/font-woff2", "application/x-font-woff", "application/x-woff", "application/vnd.ms-fontobject", "application/x-font-ttf", "application/x-font-truetype", "application/x-font-otf", "application/x-font-opentype"];
+export declare const ALLOWED_MIME_TYPES: readonly ["text/html", "text/css", "text/plain", "text/markdown", "text/xml", "text/csv", "text/tab-separated-values", "text/yaml", "text/vcard", "text/mdx", "text/x-mdx", "text/vtt", "text/srt", "text/calendar", "text/javascript", "text/typescript", "application/x-typescript", "text/tsx", "text/jsx", "text/x-scss", "text/x-sass", "text/less", "text/x-less", "text/stylus", "text/x-vue", "text/x-svelte", "text/x-sql", "text/x-diff", "text/x-patch", "text/x-protobuf", "text/x-ini", "text/x-tex", "text/x-latex", "text/x-bibtex", "text/x-r-markdown", "image/", "audio/", "video/", "font/", "application/javascript", "application/ecmascript", "application/x-javascript", "application/wasm", "application/json", "application/ld+json", "application/geo+json", "application/manifest+json", "application/x-ipynb+json", "application/x-ndjson", "application/ndjson", "text/x-ndjson", "application/jsonl", "text/jsonl", "application/json5", "text/json5", "application/schema+json", "application/source-map", "application/xml", "application/xhtml+xml", "application/rss+xml", "application/atom+xml", "application/feed+json", "application/vnd.google-earth.kml+xml", "application/yaml", "application/toml", "application/pdf", "application/x-subrip", "application/sql", "application/graphql", "application/graphql+json", "application/x-protobuf", "application/x-ini", "application/x-tex", "application/x-bibtex", "model/gltf+json", "model/gltf-binary", "application/mp4", "application/font-woff", "application/font-woff2", "application/x-font-woff", "application/x-woff", "application/vnd.ms-fontobject", "application/x-font-ttf", "application/x-font-truetype", "application/x-font-otf", "application/x-font-opentype"];
 /**
  * Check if a MIME type is allowed for upload.
  *
@@ -759,15 +759,34 @@ export interface ActivityListResponse {
  * File status constants for validation state tracking
  */
 export declare const FileValidationStatus: {
+    /** File is pending validation */
     readonly PENDING: "pending";
+    /** File failed during processing (before validation) */
     readonly PROCESSING_ERROR: "processing_error";
-    readonly EMPTY_FILE: "empty_file";
+    /** File was excluded by validation warning (not an error) */
+    readonly EXCLUDED: "excluded";
+    /** File failed validation (blocks deployment) */
     readonly VALIDATION_FAILED: "validation_failed";
+    /** File passed validation and is ready for deployment */
     readonly READY: "ready";
 };
 export type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
 /**
- * Client-side validation error structure
+ * A validation issue with a display-ready message
+ *
+ * Issues are either errors (in errors[] array) or warnings (in warnings[] array).
+ * The array position determines severity - no need to duplicate it in the object.
+ */
+export interface ValidationIssue {
+    /** File path that triggered this issue */
+    file: string;
+    /** Display-ready message explaining the issue */
+    message: string;
+}
+/**
+ * Legacy validation error structure
+ *
+ * @deprecated Use ValidationIssue[] from FileValidationResult instead
  */
 export interface ValidationError {
     error: string;
@@ -786,18 +805,40 @@ export interface ValidatableFile {
     statusMessage?: string;
 }
 /**
- * File validation result
+ * File validation result with severity-based issue reporting
+ *
+ * Validation checks files against constraints and categorizes issues by severity:
+ * - **Errors**: Block deployment (file too large, invalid type, etc.)
+ * - **Warnings**: Exclude files but allow deployment (empty files, etc.)
  *
- * NOTE: Validation is ATOMIC - if any file fails validation, ALL files are rejected.
- * This ensures deployments are all-or-nothing for data integrity.
+ * @example
+ * ```typescript
+ * const result = validateFiles(files, config);
+ *
+ * if (!result.canDeploy) {
+ *   // Has errors - must fix before deploying
+ *   console.error('Deployment blocked:', result.errors);
+ * } else if (result.warnings.length > 0) {
+ *   // Has warnings - deployment proceeds, some files excluded
+ *   console.warn('Files excluded:', result.warnings);
+ *   deploy(result.validFiles);
+ * } else {
+ *   // All files valid
+ *   deploy(result.validFiles);
+ * }
+ * ```
  */
 export interface FileValidationResult<T extends ValidatableFile> {
     /** All files with updated status */
     files: T[];
-    /** Files that passed validation (empty if ANY file failed - atomic validation) */
+    /** Files ready for deployment (status: 'ready') */
     validFiles: T[];
-    /** Validation error if any files failed */
-    error: ValidationError | null;
+    /** Blocking errors that prevent deployment */
+    errors: ValidationIssue[];
+    /** Non-blocking warnings (files excluded but deployment allowed) */
+    warnings: ValidationIssue[];
+    /** Whether deployment can proceed (true if errors.length === 0) */
+    canDeploy: boolean;
 }
 /**
  * Represents a file that has been uploaded and stored

package/dist/index.js

@@ -277,14 +277,21 @@ export const ALLOWED_MIME_TYPES = [
     'text/xml', // XML files
     // Data formats
     'text/csv', // CSV data files
+    'text/tab-separated-values', // TSV data files
     'text/yaml', // YAML config files
+    'text/vcard', // VCard contact files (.vcf)
+    // Modern documentation formats
+    'text/mdx', // MDX (Markdown with JSX) - Next.js, Docusaurus, Nextra
+    'text/x-mdx', // MDX (alternative MIME type)
     // Web-specific formats
     'text/vtt', // WebVTT video subtitles/captions (accessibility)
+    'text/srt', // SRT subtitles (SubRip format, legacy video captions)
     'text/calendar', // iCalendar (.ics) event files
     // JavaScript (legacy MIME type, still widely used by ~50% of servers)
     'text/javascript',
     // Modern web development formats (uncompiled source)
     'text/typescript', // TypeScript source (.ts)
+    'application/x-typescript', // TypeScript (alternative MIME type, .d.ts declarations)
     'text/tsx', // TypeScript JSX (.tsx)
     'text/jsx', // React JSX (.jsx)
     'text/x-scss', // SCSS preprocessor
@@ -294,6 +301,17 @@ export const ALLOWED_MIME_TYPES = [
     'text/stylus', // Stylus preprocessor
     'text/x-vue', // Vue single-file components (.vue)
     'text/x-svelte', // Svelte components (.svelte)
+    // Developer documentation formats
+    'text/x-sql', // SQL files (database schemas, migrations)
+    'text/x-diff', // Diff files (code comparisons, patches)
+    'text/x-patch', // Patch files (version upgrades, migrations)
+    'text/x-protobuf', // Protocol Buffers text format (gRPC schemas)
+    'text/x-ini', // INI configuration files
+    // Academic/research formats
+    'text/x-tex', // LaTeX documents
+    'text/x-latex', // LaTeX documents (alternative)
+    'text/x-bibtex', // BibTeX citations
+    'text/x-r-markdown', // R Markdown (statistical documentation)
     // =========================================================================
     // MEDIA (prefix matching - covers all common subtypes)
     // =========================================================================
@@ -317,7 +335,18 @@ export const ALLOWED_MIME_TYPES = [
     // JSON and structured data
     'application/json',
     'application/ld+json', // JSON-LD for structured data / SEO (Schema.org, Open Graph)
+    'application/geo+json', // GeoJSON for mapping (Leaflet, Mapbox)
     'application/manifest+json', // PWA web app manifests
+    'application/x-ipynb+json', // Jupyter Notebooks (data science, ML tutorials)
+    // JSON variants (AI/ML, streaming data, configs)
+    'application/x-ndjson', // Newline-Delimited JSON (training datasets, logs)
+    'application/ndjson', // NDJSON (alternative MIME type)
+    'text/x-ndjson', // NDJSON (text variant)
+    'application/jsonl', // JSON Lines (Hugging Face, OpenAI fine-tuning)
+    'text/jsonl', // JSON Lines (text variant)
+    'application/json5', // JSON5 (JSON with comments, trailing commas)
+    'text/json5', // JSON5 (text variant)
+    'application/schema+json', // JSON Schema (API specs, model definitions)
     // Development tools
     'application/source-map', // Source maps (.js.map, .css.map) for debugging
     // XML and feeds
@@ -325,11 +354,24 @@ export const ALLOWED_MIME_TYPES = [
     'application/xhtml+xml', // XHTML - XML-compliant HTML (legacy sites)
     'application/rss+xml', // RSS feeds (blogs, podcasts)
     'application/atom+xml', // Atom feeds
+    'application/feed+json', // JSON Feed (modern RSS alternative)
+    'application/vnd.google-earth.kml+xml', // KML for mapping (Google Earth, GIS)
     // Configuration formats
     'application/yaml', // YAML configs (static site generators)
     'application/toml', // TOML configs (Cargo, Netlify, Rust projects)
     // Documents
     'application/pdf', // PDF documents
+    // Media metadata
+    'application/x-subrip', // SRT subtitles (SubRip format)
+    // Developer tools and schemas
+    'application/sql', // SQL files (database schemas, queries)
+    'application/graphql', // GraphQL schemas (API documentation)
+    'application/graphql+json', // GraphQL with JSON encoding
+    'application/x-protobuf', // Protocol Buffers binary (gRPC)
+    'application/x-ini', // INI configuration files
+    // Academic formats
+    'application/x-tex', // LaTeX documents
+    'application/x-bibtex', // BibTeX citations
     // =========================================================================
     // 3D FORMATS (industry standard only)
     // =========================================================================
@@ -460,10 +502,15 @@ export const DEFAULT_API = 'https://api.shipstatic.com';
  * File status constants for validation state tracking
  */
 export const FileValidationStatus = {
+    /** File is pending validation */
     PENDING: 'pending',
+    /** File failed during processing (before validation) */
     PROCESSING_ERROR: 'processing_error',
-    EMPTY_FILE: 'empty_file',
+    /** File was excluded by validation warning (not an error) */
+    EXCLUDED: 'excluded',
+    /** File failed validation (blocks deployment) */
     VALIDATION_FAILED: 'validation_failed',
+    /** File passed validation and is ready for deployment */
     READY: 'ready',
 };
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "description": "Shared types for Shipstatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,10 +34,12 @@
   },
   "devDependencies": {
     "@types/node": "^24.10.9",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.8"
   },
   "scripts": {
     "build": "tsc",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "vitest"
   }
 }

package/src/index.ts

@@ -585,10 +585,17 @@ export const ALLOWED_MIME_TYPES = [
 
   // Data formats
   'text/csv',                      // CSV data files
+  'text/tab-separated-values',     // TSV data files
   'text/yaml',                     // YAML config files
+  'text/vcard',                    // VCard contact files (.vcf)
+
+  // Modern documentation formats
+  'text/mdx',                      // MDX (Markdown with JSX) - Next.js, Docusaurus, Nextra
+  'text/x-mdx',                    // MDX (alternative MIME type)
 
   // Web-specific formats
   'text/vtt',                      // WebVTT video subtitles/captions (accessibility)
+  'text/srt',                      // SRT subtitles (SubRip format, legacy video captions)
   'text/calendar',                 // iCalendar (.ics) event files
 
   // JavaScript (legacy MIME type, still widely used by ~50% of servers)
@@ -596,6 +603,7 @@ export const ALLOWED_MIME_TYPES = [
 
   // Modern web development formats (uncompiled source)
   'text/typescript',               // TypeScript source (.ts)
+  'application/x-typescript',      // TypeScript (alternative MIME type, .d.ts declarations)
   'text/tsx',                      // TypeScript JSX (.tsx)
   'text/jsx',                      // React JSX (.jsx)
   'text/x-scss',                   // SCSS preprocessor
@@ -606,6 +614,19 @@ export const ALLOWED_MIME_TYPES = [
   'text/x-vue',                    // Vue single-file components (.vue)
   'text/x-svelte',                 // Svelte components (.svelte)
 
+  // Developer documentation formats
+  'text/x-sql',                    // SQL files (database schemas, migrations)
+  'text/x-diff',                   // Diff files (code comparisons, patches)
+  'text/x-patch',                  // Patch files (version upgrades, migrations)
+  'text/x-protobuf',               // Protocol Buffers text format (gRPC schemas)
+  'text/x-ini',                    // INI configuration files
+
+  // Academic/research formats
+  'text/x-tex',                    // LaTeX documents
+  'text/x-latex',                  // LaTeX documents (alternative)
+  'text/x-bibtex',                 // BibTeX citations
+  'text/x-r-markdown',             // R Markdown (statistical documentation)
+
   // =========================================================================
   // MEDIA (prefix matching - covers all common subtypes)
   // =========================================================================
@@ -637,7 +658,19 @@ export const ALLOWED_MIME_TYPES = [
   // JSON and structured data
   'application/json',
   'application/ld+json',           // JSON-LD for structured data / SEO (Schema.org, Open Graph)
+  'application/geo+json',          // GeoJSON for mapping (Leaflet, Mapbox)
   'application/manifest+json',     // PWA web app manifests
+  'application/x-ipynb+json',      // Jupyter Notebooks (data science, ML tutorials)
+
+  // JSON variants (AI/ML, streaming data, configs)
+  'application/x-ndjson',          // Newline-Delimited JSON (training datasets, logs)
+  'application/ndjson',            // NDJSON (alternative MIME type)
+  'text/x-ndjson',                 // NDJSON (text variant)
+  'application/jsonl',             // JSON Lines (Hugging Face, OpenAI fine-tuning)
+  'text/jsonl',                    // JSON Lines (text variant)
+  'application/json5',             // JSON5 (JSON with comments, trailing commas)
+  'text/json5',                    // JSON5 (text variant)
+  'application/schema+json',       // JSON Schema (API specs, model definitions)
 
   // Development tools
   'application/source-map',        // Source maps (.js.map, .css.map) for debugging
@@ -647,6 +680,8 @@ export const ALLOWED_MIME_TYPES = [
   'application/xhtml+xml',         // XHTML - XML-compliant HTML (legacy sites)
   'application/rss+xml',           // RSS feeds (blogs, podcasts)
   'application/atom+xml',          // Atom feeds
+  'application/feed+json',         // JSON Feed (modern RSS alternative)
+  'application/vnd.google-earth.kml+xml', // KML for mapping (Google Earth, GIS)
 
   // Configuration formats
   'application/yaml',              // YAML configs (static site generators)
@@ -655,6 +690,20 @@ export const ALLOWED_MIME_TYPES = [
   // Documents
   'application/pdf',               // PDF documents
 
+  // Media metadata
+  'application/x-subrip',          // SRT subtitles (SubRip format)
+
+  // Developer tools and schemas
+  'application/sql',               // SQL files (database schemas, queries)
+  'application/graphql',           // GraphQL schemas (API documentation)
+  'application/graphql+json',      // GraphQL with JSON encoding
+  'application/x-protobuf',        // Protocol Buffers binary (gRPC)
+  'application/x-ini',             // INI configuration files
+
+  // Academic formats
+  'application/x-tex',             // LaTeX documents
+  'application/x-bibtex',          // BibTeX citations
+
   // =========================================================================
   // 3D FORMATS (industry standard only)
   // =========================================================================
@@ -1212,17 +1261,39 @@ export interface ActivityListResponse {
  * File status constants for validation state tracking
  */
 export const FileValidationStatus = {
+  /** File is pending validation */
   PENDING: 'pending',
+  /** File failed during processing (before validation) */
   PROCESSING_ERROR: 'processing_error',
-  EMPTY_FILE: 'empty_file',
+  /** File was excluded by validation warning (not an error) */
+  EXCLUDED: 'excluded',
+  /** File failed validation (blocks deployment) */
   VALIDATION_FAILED: 'validation_failed',
+  /** File passed validation and is ready for deployment */
   READY: 'ready',
 } as const;
 
 export type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
 
+
 /**
- * Client-side validation error structure
+ * A validation issue with a display-ready message
+ *
+ * Issues are either errors (in errors[] array) or warnings (in warnings[] array).
+ * The array position determines severity - no need to duplicate it in the object.
+ */
+export interface ValidationIssue {
+  /** File path that triggered this issue */
+  file: string;
+
+  /** Display-ready message explaining the issue */
+  message: string;
+}
+
+/**
+ * Legacy validation error structure
+ *
+ * @deprecated Use ValidationIssue[] from FileValidationResult instead
  */
 export interface ValidationError {
   error: string;
@@ -1243,18 +1314,44 @@ export interface ValidatableFile {
 }
 
 /**
- * File validation result
+ * File validation result with severity-based issue reporting
+ *
+ * Validation checks files against constraints and categorizes issues by severity:
+ * - **Errors**: Block deployment (file too large, invalid type, etc.)
+ * - **Warnings**: Exclude files but allow deployment (empty files, etc.)
+ *
+ * @example
+ * ```typescript
+ * const result = validateFiles(files, config);
  *
- * NOTE: Validation is ATOMIC - if any file fails validation, ALL files are rejected.
- * This ensures deployments are all-or-nothing for data integrity.
+ * if (!result.canDeploy) {
+ *   // Has errors - must fix before deploying
+ *   console.error('Deployment blocked:', result.errors);
+ * } else if (result.warnings.length > 0) {
+ *   // Has warnings - deployment proceeds, some files excluded
+ *   console.warn('Files excluded:', result.warnings);
+ *   deploy(result.validFiles);
+ * } else {
+ *   // All files valid
+ *   deploy(result.validFiles);
+ * }
+ * ```
  */
 export interface FileValidationResult<T extends ValidatableFile> {
   /** All files with updated status */
   files: T[];
-  /** Files that passed validation (empty if ANY file failed - atomic validation) */
+
+  /** Files ready for deployment (status: 'ready') */
   validFiles: T[];
-  /** Validation error if any files failed */
-  error: ValidationError | null;
+
+  /** Blocking errors that prevent deployment */
+  errors: ValidationIssue[];
+
+  /** Non-blocking warnings (files excluded but deployment allowed) */
+  warnings: ValidationIssue[];
+
+  /** Whether deployment can proceed (true if errors.length === 0) */
+  canDeploy: boolean;
 }
 
 /**