@shipstatic/types 0.9.4 → 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

@@ -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

@@ -179,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.4",
+  "version": "0.9.5",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -500,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);