@shipstatic/types 0.9.1 → 0.9.3

package/README.md

@@ -46,6 +46,20 @@ if (error.isClientError()) { /* Business | Config | File | Validation */ }
 if (error.isAuthError()) { /* handle auth */ }
 ```
 
+**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:
+
+```typescript
+// 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
+if (!response.ok) {
+  throw await ShipError.fromHttpResponse(response, 'Get account failed');
+}
+```
+
+`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.
+
 ### Status Constants
 
 ```typescript
@@ -62,7 +76,7 @@ import {
 
 ```typescript
 import type {
-  PlatformLimits,        // plan-based caps from /config (file size, file count, total size)
+  PlatformLimits,        // plan-based caps from /limits (file size, file count, total size)
   BillingStatus,
   CheckoutSession,
   ActivityListResponse,

package/dist/index.d.ts

@@ -350,8 +350,23 @@ export declare class ShipError extends Error {
     constructor(type: ErrorType, message: string, status?: number | undefined, details?: any | undefined);
     /** Convert to wire format */
     toResponse(): ErrorResponse;
-    /** Create from wire format */
-    static fromResponse(response: ErrorResponse): ShipError;
+    /**
+     * 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`.
+     *
+     * Type resolution: trusts `body.error` when it's a known `ErrorType`
+     * (preserves the wire's intent — server's `ShipError.validation(...)`
+     * round-trips back to `ErrorType.Validation` on the client). Falls back to
+     * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
+     * non-API responses (CDN errors, intermediaries) or malformed bodies.
+     *
+     * 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 validation(message: string, details?: any): ShipError;
     static notFound(resource: string, id?: string): ShipError;
     static rateLimit(message?: string): ShipError;
@@ -362,8 +377,6 @@ export declare class ShipError extends Error {
     static file(message: string, filePath?: string): ShipError;
     static config(message: string, details?: any): ShipError;
     static api(message: string, status?: number): ShipError;
-    static database(message: string, status?: number): ShipError;
-    static storage(message: string, status?: number): ShipError;
     get filePath(): string | undefined;
     isClientError(): boolean;
     isNetworkError(): boolean;

package/dist/index.js

@@ -90,6 +90,13 @@ const ERROR_CATEGORIES = {
     network: new Set([ErrorType.Network]),
     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.
+ */
+const KNOWN_ERROR_TYPES = new Set(Object.values(ErrorType));
 /**
  * Simple unified error class for both API and SDK
  */
@@ -117,9 +124,56 @@ export class ShipError extends Error {
             details
         };
     }
-    /** Create from wire format */
-    static fromResponse(response) {
-        return new ShipError(response.error, response.message, response.status, response.details);
+    /**
+     * 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`.
+     *
+     * Type resolution: trusts `body.error` when it's a known `ErrorType`
+     * (preserves the wire's intent — server's `ShipError.validation(...)`
+     * round-trips back to `ErrorType.Validation` on the client). Falls back to
+     * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
+     * non-API responses (CDN errors, intermediaries) or malformed bodies.
+     *
+     * 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) {
+        let message;
+        let details;
+        let bodyType;
+        try {
+            const contentType = response.headers.get('content-type');
+            if (contentType?.includes('application/json')) {
+                const json = await response.json();
+                if (json && typeof json === 'object') {
+                    const obj = json;
+                    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)) {
+                        bodyType = obj.error;
+                    }
+                }
+            }
+            else {
+                const text = await response.text();
+                if (text)
+                    message = text;
+            }
+        }
+        catch {
+            // Body unreadable; fall through to fallback.
+        }
+        message = message || fallbackMessage || `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);
     }
     // Factory methods for common errors
     static validation(message, details) {
@@ -153,12 +207,6 @@ export class ShipError extends Error {
     static api(message, status = 500) {
         return new ShipError(ErrorType.Api, message, status);
     }
-    static database(message, status = 500) {
-        return new ShipError(ErrorType.Api, message, status);
-    }
-    static storage(message, status = 500) {
-        return new ShipError(ErrorType.Api, message, status);
-    }
     // Helper getter for accessing file path from details
     get filePath() {
         return this.details?.filePath;

package/package.json

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

package/src/index.ts

@@ -385,6 +385,14 @@ const ERROR_CATEGORIES = {
   auth: new Set<ErrorType>([ErrorType.Authentication]),
 } 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.
+ */
+const KNOWN_ERROR_TYPES = new Set<string>(Object.values(ErrorType));
+
 /**
  * Standard error response format used everywhere
  */
@@ -428,9 +436,60 @@ export class ShipError extends Error {
     };
   }
 
-  /** Create from wire format */
-  static fromResponse(response: ErrorResponse): ShipError {
-    return new ShipError(response.error, response.message, response.status, response.details);
+  /**
+   * 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`.
+   *
+   * Type resolution: trusts `body.error` when it's a known `ErrorType`
+   * (preserves the wire's intent — server's `ShipError.validation(...)`
+   * round-trips back to `ErrorType.Validation` on the client). Falls back to
+   * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
+   * non-API responses (CDN errors, intermediaries) or malformed bodies.
+   *
+   * 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,
+  ): Promise<ShipError> {
+    let message: string | undefined;
+    let details: unknown;
+    let bodyType: ErrorType | undefined;
+
+    try {
+      const contentType = response.headers.get('content-type');
+      if (contentType?.includes('application/json')) {
+        const json: unknown = await response.json();
+        if (json && typeof json === 'object') {
+          const obj = json as Record<string, unknown>;
+          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)) {
+            bodyType = obj.error as ErrorType;
+          }
+        }
+      } else {
+        const text = await response.text();
+        if (text) message = text;
+      }
+    } catch {
+      // Body unreadable; fall through to fallback.
+    }
+
+    message = message || fallbackMessage || `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);
   }
 
   // Factory methods for common errors
@@ -475,14 +534,6 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Api, message, status);
   }
 
-  static database(message: string, status: number = 500): ShipError {
-    return new ShipError(ErrorType.Api, message, status);
-  }
-
-  static storage(message: string, status: number = 500): ShipError {
-    return new ShipError(ErrorType.Api, message, status);
-  }
-
   // Helper getter for accessing file path from details
   get filePath(): string | undefined {
     return this.details?.filePath;