@signa-so/sdk 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,66 @@
+import type { APIErrorBody } from './types.js';
+/**
+ * Base error for all SDK errors. Thrown for client-side issues
+ * (missing config, invalid arguments) — not API errors.
+ */
+export declare class SignaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the API returns an error response (4xx/5xx).
+ * Contains the parsed error body, status, request_id, and response headers.
+ */
+export declare class SignaAPIError extends SignaError {
+    readonly status: number;
+    readonly error: APIErrorBody;
+    readonly request_id: string;
+    readonly headers: Headers;
+    constructor(status: number, error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class BadRequestError extends SignaAPIError {
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class AuthenticationError extends SignaAPIError {
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class PermissionError extends SignaAPIError {
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class NotFoundError extends SignaAPIError {
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+/** Thrown when the API returns 409 Conflict (e.g., duplicate name). */
+export declare class ConflictError extends SignaAPIError {
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class RateLimitError extends SignaAPIError {
+    /** Seconds until the rate limit resets. Parsed from Retry-After header. */
+    readonly retry_after: number;
+    constructor(error: APIErrorBody, requestId: string, headers: Headers);
+}
+export declare class InternalServerError extends SignaAPIError {
+    constructor(status: number, error: APIErrorBody, requestId: string, headers: Headers);
+}
+/** Thrown when the network request fails (DNS, TCP, TLS). */
+export declare class ConnectionError extends SignaError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/** Thrown when the request times out. */
+export declare class TimeoutError extends SignaError {
+    constructor(timeoutMs: number);
+}
+/**
+ * Create the appropriate typed error from an HTTP error response.
+ * 5xx -> InternalServerError (carries actual status).
+ * Falls back to generic SignaAPIError for unmapped status codes.
+ */
+export declare function createAPIError(status: number, body: {
+    error: APIErrorBody;
+    request_id: string;
+}, headers: Headers): SignaAPIError;
+/**
+ * Returns true if this error is retryable (connection, timeout, 429, 5xx).
+ */
+export declare function isRetryable(error: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAGxB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO;CASnB;AAID,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrE;AAED,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrE;AAED,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrE;AAED,qBAAa,aAAc,SAAQ,aAAa;gBAClC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrE;AAED,uEAAuE;AACvE,qBAAa,aAAc,SAAQ,aAAa;gBAClC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrE;AAED,qBAAa,cAAe,SAAQ,aAAa;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAKrE;AAED,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;CAIrF;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,SAAkB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAK3C;AAED,yCAAyC;AACzC,qBAAa,YAAa,SAAQ,UAAU;gBAC9B,SAAS,EAAE,MAAM;CAI9B;AAgBD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EACjD,OAAO,EAAE,OAAO,GACf,aAAa,CASf;AAgBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMnD"}

package/dist/errors.js

@@ -0,0 +1,141 @@
+/**
+ * Base error for all SDK errors. Thrown for client-side issues
+ * (missing config, invalid arguments) — not API errors.
+ */
+export class SignaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SignaError';
+    }
+}
+/**
+ * Thrown when the API returns an error response (4xx/5xx).
+ * Contains the parsed error body, status, request_id, and response headers.
+ */
+export class SignaAPIError extends SignaError {
+    status;
+    error;
+    request_id;
+    headers;
+    constructor(status, error, requestId, headers) {
+        super(`${status} ${error.title}: ${error.detail}`);
+        this.name = 'SignaAPIError';
+        this.status = status;
+        this.error = error;
+        this.request_id = requestId;
+        this.headers = headers;
+    }
+}
+// ── Typed subclasses for common status codes ────────────────────────
+export class BadRequestError extends SignaAPIError {
+    constructor(error, requestId, headers) {
+        super(400, error, requestId, headers);
+        this.name = 'BadRequestError';
+    }
+}
+export class AuthenticationError extends SignaAPIError {
+    constructor(error, requestId, headers) {
+        super(401, error, requestId, headers);
+        this.name = 'AuthenticationError';
+    }
+}
+export class PermissionError extends SignaAPIError {
+    constructor(error, requestId, headers) {
+        super(403, error, requestId, headers);
+        this.name = 'PermissionError';
+    }
+}
+export class NotFoundError extends SignaAPIError {
+    constructor(error, requestId, headers) {
+        super(404, error, requestId, headers);
+        this.name = 'NotFoundError';
+    }
+}
+/** Thrown when the API returns 409 Conflict (e.g., duplicate name). */
+export class ConflictError extends SignaAPIError {
+    constructor(error, requestId, headers) {
+        super(409, error, requestId, headers);
+        this.name = 'ConflictError';
+    }
+}
+export class RateLimitError extends SignaAPIError {
+    /** Seconds until the rate limit resets. Parsed from Retry-After header. */
+    retry_after;
+    constructor(error, requestId, headers) {
+        super(429, error, requestId, headers);
+        this.name = 'RateLimitError';
+        this.retry_after = parseRetryAfter(headers);
+    }
+}
+export class InternalServerError extends SignaAPIError {
+    constructor(status, error, requestId, headers) {
+        super(status, error, requestId, headers);
+        this.name = 'InternalServerError';
+    }
+}
+/** Thrown when the network request fails (DNS, TCP, TLS). */
+export class ConnectionError extends SignaError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'ConnectionError';
+        this.cause = cause;
+    }
+}
+/** Thrown when the request times out. */
+export class TimeoutError extends SignaError {
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+// ── Factory: maps HTTP status to typed error ────────────────────────
+const STATUS_ERROR_MAP = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+};
+/**
+ * Create the appropriate typed error from an HTTP error response.
+ * 5xx -> InternalServerError (carries actual status).
+ * Falls back to generic SignaAPIError for unmapped status codes.
+ */
+export function createAPIError(status, body, headers) {
+    const ErrorClass = STATUS_ERROR_MAP[status];
+    if (ErrorClass) {
+        return new ErrorClass(body.error, body.request_id, headers);
+    }
+    if (status >= 500) {
+        return new InternalServerError(status, body.error, body.request_id, headers);
+    }
+    return new SignaAPIError(status, body.error, body.request_id, headers);
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function parseRetryAfter(headers) {
+    const value = headers.get('retry-after');
+    if (!value)
+        return 60;
+    const seconds = Number(value);
+    if (!Number.isNaN(seconds))
+        return seconds;
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+        return Math.max(0, Math.ceil((date.getTime() - Date.now()) / 1000));
+    }
+    return 60;
+}
+/**
+ * Returns true if this error is retryable (connection, timeout, 429, 5xx).
+ */
+export function isRetryable(error) {
+    if (error instanceof ConnectionError || error instanceof TimeoutError)
+        return true;
+    if (error instanceof SignaAPIError) {
+        return error.status === 429 || error.status >= 500;
+    }
+    return false;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}