@shipstatic/types 0.9.3 → 0.9.5

package/README.md

@@ -52,13 +52,23 @@ 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:
+
+// 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

@@ -317,9 +317,9 @@ export declare const ErrorType: {
     readonly Business: "business_logic_error";
     /** API server error (500) */
     readonly Api: "internal_server_error";
-    /** Network/connection error */
+    /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     readonly Network: "network_error";
-    /** Operation was cancelled */
+    /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     readonly Cancelled: "operation_cancelled";
     /** File operation error */
     readonly File: "file_error";
@@ -367,6 +367,25 @@ export declare class ShipError extends Error {
      * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
      */
     static fromHttpResponse(response: Response, fallbackMessage?: 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;

package/dist/index.js

@@ -71,9 +71,9 @@ export const ErrorType = {
     Business: 'business_logic_error',
     /** API server error (500) */
     Api: 'internal_server_error',
-    /** Network/connection error */
+    /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     Network: 'network_error',
-    /** Operation was cancelled */
+    /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     Cancelled: 'operation_cancelled',
     /** File operation error */
     File: 'file_error',
@@ -91,12 +91,16 @@ const ERROR_CATEGORIES = {
     auth: new Set([ErrorType.Authentication]),
 };
 /**
- * Lookup set of known wire-format error type strings. Used by
- * `ShipError.fromHttpResponse` to validate the body's `error` field before
- * trusting it as an `ErrorType`. Defensive against malformed/unknown values
- * that could otherwise leak into the typed `ShipError.type` field.
+ * Lookup set of error types that legitimately appear on the wire — i.e.
+ * server-thrown types. Used by `ShipError.fromHttpResponse` to validate the
+ * body's `error` field before trusting it as the `ShipError.type`.
+ *
+ * Excludes `Network` and `Cancelled`, which are client-side-only by design:
+ * they originate on the client (fetch failure, abort) and should never be
+ * reconstructed from a server response, even if a misbehaving server were
+ * to send them. A defensive omission, not a theoretical concern.
  */
-const KNOWN_ERROR_TYPES = new Set(Object.values(ErrorType));
+const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter(t => t !== ErrorType.Network && t !== ErrorType.Cancelled));
 /**
  * Simple unified error class for both API and SDK
  */
@@ -155,7 +159,7 @@ export class ShipError extends Error {
                     else if (typeof obj.error === 'string')
                         message = obj.error;
                     details = obj.details;
-                    if (typeof obj.error === 'string' && KNOWN_ERROR_TYPES.has(obj.error)) {
+                    if (typeof obj.error === 'string' && SERVER_PRODUCIBLE_ERROR_TYPES.has(obj.error)) {
                         bodyType = obj.error;
                     }
                 }
@@ -175,6 +179,39 @@ export class ShipError extends Error {
                 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);

package/package.json

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

package/src/index.ts

@@ -362,9 +362,9 @@ export const ErrorType = {
   Business: 'business_logic_error',
   /** API server error (500) */
   Api: 'internal_server_error',
-  /** Network/connection error */
+  /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
   Network: 'network_error',
-  /** Operation was cancelled */
+  /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
   Cancelled: 'operation_cancelled',
   /** File operation error */
   File: 'file_error',
@@ -386,12 +386,20 @@ const ERROR_CATEGORIES = {
 } as const;
 
 /**
- * Lookup set of known wire-format error type strings. Used by
- * `ShipError.fromHttpResponse` to validate the body's `error` field before
- * trusting it as an `ErrorType`. Defensive against malformed/unknown values
- * that could otherwise leak into the typed `ShipError.type` field.
+ * Lookup set of error types that legitimately appear on the wire — i.e.
+ * server-thrown types. Used by `ShipError.fromHttpResponse` to validate the
+ * body's `error` field before trusting it as the `ShipError.type`.
+ *
+ * Excludes `Network` and `Cancelled`, which are client-side-only by design:
+ * they originate on the client (fetch failure, abort) and should never be
+ * reconstructed from a server response, even if a misbehaving server were
+ * to send them. A defensive omission, not a theoretical concern.
  */
-const KNOWN_ERROR_TYPES = new Set<string>(Object.values(ErrorType));
+const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
+  Object.values(ErrorType).filter(
+    t => t !== ErrorType.Network && t !== ErrorType.Cancelled,
+  ),
+);
 
 /**
  * Standard error response format used everywhere
@@ -469,7 +477,7 @@ export class ShipError extends Error {
           if (typeof obj.message === 'string') message = obj.message;
           else if (typeof obj.error === 'string') message = obj.error;
           details = obj.details;
-          if (typeof obj.error === 'string' && KNOWN_ERROR_TYPES.has(obj.error)) {
+          if (typeof obj.error === 'string' && SERVER_PRODUCIBLE_ERROR_TYPES.has(obj.error)) {
             bodyType = obj.error as ErrorType;
           }
         }
@@ -492,6 +500,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);