@shipstatic/types 0.9.1 → 0.9.2

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` derives the error type from HTTP status (401 → `Authentication`, 429 → `RateLimit`, else → `Api`), preserving the body's `message`, `error`, and `details` 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,20 @@ 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`. Status drives the error type — same
+     * convention used by the SDK and web console — so `error.status === 429`
+     * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+     * body's `error` field claims.
+     *
+     * 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;

package/dist/index.js

@@ -117,9 +117,49 @@ 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`. Status drives the error type — same
+     * convention used by the SDK and web console — so `error.status === 429`
+     * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+     * body's `error` field claims.
+     *
+     * 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;
+        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;
+                }
+            }
+            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 = 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) {

package/package.json

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

package/src/index.ts

@@ -428,9 +428,52 @@ 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`. Status drives the error type — same
+   * convention used by the SDK and web console — so `error.status === 429`
+   * always lines up with `ErrorType.RateLimit`, etc., regardless of what the
+   * body's `error` field claims.
+   *
+   * 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;
+
+    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;
+        }
+      } 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 =
+      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