bunqueue-client 0.1.9 → 0.2.0

package/README.md

@@ -1,381 +1,236 @@
-<div align="center">
-
-<a href="https://bunqueue.dev">
-  <img src="https://raw.githubusercontent.com/egeominotti/bunqueue/main/.github/logo.png" alt="bunqueue logo" width="110" />
-</a>
-
 # bunqueue-client
 
-**The official TypeScript client for [bunqueue](https://bunqueue.dev), the high performance job queue server.**
-
-Native TCP protocol (msgpack, pipelined), full parity with the built in Bun client, one runtime dependency.
-Runs everywhere: Node.js, Bun, Deno and Cloudflare Workers.
-
-[![npm version](https://img.shields.io/npm/v/bunqueue-client?color=d3156d&label=npm)](https://www.npmjs.com/package/bunqueue-client)
-[![npm downloads](https://img.shields.io/npm/dm/bunqueue-client?color=ff4f9f)](https://www.npmjs.com/package/bunqueue-client)
-[![license](https://img.shields.io/npm/l/bunqueue-client?color=1a1a2e)](https://github.com/egeominotti/bunqueue/blob/main/sdk/typescript/LICENSE)
-[![runtimes](https://img.shields.io/badge/runtimes-node%20%7C%20bun%20%7C%20deno%20%7C%20workers-2ea44f)](#compatibility)
-
-[Documentation](https://bunqueue.dev/guide/sdks/) · [Server](https://github.com/egeominotti/bunqueue) · [Changelog](https://github.com/egeominotti/bunqueue/blob/main/sdk/typescript/CHANGELOG.md) · [Python SDK](https://github.com/egeominotti/bunqueue/tree/main/sdk/python)
-
-</div>
-
----
-
-The bunqueue server runs on Bun, distributed as a binary or a Docker image. This client allows any Node.js, Bun, Deno, or Cloudflare Workers service to produce and consume jobs against it: one queue, any language, any runtime.
-
-## Why bunqueue-client
-
-- **Full API surface.** Queues, workers, flows (parent/children trees), schedulers, DLQ, rate limits, webhooks, Simple Mode: 110+ public methods, each covered by an e2e test against a real server.
-- **Cross runtime by design.** Only `node:*` builtins, zero `Bun.*` globals, a single dependency (`msgpackr`). The same package runs on Node 20+, Bun, Deno 2 and Cloudflare Workers (`nodejs_compat`).
-- **Production semantics.** Lock leasing with heartbeat renewal, at least once delivery with retries and backoff, unrecoverable failures straight to the DLQ, reconnection with half open detection, opt in ACK batching and connection pooling.
-- **Typed end to end.** Generic `Queue<T>` / `Worker<T, R>`, typed worker events, structured telemetry hooks for your metrics stack.
-
-## Compatibility
-
-| Runtime | Status | Notes |
-|---|---|---|
-| Node.js 20 or later | Supported, 110/110 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
-| Bun | Supported, 110/110 e2e and 8/8 integration tests | No additional configuration required |
-| Deno 2 or later | Supported, 110/110 e2e and 8/8 integration tests | Uses `node:` builtins and the npm `msgpackr` package |
-| tsx, ts-node, vitest, jest | Supported | These environments execute on Node.js |
-| Cloudflare Workers | Supported, 16/16 e2e tests inside workerd, including Simple Mode and the full API surface | Requires the `nodejs_compat` compatibility flag. The runtime is request scoped, so long lived worker loops are not available: consume in batches from Cron Triggers or Durable Object alarms, a pattern covered by the test suite. TLS connections require a publicly trusted certificate |
-| Browser | Not supported | Raw TCP sockets are unavailable. Use the server HTTP API instead |
-
-Portability is guaranteed by design: the client relies exclusively on `node:*` builtins (`net`, `tls`, `events`, `crypto`, `os`), uses no `Bun.*` globals and no runtime specific imports, and carries a single runtime dependency, `msgpackr`.
-
-## Installation
+The cross-runtime distribution of the canonical `bunqueue/client` API.
+Queue, Worker, QueueEvents, QueueGroup, FlowProducer, Simple Mode, groups,
+processor batches, options, job objects, and errors come from the same source.
+The portable build replaces runtime I/O primitives; it does not maintain a
+second implementation of queue or worker behavior.
 
-```bash
-npm install bunqueue-client
-# or: bun add bunqueue-client / pnpm add bunqueue-client / deno add npm:bunqueue-client
-```
-
-## Quick start, step by step
-
-Every step from zero to a production ready queue.
-
-### Step 1. Run the bunqueue server
-
-The server is the only component that requires [Bun](https://bun.sh). Pick one:
-
-```bash
-# Option A: one command, no install (requires Bun)
-bunx bunqueue start
+> **Upgrading from 0.1.x?** 0.2.0 is a breaking release: the default entry is
+> now the canonical client. Read [Migrating from 0.1.x](#migrating-from-01x),
+> or keep the old API unchanged with `bunqueue-client/legacy`.
 
-# Option B: Docker, with persistent data
-docker run -d --name bunqueue \
-  -p 6789:6789 -p 6790:6790 \
-  -v bunqueue-data:/app/data \
-  ghcr.io/egeominotti/bunqueue:latest
-```
-
-Port 6789 is the TCP protocol (what this client uses), port 6790 is the HTTP API with `/health`, `/metrics`, and dashboard endpoints.
+## Install and run
 
-### Step 2. Install the client
-
-```bash
+```sh
 npm install bunqueue-client
-# or: bun add bunqueue-client / pnpm add bunqueue-client / deno add npm:bunqueue-client
-```
-
-### Step 3. Add your first job and process it
-
-Create `app.ts`, one file for the sake of the demo:
-
-```typescript
-import { Queue, Worker } from 'bunqueue-client';
-
-const worker = new Worker('hello', async (job) => {
-  console.log('processing', job.data);
-  return { greeted: job.data.name };
-});
-worker.on('completed', (job, result) => {
-  console.log('completed', job.id, result);
-  worker.close();
-});
-
-const queue = new Queue('hello');
-await queue.add('greet', { name: 'world' });
-queue.close();
-```
-
-Run it with the runtime you already use:
-
-```bash
-node --experimental-strip-types app.ts    # Node 22 or later
-bun app.ts                                # Bun
-deno run -A app.ts                        # Deno 2 or later
-```
-
-Expected output:
-
-```
-processing { name: 'world' }
-completed 019f40a5-... { greeted: 'world' }
-```
-
-Defaults are `host: 'localhost'` and `port: 6789`, so constructors need no options on a local setup.
-
-### Step 4. Split producer and worker
-
-In production the producer and the worker are separate services, often in different languages. The producer is typically an API endpoint:
-
-```typescript
-// api-service: adds jobs, no processing
-import { Queue } from 'bunqueue-client';
-const queue = new Queue('emails', { host: 'queue.internal', port: 6789 });
-await queue.add('welcome', { to: 'user@example.com' }, { attempts: 3 });
 ```
 
-The worker is a long running process:
+Start a bunqueue broker, then use the same code in Node.js, Deno, or Bun:
 
 ```typescript
-// worker-service: processes jobs, no HTTP
-import { Worker } from 'bunqueue-client';
-new Worker('emails', sendEmail, { host: 'queue.internal', port: 6789, concurrency: 10 });
-```
-
-The [Python client](https://github.com/egeominotti/bunqueue/tree/main/sdk/python) speaks the same protocol against the same queue, so the worker can be a Python service instead.
-
-### Step 5. Observe and operate
+import { Queue, Worker, QueueEvents } from 'bunqueue-client';
+
+const options = {
+  embedded: false,
+  connection: { host: '127.0.0.1', port: 6789 },
+};
+const queue = new Queue<{ to: string }>('emails', options);
+const events = new QueueEvents('emails', options);
+await events.waitUntilReady();
+const worker = new Worker('emails', async (job) => {
+  await job.updateProgress(50);
+  await job.log('Sending email');
+  return { sent: true };
+}, { ...options, concurrency: 5 });
+worker.on('error', console.error);
+
+const job = await queue.add('welcome', { to: 'user@example.com' });
+const result = await queue.waitJobUntilFinished(job.id, events, 30_000);
+console.log(result);
+
+await worker.close();
+events.close();
+await queue.close();
+```
+
+Node.js 20+, Bun, Deno 2+, and Cloudflare Workers with `nodejs_compat` can
+connect over TCP. Install with npm-compatible tooling in the chosen runtime.
+The embedded SQLite engine continues to require Bun; under Bun the package
+loads the actual shared engine synchronously the first time `embedded: true`
+is used. Node, Deno, and Workers never load `bun:sqlite`. Database
+configuration for TCP belongs on the broker.
+
+The published JavaScript has no top-level `await`, so CommonJS bundlers
+(for example `esbuild --bundle --format=cjs` for AWS Lambda) accept it. esbuild
+reports one harmless `empty-import-meta` warning for the Bun-only engine
+loader; embedded mode is unavailable from a CommonJS re-bundle and says so.
+
+TypeScript declarations are self-contained: they reference neither `bun-types`
+nor Bun globals, and the package does not install `@types/node`. Node projects
+use their own `@types/node` (20 or newer) and type-check with
+`skipLibCheck: false`, with or without the DOM library.
+
+## One public contract
+
+Use the [Queue guide](https://bunqueue.dev/guide/queue/),
+[Worker guide](https://bunqueue.dev/guide/worker/), and
+[Flow guide](https://bunqueue.dev/guide/flow/), replacing the import path
+`bunqueue/client` with `bunqueue-client`.
+
+- Connection settings use `connection: { host, port, token, ... }`.
+- Constructor defaults, per-job defaults, return shapes, errors, and events
+  follow the canonical Bun client.
+- Use the `Async` administrative/query variants for authoritative TCP reads
+  and ordered operations. The synchronous embedded-only methods retain the
+  canonical contract; they do not become asynchronous by changing packages.
+- `QueuePro`, `WorkerPro`, and `QueueEventsPro` are the same canonical aliases.
+- Native processor batches and broker-authoritative job groups share the
+  same implementation and lease/counter transitions as the Bun client.
+- `SandboxedWorker` shares its pool logic, with a portable worker-thread
+  adapter. It remains experimental execution isolation, not a security
+  boundary. Processor modules must be executable by the host runtime.
+
+Low-level `Connection`, `ConnectionPool`, and telemetry helpers remain
+additive exports. They do not redefine canonical Queue or Worker types.
+
+## Migrating from 0.1.x
+
+0.2.0 makes the canonical `bunqueue/client` API the default entry. Nothing
+below applies to code that switches its import to `bunqueue-client/legacy`.
+
+### 1. Keep the 0.1.x API unchanged
+
+The compatibility entry keeps the historical flat-option API, method
+signatures, `Job` class, error classes, and wire types exactly as in 0.1.x.
+See [LEGACY.md](./LEGACY.md).
 
 ```typescript
-await queue.getJobCounts();      // { waiting, active, completed, failed, delayed, ... }
-await queue.getDlq();            // jobs that exhausted their retries
-await queue.retryDlq();          // send them back to the queue
-await queue.getWorkers();        // connected workers
-await queue.getStats();          // throughput and totals
+// Before (0.1.x)
+import { Queue, Worker } from 'bunqueue-client';
+// After: same behavior, no other change
+import { Queue, Worker } from 'bunqueue-client/legacy';
 ```
 
-Or hit the HTTP side: `curl http://localhost:6790/health`.
-
-### Step 6. Go to production
+### 2. Connection options live in `connection`
 
 ```typescript
+// Before (0.1.x)
+const queue = new Queue('emails', { host: 'queue.internal', port: 6789, token, tls: true });
+// After (0.2.0)
 const queue = new Queue('emails', {
-  host: 'queue.example.com',
-  port: 6789,
-  token: process.env.BUNQUEUE_TOKEN,   // server started with AUTH_TOKENS=...
-  tls: true,                            // or { caFile: './ca.pem' }
-});
-```
-
-Checklist: set `AUTH_TOKENS` on the server, enable TLS (`TLS_CERT_FILE`/`TLS_KEY_FILE`), mount a volume for the SQLite data path, monitor `/health` and `/metrics`, and size worker `concurrency` to your workload. Full guide: [bunqueue.dev/guide/deployment](https://bunqueue.dev/guide/deployment/).
-
-## Producing jobs
-
-```typescript
-import { Queue } from 'bunqueue-client';
-
-const queue = new Queue('emails', { host: 'localhost', port: 6789 });
-
-await queue.add('send', { to: 'user@example.com' }, { priority: 5, attempts: 3 });
-await queue.addBulk([
-  { name: 'send', data: { to: 'a@b.c' } },
-  { name: 'send', data: { to: 'x@y.z' }, opts: { delay: 5000 } },
-]);
-
-const counts = await queue.getJobCounts();
-queue.close();
-```
-
-## Processing jobs
-
-```typescript
-import { Worker, UnrecoverableError } from 'bunqueue-client';
-
-const worker = new Worker(
-  'emails',
-  async (job) => {
-    await job.updateProgress(50);
-    if (job.data.invalid) throw new UnrecoverableError('bad payload'); // no retries, straight to the DLQ
-    return { sent: true };
-  },
-  { host: 'localhost', port: 6789, concurrency: 10 }
-);
-
-worker.on('completed', (job, result) => console.log(job.id, result));
-worker.on('failed', (job, err) => console.error(job.id, err.message));
-
-// later: await worker.close();  // graceful shutdown, waits for in flight jobs
-```
-
-Retry, backoff, dead letter queue, stall detection, priorities, and rate limiting all execute server side. The worker only pulls, heartbeats, and acknowledges, which keeps the client thin and the behavior consistent across languages.
-
-## Flows
-
-```typescript
-import { FlowProducer } from 'bunqueue-client';
-
-const flow = new FlowProducer({ host: 'localhost', port: 6789 });
-
-// sequential chain: step1, then step2, then step3
-await flow.addChain([
-  { name: 'step1', queueName: 'pipeline' },
-  { name: 'step2', queueName: 'pipeline' },
-  { name: 'step3', queueName: 'pipeline' },
-]);
-
-// fan in: parallel jobs converge into a final job that reads their results
-const { finalId } = await flow.addBulkThen(
-  [
-    { name: 'part1', queueName: 'pipeline' },
-    { name: 'part2', queueName: 'pipeline' },
-  ],
-  { name: 'merge', queueName: 'pipeline' }
-);
-// inside the 'merge' processor: await job.getChildrenValues()
-
-// parent and child tree: children always run before the parent
-const node = await flow.add({
-  name: 'assemble', queueName: 'orders',
-  children: [
-    { name: 'reserve-stock', queueName: 'orders' },
-    { name: 'charge-card', queueName: 'orders' },
-  ],
+  connection: { host: 'queue.internal', port: 6789, token, tls: true },
 });
 ```
 
-## Simple Mode
+The same applies to `Worker`, `FlowProducer`, `QueueEvents`, `Bunqueue`,
+`SandboxedWorker`, `QueueGroup.getQueue()/getWorker()`, and the workflow
+`Engine`. Top-level `host`, `port`, `token`, or `tls` were never read by the
+canonical client, which silently connected to `localhost:6789` without the
+token or TLS. They now throw an `Error` that names the keys to move.
 
-`Bunqueue` bundles a Queue and a Worker in one object, with routes, onion middleware, in process retry strategies, a circuit breaker, batch accumulation, event triggers, job TTL, priority aging, cooperative cancellation, and dedup or debounce defaults. It is a 1:1 port of the official client's Simple Mode, TCP only (the `embedded` option raises).
-
-```typescript
-import { Bunqueue, type Job } from 'bunqueue-client';
-
-const app = new Bunqueue('notifications', {
-  connection: { host: 'localhost', port: 6789 },
-  concurrency: 10,
-  routes: {
-    'send-email': async (job: Job<{ to: string }>) => ({ channel: 'email' }),
-    'send-sms': async (job: Job<{ to: string }>) => ({ channel: 'sms' }),
-  },
-  retry: { maxAttempts: 5, delay: 1000, strategy: 'jitter' },
-  circuitBreaker: { threshold: 5, resetTimeout: 30_000 },
-  ttl: { perName: { 'verify-otp': 60_000 } },
-  deduplication: { ttl: 5000 },
-});
-
-app.use(async (job, next) => {
-  const start = Date.now();
-  const result = await next();
-  console.log(`${job.name}: ${Date.now() - start}ms`);
-  return result;
-});
-
-app.trigger({
-  on: 'send-email',
-  create: 'send-sms',
-  data: (result, job) => job.data,
-  condition: (result) => (result as { channel: string }).channel === 'email',
-});
-
-await app.cron('daily-digest', '0 9 * * *', { to: 'all' });
-await app.add('send-email', { to: 'alice@example.com' });
-// later: await app.close();
-```
-
-Use `processor` for a single handler, `routes` to dispatch by job name, or `batch` to accumulate N jobs into one call. Exactly one of the three is required.
-
-## Scheduling
-
-```typescript
-await queue.addCron('daily-report', '0 9 * * *', { type: 'report' });
-await queue.every('health-ping', 30_000, { type: 'ping' });
-await queue.removeJobScheduler('daily-report');
-```
+### 3. Await the `*Async` control methods in TCP mode
 
-## Security
+`pause()`, `resume()`, `drain()`, `obliterate()`, `remove()`,
+`setGlobalConcurrency()`, `removeGlobalConcurrency()`, `setGlobalRateLimit()`,
+`removeGlobalRateLimit()`, `setStallConfig()`, `setDlqConfig()`, `retryDlq()`,
+`retryDlqByFilter()`, `purgeDlq()`, and `retryCompleted()` return
+synchronously and send their command without waiting for the broker. Awaiting
+them waits for nothing, and a job added right after `obliterate()` or
+`drain()` can be processed first and then wiped. Use the variant that resolves
+after the broker applied the command:
 
 ```typescript
-const queue = new Queue('emails', {
-  host: 'queue.example.com',
-  port: 6789,
-  token: process.env.BUNQUEUE_TOKEN,
-  tls: { caFile: './ca.pem' }, // or `true` for system certificate authorities
-});
+// Before (0.1.x): every method returned a broker-acknowledged Promise
+await queue.obliterate();
+await queue.add('fresh', data);
+// After (0.2.0)
+await queue.obliterateAsync(); // also pauseAsync, resumeAsync, drainAsync, removeAsync, ...
+await queue.add('fresh', data);
 ```
 
-Authentication uses server side tokens (`AUTH_TOKENS`). Transport security uses native TLS, with support for system certificate authorities, a custom CA bundle, or disabled verification for development environments.
+### 4. Use `*Async` reads in TCP mode
 
-## Observability
+The synchronous reads are embedded-only. In TCP mode they return a default
+without contacting the broker:
 
-Inject a logger and a telemetry sink to bridge the client into your stack. There are no hard dependencies — you wire OpenTelemetry, Prometheus or your own logger. Defaults are silent.
-
-```typescript
-import { Queue, consoleLogger, type TelemetryEvent } from 'bunqueue-client';
-
-const queue = new Queue('emails', {
-  logger: consoleLogger('info'), // or your own { debug, info, warn, error }
-  onTelemetry: (e: TelemetryEvent) => {
-    // per-command latency, connect/disconnect/reconnect, auth, backpressure
-    if (e.type === 'command') metrics.observe(e.cmd, e.durationMs, e.ok);
-  },
-});
+| 0.1.x call (TCP)                      | 0.2.0 sync result in TCP mode | Use instead                           |
+| ------------------------------------- | ----------------------------- | ------------------------------------- |
+| `await queue.isPaused()`              | `false`                       | `await queue.isPausedAsync()`         |
+| `await queue.count()`                 | `0`                           | `await queue.countAsync()`            |
+| `await queue.getJobs(...)`            | `[]`                          | `await queue.getJobsAsync(...)`       |
+| `await queue.getWaiting()` (and `getActive`, `getDelayed`, `getCompleted`, `getFailed`) | `[]` | `await queue.getWaitingAsync()` (and the matching `*Async`) |
+| `await queue.getCountsPerPriority()`  | `{}`                          | `await queue.getCountsPerPriorityAsync()` |
+| `await queue.getDlq(...)`             | `[]`                          | `await queue.getDlqAsync(...)`        |
+| `queue.getDlqStats()`                 | empty stats                   | `await queue.getDlqStatsAsync()`      |
+| `queue.getStallConfig()` / `getDlqConfig()` | local cache or defaults | `await queue.getStallConfigAsync()` / `getDlqConfigAsync()` |
+| `await queue.clean(...)`              | `[]`                          | `await queue.cleanAsync(...)`         |
 
-// Connection is an EventEmitter for lifecycle hooks:
-queue.connection.on('reconnect_scheduled', (i) => log.warn('reconnecting', i));
-queue.connection.on('disconnect', () => log.warn('link down'));
-```
+`getJobCounts()` returns a `Promise` in TCP mode; await it or call
+`getJobCountsAsync()`.
 
-## Throughput and resilience
+### 5. `Job` is a type, not a class
 
 ```typescript
-// Bound in-flight commands (backpressure) — parks callers instead of growing memory:
-const queue = new Queue('emails', { maxInFlight: 10_000 });
-
-// Fan producer commands across N connections (round-robin, producer-side):
-const pooled = new Queue('emails', { poolSize: 4 });
-
-// Batch worker ACKs into ACKB round-trips (opt-in) for high-volume consumers:
-const worker = new Worker('emails', process, {
-  ackBatch: { enabled: true, maxSize: 50, maxDelayMs: 5 },
-});
-```
-
-Always attach a `worker.on('error', …)` listener: per Node `EventEmitter` semantics an unhandled `error` event throws. The worker frees each job's concurrency slot before emitting, so even a throwing listener cannot degrade throughput — but the error itself is yours to observe.
-
-Half-open links are detected via TCP keepalive and a consecutive-timeout teardown, so a silently dropped connection (cloud LB/NAT idle drop) recovers in seconds rather than minutes.
-
-## Typed responses
-
-`connection.call<R>()` and `queue.call<R>()` are generic over the exported response shapes (`JobResponse`, `PulledJobsResponse`, `JobCountsResponse`, `WaitJobResponse`, …), so raw command access is fully typed without casting.
-
-## API surface
-
-| Area | Capabilities |
-|---|---|
-| Queue | `add`, `addBulk`, full `JobOptions`: priority, delay, attempts, backoff, ttl, timeout, jobId, deduplication, dependsOn, tags, groupId, lifo, removeOnComplete, removeOnFail, durable, repeat, debounce |
-| Query | `getJob`, `getJobByCustomId`, `getJobs` with per state helpers, state, result, progress, `waitForJob` (throws on timeout, BullMQ contract), counts, counts per priority, children values, job logs |
-| Control | pause, resume, drain, obliterate, clean, remove, discard, promote, `retryJob`, `retryJobs`, move to wait or delayed, change priority or delay, update data, extend lock |
-| Dead letter queue | `getDlq`, `retryDlq`, `purgeDlq`, DLQ configuration |
-| Administration | rate limiting, global concurrency, stall configuration, webhooks, stats, metrics, `listQueues`, `getWorkers` |
-| Worker events | `ready`, `active`, `completed`, `failed`, `progress`, `drained`, `error`, `closed`, with automatic lock heartbeats so that jobs longer than the lock TTL survive |
-| Simple Mode | `Bunqueue`: routes, middleware, in process retry (fixed, exponential, jitter, fibonacci, custom), circuit breaker, batch accumulation, triggers, TTL, priority aging, cancellation via `getSignal`, dedup and debounce defaults, cron shorthands |
-
-The following features require the in process Bun runtime and are intentionally out of scope for this client: embedded mode, sandboxed workers, and `QueueEvents`. Use webhooks or the HTTP SSE and WebSocket endpoints for event streaming.
-
-Note on numeric payloads: JavaScript numbers are IEEE 754 doubles, exact up to 2^53. Pass larger 64 bit identifiers, for example snowflake IDs, as strings to avoid silent precision loss. Never place `BigInt` values in job data.
-
-## Quality assurance
-
-Every release is validated against a real bunqueue server, spawned fresh for each run, across every supported runtime:
-
-```bash
-bun install
-bun run build          # tsc, emits dist/
-bun run check          # Biome lint and format verification
-
-bun tests/integration.ts                            # smoke suite
-bun tests/e2e.ts                                    # full surface, edge cases, realistic load
-node --experimental-strip-types tests/e2e.ts        # identical suite on Node 22 or later
-deno run -A tests/e2e.ts                            # identical suite on Deno 2 or later
-bun run test:workers                                # full suite inside workerd, the Cloudflare Workers runtime
-```
-
-The e2e suite includes payload limits, unicode integrity, pipelining under concurrency, server crash and restart with automatic reconnection, and a realistic multi queue production scenario with zero loss accounting. Engineering standards: Biome, a maximum of 250 lines per file, and relative imports with explicit `.js` extensions for NodeNext resolution. See `CLAUDE.md` for the full development guide and wire protocol notes.
-
-## License
-
-MIT. See the [LICENSE](./LICENSE) file. Documentation: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/). Issues and feature requests: [GitHub issues](https://github.com/egeominotti/bunqueue/issues).
+// Before (0.1.x)
+import { Job } from 'bunqueue-client';
+if (value instanceof Job) { /* ... */ }
+// After (0.2.0): jobs come from add(), getJob(), and Worker callbacks
+import type { Job } from 'bunqueue-client';
+```
+
+There is no `job.raw`; use `job.toJSON()` (`JobJson`) or `job.asJSON()`
+(`JobJsonRaw`).
+
+### 6. Removed type exports
+
+| 0.1.x type                                                 | 0.2.0 replacement                                          |
+| ---------------------------------------------------------- | ---------------------------------------------------------- |
+| `BunqueueConnection`                                       | `ConnectionOptions`                                        |
+| `TlsOption`                                                | `ConnectionOptions['tls']`                                 |
+| `BackoffOptions`                                           | `Exclude<NonNullable<JobOptions['backoff']>, number>`      |
+| `DeduplicationOptions`                                     | `NonNullable<JobOptions['deduplication']>`                 |
+| `RepeatOptions`                                            | `NonNullable<JobOptions['repeat']>`                        |
+| `SchedulerOptions`                                         | `RepeatOpts` (with `JobTemplate` for the job)              |
+| `FlowOptions`                                              | `FlowOpts`                                                 |
+| `GetFlowOptions`                                           | `Parameters<FlowProducer['getFlow']>[0]`                   |
+| `BulkJobEntry<T>`                                          | `Parameters<Queue<T>['addBulk']>[0][number]`               |
+| `JobCounts`                                                | `Awaited<ReturnType<Queue['getJobCountsAsync']>>`          |
+| `JobStateName`                                             | `Awaited<ReturnType<Queue['getJobState']>>`                |
+| `JobRaw`                                                   | `JobJson` / `JobJsonRaw`                                   |
+| `CircuitState`                                             | `ReturnType<Bunqueue['getCircuitState']>`                  |
+| `TelemetryErrorOperation`                                  | `Extract<TelemetryEvent, { type: 'error' }>['operation']`  |
+| `WorkerEventMap`, `AckBatchOptions`                        | none: `Worker.on()` overloads type every event             |
+| `Command`, `Response`, and the `*Response` wire types      | none: import them from `bunqueue-client/legacy`            |
+
+### 7. Error classes
+
+`AuthError`, `BunqueueError`, `CommandError`, `CommandTimeoutError`,
+`ConnectionClosedError`, and `SerializationError` are still exported, but only
+the low-level `Connection` and `ConnectionPool` throw them. `Queue`, `Worker`,
+`FlowProducer`, and `QueueEvents` reject with plain `Error` instances (for
+example `Command timeout`, `Authentication failed`, `Connection lost`, or the
+broker's error text), so `instanceof` checks against those classes no longer
+match. `UnrecoverableError`, `DelayedError`, and `RateLimitError` are the
+canonical processor errors.
+
+### 8. TypeScript setup
+
+The package no longer installs `bun-types` or `@types/node`. Node projects keep
+their own `@types/node` (20 or newer); Bun globals are not declared.
+
+## Parity gates
+
+```sh
+bun run build
+bun run test:parity
+bun run test:shared-contract
+bun run test:canonical
+```
+
+The build consumes the repository's canonical sources and emits a manifest
+covering source hashes and every generated artifact. The parity checker
+rejects missing/stale artifacts, missing exports, changed signatures,
+constructors, overloads, options, nested type references, and event contracts.
+The unchanged native documentation suites also run against the built package
+with real embedded engines and TCP brokers. Differential and generated-history
+tests check results, states, counters, and lifecycle events.
+
+Bun, Node, and Deno run the canonical public scenarios in CI. Protocol
+conformance and Cloudflare Workers exercise the built package too. A failed
+parity gate blocks the SDK build/publish preparation; it cannot be bypassed by
+updating an API count or accepting a new snapshot.
+
+Only `msgpackr` is needed at runtime for protocol serialization. Build and test
+tooling stays in development dependencies. The Bun-only backend is loaded
+conditionally and retains the same storage/runtime requirements as bunqueue.