@shipstatic/types 0.9.5 → 0.9.6

package/README.md

@@ -43,7 +43,8 @@ if (isShipError(error)) {
 }
 
 if (error.isClientError()) { /* Business | Config | File | Validation */ }
-if (error.isAuthError()) { /* handle auth */ }
+if (error.isAuthError())   { /* handle auth */ }
+if (error.type === ErrorType.Validation) { /* specific-type checks */ }
 ```
 
 **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:
@@ -54,6 +55,8 @@ return c.json(error.toResponse(), error.status ?? 500);
 
 // Consumer side — two symmetric helpers cover both HTTP error modes:
 
+// Both helpers take an optional operationName for context-aware fallback messages.
+
 // 1. Server returned a non-OK response
 if (!response.ok) {
   throw await ShipError.fromHttpResponse(response, 'Get account');

package/dist/index.d.ts

@@ -354,8 +354,8 @@ export declare class ShipError extends Error {
      * 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`.
+     * resolution: `body.message` → `body.error` → `"<operationName> failed with
+     * status <N>"`.
      *
      * Type resolution: trusts `body.error` when it's a known `ErrorType`
      * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -363,10 +363,13 @@ export declare class ShipError extends Error {
      * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
      * non-API responses (CDN errors, intermediaries) or malformed bodies.
      *
+     * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+     * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+     *
      * 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 fromHttpResponse(response: Response, operationName?: string): Promise<ShipError>;
     /**
      * Construct a `ShipError` from an error caught around a `fetch()` call.
      *
@@ -391,18 +394,14 @@ export declare class ShipError extends Error {
     static rateLimit(message?: string): ShipError;
     static authentication(message?: string, details?: any): ShipError;
     static business(message: string, status?: number): ShipError;
-    static network(message: string, cause?: Error): ShipError;
+    static network(message: string, details?: any): ShipError;
     static cancelled(message: string): ShipError;
-    static file(message: string, filePath?: string): ShipError;
+    static file(message: string, details?: any): ShipError;
     static config(message: string, details?: any): ShipError;
     static api(message: string, status?: number): ShipError;
-    get filePath(): string | undefined;
     isClientError(): boolean;
     isNetworkError(): boolean;
     isAuthError(): boolean;
-    isValidationError(): boolean;
-    isFileError(): boolean;
-    isConfigError(): boolean;
     isType(errorType: ErrorType): boolean;
 }
 /**

package/dist/index.js

@@ -132,8 +132,8 @@ export class ShipError extends Error {
      * 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`.
+     * resolution: `body.message` → `body.error` → `"<operationName> failed with
+     * status <N>"`.
      *
      * Type resolution: trusts `body.error` when it's a known `ErrorType`
      * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -141,10 +141,13 @@ export class ShipError extends Error {
      * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
      * non-API responses (CDN errors, intermediaries) or malformed bodies.
      *
+     * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+     * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+     *
      * 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) {
+    static async fromHttpResponse(response, operationName) {
         let message;
         let details;
         let bodyType;
@@ -171,9 +174,9 @@ export class ShipError extends Error {
             }
         }
         catch {
-            // Body unreadable; fall through to fallback.
+            // Body unreadable; fall through to operationName-derived message.
         }
-        message = message || fallbackMessage || `Request failed with status ${response.status}`;
+        message = message || `${operationName || 'Request'} failed with status ${response.status}`;
         const type = bodyType ?? (response.status === 401 ? ErrorType.Authentication :
             response.status === 429 ? ErrorType.RateLimit :
                 ErrorType.Api);
@@ -206,7 +209,7 @@ export class ShipError extends Error {
                 return ShipError.cancelled(`${op} was cancelled`);
             }
             if (cause instanceof TypeError && cause.message.includes('fetch')) {
-                return ShipError.network(`${op} failed: ${cause.message}`, cause);
+                return ShipError.network(`${op} failed: ${cause.message}`, { cause });
             }
             return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
         }
@@ -229,14 +232,14 @@ export class ShipError extends Error {
     static business(message, status = 400) {
         return new ShipError(ErrorType.Business, message, status);
     }
-    static network(message, cause) {
-        return new ShipError(ErrorType.Network, message, undefined, { cause });
+    static network(message, details) {
+        return new ShipError(ErrorType.Network, message, undefined, details);
     }
     static cancelled(message) {
         return new ShipError(ErrorType.Cancelled, message);
     }
-    static file(message, filePath) {
-        return new ShipError(ErrorType.File, message, undefined, { filePath });
+    static file(message, details) {
+        return new ShipError(ErrorType.File, message, undefined, details);
     }
     static config(message, details) {
         return new ShipError(ErrorType.Config, message, undefined, details);
@@ -244,11 +247,8 @@ export class ShipError extends Error {
     static api(message, status = 500) {
         return new ShipError(ErrorType.Api, message, status);
     }
-    // Helper getter for accessing file path from details
-    get filePath() {
-        return this.details?.filePath;
-    }
-    // Helper methods for error type checking using categorization
+    // Semantic-category type guards. For specific-type checks, use
+    // `error.type === ErrorType.X` directly or the generic `isType(t)`.
     isClientError() {
         return ERROR_CATEGORIES.client.has(this.type);
     }
@@ -258,16 +258,6 @@ export class ShipError extends Error {
     isAuthError() {
         return ERROR_CATEGORIES.auth.has(this.type);
     }
-    isValidationError() {
-        return this.type === ErrorType.Validation;
-    }
-    isFileError() {
-        return this.type === ErrorType.File;
-    }
-    isConfigError() {
-        return this.type === ErrorType.Config;
-    }
-    // Generic type checker
     isType(errorType) {
         return this.type === errorType;
     }

package/package.json

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

package/src/index.ts

@@ -448,8 +448,8 @@ export class ShipError extends Error {
    * 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`.
+   * resolution: `body.message` → `body.error` → `"<operationName> failed with
+   * status <N>"`.
    *
    * Type resolution: trusts `body.error` when it's a known `ErrorType`
    * (preserves the wire's intent — server's `ShipError.validation(...)`
@@ -457,12 +457,15 @@ export class ShipError extends Error {
    * status-derived (401 → Authentication, 429 → RateLimit, else → Api) for
    * non-API responses (CDN errors, intermediaries) or malformed bodies.
    *
+   * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+   * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+   *
    * 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,
+    operationName?: string,
   ): Promise<ShipError> {
     let message: string | undefined;
     let details: unknown;
@@ -486,10 +489,10 @@ export class ShipError extends Error {
         if (text) message = text;
       }
     } catch {
-      // Body unreadable; fall through to fallback.
+      // Body unreadable; fall through to operationName-derived message.
     }
 
-    message = message || fallbackMessage || `Request failed with status ${response.status}`;
+    message = message || `${operationName || 'Request'} failed with status ${response.status}`;
 
     const type = bodyType ?? (
       response.status === 401 ? ErrorType.Authentication :
@@ -528,7 +531,7 @@ export class ShipError extends Error {
         return ShipError.cancelled(`${op} was cancelled`);
       }
       if (cause instanceof TypeError && cause.message.includes('fetch')) {
-        return ShipError.network(`${op} failed: ${cause.message}`, cause);
+        return ShipError.network(`${op} failed: ${cause.message}`, { cause });
       }
       return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
     }
@@ -558,16 +561,16 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Business, message, status);
   }
 
-  static network(message: string, cause?: Error): ShipError {
-    return new ShipError(ErrorType.Network, message, undefined, { cause });
+  static network(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.Network, message, undefined, details);
   }
 
   static cancelled(message: string): ShipError {
     return new ShipError(ErrorType.Cancelled, message);
   }
 
-  static file(message: string, filePath?: string): ShipError {
-    return new ShipError(ErrorType.File, message, undefined, { filePath });
+  static file(message: string, details?: any): ShipError {
+    return new ShipError(ErrorType.File, message, undefined, details);
   }
 
   static config(message: string, details?: any): ShipError {
@@ -578,12 +581,8 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Api, message, status);
   }
 
-  // Helper getter for accessing file path from details
-  get filePath(): string | undefined {
-    return this.details?.filePath;
-  }
-
-  // Helper methods for error type checking using categorization
+  // Semantic-category type guards. For specific-type checks, use
+  // `error.type === ErrorType.X` directly or the generic `isType(t)`.
   isClientError(): boolean {
     return ERROR_CATEGORIES.client.has(this.type);
   }
@@ -596,19 +595,6 @@ export class ShipError extends Error {
     return ERROR_CATEGORIES.auth.has(this.type);
   }
 
-  isValidationError(): boolean {
-    return this.type === ErrorType.Validation;
-  }
-
-  isFileError(): boolean {
-    return this.type === ErrorType.File;
-  }
-
-  isConfigError(): boolean {
-    return this.type === ErrorType.Config;
-  }
-
-  // Generic type checker
   isType(errorType: ErrorType): boolean {
     return this.type === errorType;
   }