@kaiban/sdk 0.3.0 → 0.3.1

package/README.md

@@ -286,6 +286,9 @@ import {
   ValidationError,
   UnauthorizedError,
   RateLimitError,
+  BadGatewayError,
+  GatewayTimeoutError,
+  UnavailableError,
   TimeoutError,
   AbortedError,
 } from '@kaiban/sdk';
@@ -300,22 +303,44 @@ try {
 } catch (err) {
   if (err instanceof NotFoundError) {
     console.error('Card not found:', err.message);
-    console.error('Error code:', err.code); // Optional error code from API
+    console.error('Error code:', err.code); // 'not_found'
+    console.error('Request ID:', err.meta?.request_id);
+    console.error('Timestamp:', err.meta?.timestamp);
   } else if (err instanceof ValidationError) {
     console.error('Validation failed:', err.message);
-    console.error('Details:', err.details); // Additional error details from API
+    console.error('Error code:', err.code); // 'validation_error'
+    // ValidationError.details includes issues array
+    if (err.details?.issues) {
+      err.details.issues.forEach((issue) => {
+        console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+      });
+    }
   } else if (err instanceof BadRequestError) {
     console.error('Invalid request:', err.message);
+    console.error('Error code:', err.code); // 'invalid_argument'
   } else if (err instanceof UnauthorizedError) {
     console.error('Authentication required:', err.message);
+    console.error('Error code:', err.code); // 'unauthenticated'
   } else if (err instanceof RateLimitError) {
     console.error('Rate limit exceeded:', err.message);
+    console.error('Error code:', err.code); // 'rate_limit_exceeded'
+  } else if (err instanceof BadGatewayError) {
+    console.error('Bad gateway:', err.message);
+    console.error('Error code:', err.code); // 'bad_gateway'
+  } else if (err instanceof GatewayTimeoutError) {
+    console.error('Gateway timeout:', err.message);
+    console.error('Error code:', err.code); // 'gateway_timeout'
+  } else if (err instanceof UnavailableError) {
+    console.error('Service unavailable:', err.message);
+    console.error('Error code:', err.code); // 'service_unavailable'
   } else if (err instanceof TimeoutError) {
     console.error('Request timed out');
   } else if (err instanceof AbortedError) {
     console.error('Request was cancelled');
   } else if (err instanceof ApiError) {
     console.error('API error:', err.message);
+    console.error('Error code:', err.code);
+    console.error('Details:', err.details);
   } else {
     console.error('Unexpected error:', err);
   }
@@ -324,20 +349,29 @@ try {
 
 ### Available Error Classes
 
-- **`ApiError`**: Base class for all API errors (includes `code`, `message`, `details` properties)
-- **`BadRequestError`**: 400 - Invalid request format or parameters
-- **`ValidationError`**: 422 - Request validation failed
-- **`UnauthorizedError`**: 401 - Authentication required or failed
-- **`ForbiddenError`**: 403 - Insufficient permissions
-- **`NotFoundError`**: 404 - Resource not found
-- **`ConflictError`**: 409 - Resource conflict
-- **`RateLimitError`**: 429 - Too many requests
-- **`UnavailableError`**: 502, 503, 504 - Service temporarily unavailable
-- **`ServerError`**: 500 or other server errors
+- **`ApiError`**: Base class for all API errors (includes `code`, `message`, `details`, `meta` properties)
+- **`BadRequestError`**: 400 - Invalid request format or parameters (`invalid_argument`)
+- **`ValidationError`**: 422 - Request validation failed (`validation_error`, includes `details.issues[]`)
+- **`UnauthorizedError`**: 401 - Authentication required or failed (`unauthenticated`)
+- **`ForbiddenError`**: 403 - Insufficient permissions (`permission_denied`)
+- **`NotFoundError`**: 404 - Resource not found (`not_found`)
+- **`ConflictError`**: 409 - Resource conflict (`conflict`)
+- **`RateLimitError`**: 429 - Too many requests (`rate_limit_exceeded`)
+- **`BadGatewayError`**: 502 - Bad gateway (`bad_gateway`)
+- **`UnavailableError`**: 503 - Service temporarily unavailable (`service_unavailable`)
+- **`GatewayTimeoutError`**: 504 - Gateway timeout (`gateway_timeout`)
+- **`ServerError`**: 500 - Internal server error (`internal`)
 - **`TimeoutError`**: Request exceeded configured timeout
 - **`AbortedError`**: Request was cancelled via AbortSignal
 - **`HttpError`**: Low-level HTTP error (includes `status`, `url`, `body` properties)
 
+All API errors include:
+
+- `code`: Backend error code (e.g., `validation_error`, `not_found`)
+- `message`: Human-readable error message
+- `details`: Optional error details (for `ValidationError`, includes `issues[]` array)
+- `meta`: Request metadata with `request_id?` and `timestamp`
+
 ## Examples by resource
 
 ### Agents

package/dist/cjs/lib/http/HttpClient.js

@@ -165,7 +165,11 @@ class HttpClient {
             if (err instanceof errors_1.RateLimitError)
                 return retryCfg.retryOn?.includes(429) ?? false;
             if (err instanceof errors_1.UnavailableError)
-                return retryCfg.retryOn?.some((c) => c === 502 || c === 503 || c === 504) ?? false;
+                return retryCfg.retryOn?.includes(503) ?? false;
+            if (err instanceof errors_1.BadGatewayError)
+                return retryCfg.retryOn?.includes(502) ?? false;
+            if (err instanceof errors_1.GatewayTimeoutError)
+                return retryCfg.retryOn?.includes(504) ?? false;
             if (err instanceof errors_1.ServerError)
                 return retryCfg.retryOn?.includes(500) ?? false;
             return false;

package/dist/cjs/lib/http/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServerError = exports.UnavailableError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.BadRequestError = exports.ApiError = exports.AbortedError = exports.TimeoutError = exports.HttpError = void 0;
+exports.ServerError = exports.GatewayTimeoutError = exports.BadGatewayError = exports.UnavailableError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.BadRequestError = exports.ApiError = exports.AbortedError = exports.TimeoutError = exports.HttpError = void 0;
 exports.mapHttpToSdkError = mapHttpToSdkError;
 class HttpError extends Error {
     constructor(message, status, url, body) {
@@ -32,6 +32,7 @@ class ApiError extends Error {
         this.name = 'ApiError';
         this.code = shape.code;
         this.details = shape.details;
+        this.meta = shape.meta;
     }
 }
 exports.ApiError = ApiError;
@@ -46,6 +47,7 @@ class ValidationError extends ApiError {
     constructor(shape) {
         super(shape);
         this.name = 'ValidationError';
+        this.details = shape.details;
     }
 }
 exports.ValidationError = ValidationError;
@@ -91,6 +93,20 @@ class UnavailableError extends ApiError {
     }
 }
 exports.UnavailableError = UnavailableError;
+class BadGatewayError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'BadGatewayError';
+    }
+}
+exports.BadGatewayError = BadGatewayError;
+class GatewayTimeoutError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'GatewayTimeoutError';
+    }
+}
+exports.GatewayTimeoutError = GatewayTimeoutError;
 class ServerError extends ApiError {
     constructor(shape) {
         super(shape);
@@ -99,8 +115,38 @@ class ServerError extends ApiError {
 }
 exports.ServerError = ServerError;
 // Map HTTP response status and body to human-friendly SDK errors
+// Uses backend error code when available, falls back to HTTP status mapping
 function mapHttpToSdkError(status, body) {
     const shape = normalizeBody(body);
+    // If backend provided an explicit error code, use it to determine error type
+    if (shape.code) {
+        switch (shape.code) {
+            case 'invalid_argument':
+                return new BadRequestError(shape);
+            case 'unauthenticated':
+                return new UnauthorizedError(shape);
+            case 'permission_denied':
+                return new ForbiddenError(shape);
+            case 'not_found':
+                return new NotFoundError(shape);
+            case 'conflict':
+                return new ConflictError(shape);
+            case 'validation_error':
+                return new ValidationError(shape);
+            case 'rate_limit_exceeded':
+                return new RateLimitError(shape);
+            case 'bad_gateway':
+                return new BadGatewayError(shape);
+            case 'service_unavailable':
+                return new UnavailableError(shape);
+            case 'gateway_timeout':
+                return new GatewayTimeoutError(shape);
+            case 'internal':
+            default:
+                return new ServerError(shape);
+        }
+    }
+    // Fallback to HTTP status code mapping if no backend code provided
     switch (status) {
         case 400:
             return new BadRequestError(shape);
@@ -117,14 +163,20 @@ function mapHttpToSdkError(status, body) {
         case 429:
             return new RateLimitError(shape);
         case 502:
+            return new BadGatewayError(shape);
         case 503:
-        case 504:
             return new UnavailableError(shape);
+        case 504:
+            return new GatewayTimeoutError(shape);
         case 500:
         default:
             return new ServerError(shape);
     }
 }
+/**
+ * Normalizes error response body to ApiErrorShape
+ * Backend returns: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+ */
 function normalizeBody(body) {
     if (!body)
         return { message: 'Unknown error' };
@@ -132,12 +184,26 @@ function normalizeBody(body) {
         return { message: body };
     if (typeof body === 'object') {
         const anyBody = body;
-        const code = anyBody['code'] || anyBody['error'];
+        // Backend structure: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+        if (anyBody['error'] && typeof anyBody['error'] === 'object') {
+            const errorObj = anyBody['error'];
+            const meta = anyBody['meta'];
+            return {
+                code: errorObj['code'],
+                message: errorObj['message'] || 'Request failed',
+                details: errorObj['details'],
+                meta,
+            };
+        }
+        // Fallback: try to extract from flat structure (legacy support)
+        const code = anyBody['code'] ||
+            anyBody['error'];
         const message = anyBody['message'] ||
             anyBody['error_description'] ||
             'Request failed';
         const details = anyBody['details'];
-        return { code, message, details };
+        const meta = anyBody['meta'];
+        return { code, message, details, meta };
     }
     return { message: 'Request failed' };
 }

package/dist/esm/lib/http/HttpClient.js

@@ -1,4 +1,4 @@
-import { AbortedError, RateLimitError, ServerError, TimeoutError, UnavailableError, mapHttpToSdkError, } from './errors.js';
+import { AbortedError, BadGatewayError, GatewayTimeoutError, RateLimitError, ServerError, TimeoutError, UnavailableError, mapHttpToSdkError, } from './errors.js';
 function buildQuery(query) {
     if (!query)
         return '';
@@ -162,7 +162,11 @@ export class HttpClient {
             if (err instanceof RateLimitError)
                 return retryCfg.retryOn?.includes(429) ?? false;
             if (err instanceof UnavailableError)
-                return retryCfg.retryOn?.some((c) => c === 502 || c === 503 || c === 504) ?? false;
+                return retryCfg.retryOn?.includes(503) ?? false;
+            if (err instanceof BadGatewayError)
+                return retryCfg.retryOn?.includes(502) ?? false;
+            if (err instanceof GatewayTimeoutError)
+                return retryCfg.retryOn?.includes(504) ?? false;
             if (err instanceof ServerError)
                 return retryCfg.retryOn?.includes(500) ?? false;
             return false;

package/dist/esm/lib/http/errors.js

@@ -25,6 +25,7 @@ export class ApiError extends Error {
         this.name = 'ApiError';
         this.code = shape.code;
         this.details = shape.details;
+        this.meta = shape.meta;
     }
 }
 export class BadRequestError extends ApiError {
@@ -37,6 +38,7 @@ export class ValidationError extends ApiError {
     constructor(shape) {
         super(shape);
         this.name = 'ValidationError';
+        this.details = shape.details;
     }
 }
 export class UnauthorizedError extends ApiError {
@@ -75,6 +77,18 @@ export class UnavailableError extends ApiError {
         this.name = 'UnavailableError';
     }
 }
+export class BadGatewayError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'BadGatewayError';
+    }
+}
+export class GatewayTimeoutError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'GatewayTimeoutError';
+    }
+}
 export class ServerError extends ApiError {
     constructor(shape) {
         super(shape);
@@ -82,8 +96,38 @@ export class ServerError extends ApiError {
     }
 }
 // Map HTTP response status and body to human-friendly SDK errors
+// Uses backend error code when available, falls back to HTTP status mapping
 export function mapHttpToSdkError(status, body) {
     const shape = normalizeBody(body);
+    // If backend provided an explicit error code, use it to determine error type
+    if (shape.code) {
+        switch (shape.code) {
+            case 'invalid_argument':
+                return new BadRequestError(shape);
+            case 'unauthenticated':
+                return new UnauthorizedError(shape);
+            case 'permission_denied':
+                return new ForbiddenError(shape);
+            case 'not_found':
+                return new NotFoundError(shape);
+            case 'conflict':
+                return new ConflictError(shape);
+            case 'validation_error':
+                return new ValidationError(shape);
+            case 'rate_limit_exceeded':
+                return new RateLimitError(shape);
+            case 'bad_gateway':
+                return new BadGatewayError(shape);
+            case 'service_unavailable':
+                return new UnavailableError(shape);
+            case 'gateway_timeout':
+                return new GatewayTimeoutError(shape);
+            case 'internal':
+            default:
+                return new ServerError(shape);
+        }
+    }
+    // Fallback to HTTP status code mapping if no backend code provided
     switch (status) {
         case 400:
             return new BadRequestError(shape);
@@ -100,14 +144,20 @@ export function mapHttpToSdkError(status, body) {
         case 429:
             return new RateLimitError(shape);
         case 502:
+            return new BadGatewayError(shape);
         case 503:
-        case 504:
             return new UnavailableError(shape);
+        case 504:
+            return new GatewayTimeoutError(shape);
         case 500:
         default:
             return new ServerError(shape);
     }
 }
+/**
+ * Normalizes error response body to ApiErrorShape
+ * Backend returns: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+ */
 function normalizeBody(body) {
     if (!body)
         return { message: 'Unknown error' };
@@ -115,12 +165,26 @@ function normalizeBody(body) {
         return { message: body };
     if (typeof body === 'object') {
         const anyBody = body;
-        const code = anyBody['code'] || anyBody['error'];
+        // Backend structure: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+        if (anyBody['error'] && typeof anyBody['error'] === 'object') {
+            const errorObj = anyBody['error'];
+            const meta = anyBody['meta'];
+            return {
+                code: errorObj['code'],
+                message: errorObj['message'] || 'Request failed',
+                details: errorObj['details'],
+                meta,
+            };
+        }
+        // Fallback: try to extract from flat structure (legacy support)
+        const code = anyBody['code'] ||
+            anyBody['error'];
         const message = anyBody['message'] ||
             anyBody['error_description'] ||
             'Request failed';
         const details = anyBody['details'];
-        return { code, message, details };
+        const meta = anyBody['meta'];
+        return { code, message, details, meta };
     }
     return { message: 'Request failed' };
 }

package/dist/types/lib/http/errors.d.ts

@@ -10,20 +10,38 @@ export declare class TimeoutError extends Error {
 export declare class AbortedError extends Error {
     constructor(message?: string);
 }
+export type ApiErrorCode = 'invalid_argument' | 'not_found' | 'internal' | 'validation_error' | 'permission_denied' | 'unauthenticated' | 'conflict' | 'rate_limit_exceeded' | 'bad_gateway' | 'service_unavailable' | 'gateway_timeout';
+export interface ValidationIssue {
+    code: string;
+    path: Array<string | number>;
+    message: string;
+}
 export interface ApiErrorShape {
-    code?: string;
+    code?: ApiErrorCode;
     message: string;
     details?: unknown;
+    meta?: {
+        request_id?: string;
+        timestamp: string;
+    };
 }
 export declare class ApiError extends Error {
-    readonly code?: string;
+    readonly code?: ApiErrorCode;
     readonly details?: unknown;
+    readonly meta?: {
+        request_id?: string;
+        timestamp: string;
+    };
     constructor(shape: ApiErrorShape);
 }
 export declare class BadRequestError extends ApiError {
     constructor(shape: ApiErrorShape);
 }
 export declare class ValidationError extends ApiError {
+    readonly details?: {
+        issues?: ValidationIssue[];
+        [key: string]: unknown;
+    };
     constructor(shape: ApiErrorShape);
 }
 export declare class UnauthorizedError extends ApiError {
@@ -44,6 +62,12 @@ export declare class RateLimitError extends ApiError {
 export declare class UnavailableError extends ApiError {
     constructor(shape: ApiErrorShape);
 }
+export declare class BadGatewayError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class GatewayTimeoutError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
 export declare class ServerError extends ApiError {
     constructor(shape: ApiErrorShape);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaiban/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Official TypeScript SDK for the Kaiban API",
   "keywords": [
     "kaiban",