@shipstatic/types 0.9.4 → 0.9.6

package/README.md

@@ -43,7 +43,8 @@ if (isShipError(error)) {
 }
 
 if (error.isClientError()) { /* Business | Config | File | Validation */ }
-if (error.isAuthError()) { /* handle auth */ }
+if (error.isAuthError())   { /* handle auth */ }
+if (error.type === ErrorType.Validation) { /* specific-type checks */ }
 ```
 
 **HTTP client integration.** Both producer and consumer sides of the wire have first-class helpers, so every HTTP client across the platform reconstructs the same `ShipError` shape:
@@ -52,13 +53,25 @@ if (error.isAuthError()) { /* handle auth */ }
 // Producer side (API workers): serialize a ShipError to JSON
 return c.json(error.toResponse(), error.status ?? 500);
 
-// Consumer side (SDK, web app): rehydrate from any error Response
+// Consumer side — two symmetric helpers cover both HTTP error modes:
+
+// Both helpers take an optional operationName for context-aware fallback messages.
+
+// 1. Server returned a non-OK response
 if (!response.ok) {
-  throw await ShipError.fromHttpResponse(response, 'Get account failed');
+  throw await ShipError.fromHttpResponse(response, 'Get account');
 }
+
+// 2. fetch itself threw (offline, abort, CORS, ...)
+try { response = await fetch(url); }
+catch (cause) { throw ShipError.fromFetchError(cause, 'Get account'); }
 ```
 
-`fromHttpResponse` trusts the body's `error` field when it's a known `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 429 → `RateLimit`, else → `Api`). Body's `message` and `details` are preserved best-effort. The optional second arg is a fallback message used when the body has nothing usable.
+`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 429 → `RateLimit`, else → `Api`). Body's `message` and `details` are preserved best-effort.
+
+`fromFetchError` routes by the thrown cause: an existing `ShipError` is returned unchanged, `AbortError` becomes `Cancelled`, a fetch `TypeError` becomes `Network`, anything else becomes `Api` (with no HTTP status — the request never reached the server).
+
+Both helpers accept an optional operation-name string for contextual messages (`"Get account was cancelled"`, `"Get account failed: ..."`).
 
 ### Status Constants
 

package/dist/index.d.ts

@@ -354,8 +354,8 @@ export declare class ShipError extends Error {
      * Construct a `ShipError` from an HTTP error response.
      *
      * Best-effort body parse for `{ message, error?, details? }`. Message
-     * resolution: `body.message` → `body.error` → `fallbackMessage` →
-     * `Request failed with status N`.
+     * resolution: `body.message` → `body.error` → `"<operationName> failed with
+     * status <N>"`.
      *
      * Type resolution: trusts `body.error` when it's a known `ErrorType`
      * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -363,27 +363,45 @@ export declare class ShipError extends Error {
      * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
      * non-API responses (CDN errors, intermediaries) or malformed bodies.
      *
+     * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+     * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+     *
      * Async because it reads the response body. Returns rather than throws so
      * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
      */
-    static fromHttpResponse(response: Response, fallbackMessage?: string): Promise<ShipError>;
+    static fromHttpResponse(response: Response, operationName?: string): Promise<ShipError>;
+    /**
+     * Construct a `ShipError` from an error caught around a `fetch()` call.
+     *
+     * The mirror of `fromHttpResponse` for the *other* side of the HTTP error
+     * story — the network layer failing (offline, CORS, abort) rather than the
+     * server returning a non-OK response.
+     *
+     * Routing:
+     * - Already a `ShipError` → returned as-is (caller's intent preserved)
+     * - `AbortError` → `ShipError.cancelled(...)`
+     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
+     * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
+     *
+     * The optional `operationName` is composed into the message for context:
+     * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
+     * `"Request"` when omitted.
+     */
+    static fromFetchError(cause: unknown, operationName?: string): ShipError;
     static validation(message: string, details?: any): ShipError;
     static notFound(resource: string, id?: string): ShipError;
     static rateLimit(message?: string): ShipError;
     static authentication(message?: string, details?: any): ShipError;
     static business(message: string, status?: number): ShipError;
-    static network(message: string, cause?: Error): ShipError;
+    static network(message: string, details?: any): ShipError;
     static cancelled(message: string): ShipError;
-    static file(message: string, filePath?: string): ShipError;
+    static file(message: string, details?: any): ShipError;
     static config(message: string, details?: any): ShipError;
     static api(message: string, status?: number): ShipError;
-    get filePath(): string | undefined;
     isClientError(): boolean;
     isNetworkError(): boolean;
     isAuthError(): boolean;
-    isValidationError(): boolean;
-    isFileError(): boolean;
-    isConfigError(): boolean;
     isType(errorType: ErrorType): boolean;
 }
 /**

package/dist/index.js

@@ -132,8 +132,8 @@ export class ShipError extends Error {
      * Construct a `ShipError` from an HTTP error response.
      *
      * Best-effort body parse for `{ message, error?, details? }`. Message
-     * resolution: `body.message` → `body.error` → `fallbackMessage` →
-     * `Request failed with status N`.
+     * resolution: `body.message` → `body.error` → `"<operationName> failed with
+     * status <N>"`.
      *
      * Type resolution: trusts `body.error` when it's a known `ErrorType`
      * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -141,10 +141,13 @@ export class ShipError extends Error {
      * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
      * non-API responses (CDN errors, intermediaries) or malformed bodies.
      *
+     * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+     * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+     *
      * Async because it reads the response body. Returns rather than throws so
      * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
      */
-    static async fromHttpResponse(response, fallbackMessage) {
+    static async fromHttpResponse(response, operationName) {
         let message;
         let details;
         let bodyType;
@@ -171,14 +174,47 @@ export class ShipError extends Error {
             }
         }
         catch {
-            // Body unreadable; fall through to fallback.
+            // Body unreadable; fall through to operationName-derived message.
         }
-        message = message || fallbackMessage || `Request failed with status ${response.status}`;
+        message = message || `${operationName || 'Request'} failed with status ${response.status}`;
         const type = bodyType ?? (response.status === 401 ? ErrorType.Authentication :
             response.status === 429 ? ErrorType.RateLimit :
                 ErrorType.Api);
         return new ShipError(type, message, response.status, details);
     }
+    /**
+     * Construct a `ShipError` from an error caught around a `fetch()` call.
+     *
+     * The mirror of `fromHttpResponse` for the *other* side of the HTTP error
+     * story — the network layer failing (offline, CORS, abort) rather than the
+     * server returning a non-OK response.
+     *
+     * Routing:
+     * - Already a `ShipError` → returned as-is (caller's intent preserved)
+     * - `AbortError` → `ShipError.cancelled(...)`
+     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
+     * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
+     *
+     * The optional `operationName` is composed into the message for context:
+     * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
+     * `"Request"` when omitted.
+     */
+    static fromFetchError(cause, operationName) {
+        if (isShipError(cause))
+            return cause;
+        const op = operationName || 'Request';
+        if (cause instanceof Error) {
+            if (cause.name === 'AbortError') {
+                return ShipError.cancelled(`${op} was cancelled`);
+            }
+            if (cause instanceof TypeError && cause.message.includes('fetch')) {
+                return ShipError.network(`${op} failed: ${cause.message}`, { cause });
+            }
+            return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
+        }
+        return new ShipError(ErrorType.Api, `${op} failed: Unknown error`);
+    }
     // Factory methods for common errors
     static validation(message, details) {
         return new ShipError(ErrorType.Validation, message, 400, details);
@@ -196,14 +232,14 @@ export class ShipError extends Error {
     static business(message, status = 400) {
         return new ShipError(ErrorType.Business, message, status);
     }
-    static network(message, cause) {
-        return new ShipError(ErrorType.Network, message, undefined, { cause });
+    static network(message, details) {
+        return new ShipError(ErrorType.Network, message, undefined, details);
     }
     static cancelled(message) {
         return new ShipError(ErrorType.Cancelled, message);
     }
-    static file(message, filePath) {
-        return new ShipError(ErrorType.File, message, undefined, { filePath });
+    static file(message, details) {
+        return new ShipError(ErrorType.File, message, undefined, details);
     }
     static config(message, details) {
         return new ShipError(ErrorType.Config, message, undefined, details);
@@ -211,11 +247,8 @@ export class ShipError extends Error {
     static api(message, status = 500) {
         return new ShipError(ErrorType.Api, message, status);
     }
-    // Helper getter for accessing file path from details
-    get filePath() {
-        return this.details?.filePath;
-    }
-    // Helper methods for error type checking using categorization
+    // Semantic-category type guards. For specific-type checks, use
+    // `error.type === ErrorType.X` directly or the generic `isType(t)`.
     isClientError() {
         return ERROR_CATEGORIES.client.has(this.type);
     }
@@ -225,16 +258,6 @@ export class ShipError extends Error {
     isAuthError() {
         return ERROR_CATEGORIES.auth.has(this.type);
     }
-    isValidationError() {
-        return this.type === ErrorType.Validation;
-    }
-    isFileError() {
-        return this.type === ErrorType.File;
-    }
-    isConfigError() {
-        return this.type === ErrorType.Config;
-    }
-    // Generic type checker
     isType(errorType) {
         return this.type === errorType;
     }

package/package.json

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

package/src/index.ts

@@ -448,8 +448,8 @@ export class ShipError extends Error {
    * Construct a `ShipError` from an HTTP error response.
    *
    * Best-effort body parse for `{ message, error?, details? }`. Message
-   * resolution: `body.message` → `body.error` → `fallbackMessage` →
-   * `Request failed with status N`.
+   * resolution: `body.message` → `body.error` → `"<operationName> failed with
+   * status <N>"`.
    *
    * Type resolution: trusts `body.error` when it's a known `ErrorType`
    * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -457,12 +457,15 @@ export class ShipError extends Error {
    * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
    * non-API responses (CDN errors, intermediaries) or malformed bodies.
    *
+   * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+   * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+   *
    * Async because it reads the response body. Returns rather than throws so
    * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
    */
   static async fromHttpResponse(
     response: Response,
-    fallbackMessage?: string,
+    operationName?: string,
   ): Promise<ShipError> {
     let message: string | undefined;
     let details: unknown;
@@ -486,10 +489,10 @@ export class ShipError extends Error {
         if (text) message = text;
       }
     } catch {
-      // Body unreadable; fall through to fallback.
+      // Body unreadable; fall through to operationName-derived message.
     }
 
-    message = message || fallbackMessage || `Request failed with status ${response.status}`;
+    message = message || `${operationName || 'Request'} failed with status ${response.status}`;
 
     const type = bodyType ?? (
       response.status === 401 ? ErrorType.Authentication :
@@ -500,6 +503,42 @@ export class ShipError extends Error {
     return new ShipError(type, message, response.status, details);
   }
 
+  /**
+   * Construct a `ShipError` from an error caught around a `fetch()` call.
+   *
+   * The mirror of `fromHttpResponse` for the *other* side of the HTTP error
+   * story — the network layer failing (offline, CORS, abort) rather than the
+   * server returning a non-OK response.
+   *
+   * Routing:
+   * - Already a `ShipError` → returned as-is (caller's intent preserved)
+   * - `AbortError` → `ShipError.cancelled(...)`
+   * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+   * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
+   * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
+   *
+   * The optional `operationName` is composed into the message for context:
+   * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
+   * `"Request"` when omitted.
+   */
+  static fromFetchError(cause: unknown, operationName?: string): ShipError {
+    if (isShipError(cause)) return cause;
+
+    const op = operationName || 'Request';
+
+    if (cause instanceof Error) {
+      if (cause.name === 'AbortError') {
+        return ShipError.cancelled(`${op} was cancelled`);
+      }
+      if (cause instanceof TypeError && cause.message.includes('fetch')) {
+        return ShipError.network(`${op} failed: ${cause.message}`, { cause });
+      }
+      return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
+    }
+
+    return new ShipError(ErrorType.Api, `${op} failed: Unknown error`);
+  }
+
   // Factory methods for common errors
   static validation(message: string, details?: any): ShipError {
     return new ShipError(ErrorType.Validation, message, 400, details);
@@ -522,16 +561,16 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Business, message, status);
   }
 
-  static network(message: string, cause?: Error): ShipError {
-    return new ShipError(ErrorType.Network, message, undefined, { cause });
+  static network(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.Network, message, undefined, details);
   }
 
   static cancelled(message: string): ShipError {
     return new ShipError(ErrorType.Cancelled, message);
   }
 
-  static file(message: string, filePath?: string): ShipError {
-    return new ShipError(ErrorType.File, message, undefined, { filePath });
+  static file(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.File, message, undefined, details);
   }
 
   static config(message: string, details?: any): ShipError {
@@ -542,12 +581,8 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Api, message, status);
   }
 
-  // Helper getter for accessing file path from details
-  get filePath(): string | undefined {
-    return this.details?.filePath;
-  }
-
-  // Helper methods for error type checking using categorization
+  // Semantic-category type guards. For specific-type checks, use
+  // `error.type === ErrorType.X` directly or the generic `isType(t)`.
   isClientError(): boolean {
     return ERROR_CATEGORIES.client.has(this.type);
   }
@@ -560,19 +595,6 @@ export class ShipError extends Error {
     return ERROR_CATEGORIES.auth.has(this.type);
   }
 
-  isValidationError(): boolean {
-    return this.type === ErrorType.Validation;
-  }
-
-  isFileError(): boolean {
-    return this.type === ErrorType.File;
-  }
-
-  isConfigError(): boolean {
-    return this.type === ErrorType.Config;
-  }
-
-  // Generic type checker
   isType(errorType: ErrorType): boolean {
     return this.type === errorType;
   }