@shipstatic/types 0.9.5 → 0.9.7

package/README.md

@@ -35,6 +35,7 @@ import { ShipError, ErrorType, isShipError } from '@shipstatic/types';
 
 throw ShipError.validation('File too large');
 throw ShipError.notFound('Deployment', id);
+throw ShipError.forbidden('Account terminated');
 throw ShipError.authentication();
 throw ShipError.business('Plan limit reached');
 
@@ -43,7 +44,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 +56,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

@@ -305,25 +305,27 @@ export interface AccountOverrides {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export declare const ErrorType: {
-    /** Validation failed (400) */
+    /** Validation failed (400). Input shape is wrong. */
     readonly Validation: "validation_failed";
-    /** Resource not found (404) */
+    /** Resource not found (404). */
     readonly NotFound: "not_found";
-    /** Rate limit exceeded (429) */
+    /** Authenticated but not allowed (403). User lacks permission for this action. */
+    readonly Forbidden: "forbidden";
+    /** Rate limit exceeded (429). */
     readonly RateLimit: "rate_limit_exceeded";
-    /** Authentication required (401) */
+    /** Authentication required or failed (401). Missing/invalid credentials. */
     readonly Authentication: "authentication_failed";
-    /** Business logic error (400) */
+    /** Business rule violation. Catch-all for 4xx state-rule errors that aren't more specific. */
     readonly Business: "business_logic_error";
-    /** API server error (500) */
+    /** API server error (500). Generic server-side fault. */
     readonly Api: "internal_server_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. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     readonly Cancelled: "operation_cancelled";
-    /** File operation error */
+    /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
     readonly File: "file_error";
-    /** Configuration error */
+    /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
     readonly Config: "config_error";
 };
 export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
@@ -337,8 +339,8 @@ export interface ErrorResponse {
     message: string;
     /** HTTP status code (API contexts) */
     status?: number;
-    /** Optional additional error details */
-    details?: any;
+    /** Optional additional error details. Untyped by design — narrow at the read site. */
+    details?: unknown;
 }
 /**
  * Simple unified error class for both API and SDK
@@ -346,27 +348,33 @@ export interface ErrorResponse {
 export declare class ShipError extends Error {
     readonly type: ErrorType;
     readonly status?: number | undefined;
-    readonly details?: any | undefined;
-    constructor(type: ErrorType, message: string, status?: number | undefined, details?: any | undefined);
+    readonly details?: unknown | undefined;
+    constructor(type: ErrorType, message: string, status?: number | undefined, details?: unknown | undefined);
     /** Convert to wire format */
     toResponse(): ErrorResponse;
     /**
      * 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(...)`
-     * 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.
+     * Type resolution: trusts `body.error` when it's a known server-producible
+     * `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,
+     * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
+     * (CDN errors, intermediaries) or malformed bodies. Client-only types
+     * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+     * trusted set — a misbehaving server claiming one of those is ignored.
+     *
+     * `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.
      *
@@ -386,23 +394,33 @@ export declare class ShipError extends Error {
      * `"Request"` when omitted.
      */
     static fromFetchError(cause: unknown, operationName?: string): ShipError;
-    static validation(message: string, details?: any): ShipError;
+    static validation(message: string, details?: unknown): ShipError;
     static notFound(resource: string, id?: string): ShipError;
+    static forbidden(message: string, details?: unknown): ShipError;
     static rateLimit(message?: string): ShipError;
-    static authentication(message?: string, details?: any): ShipError;
+    /**
+     * Construct an Authentication (401) error.
+     *
+     * **Telemetry pattern — `details: { internal: '<tag>' }`.** When the
+     * server creates an auth error with an `internal` key in `details`
+     * (e.g. `{ internal: 'jwt_missing_subject' }`), `toResponse()` strips the
+     * entire `details` object before serialization. This keeps the wire
+     * response a clean "Authentication failed" while preserving granular
+     * server-side telemetry (which strategy/check failed) for logs and tests.
+     *
+     * Use this pattern in API auth code; do not put client-visible info under
+     * `internal`. Other `details` keys round-trip normally.
+     */
+    static authentication(message?: string, details?: unknown): ShipError;
     static business(message: string, status?: number): ShipError;
-    static network(message: string, cause?: Error): ShipError;
+    static network(message: string, details?: unknown): ShipError;
     static cancelled(message: string): ShipError;
-    static file(message: string, filePath?: string): ShipError;
-    static config(message: string, details?: any): ShipError;
+    static file(message: string, details?: unknown): ShipError;
+    static config(message: string, details?: unknown): 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

@@ -59,48 +59,59 @@ export const AccountPlan = {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export const ErrorType = {
-    /** Validation failed (400) */
+    /** Validation failed (400). Input shape is wrong. */
     Validation: 'validation_failed',
-    /** Resource not found (404) */
+    /** Resource not found (404). */
     NotFound: 'not_found',
-    /** Rate limit exceeded (429) */
+    /** Authenticated but not allowed (403). User lacks permission for this action. */
+    Forbidden: 'forbidden',
+    /** Rate limit exceeded (429). */
     RateLimit: 'rate_limit_exceeded',
-    /** Authentication required (401) */
+    /** Authentication required or failed (401). Missing/invalid credentials. */
     Authentication: 'authentication_failed',
-    /** Business logic error (400) */
+    /** Business rule violation. Catch-all for 4xx state-rule errors that aren't more specific. */
     Business: 'business_logic_error',
-    /** API server error (500) */
+    /** API server error (500). Generic server-side fault. */
     Api: 'internal_server_error',
     /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     Network: 'network_error',
     /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     Cancelled: 'operation_cancelled',
-    /** File operation error */
+    /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
     File: 'file_error',
-    /** Configuration error */
+    /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
     Config: 'config_error',
 };
+/**
+ * Error types that originate exclusively on the client (HTTP clients, SDK
+ * file processing, local config parsing). These never appear on the wire
+ * from the server, so `fromHttpResponse` will not trust them even if a
+ * misbehaving server claims one in `body.error`.
+ */
+const CLIENT_ONLY_ERROR_TYPES = new Set([
+    ErrorType.Network,
+    ErrorType.Cancelled,
+    ErrorType.File,
+    ErrorType.Config,
+]);
 /**
  * Categorizes error types for the `isClientError` / `isNetworkError` /
  * `isAuthError` helpers. Each `Set` is typed against the wider `ErrorType`
  * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
-    client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
+    client: new Set([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Forbidden, ErrorType.Validation]),
     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.
+ * Error types the server can legitimately produce on the wire. Used by
+ * `ShipError.fromHttpResponse` to validate the body's `error` field before
+ * trusting it as `ShipError.type`. Derived by exclusion from
+ * `CLIENT_ONLY_ERROR_TYPES` so adding a new server-producible type to
+ * `ErrorType` is automatically picked up.
  */
-const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter(t => t !== ErrorType.Network && t !== ErrorType.Cancelled));
+const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter(t => !CLIENT_ONLY_ERROR_TYPES.has(t)));
 /**
  * Simple unified error class for both API and SDK
  */
@@ -117,8 +128,11 @@ export class ShipError extends Error {
     }
     /** Convert to wire format */
     toResponse() {
-        // For security, exclude internal details from authentication errors in API responses
-        const details = this.type === ErrorType.Authentication && this.details?.internal
+        // Strip authentication details when they carry an `internal` telemetry
+        // tag (see `ShipError.authentication` JSDoc) — these are server-side
+        // diagnostics like 'jwt_missing_subject' that must not leak to clients.
+        const authDetails = this.details;
+        const details = this.type === ErrorType.Authentication && authDetails?.internal
             ? undefined
             : this.details;
         return {
@@ -132,19 +146,25 @@ 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(...)`
-     * 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.
+     * Type resolution: trusts `body.error` when it's a known server-producible
+     * `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,
+     * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
+     * (CDN errors, intermediaries) or malformed bodies. Client-only types
+     * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+     * trusted set — a misbehaving server claiming one of those is ignored.
+     *
+     * `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,12 +191,13 @@ 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);
+            response.status === 403 ? ErrorType.Forbidden :
+                response.status === 429 ? ErrorType.RateLimit :
+                    ErrorType.Api);
         return new ShipError(type, message, response.status, details);
     }
     /**
@@ -206,13 +227,16 @@ 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}`);
         }
         return new ShipError(ErrorType.Api, `${op} failed: Unknown error`);
     }
-    // Factory methods for common errors
+    // Factory methods. Uniform shape `(message, details?)` with two principled
+    // exceptions: `notFound` composes its message from (resource, id?), and
+    // `business` / `api` accept an optional status because they're the
+    // multi-status fallbacks.
     static validation(message, details) {
         return new ShipError(ErrorType.Validation, message, 400, details);
     }
@@ -220,23 +244,39 @@ export class ShipError extends Error {
         const message = id ? `${resource} ${id} not found` : `${resource} not found`;
         return new ShipError(ErrorType.NotFound, message, 404);
     }
+    static forbidden(message, details) {
+        return new ShipError(ErrorType.Forbidden, message, 403, details);
+    }
     static rateLimit(message = "Too many requests") {
         return new ShipError(ErrorType.RateLimit, message, 429);
     }
+    /**
+     * Construct an Authentication (401) error.
+     *
+     * **Telemetry pattern — `details: { internal: '<tag>' }`.** When the
+     * server creates an auth error with an `internal` key in `details`
+     * (e.g. `{ internal: 'jwt_missing_subject' }`), `toResponse()` strips the
+     * entire `details` object before serialization. This keeps the wire
+     * response a clean "Authentication failed" while preserving granular
+     * server-side telemetry (which strategy/check failed) for logs and tests.
+     *
+     * Use this pattern in API auth code; do not put client-visible info under
+     * `internal`. Other `details` keys round-trip normally.
+     */
     static authentication(message = "Authentication required", details) {
         return new ShipError(ErrorType.Authentication, message, 401, details);
     }
     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 +284,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 +295,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.7",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -350,55 +350,65 @@ export interface AccountOverrides {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export const ErrorType = {
-  /** Validation failed (400) */
+  /** Validation failed (400). Input shape is wrong. */
   Validation: 'validation_failed',
-  /** Resource not found (404) */
+  /** Resource not found (404). */
   NotFound: 'not_found',
-  /** Rate limit exceeded (429) */
+  /** Authenticated but not allowed (403). User lacks permission for this action. */
+  Forbidden: 'forbidden',
+  /** Rate limit exceeded (429). */
   RateLimit: 'rate_limit_exceeded',
-  /** Authentication required (401) */
+  /** Authentication required or failed (401). Missing/invalid credentials. */
   Authentication: 'authentication_failed',
-  /** Business logic error (400) */
+  /** Business rule violation. Catch-all for 4xx state-rule errors that aren't more specific. */
   Business: 'business_logic_error',
-  /** API server error (500) */
+  /** API server error (500). Generic server-side fault. */
   Api: 'internal_server_error',
   /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
   Network: 'network_error',
   /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
   Cancelled: 'operation_cancelled',
-  /** File operation error */
+  /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
   File: 'file_error',
-  /** Configuration error */
+  /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
   Config: 'config_error',
 } as const;
 
 export type ErrorType = typeof ErrorType[keyof typeof ErrorType];
 
+/**
+ * Error types that originate exclusively on the client (HTTP clients, SDK
+ * file processing, local config parsing). These never appear on the wire
+ * from the server, so `fromHttpResponse` will not trust them even if a
+ * misbehaving server claims one in `body.error`.
+ */
+const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
+  ErrorType.Network,
+  ErrorType.Cancelled,
+  ErrorType.File,
+  ErrorType.Config,
+]);
+
 /**
  * Categorizes error types for the `isClientError` / `isNetworkError` /
  * `isAuthError` helpers. Each `Set` is typed against the wider `ErrorType`
  * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
-  client: new Set<ErrorType>([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Validation]),
+  client: new Set<ErrorType>([ErrorType.Business, ErrorType.Config, ErrorType.File, ErrorType.Forbidden, ErrorType.Validation]),
   network: new Set<ErrorType>([ErrorType.Network]),
   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.
+ * Error types the server can legitimately produce on the wire. Used by
+ * `ShipError.fromHttpResponse` to validate the body's `error` field before
+ * trusting it as `ShipError.type`. Derived by exclusion from
+ * `CLIENT_ONLY_ERROR_TYPES` so adding a new server-producible type to
+ * `ErrorType` is automatically picked up.
  */
 const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
-  Object.values(ErrorType).filter(
-    t => t !== ErrorType.Network && t !== ErrorType.Cancelled,
-  ),
+  Object.values(ErrorType).filter(t => !CLIENT_ONLY_ERROR_TYPES.has(t)),
 );
 
 /**
@@ -411,8 +421,8 @@ export interface ErrorResponse {
   message: string;
   /** HTTP status code (API contexts) */
   status?: number;
-  /** Optional additional error details */
-  details?: any;
+  /** Optional additional error details. Untyped by design — narrow at the read site. */
+  details?: unknown;
 }
 
 /**
@@ -423,7 +433,7 @@ export class ShipError extends Error {
     public readonly type: ErrorType,
     message: string,
     public readonly status?: number,
-    public readonly details?: any
+    public readonly details?: unknown,
   ) {
     super(message);
     this.name = 'ShipError';
@@ -431,8 +441,11 @@ export class ShipError extends Error {
 
   /** Convert to wire format */
   toResponse(): ErrorResponse {
-    // For security, exclude internal details from authentication errors in API responses
-    const details = this.type === ErrorType.Authentication && this.details?.internal
+    // Strip authentication details when they carry an `internal` telemetry
+    // tag (see `ShipError.authentication` JSDoc) — these are server-side
+    // diagnostics like 'jwt_missing_subject' that must not leak to clients.
+    const authDetails = this.details as { internal?: unknown } | undefined;
+    const details = this.type === ErrorType.Authentication && authDetails?.internal
       ? undefined
       : this.details;
 
@@ -448,21 +461,27 @@ 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 server-producible
+   * `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,
+   * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
+   * (CDN errors, intermediaries) or malformed bodies. Client-only types
+   * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+   * trusted set — a misbehaving server claiming one of those is ignored.
    *
-   * 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.
+   * `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,13 +505,14 @@ 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 :
+      response.status === 403 ? ErrorType.Forbidden :
       response.status === 429 ? ErrorType.RateLimit :
       ErrorType.Api
     );
@@ -528,7 +548,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}`);
     }
@@ -536,8 +556,12 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Api, `${op} failed: Unknown error`);
   }
 
-  // Factory methods for common errors
-  static validation(message: string, details?: any): ShipError {
+  // Factory methods. Uniform shape `(message, details?)` with two principled
+  // exceptions: `notFound` composes its message from (resource, id?), and
+  // `business` / `api` accept an optional status because they're the
+  // multi-status fallbacks.
+
+  static validation(message: string, details?: unknown): ShipError {
     return new ShipError(ErrorType.Validation, message, 400, details);
   }
 
@@ -546,11 +570,28 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.NotFound, message, 404);
   }
 
+  static forbidden(message: string, details?: unknown): ShipError {
+    return new ShipError(ErrorType.Forbidden, message, 403, details);
+  }
+
   static rateLimit(message: string = "Too many requests"): ShipError {
     return new ShipError(ErrorType.RateLimit, message, 429);
   }
 
-  static authentication(message: string = "Authentication required", details?: any): ShipError {
+  /**
+   * Construct an Authentication (401) error.
+   *
+   * **Telemetry pattern — `details: { internal: '<tag>' }`.** When the
+   * server creates an auth error with an `internal` key in `details`
+   * (e.g. `{ internal: 'jwt_missing_subject' }`), `toResponse()` strips the
+   * entire `details` object before serialization. This keeps the wire
+   * response a clean "Authentication failed" while preserving granular
+   * server-side telemetry (which strategy/check failed) for logs and tests.
+   *
+   * Use this pattern in API auth code; do not put client-visible info under
+   * `internal`. Other `details` keys round-trip normally.
+   */
+  static authentication(message: string = "Authentication required", details?: unknown): ShipError {
     return new ShipError(ErrorType.Authentication, message, 401, details);
   }
 
@@ -558,19 +599,19 @@ 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?: unknown): 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?: unknown): ShipError {
+    return new ShipError(ErrorType.File, message, undefined, details);
   }
 
-  static config(message: string, details?: any): ShipError {
+  static config(message: string, details?: unknown): ShipError {
     return new ShipError(ErrorType.Config, message, undefined, details);
   }
 
@@ -578,12 +619,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 +633,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;
   }