@pellux/goodvibes-errors 0.18.3

package/README.md

@@ -0,0 +1,33 @@
+# @pellux/goodvibes-errors
+
+Structured GoodVibes SDK error types.
+
+Install:
+
+```bash
+npm install @pellux/goodvibes-errors
+```
+
+Use this package when you need to branch on:
+- HTTP status
+- error category
+- error source
+- recovery hints
+- request ids
+- retry timing
+
+Example:
+
+```ts
+import { HttpStatusError } from '@pellux/goodvibes-errors';
+
+try {
+  // integration code
+} catch (error) {
+  if (error instanceof HttpStatusError && error.status === 401) {
+    // re-authenticate
+  }
+}
+```
+
+The exported fields are intended to replace fragile message parsing in client and daemon integrations.

package/dist/daemon-error-contract.d.ts

@@ -0,0 +1,19 @@
+export type DaemonErrorCategory = 'authentication' | 'authorization' | 'billing' | 'rate_limit' | 'timeout' | 'network' | 'bad_request' | 'not_found' | 'permission' | 'tool' | 'config' | 'protocol' | 'service' | 'internal' | 'unknown';
+export type DaemonErrorSource = 'provider' | 'tool' | 'transport' | 'config' | 'permission' | 'runtime' | 'render' | 'acp' | 'unknown';
+export interface StructuredDaemonErrorBody {
+    readonly error: string;
+    readonly hint?: string;
+    readonly code?: string;
+    readonly category?: DaemonErrorCategory;
+    readonly source?: DaemonErrorSource;
+    readonly recoverable?: boolean;
+    readonly status?: number;
+    readonly provider?: string;
+    readonly operation?: string;
+    readonly phase?: string;
+    readonly requestId?: string;
+    readonly providerCode?: string;
+    readonly providerType?: string;
+    readonly retryAfterMs?: number;
+}
+//# sourceMappingURL=daemon-error-contract.d.ts.map

package/dist/daemon-error-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-error-contract.d.ts","sourceRoot":"","sources":["../src/daemon-error-contract.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,mBAAmB,GAC3B,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,YAAY,GACZ,SAAS,GACT,SAAS,GACT,aAAa,GACb,WAAW,GACX,YAAY,GACZ,MAAM,GACN,QAAQ,GACR,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,MAAM,GACN,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,KAAK,GACL,SAAS,CAAC;AAEd,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC"}

package/dist/daemon-error-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import type { DaemonErrorCategory, DaemonErrorSource, StructuredDaemonErrorBody } from './daemon-error-contract.js';
+export type { DaemonErrorCategory, DaemonErrorSource, StructuredDaemonErrorBody, } from './daemon-error-contract.js';
+export type ErrorCategory = DaemonErrorCategory | 'contract';
+export type ErrorSource = DaemonErrorSource | 'contract';
+export interface GoodVibesSdkErrorOptions {
+    readonly code?: string;
+    readonly category?: ErrorCategory;
+    readonly source?: ErrorSource;
+    readonly recoverable?: boolean;
+    readonly status?: number;
+    readonly url?: string;
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly hint?: string;
+    readonly provider?: string;
+    readonly operation?: string;
+    readonly phase?: string;
+    readonly requestId?: string;
+    readonly providerCode?: string;
+    readonly providerType?: string;
+    readonly retryAfterMs?: number;
+}
+export declare const RETRYABLE_STATUS_CODES: readonly number[];
+export declare class GoodVibesSdkError extends Error {
+    readonly code?: string;
+    readonly category: ErrorCategory;
+    readonly source: ErrorSource;
+    readonly recoverable: boolean;
+    readonly status?: number;
+    readonly url?: string;
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly hint?: string;
+    readonly provider?: string;
+    readonly operation?: string;
+    readonly phase?: string;
+    readonly requestId?: string;
+    readonly providerCode?: string;
+    readonly providerType?: string;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: GoodVibesSdkErrorOptions);
+}
+export declare class ConfigurationError extends GoodVibesSdkError {
+    constructor(message: string, options?: GoodVibesSdkErrorOptions);
+}
+export declare class ContractError extends GoodVibesSdkError {
+    constructor(message: string, options?: GoodVibesSdkErrorOptions);
+}
+export declare class HttpStatusError extends GoodVibesSdkError {
+    constructor(message: string, options?: GoodVibesSdkErrorOptions);
+}
+export declare function isStructuredDaemonErrorBody(value: unknown): value is StructuredDaemonErrorBody;
+export declare function createHttpStatusError(status: number, url: string, method: string, body: unknown): HttpStatusError;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,123 @@
+export const RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+function inferCategory(status) {
+    if (status === 400)
+        return 'bad_request';
+    if (status === 401)
+        return 'authentication';
+    if (status === 402)
+        return 'billing';
+    if (status === 403)
+        return 'authorization';
+    if (status === 404)
+        return 'not_found';
+    if (status === 408)
+        return 'timeout';
+    if (status === 429)
+        return 'rate_limit';
+    if (status !== undefined && status >= 500)
+        return 'service';
+    return 'unknown';
+}
+export class GoodVibesSdkError extends Error {
+    code;
+    category;
+    source;
+    recoverable;
+    status;
+    url;
+    method;
+    body;
+    hint;
+    provider;
+    operation;
+    phase;
+    requestId;
+    providerCode;
+    providerType;
+    retryAfterMs;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = options.code;
+        this.category = options.category ?? inferCategory(options.status);
+        this.source = options.source ?? 'unknown';
+        this.recoverable = options.recoverable ?? (options.status !== undefined && RETRYABLE_STATUS_CODES.includes(options.status));
+        this.status = options.status;
+        this.url = options.url;
+        this.method = options.method;
+        this.body = options.body;
+        this.hint = options.hint;
+        this.provider = options.provider;
+        this.operation = options.operation;
+        this.phase = options.phase;
+        this.requestId = options.requestId;
+        this.providerCode = options.providerCode;
+        this.providerType = options.providerType;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+}
+export class ConfigurationError extends GoodVibesSdkError {
+    constructor(message, options = {}) {
+        super(message, {
+            ...options,
+            code: options.code ?? 'SDK_CONFIGURATION_ERROR',
+            category: 'config',
+            source: options.source ?? 'config',
+            recoverable: false,
+        });
+    }
+}
+export class ContractError extends GoodVibesSdkError {
+    constructor(message, options = {}) {
+        super(message, {
+            ...options,
+            code: options.code ?? 'SDK_CONTRACT_ERROR',
+            category: 'contract',
+            source: options.source ?? 'contract',
+            recoverable: false,
+        });
+    }
+}
+export class HttpStatusError extends GoodVibesSdkError {
+    constructor(message, options = {}) {
+        super(message, {
+            ...options,
+            code: options.code ?? 'SDK_HTTP_STATUS_ERROR',
+            source: options.source ?? 'transport',
+        });
+    }
+}
+export function isStructuredDaemonErrorBody(value) {
+    return typeof value === 'object' && value !== null && typeof value.error === 'string';
+}
+export function createHttpStatusError(status, url, method, body) {
+    if (isStructuredDaemonErrorBody(body)) {
+        return new HttpStatusError(body.error, {
+            code: body.code,
+            category: body.category,
+            source: body.source ?? 'transport',
+            recoverable: body.recoverable,
+            status: body.status ?? status,
+            url,
+            method,
+            body,
+            hint: body.hint,
+            provider: body.provider,
+            operation: body.operation,
+            phase: body.phase,
+            requestId: body.requestId,
+            providerCode: body.providerCode,
+            providerType: body.providerType,
+            retryAfterMs: body.retryAfterMs,
+        });
+    }
+    const message = typeof body === 'string' && body.trim()
+        ? body.trim()
+        : `Request failed with status ${status}`;
+    return new HttpStatusError(message, {
+        status,
+        url,
+        method,
+        body,
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pellux/goodvibes-errors",
+  "version": "0.18.3",
+  "description": "Structured SDK, transport, and daemon error types for GoodVibes integrations.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mgd34msu/goodvibes-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgd34msu/goodvibes-sdk/issues"
+  },
+  "homepage": "https://github.com/mgd34msu/goodvibes-sdk",
+  "keywords": [
+    "goodvibes",
+    "sdk",
+    "errors",
+    "telemetry",
+    "transport"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}