@pellux/goodvibes-errors

Public GoodVibes error package for structured SDK, transport, and daemon failures.

Most applications should install @pellux/goodvibes-sdk and import @pellux/goodvibes-sdk/errors. Install this package directly when you only need the shared error model.

Install

npm install @pellux/goodvibes-errors

The error model

Every error thrown from the SDK's public surface is a GoodVibesSdkError. The kind field is the primary discriminant — switch on it instead of instanceof chains or message parsing:

import { GoodVibesSdkError } from '@pellux/goodvibes-errors';

try {
  await callIntegration();
} catch (err) {
  if (err instanceof GoodVibesSdkError) {
    switch (err.kind) {
      case 'auth':       /* re-authenticate */ break;
      case 'rate-limit': await delay(err.retryAfterMs ?? 1000); break;
      case 'network':
      case 'service':    if (err.recoverable) { /* retry with backoff */ } break;
      default:           /* log and surface */ break;
    }
  } else {
    throw err;
  }
}

Concrete subclasses (ConfigurationError, ContractError, HttpStatusError) remain available for class-specific handling:

import { HttpStatusError } from '@pellux/goodvibes-errors';

try {
  // integration code
} catch (error) {
  if (error instanceof HttpStatusError && error.status === 401) {
    // re-authenticate
  }
}

The same symbols are re-exported from the SDK facade, so SDK consumers can import them from @pellux/goodvibes-sdk/errors instead:

import { HttpStatusError } from '@pellux/goodvibes-sdk/errors';

Branch on structured fields

Use the structured fields instead of fragile message parsing:

• HTTP status (status)
• error category (category) and source (source)
• recovery hints (recoverable, hint, retryAfterMs)
• request correlation (requestId)
• typed code (code) — match it with isErrorCode(err, SDKErrorCodes.RATE_LIMITED)

Daemon wire contract

The ./daemon-error-contract subpath exports the daemon-side wire types, independent of the runtime error classes:

import {
  DaemonErrorCategory,
  type DaemonErrorSource,
  type StructuredDaemonErrorBody,
} from '@pellux/goodvibes-errors/daemon-error-contract';

DaemonErrorCategory is both a string-literal union and a runtime const; StructuredDaemonErrorBody is the JSON shape the daemon returns in HTTP error responses.

The exported fields are intended to replace fragile message parsing in client and daemon integrations.

Documentation

• SDK Error Kinds — per-kind consumer reference
• Error Handling — handling patterns
• Error Architecture — internal source map