Errors

PluckError
├── ConnectionError       – connect phase, network-level failures
├── AuthenticationError   – connect phase, bad credentials
├── RateLimitError        – connect phase, 429s
├── TimeoutError          – any phase, per-call timeout exceeded
├── NavigationError       – navigate phase
├── ExtractionError       – extract phase
├── TranscriptionError    – extract phase, Whisper-specific
├── ActionError           – act phase
├── SenseError            – sense phase
├── OutputError           – output phase, format rendering failures
└── InvalidInputError     – argument validation anywhere

import { pluck, PluckError, ConnectionError, RateLimitError } from "@sizls/pluck";

try {
  await pluck("https://flaky.example.com");
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep(err.retryAfterMs ?? 30_000);
    return retry();
  }
  if (err instanceof ConnectionError) {
    console.error("Network:", err.code, err.message);
    return;
  }
  if (err instanceof PluckError) {
    console.error(`[${err.phase}] ${err.code}: ${err.message}`);
    return;
  }
  throw err; // unknown – let it bubble.
}

class PluckError extends Error {
  readonly code: string;               // Stable code above
  readonly phase: PluckPhase;          // "connect" | ... | "output"
  readonly cause?: unknown;            // Original error, when wrapping
  readonly details?: Record<string, unknown>; // Phase-specific metadata
}

import { pluck } from "@sizls/pluck";

const safe = await pluck.safe("https://broken.example.com");

if (!safe.success) {
  logger.error(JSON.stringify(safe.error, null, 2));
  // {
  //   "name": "ConnectionError",
  //   "code": "DNS_ERROR",
  //   "phase": "connect",
  //   "message": "getaddrinfo ENOTFOUND broken.example.com",
  //   "details": { "hostname": "broken.example.com" }
  // }
}

const res = await pluck.safe("https://example.com");

if (res.success) {
  console.log(res.data.text);
} else {
  console.error(`[${res.error.phase}] ${res.error.code}`);
}