@shipstatic/types 0.9.2 → 0.9.4

package/README.md

@@ -58,7 +58,7 @@ if (!response.ok) {
 }
 ```
 
-`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.
+`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
 

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";
@@ -355,10 +355,13 @@ export declare class ShipError extends Error {
      *
      * 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.
+     * `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(...)`.
@@ -374,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

@@ -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',
@@ -90,6 +90,17 @@ const ERROR_CATEGORIES = {
     network: new Set([ErrorType.Network]),
     auth: new Set([ErrorType.Authentication]),
 };
+/**
+ * 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 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
  */
@@ -122,10 +133,13 @@ export class ShipError extends Error {
      *
      * 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.
+     * `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(...)`.
@@ -133,6 +147,7 @@ export class ShipError extends Error {
     static async fromHttpResponse(response, fallbackMessage) {
         let message;
         let details;
+        let bodyType;
         try {
             const contentType = response.headers.get('content-type');
             if (contentType?.includes('application/json')) {
@@ -144,6 +159,9 @@ export class ShipError extends Error {
                     else if (typeof obj.error === 'string')
                         message = obj.error;
                     details = obj.details;
+                    if (typeof obj.error === 'string' && SERVER_PRODUCIBLE_ERROR_TYPES.has(obj.error)) {
+                        bodyType = obj.error;
+                    }
                 }
             }
             else {
@@ -156,9 +174,9 @@ export class ShipError extends Error {
             // Body unreadable; fall through to fallback.
         }
         message = message || fallbackMessage || `Request failed with status ${response.status}`;
-        const type = response.status === 401 ? ErrorType.Authentication :
+        const type = bodyType ?? (response.status === 401 ? ErrorType.Authentication :
             response.status === 429 ? ErrorType.RateLimit :
-                ErrorType.Api;
+                ErrorType.Api);
         return new ShipError(type, message, response.status, details);
     }
     // Factory methods for common errors
@@ -193,12 +211,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.2",
+  "version": "0.9.4",
   "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',
@@ -385,6 +385,22 @@ const ERROR_CATEGORIES = {
   auth: new Set<ErrorType>([ErrorType.Authentication]),
 } as const;
 
+/**
+ * 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 SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
+  Object.values(ErrorType).filter(
+    t => t !== ErrorType.Network && t !== ErrorType.Cancelled,
+  ),
+);
+
 /**
  * Standard error response format used everywhere
  */
@@ -433,10 +449,13 @@ export class ShipError extends Error {
    *
    * 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.
+   * `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(...)`.
@@ -447,6 +466,7 @@ export class ShipError extends Error {
   ): Promise<ShipError> {
     let message: string | undefined;
     let details: unknown;
+    let bodyType: ErrorType | undefined;
 
     try {
       const contentType = response.headers.get('content-type');
@@ -457,6 +477,9 @@ 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' && SERVER_PRODUCIBLE_ERROR_TYPES.has(obj.error)) {
+            bodyType = obj.error as ErrorType;
+          }
         }
       } else {
         const text = await response.text();
@@ -468,10 +491,11 @@ export class ShipError extends Error {
 
     message = message || fallbackMessage || `Request failed with status ${response.status}`;
 
-    const type =
+    const type = bodyType ?? (
       response.status === 401 ? ErrorType.Authentication :
       response.status === 429 ? ErrorType.RateLimit :
-      ErrorType.Api;
+      ErrorType.Api
+    );
 
     return new ShipError(type, message, response.status, details);
   }
@@ -518,14 +542,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;