autotel 4.1.0 → 4.2.0

package/src/error-catalog.test.ts

@@ -1,133 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  defineErrorCatalog,
-  defineAuditCatalog,
-  isCatalogError,
-  getCatalogCode,
-} from './error-catalog';
-
-describe('defineErrorCatalog', () => {
-  const billing = defineErrorCatalog('billing', {
-    PAYMENT_DECLINED: {
-      status: 402,
-      message: 'Card declined',
-      why: 'The issuer rejected the charge',
-      fix: 'Try a different payment method',
-      link: 'https://docs.example.com/billing',
-    },
-    INSUFFICIENT_FUNDS: {
-      status: 402,
-      message: ({
-        available,
-        required,
-      }: {
-        available: number;
-        required: number;
-      }) => `Insufficient funds: $${available} of $${required}`,
-      why: ({ required }: { available: number; required: number }) =>
-        `Needs $${required}`,
-    },
-    LEGACY: {
-      code: 'BILLING_LEGACY_42',
-      message: 'Legacy failure',
-    },
-  });
-
-  it('builds a structured error from a static entry', () => {
-    const err = billing.PAYMENT_DECLINED();
-    expect(err).toBeInstanceOf(Error);
-    expect(err.message).toBe('Card declined');
-    expect(err.status).toBe(402);
-    expect(err.why).toBe('The issuer rejected the charge');
-    expect(err.fix).toBe('Try a different payment method');
-    expect(err.link).toBe('https://docs.example.com/billing');
-    expect(err.code).toBe('billing.PAYMENT_DECLINED');
-    expect(err.name).toBe('PAYMENT_DECLINED');
-  });
-
-  it('interpolates typed params in message and why', () => {
-    const err = billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
-    expect(err.message).toBe('Insufficient funds: $5 of $100');
-    expect(err.why).toBe('Needs $100');
-  });
-
-  it('honors a custom code', () => {
-    const err = billing.LEGACY();
-    expect(err.code).toBe('BILLING_LEGACY_42');
-  });
-
-  it('exposes the code on the builder', () => {
-    expect(billing.PAYMENT_DECLINED.code).toBe('billing.PAYMENT_DECLINED');
-    expect(billing.LEGACY.code).toBe('BILLING_LEGACY_42');
-  });
-
-  it('matches its own errors and rejects others', () => {
-    const declined = billing.PAYMENT_DECLINED();
-    const funds = billing.INSUFFICIENT_FUNDS({ available: 1, required: 2 });
-    expect(billing.PAYMENT_DECLINED.match(declined)).toBe(true);
-    expect(billing.PAYMENT_DECLINED.match(funds)).toBe(false);
-    expect(billing.PAYMENT_DECLINED.match(new Error('nope'))).toBe(false);
-    expect(billing.PAYMENT_DECLINED.match(null)).toBe(false);
-  });
-
-  it('tags errors so isCatalogError / getCatalogCode work', () => {
-    const err = billing.PAYMENT_DECLINED();
-    expect(isCatalogError(err)).toBe(true);
-    expect(isCatalogError(new Error('plain'))).toBe(false);
-    expect(getCatalogCode(err)).toBe('billing.PAYMENT_DECLINED');
-    expect(getCatalogCode(new Error('plain'))).toBeUndefined();
-  });
-
-  it('passes cause, details, and internal through build options', () => {
-    const cause = new Error('stripe boom');
-    const err = billing.PAYMENT_DECLINED({
-      cause,
-      details: { attempt: 2 },
-      internal: { stripeId: 'ch_1' },
-    });
-    expect(err.cause).toBe(cause);
-    expect(err.details).toEqual({ attempt: 2 });
-    expect(err.internal).toEqual({ stripeId: 'ch_1' });
-  });
-
-  it('accepts options as the second arg for param entries', () => {
-    const cause = new Error('root');
-    const err = billing.INSUFFICIENT_FUNDS(
-      { available: 5, required: 100 },
-      { cause },
-    );
-    expect(err.message).toBe('Insufficient funds: $5 of $100');
-    expect(err.cause).toBe(cause);
-  });
-});
-
-describe('defineAuditCatalog', () => {
-  const audit = defineAuditCatalog('user', {
-    LOGIN: { message: 'User logged in' },
-    ROLE_CHANGED: {
-      severity: 'critical',
-      message: ({ role }: { role: string }) => `Role set to ${role}`,
-    },
-    DELETED: { action: 'user.account.deleted', severity: 'warn' },
-  });
-
-  it('produces typed action descriptors with defaults', () => {
-    const action = audit.LOGIN();
-    expect(action.action).toBe('user.LOGIN');
-    expect(action.severity).toBe('info');
-    expect(action.message).toBe('User logged in');
-  });
-
-  it('interpolates params and respects severity', () => {
-    const action = audit.ROLE_CHANGED({ role: 'admin' });
-    expect(action.action).toBe('user.ROLE_CHANGED');
-    expect(action.severity).toBe('critical');
-    expect(action.message).toBe('Role set to admin');
-  });
-
-  it('honors a custom action name', () => {
-    expect(audit.DELETED.action).toBe('user.account.deleted');
-    expect(audit.DELETED.severity).toBe('warn');
-    expect(audit.DELETED().message).toBeUndefined();
-  });
-});

package/src/error-catalog.ts

@@ -1,262 +0,0 @@
-/**
- * Typed error and audit catalogs.
- *
- * Group related errors into one catalog and get a refactor-safe builder per
- * code, with autocomplete at every call site and typed message parameters.
- *
- * @example
- * ```typescript
- * import { defineErrorCatalog } from 'autotel';
- *
- * export const billing = defineErrorCatalog('billing', {
- *   PAYMENT_DECLINED: {
- *     status: 402,
- *     message: 'Card declined',
- *     why: 'The issuer rejected the charge',
- *     fix: 'Try a different payment method',
- *   },
- *   INSUFFICIENT_FUNDS: {
- *     status: 402,
- *     message: ({ available, required }: { available: number; required: number }) =>
- *       `Insufficient funds: $${available} of $${required}`,
- *   },
- * });
- *
- * throw billing.PAYMENT_DECLINED({ cause: stripeError });
- * throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
- *
- * // In a catch block — refactor-safe, no magic strings:
- * if (billing.PAYMENT_DECLINED.match(err)) { ... }
- * ```
- */
-
-import {
-  createStructuredError,
-  type StructuredError,
-} from './structured-error';
-
-const catalogCodeKey = Symbol.for('autotel.catalog.code');
-
-/** Definition of a single error in a catalog. */
-export interface ErrorCatalogEntry {
-  /**
-   * Human-readable message. Use a function to interpolate typed parameters;
-   * the parameter type flows through to the call site.
-   */
-  message: string | ((params: never) => string);
-  /** HTTP status to surface to clients. */
-  status?: number;
-  /** Stable error code. Defaults to `${namespace}.${KEY}`. */
-  code?: string | number;
-  /** Why it happened. A function receives the same params as `message`. */
-  why?: string | ((params: never) => string);
-  /** What the caller should do next. */
-  fix?: string;
-  /** Docs or runbook link. */
-  link?: string;
-  /** Error name. Defaults to the catalog key. */
-  name?: string;
-}
-
-/** Per-call options passed alongside (or instead of) typed params. */
-export interface ErrorBuildOptions {
-  cause?: unknown;
-  details?: Record<string, unknown>;
-  /** Backend-only context. Never serialized to clients. */
-  internal?: Record<string, unknown>;
-}
-
-type ParamsOf<E> = E extends { message: (params: infer P) => string }
-  ? P
-  : E extends { why: (params: infer P) => string }
-    ? P
-    : void;
-
-type BuilderArgs<E extends ErrorCatalogEntry> =
-  ParamsOf<E> extends void
-    ? [options?: ErrorBuildOptions]
-    : [params: ParamsOf<E>, options?: ErrorBuildOptions];
-
-/** A callable error factory produced by {@link defineErrorCatalog}. */
-export interface ErrorBuilder<E extends ErrorCatalogEntry> {
-  (...args: BuilderArgs<E>): StructuredError;
-  /** Stable code assigned to every error from this entry. */
-  readonly code: string | number;
-  /** True when `error` was produced by this catalog entry. */
-  match(error: unknown): boolean;
-}
-
-export type ErrorCatalog<T extends Record<string, ErrorCatalogEntry>> = {
-  readonly [K in keyof T]: ErrorBuilder<T[K]>;
-};
-
-function readCatalogCode(error: unknown): string | number | undefined {
-  if (error === null || typeof error !== 'object') return undefined;
-  return (error as Record<symbol, unknown>)[catalogCodeKey] as
-    | string
-    | number
-    | undefined;
-}
-
-/** True when `error` was produced by any autotel error catalog. */
-export function isCatalogError(error: unknown): error is StructuredError {
-  return readCatalogCode(error) !== undefined;
-}
-
-/** Returns the catalog code of `error`, or `undefined` if it has none. */
-export function getCatalogCode(error: unknown): string | number | undefined {
-  return readCatalogCode(error);
-}
-
-/**
- * Define a typed error catalog. Returns an object whose keys are error
- * builders. Each builder produces a {@link StructuredError} carrying the
- * entry's message, status, code, why, fix, and link.
- */
-export function defineErrorCatalog<
-  const T extends Record<string, ErrorCatalogEntry>,
->(namespace: string, entries: T): ErrorCatalog<T> {
-  const catalog: Record<string, ErrorBuilder<ErrorCatalogEntry>> = {};
-
-  for (const [key, entry] of Object.entries(entries) as [
-    string,
-    ErrorCatalogEntry,
-  ][]) {
-    const code = entry.code ?? `${namespace}.${key}`;
-    const usesParams =
-      typeof entry.message === 'function' || typeof entry.why === 'function';
-
-    const builder = ((
-      paramsOrOptions?: unknown,
-      maybeOptions?: ErrorBuildOptions,
-    ): StructuredError => {
-      const params = usesParams ? paramsOrOptions : undefined;
-      const options = (usesParams ? maybeOptions : paramsOrOptions) as
-        | ErrorBuildOptions
-        | undefined;
-
-      const message =
-        typeof entry.message === 'function'
-          ? (entry.message as (p: unknown) => string)(params)
-          : entry.message;
-      const why =
-        typeof entry.why === 'function'
-          ? (entry.why as (p: unknown) => string)(params)
-          : entry.why;
-
-      const error = createStructuredError({
-        message,
-        name: entry.name ?? key,
-        code,
-        ...(entry.status === undefined ? {} : { status: entry.status }),
-        ...(why === undefined ? {} : { why }),
-        ...(entry.fix === undefined ? {} : { fix: entry.fix }),
-        ...(entry.link === undefined ? {} : { link: entry.link }),
-        ...(options?.cause === undefined ? {} : { cause: options.cause }),
-        ...(options?.details === undefined ? {} : { details: options.details }),
-        ...(options?.internal === undefined
-          ? {}
-          : { internal: options.internal }),
-      });
-
-      Object.defineProperty(error, catalogCodeKey, {
-        value: code,
-        enumerable: false,
-        writable: false,
-        configurable: true,
-      });
-
-      return error;
-    }) as ErrorBuilder<ErrorCatalogEntry>;
-
-    Object.defineProperty(builder, 'code', {
-      value: code,
-      enumerable: true,
-    });
-    Object.defineProperty(builder, 'match', {
-      value: (error: unknown): boolean => readCatalogCode(error) === code,
-      enumerable: false,
-    });
-
-    catalog[key] = builder;
-  }
-
-  return Object.freeze(catalog) as ErrorCatalog<T>;
-}
-
-/** Severity of an audit action. */
-export type AuditSeverity = 'info' | 'warn' | 'critical';
-
-/** Definition of a single action in an audit catalog. */
-export interface AuditCatalogEntry {
-  /** Human-readable description. Use a function for typed params. */
-  message?: string | ((params: never) => string);
-  /** Stable action name. Defaults to `${namespace}.${KEY}`. */
-  action?: string;
-  /** Severity of the action. Defaults to `'info'`. */
-  severity?: AuditSeverity;
-}
-
-/** A resolved audit action descriptor produced by an audit catalog. */
-export interface AuditAction {
-  readonly action: string;
-  readonly severity: AuditSeverity;
-  readonly message?: string;
-}
-
-type AuditDescriptorArgs<E extends AuditCatalogEntry> =
-  ParamsOf<E> extends void ? [] : [params: ParamsOf<E>];
-
-/** A callable audit-action descriptor produced by {@link defineAuditCatalog}. */
-export interface AuditDescriptor<E extends AuditCatalogEntry> {
-  (...args: AuditDescriptorArgs<E>): AuditAction;
-  readonly action: string;
-  readonly severity: AuditSeverity;
-}
-
-export type AuditCatalog<T extends Record<string, AuditCatalogEntry>> = {
-  readonly [K in keyof T]: AuditDescriptor<T[K]>;
-};
-
-/**
- * Define a typed audit catalog. Returns typed action descriptors you can pass
- * to `track()` or audit helpers without scattering magic strings.
- */
-export function defineAuditCatalog<
-  const T extends Record<string, AuditCatalogEntry>,
->(namespace: string, entries: T): AuditCatalog<T> {
-  const catalog: Record<string, AuditDescriptor<AuditCatalogEntry>> = {};
-
-  for (const [key, entry] of Object.entries(entries) as [
-    string,
-    AuditCatalogEntry,
-  ][]) {
-    const action = entry.action ?? `${namespace}.${key}`;
-    const severity: AuditSeverity = entry.severity ?? 'info';
-
-    const descriptor = ((params?: unknown): AuditAction => {
-      const message =
-        typeof entry.message === 'function'
-          ? (entry.message as (p: unknown) => string)(params)
-          : entry.message;
-      return Object.freeze({
-        action,
-        severity,
-        ...(message === undefined ? {} : { message }),
-      });
-    }) as AuditDescriptor<AuditCatalogEntry>;
-
-    Object.defineProperty(descriptor, 'action', {
-      value: action,
-      enumerable: true,
-    });
-    Object.defineProperty(descriptor, 'severity', {
-      value: severity,
-      enumerable: true,
-    });
-
-    catalog[key] = descriptor;
-  }
-
-  return Object.freeze(catalog) as AuditCatalog<T>;
-}