autotel 2.22.0 → 2.23.1

package/skills/autotel-instrumentation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: autotel-instrumentation
+description: >
+  trace(), span(), instrument(), init(). Factory vs direct pattern, name inference. Sync init; use node-require for optional deps. Load when wrapping handlers or functions with spans.
+type: core
+library: autotel
+library_version: '2.23.0'
+sources:
+  - jagreehal/autotel:docs/ARCHITECTURE.md
+  - jagreehal/autotel:packages/autotel/src/functional.ts
+  - jagreehal/autotel:packages/autotel/CLAUDE.md
+---
+
+# Autotel — Instrumentation
+
+Wrap functions and handlers with `trace()`, `span()`, or `instrument()`. Call `init()` once at app startup. Keep init synchronous; use `safeRequire`/`requireModule` for optional dependencies.
+
+## Setup
+
+```typescript
+import { init, trace } from 'autotel';
+
+init({ service: 'my-app' });
+
+const handler = trace(async (req: Request) => {
+  return processRequest(req);
+});
+```
+
+With span context (attributes, request logger):
+
+```typescript
+const handler = trace((ctx) => async (req: Request) => {
+  ctx.setAttribute('http.route', '/api/checkout');
+  const log = getRequestLogger(ctx);
+  log.set({ path: req.url });
+  return processRequest(req);
+});
+```
+
+## Core Patterns
+
+**Explicit span name:**
+
+```typescript
+const checkout = trace('checkout', async (body) => {
+  return processCheckout(body);
+});
+```
+
+**instrument() with key:**
+
+```typescript
+import { instrument } from 'autotel';
+const fn = instrument({
+  key: 'processOrder',
+  fn: async (id) => db.orders.get(id),
+});
+```
+
+**span() for a child span:**
+
+```typescript
+import { span } from 'autotel';
+const result = await span('db.query', async () => db.query(sql));
+```
+
+**Init with optional config:**
+
+```typescript
+init({
+  service: 'my-api',
+  // see docs/CONFIGURATION.md for full options
+});
+```
+
+## Common Mistakes
+
+### HIGH Forget to call init() before using trace/span
+
+Wrong:
+
+```typescript
+import { trace } from 'autotel';
+export const fn = trace(async () => {});
+```
+
+Correct:
+
+```typescript
+import { init, trace } from 'autotel';
+init({ service: 'my-app' });
+export const fn = trace(async () => {});
+```
+
+SDK must be initialized; trace() and span() rely on the global tracer.
+
+Source: packages/autotel/CLAUDE.md
+
+### MEDIUM Wrong export path for submodules
+
+Wrong:
+
+```typescript
+import { Event } from 'autotel'; // Event is on autotel/event
+import { createTraceCollector } from 'autotel'; // testing subpath
+```
+
+Correct:
+
+```typescript
+import { trace, init, getRequestLogger } from 'autotel';
+import { Event } from 'autotel/event';
+import { createTraceCollector } from 'autotel/testing';
+```
+
+Use the exact export paths from package.json (autotel/event, autotel/testing, autotel/attributes, etc.).
+
+Source: packages/autotel/package.json exports
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-core/SKILL.md — when to use what. autotel-request-logging/SKILL.md — getRequestLogger requires active span.

package/skills/autotel-request-logging/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: autotel-request-logging
+description: >
+  getRequestLogger(), set(), info/warn/error, emitNow(). One snapshot per request; requires active span. Use when adding request-scoped context or replacing scattered console.log.
+type: core
+library: autotel
+library_version: '2.23.0'
+requires:
+  - autotel-instrumentation
+sources:
+  - jagreehal/autotel:packages/autotel/src/request-logger.ts
+  - jagreehal/autotel:docs/AGENT-GUIDE.md
+---
+
+# Autotel — Request Logging
+
+This skill builds on autotel-instrumentation. Read it first for init and span creation.
+
+Accumulate context with `getRequestLogger(ctx)`, `.set()`, and `.info()`/`.warn()`/`.error()`. Call `.emitNow()` (or rely on middleware) to emit one snapshot per request. Request logger requires an active span — use inside `trace()` or framework middleware.
+
+## Setup
+
+```typescript
+import { init, trace, getRequestLogger } from 'autotel';
+
+init({ service: 'my-app' });
+
+const handler = trace((ctx) => async (req: Request, res: Response) => {
+  const log = getRequestLogger(ctx);
+  log.set({ method: req.method, path: req.url });
+
+  const user = await getAuth(req);
+  log.set({ user: { id: user.id } });
+
+  const result = await doWork(req);
+  log.set({ result: { id: result.id } });
+  log.emitNow();
+  return res.json(result);
+});
+```
+
+When the framework creates the span (e.g. Hono middleware), call `getRequestLogger()` with no args:
+
+```typescript
+app.use(autotelMiddleware());
+app.get('/api/users', (c) => {
+  const log = getRequestLogger();
+  log.set({ route: 'users' });
+  return c.json({ users: [] });
+});
+```
+
+## Core Patterns
+
+**Accumulate then emit:**
+
+```typescript
+const log = getRequestLogger(ctx);
+log.set({ cart: { items: body.items.length } });
+log.set({ payment: { method: body.method } });
+log.error(err, { step: 'payment' });
+log.emitNow();
+```
+
+**RequestLogSnapshot:** `emitNow()` returns `{ timestamp, traceId, spanId, correlationId, context }`. You can pass `onEmit` in options to forward it.
+
+**Options:** `getRequestLogger(ctx?, { onEmit?: (snapshot) => void })` for custom fan-out on emit.
+
+## Common Mistakes
+
+### HIGH Call getRequestLogger() outside a span
+
+Wrong:
+
+```typescript
+function helper() {
+  const log = getRequestLogger();
+  log.set({ step: 'helper' });
+}
+```
+
+Correct:
+
+```typescript
+// Ensure helper runs inside trace() or middleware-created span
+function helper(ctx?: TraceContext) {
+  const log = getRequestLogger(ctx);
+  log.set({ step: 'helper' });
+}
+```
+
+Request logger attaches to the active span. If there is no active span, it throws. Wrap the call path with `trace()` or register middleware that creates a span per request.
+
+Source: packages/autotel/src/request-logger.ts
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-instrumentation/SKILL.md — creating the span. autotel-structured-errors/SKILL.md — use .error() to record errors in the snapshot.

package/skills/autotel-structured-errors/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: autotel-structured-errors
+description: >
+  createStructuredError, parseError, recordStructuredError. API errors with message, why, fix, link; client parsing for UI. Use in API routes and client catch blocks.
+type: core
+library: autotel
+library_version: '2.23.0'
+sources:
+  - jagreehal/autotel:packages/autotel/src/structured-error.ts
+  - jagreehal/autotel:packages/autotel/src/parse-error.ts
+  - jagreehal/autotel:docs/AGENT-GUIDE.md
+---
+
+# Autotel — Structured Errors
+
+Throw errors with `createStructuredError({ message, why?, fix?, link?, status?, cause? })` in API routes and services. On the client, use `parseError(caught)` to get `message`, `status`, `why`, `fix`, `link` for toasts and UI.
+
+## Setup
+
+**Server (API route or service):**
+
+```typescript
+import { createStructuredError } from 'autotel';
+
+if (!user) {
+  throw createStructuredError({
+    message: 'User not found',
+    status: 404,
+    why: `No user with ID "${userId}"`,
+    fix: 'Check the user ID and try again',
+    link: 'https://docs.example.com/errors/user-not-found',
+  });
+}
+```
+
+**Client:**
+
+```typescript
+import { parseError } from 'autotel';
+
+try {
+  await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(data) });
+} catch (err) {
+  const e = parseError(err);
+  toast.error(e.message, { description: e.why });
+  if (e.fix) setHelp(e.fix);
+  if (e.link) setDocLink(e.link);
+}
+```
+
+## Core Patterns
+
+**Wrap a caught error (preserve cause):**
+
+```typescript
+try {
+  await stripe.charges.create(data);
+} catch (err) {
+  throw createStructuredError({
+    message: 'Payment failed',
+    status: 402,
+    why: err instanceof Error ? err.message : 'Unknown error',
+    fix: 'Try a different payment method or contact support',
+    link: 'https://docs.stripe.com/declines',
+    cause: err,
+  });
+}
+```
+
+**Record on current span:** Use `recordStructuredError(ctx, error)` or the request logger's `.error(error, fields)` so the span gets error attributes and status.
+
+**parseError** handles FetchError (ofetch), nested `data.data`, and plain Error. Returns `{ message, status, why?, fix?, link?, raw }`.
+
+## Common Mistakes
+
+### HIGH Throw new Error() in API routes instead of createStructuredError
+
+Wrong:
+
+```typescript
+throw new Error('Payment failed');
+```
+
+Correct:
+
+```typescript
+throw createStructuredError({
+  message: 'Payment failed',
+  status: 402,
+  why: 'Card declined by issuer',
+  fix: 'Try a different payment method',
+  link: 'https://docs.example.com/payments',
+});
+```
+
+Clients and agents need structured fields (why, fix, link) for actionable errors. parseError() reads these from API responses.
+
+Source: docs/AGENT-GUIDE.md, AGENTS.md
+
+### MEDIUM Client only shows error.message and ignores why/fix/link
+
+Wrong:
+
+```typescript
+catch (err) {
+  toast.error(err.message);
+}
+```
+
+Correct:
+
+```typescript
+import { parseError } from 'autotel';
+catch (err) {
+  const e = parseError(err);
+  toast.error(e.message, { description: e.why });
+  if (e.fix) showFix(e.fix);
+  if (e.link) setDocLink(e.link);
+}
+```
+
+parseError() extracts status, why, fix, and link from API error responses and FetchError so the UI can show them.
+
+Source: docs/AGENT-GUIDE.md
+
+## Version
+
+Targets autotel v2.23.x.
+
+See also: autotel-request-logging/SKILL.md — use .error() to record errors in the request snapshot.

package/src/drain-pipeline.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createDrainPipeline } from './drain-pipeline';
+
+describe('createDrainPipeline', () => {
+  it('batches by size and sends to drain', async () => {
+    const batchDrain = vi.fn(async () => {});
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 2, intervalMs: 1000 },
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(1);
+    drain(2);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(batchDrain).toHaveBeenCalledTimes(1);
+    expect(batchDrain).toHaveBeenCalledWith([1, 2]);
+    expect(drain.pending).toBe(0);
+  });
+
+  it('retries failed batches and eventually succeeds', async () => {
+    let attempts = 0;
+    const batchDrain = vi.fn(async () => {
+      attempts++;
+      if (attempts < 2) throw new Error('temporary');
+    });
+
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 1, intervalMs: 1000 },
+      retry: {
+        maxAttempts: 3,
+        initialDelayMs: 1,
+        maxDelayMs: 2,
+        backoff: 'fixed',
+        jitter: false,
+      },
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(42);
+    await drain.flush();
+
+    expect(batchDrain).toHaveBeenCalledTimes(2);
+    expect(drain.pending).toBe(0);
+  });
+
+  it('drops overflowed events based on policy', async () => {
+    const dropped: number[] = [];
+    const batchDrain = vi.fn(async () => {});
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 10, intervalMs: 1000 },
+      maxBufferSize: 2,
+      dropPolicy: 'oldest',
+      onDropped: (events) => dropped.push(...events),
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(1);
+    drain(2);
+    drain(3); // drops 1
+
+    expect(dropped).toEqual([1]);
+    expect(drain.pending).toBe(2);
+
+    await drain.flush();
+    expect(batchDrain).toHaveBeenCalledWith([2, 3]);
+  });
+});

package/src/drain-pipeline.ts

@@ -0,0 +1,199 @@
+export interface DrainPipelineOptions<T = unknown> {
+  batch?: {
+    /** Maximum events per batch. @default 50 */
+    size?: number;
+    /** Max time an event can stay buffered before flush. @default 5000 */
+    intervalMs?: number;
+  };
+  retry?: {
+    /** Total attempts including first try. @default 3 */
+    maxAttempts?: number;
+    /** Delay strategy between attempts. @default 'exponential' */
+    backoff?: 'exponential' | 'linear' | 'fixed';
+    /** Base delay for first retry. @default 1000 */
+    initialDelayMs?: number;
+    /** Max delay cap. @default 30000 */
+    maxDelayMs?: number;
+    /** Add random jitter to delays. @default true */
+    jitter?: boolean;
+  };
+  /** Max buffered events before dropping. @default 1000 */
+  maxBufferSize?: number;
+  /** Overflow policy. @default 'oldest' */
+  dropPolicy?: 'oldest' | 'newest';
+  /** Called when events are dropped from overflow or exhausted retries. */
+  onDropped?: (events: T[], error?: Error) => void;
+}
+
+export interface PipelineDrainFn<T> {
+  (ctx: T): void;
+  /** Flush all buffered events. */
+  flush: () => Promise<void>;
+  /** Flush and stop scheduling future timer work. */
+  shutdown: () => Promise<void>;
+  readonly pending: number;
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+export function createDrainPipeline<T = unknown>(
+  options?: DrainPipelineOptions<T>,
+): (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T> {
+  const batchSize = options?.batch?.size ?? 50;
+  const intervalMs = options?.batch?.intervalMs ?? 5000;
+  const maxBufferSize = options?.maxBufferSize ?? 1000;
+  const maxAttempts = options?.retry?.maxAttempts ?? 3;
+  const backoff = options?.retry?.backoff ?? 'exponential';
+  const initialDelayMs = options?.retry?.initialDelayMs ?? 1000;
+  const maxDelayMs = options?.retry?.maxDelayMs ?? 30_000;
+  const jitter = options?.retry?.jitter ?? true;
+  const dropPolicy = options?.dropPolicy ?? 'oldest';
+  const onDropped = options?.onDropped;
+
+  if (!Number.isFinite(batchSize) || batchSize <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] batch.size must be a positive finite number, got: ${batchSize}`,
+    );
+  }
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] batch.intervalMs must be a positive finite number, got: ${intervalMs}`,
+    );
+  }
+  if (!Number.isFinite(maxBufferSize) || maxBufferSize <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] maxBufferSize must be a positive finite number, got: ${maxBufferSize}`,
+    );
+  }
+  if (!Number.isFinite(maxAttempts) || maxAttempts <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] retry.maxAttempts must be a positive finite number, got: ${maxAttempts}`,
+    );
+  }
+
+  return (drain: (batch: T[]) => void | Promise<void>): PipelineDrainFn<T> => {
+    const buffer: T[] = [];
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let activeFlush: Promise<void> | null = null;
+    let isShutdown = false;
+
+    const clearTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+
+    const computeDelay = (attempt: number): number => {
+      const base =
+        backoff === 'fixed'
+          ? initialDelayMs
+          : backoff === 'linear'
+            ? initialDelayMs * attempt
+            : initialDelayMs * 2 ** (attempt - 1);
+
+      const bounded = Math.min(base, maxDelayMs);
+      if (!jitter || bounded <= 0) return bounded;
+      const factor = 0.5 + Math.random(); // [0.5, 1.5)
+      return Math.max(0, Math.round(bounded * factor));
+    };
+
+    const sendWithRetry = async (batch: T[]): Promise<void> => {
+      let lastError: Error | undefined;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          await drain(batch);
+          return;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < maxAttempts) {
+            await wait(computeDelay(attempt));
+          }
+        }
+      }
+      onDropped?.(batch, lastError);
+    };
+
+    const drainBuffer = async (): Promise<void> => {
+      while (buffer.length > 0) {
+        const batch = buffer.splice(0, batchSize);
+        await sendWithRetry(batch);
+      }
+    };
+
+    const scheduleFlush = () => {
+      if (isShutdown || timer || activeFlush) return;
+      timer = setTimeout(() => {
+        timer = null;
+        startFlush();
+      }, intervalMs);
+      timer.unref?.();
+    };
+
+    const startFlush = () => {
+      if (activeFlush || isShutdown) return;
+      activeFlush = drainBuffer().finally(() => {
+        activeFlush = null;
+        if (isShutdown) return;
+        if (buffer.length >= batchSize) {
+          startFlush();
+        } else if (buffer.length > 0) {
+          scheduleFlush();
+        }
+      });
+    };
+
+    const push = (ctx: T) => {
+      if (isShutdown) return;
+
+      if (buffer.length >= maxBufferSize) {
+        if (dropPolicy === 'newest') {
+          onDropped?.([ctx]);
+          return;
+        }
+        const dropped = buffer.splice(0, 1);
+        onDropped?.(dropped);
+      }
+
+      buffer.push(ctx);
+      if (buffer.length >= batchSize) {
+        clearTimer();
+        startFlush();
+      } else {
+        scheduleFlush();
+      }
+    };
+
+    const flush = async (): Promise<void> => {
+      clearTimer();
+      if (activeFlush) await activeFlush;
+
+      const snapshot = buffer.length;
+      if (snapshot <= 0) return;
+      const toFlush = buffer.splice(0, snapshot);
+      while (toFlush.length > 0) {
+        const batch = toFlush.splice(0, batchSize);
+        await sendWithRetry(batch);
+      }
+    };
+
+    const shutdown = async (): Promise<void> => {
+      isShutdown = true;
+      await flush();
+    };
+
+    const fn = push as PipelineDrainFn<T>;
+    fn.flush = flush;
+    fn.shutdown = shutdown;
+    Object.defineProperty(fn, 'pending', {
+      enumerable: true,
+      get: () => buffer.length,
+    });
+    return fn;
+  };
+}