@simpleq/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimpleQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# @simpleq/sdk
+
+Official Node/TypeScript SDK for [SimpleQ](https://docs.simpleq.io): publish jobs, verify webhook signatures, and run the ack-mode callbacks. ESM + CommonJS, bundled types, zero runtime dependencies. Requires Node 22+. All durations are in **seconds**. The live API contract is machine-readable at [docs.simpleq.io/openapi.json](https://docs.simpleq.io/openapi.json).
+
+```bash
+npm install @simpleq/sdk
+```
+
+## Client
+
+An API key is **required** — pass `apiKey`, or set the `SIMPLEQ_API_KEY` environment variable and construct with no arguments. The constructor throws if neither is present.
+
+```ts
+import { SimpleQ } from '@simpleq/sdk';
+
+const simpleq = new SimpleQ(); // reads SIMPLEQ_API_KEY
+// or explicitly:
+const simpleq2 = new SimpleQ({ apiKey: 'sq_live_…' });
+```
+
+`SimpleQ(options)`:
+
+| Option | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `apiKey` | yes (here or via `SIMPLEQ_API_KEY`) | `process.env.SIMPLEQ_API_KEY` | API key (`sq_live_…`). |
+| `timeout` | no | `30` | Timeout for the SDK's **own** requests to the SimpleQ API, in seconds. |
+| `maxRetries` | no | `2` | How many times the SDK retries **its own** API request on a transient failure (network / 5xx / 429). |
+
+`timeout` and `maxRetries` govern the SDK's calls to the SimpleQ API (publishing, ack/nack/defer, getJob). They do **not** control how SimpleQ retries delivery to your webhook — `maxAttempts`, backoff, rate limits, and `ackTimeout` are [per-queue settings](https://docs.simpleq.io/reference/#queues) you configure when you create or edit a queue.
+
+## publish
+
+Publish a job to a queue.
+
+```ts
+const job = await simpleq.publish('emails', {
+  payload: { to: 'a@b.com', template: 'welcome' },
+  idempotencyKey: `welcome:${userId}`,
+  delay: 30,
+});
+// job: {
+//   id: string;
+//   status: 'pending' | 'processing' | 'awaiting_ack' | 'completed' | 'failed' | 'dead';
+//   createdAt: string;  // ISO 8601
+// }
+```
+
+`publish(queueName, params)`:
+
+| Param | Required | Constraint | Meaning |
+| --- | --- | --- | --- |
+| `payload` | yes | JSON object | Delivered verbatim to the queue's webhook. |
+| `idempotencyKey` | no | ≤255 chars | Cross-call dedupe: publishing again with the same key returns the existing job. |
+| `delay` | no | seconds, 0–86400 | Defer first delivery. |
+
+If you omit the `idempotencyKey`, the `publish` method generates one per call and reuses it across the SDK's automatic retries, so a retried request can never create a duplicate job. Pass your own key to dedupe across *separate* calls (e.g. one welcome email per user). A `201` (created — status `pending`) and a `200` (idempotent hit — returns the existing job, any status) both resolve as success.
+
+## Verifying webhooks
+
+SimpleQ signs every delivery with an `x-simpleq-signature` header (HMAC-SHA256 of the raw body, keyed with the queue's `signingSecret`). Verify it before trusting the payload.
+
+- **`verifyWebhook(rawBody, header, signingSecret)`** — the framework-agnostic primitive. Returns the typed envelope or throws `SignatureVerificationError`. Use it anywhere: Lambda, Cloud Functions, Fastify, Hono, Next.js route handlers, raw `http`.
+- **Framework adapters** wrap that primitive for you, including the raw-body capture: **Express** via `simpleqWebhookHandler` (`@simpleq/sdk/express`), and **Nest.js** via `SimpleQModule`, `SimpleQSignatureGuard`, `@SimpleQJob()`, and `SimpleQBackpressureFilter` (`@simpleq/sdk/nest`).
+
+> **`signingSecret` is per-queue.** Each queue has its own — store each as its own env var (e.g. `SQ_SIGNING_SECRET_EMAILS`). A worker serving multiple queues should expose **one webhook route per queue**, each wired to that queue's secret (you can't safely pick the secret from the unverified body).
+
+### verifyWebhook — any framework
+
+The primitive: verify the raw body and get back the typed envelope, or a `SignatureVerificationError`.
+
+```ts
+import { verifyWebhook } from '@simpleq/sdk';
+
+const job = verifyWebhook(rawBody, signatureHeader, process.env.SQ_SIGNING_SECRET_EMAILS!);
+// job: {
+//   id: string;            // job ID — pass to ack/nack/defer
+//   queue: string;         // queue name
+//   payload: Record<string, unknown>;  // your data, verbatim
+//   attempt: number;       // starts at 1
+//   maxAttempts: number;
+//   createdAt: string;     // ISO 8601 — when the job was published
+// }
+```
+
+`rawBody` is a `string`, `Buffer`, or `Uint8Array`. `verifyWebhookSignature(rawBody, header, secret): boolean` is the non-throwing variant.
+
+### Express — `@simpleq/sdk/express`
+
+`simpleqWebhookHandler` captures the raw body, verifies the signature, and maps your handler's outcome to a response (see [Response contract](#response-contract)).
+
+```ts
+import express from 'express';
+import { simpleqWebhookHandler } from '@simpleq/sdk/express';
+
+const app = express();
+
+app.post(
+  '/webhook',
+  simpleqWebhookHandler(process.env.SQ_SIGNING_SECRET_EMAILS!, async (job) => {
+    // `job` is the verified, typed envelope. Resolve → 200.
+    console.log(`processing job ${job.id} from queue ${job.queue}`);
+  }),
+);
+```
+
+### Nest.js — `@simpleq/sdk/nest`
+
+Create the app with `rawBody: true`, register `SimpleQModule.forRoot`, then guard the route and inject the typed job.
+
+```ts
+// main.ts
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { SimpleQModule } from '@simpleq/sdk/nest';
+
+@Module({
+  imports: [SimpleQModule.forRoot({ signingSecret: process.env.SQ_SIGNING_SECRET_EMAILS! })],
+  controllers: [WebhookController],
+})
+export class AppModule {}
+```
+
+```ts
+// webhook.controller.ts
+import { Controller, HttpCode, Post, UseFilters, UseGuards } from '@nestjs/common';
+import type { WebhookPayload } from '@simpleq/sdk';
+import { SimpleQSignatureGuard, SimpleQJob, SimpleQBackpressureFilter } from '@simpleq/sdk/nest';
+
+@Controller('webhook')
+export class WebhookController {
+  @Post()
+  @HttpCode(200)
+  @UseGuards(SimpleQSignatureGuard)
+  @UseFilters(SimpleQBackpressureFilter)
+  async handle(@SimpleQJob() job: WebhookPayload) {
+    console.log(`processing job ${job.id} from queue ${job.queue}`);
+  }
+}
+```
+
+## Response contract
+
+The adapters (`simpleqWebhookHandler`, the Nest guard) map your handler's outcome to a SimpleQ response.
+
+| Handler | Response | SimpleQ |
+| --- | --- | --- |
+| resolves | `200` | **standard mode:** completes the job · **ack mode:** moves it to `awaiting_ack` |
+| `throw new SimpleQBackpressure(retryAfter?, { status? })` | that status (default `503`) + `Retry-After` | holds and redelivers — no attempt burned |
+| throws anything else | `500` | counts a failed attempt, retries with backoff |
+| bad signature | `401` | not a job outcome |
+
+**Backpressure** (a `429`/`503`/`529` from your downstream) tells SimpleQ to hold and redeliver the job without burning an attempt. In a **standard-mode** handler, `throw` a `SimpleQBackpressure` and the adapter turns it into the response; `SimpleQBackpressure.from(err, { fallback })` builds one from the provider error, relaying its status and `Retry-After`.
+
+```ts
+import { SimpleQBackpressure } from '@simpleq/sdk';
+
+simpleqWebhookHandler(process.env.SQ_SIGNING_SECRET_EMAILS!, async (job) => {
+  try {
+    await callProvider(job.payload); // your downstream call
+  } catch (err) {
+    if (err.status === 429 || err.status === 503 || err.status === 529) {
+      throw SimpleQBackpressure.from(err, { fallback: 30 });
+    }
+    throw err; // anything else → 500, retried with backoff
+  }
+});
+```
+
+In **ack mode** you've already returned `200`, so there's no response left to throw into — call `simpleq.defer(...)` out of band instead (see below).
+
+## Ack mode
+
+For work longer than the 15s delivery window, use an ack-mode queue: return `200` immediately, then do the work and report the outcome with `ack` / `nack` / `defer`. Send the `200` yourself from the handler (via `res`), then run the work — the adapter won't respond again once you have.
+
+```ts
+import express from 'express';
+import { SimpleQ, retryAfterSeconds } from '@simpleq/sdk';
+import { simpleqWebhookHandler } from '@simpleq/sdk/express';
+
+const simpleq = new SimpleQ(); // reads SIMPLEQ_API_KEY
+const app = express();
+
+app.post(
+  '/webhook',
+  simpleqWebhookHandler(process.env.SQ_SIGNING_SECRET_EMAILS!, async (job, { res }) => {
+    res.status(200).end(); // ack mode: respond now, do the work after
+
+    try {
+      await callProvider(job.payload); // your downstream call
+      await simpleq.ack(job.id);
+    } catch (err) {
+      if (err.status === 429 || err.status === 503 || err.status === 529) {
+        // Backpressure: hold and redeliver, no attempt burned. Relay the provider's Retry-After.
+        await simpleq.defer(job.id, { retryAfter: retryAfterSeconds(err) ?? 10 });
+      } else if (err.status >= 400 && err.status < 500) {
+        await simpleq.nack(job.id, { retryable: false, reason: `downstream ${err.status}` }); // dead-letter
+      } else {
+        await simpleq.nack(job.id, { retryable: true, reason: String(err) }); // retry with backoff
+      }
+    }
+  }),
+);
+```
+
+The three callbacks, each resolving to `{ id: string; accepted: true }`:
+
+| Callback | Effect |
+| --- | --- |
+| `simpleq.ack(id)` | Mark the job completed. |
+| `simpleq.nack(id, { retryable?, reason? })` | Mark failed. `retryable: false` dead-letters immediately; default `true` retries with backoff. `reason` ≤500 chars. |
+| `simpleq.defer(id, { retryAfter, reason? })` | Backpressure: held and redelivered, no attempt burned. `retryAfter` seconds (0–3600); `reason` ≤500 chars. |
+
+## getJob
+
+Fetch a job's current status and attempt history.
+
+```ts
+const job = await simpleq.getJob(jobId);
+// job: {
+//   id: string;
+//   queue: string;                       // queue name
+//   status: 'pending' | 'processing' | 'awaiting_ack' | 'completed' | 'failed' | 'dead';
+//   attempts: number;
+//   maxAttempts: number;
+//   idempotencyKey: string | null;
+//   payload: Record<string, unknown>;
+//   scheduledFor: string;                // ISO 8601
+//   lastError: string | null;
+//   history: Array<{
+//     attempt: number;
+//     status: 'success' | 'failed' | 'nacked' | 'deferred';
+//     error: string | null;
+//     webhookStatusCode: number | null;
+//     timestamp: string;                 // ISO 8601
+//   }>;
+//   createdAt: string;                   // ISO 8601
+//   completedAt: string | null;          // ISO 8601
+// }
+```
+
+## Errors
+
+Every thrown value extends `SimpleQError`. API responses throw `ApiError` (or a subclass) carrying `.status` and `.body`.
+
+| Class | Thrown when | Extra fields |
+| --- | --- | --- |
+| `AuthenticationError` | `401`/`403` — missing, invalid, or revoked API key | `.status`, `.body` |
+| `ValidationError` | `400` — request validation failed | `.status`, `.body` (field-level details) |
+| `NotFoundError` | `404` — queue or job not found | `.status`, `.body` |
+| `RateLimitError` | `429` — rate limited | `.status`, `.body`, `.retryAfter` (seconds) |
+| `ApiError` | any other non-2xx | `.status`, `.body` |
+| `SimpleQConnectionError` | network failure or timeout | — |
+| `SignatureVerificationError` | webhook signature mismatch | — |
+| `SimpleQError` | base class — catch-all (also config errors, e.g. missing API key) | — |
+
+```ts
+import { ApiError, NotFoundError, RateLimitError, SimpleQError } from '@simpleq/sdk';
+
+try {
+  await simpleq.publish('emails', { payload: { to: 'a@b.com' } });
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.error('Queue does not exist:', err.body);
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limited; retry after ${err.retryAfter}s`);
+  } else if (err instanceof ApiError) {
+    console.error(`SimpleQ API error ${err.status}:`, err.body);
+  } else if (err instanceof SimpleQError) {
+    console.error('Network, signature, or config error:', err.message);
+  } else {
+    throw err;
+  }
+}
+```

package/dist/chunk-72DDDNF6.js

@@ -0,0 +1,138 @@
+import { timingSafeEqual, createHmac } from 'crypto';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/errors.ts
+var SimpleQError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+};
+var SimpleQConnectionError = class extends SimpleQError {
+};
+var SignatureVerificationError = class extends SimpleQError {
+};
+var SimpleQBackpressure = class _SimpleQBackpressure extends SimpleQError {
+  constructor(retryAfter, options) {
+    const detail = retryAfter != null ? ` (retry after ${retryAfter}s)` : "";
+    super(options?.reason ?? `SimpleQ backpressure${detail}`);
+    this.retryAfter = retryAfter;
+    this.status = options?.status ?? 503;
+  }
+  /**
+   * Build a backpressure signal directly from a provider error (Anthropic, OpenAI, any
+   * HTTP-shaped error). Reads `err.status` (429/503/529 pass through; anything else maps
+   * to 503) and the `Retry-After` header in seconds from `err.headers` or
+   * `err.response.headers` (plain object or Headers). When no header is present,
+   * `options.fallback` seconds is used; with neither, SimpleQ applies its own 60s hold.
+   */
+  static from(err, options) {
+    const e = err;
+    const status = e?.status === 429 || e?.status === 503 || e?.status === 529 ? e.status : 503;
+    const retryAfter = retryAfterSeconds(err) ?? options?.fallback;
+    const reason = options?.reason ?? (typeof e?.message === "string" && e.message ? e.message : void 0);
+    return new _SimpleQBackpressure(retryAfter, { status, reason });
+  }
+};
+function readHeader(headers, name) {
+  if (!headers || typeof headers !== "object") return void 0;
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const record = headers;
+  const value = record[name.toLowerCase()] ?? record["Retry-After"];
+  return typeof value === "string" ? value : void 0;
+}
+function retryAfterSeconds(err) {
+  const e = err;
+  const raw = readHeader(e?.headers, "retry-after") ?? readHeader(e?.response?.headers, "retry-after");
+  if (raw === void 0) return void 0;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
+var ApiError = class extends SimpleQError {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+};
+var AuthenticationError = class extends ApiError {
+};
+var ValidationError = class extends ApiError {
+};
+var NotFoundError = class extends ApiError {
+};
+var RateLimitError = class extends ApiError {
+  constructor(message, status, body, retryAfter) {
+    super(message, status, body);
+    this.retryAfter = retryAfter;
+  }
+};
+function extractMessage(status, body) {
+  if (body && typeof body === "object" && "error" in body) {
+    const err = body.error;
+    if (typeof err === "string") return err;
+    if (err && typeof err === "object") return `Validation failed: ${JSON.stringify(err)}`;
+  }
+  return `SimpleQ API error (HTTP ${status})`;
+}
+function mapApiError(status, body, headers) {
+  const message = extractMessage(status, body);
+  switch (status) {
+    case 400:
+      return new ValidationError(message, status, body);
+    case 401:
+    case 403:
+      return new AuthenticationError(message, status, body);
+    case 404:
+      return new NotFoundError(message, status, body);
+    case 429: {
+      const raw = headers?.get("retry-after");
+      const retryAfter = raw != null ? Number(raw) : NaN;
+      return new RateLimitError(message, status, body, Number.isFinite(retryAfter) ? retryAfter : void 0);
+    }
+    default:
+      return new ApiError(message, status, body);
+  }
+}
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "x-simpleq-signature";
+function toBuffer(rawBody) {
+  if (typeof rawBody === "string") return Buffer.from(rawBody, "utf8");
+  if (Buffer.isBuffer(rawBody)) return rawBody;
+  return Buffer.from(rawBody);
+}
+function expectedSignature(rawBody, signingSecret) {
+  return "sha256=" + createHmac("sha256", signingSecret).update(toBuffer(rawBody)).digest("hex");
+}
+function verifyWebhookSignature(rawBody, signatureHeader, signingSecret) {
+  if (!signatureHeader) return false;
+  const expected = Buffer.from(expectedSignature(rawBody, signingSecret));
+  const received = Buffer.from(signatureHeader);
+  if (expected.length !== received.length) return false;
+  return timingSafeEqual(expected, received);
+}
+function verifyWebhook(rawBody, signatureHeader, signingSecret) {
+  if (!verifyWebhookSignature(rawBody, signatureHeader, signingSecret)) {
+    throw new SignatureVerificationError("SimpleQ webhook signature verification failed");
+  }
+  const text = typeof rawBody === "string" ? rawBody : toBuffer(rawBody).toString("utf8");
+  return JSON.parse(text);
+}
+
+export { ApiError, AuthenticationError, NotFoundError, RateLimitError, SIGNATURE_HEADER, SignatureVerificationError, SimpleQBackpressure, SimpleQConnectionError, SimpleQError, ValidationError, __decorateClass, __decorateParam, mapApiError, retryAfterSeconds, verifyWebhook, verifyWebhookSignature };
+//# sourceMappingURL=chunk-72DDDNF6.js.map
+//# sourceMappingURL=chunk-72DDDNF6.js.map

package/dist/chunk-72DDDNF6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/webhooks.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAGO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EACtC,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,KAAK,WAAA,CAAY,IAAA;AAAA,EAC/B;AACF;AAGO,IAAM,sBAAA,GAAN,cAAqC,YAAA,CAAa;AAAC;AAGnD,IAAM,0BAAA,GAAN,cAAyC,YAAA,CAAa;AAAC;AASvD,IAAM,mBAAA,GAAN,MAAM,oBAAA,SAA4B,YAAA,CAAa;AAAA,EAMpD,WAAA,CAAY,YAAqB,OAAA,EAA4D;AAC3F,IAAA,MAAM,MAAA,GAAS,UAAA,IAAc,IAAA,GAAO,CAAA,cAAA,EAAiB,UAAU,CAAA,EAAA,CAAA,GAAO,EAAA;AACtE,IAAA,KAAA,CAAM,OAAA,EAAS,MAAA,IAAU,CAAA,oBAAA,EAAuB,MAAM,CAAA,CAAE,CAAA;AACxD,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAClB,IAAA,IAAA,CAAK,MAAA,GAAS,SAAS,MAAA,IAAU,GAAA;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,IAAA,CAAK,GAAA,EAAc,OAAA,EAAuE;AAC/F,IAAA,MAAM,CAAA,GAAI,GAAA;AACV,IAAA,MAAM,MAAA,GACJ,CAAA,EAAG,MAAA,KAAW,GAAA,IAAO,CAAA,EAAG,MAAA,KAAW,GAAA,IAAO,CAAA,EAAG,MAAA,KAAW,GAAA,GAAM,CAAA,CAAE,MAAA,GAAS,GAAA;AAC3E,IAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,GAAG,CAAA,IAAK,OAAA,EAAS,QAAA;AACtD,IAAA,MAAM,MAAA,GACJ,OAAA,EAAS,MAAA,KAAW,OAAO,CAAA,EAAG,YAAY,QAAA,IAAY,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,GAAU,MAAA,CAAA;AAChF,IAAA,OAAO,IAAI,oBAAA,CAAoB,UAAA,EAAY,EAAE,MAAA,EAAQ,QAAQ,CAAA;AAAA,EAC/D;AACF;AAEA,SAAS,UAAA,CAAW,SAAkB,IAAA,EAAkC;AACtE,EAAA,IAAI,CAAC,OAAA,IAAW,OAAO,OAAA,KAAY,UAAU,OAAO,MAAA;AACpD,EAAA,IAAI,OAAQ,OAAA,CAAoB,GAAA,KAAQ,UAAA,EAAY;AAClD,IAAA,OAAQ,OAAA,CAAoB,GAAA,CAAI,IAAI,CAAA,IAAK,MAAA;AAAA,EAC3C;AACA,EAAA,MAAM,MAAA,GAAS,OAAA;AACf,EAAA,MAAM,QAAQ,MAAA,CAAO,IAAA,CAAK,aAAa,CAAA,IAAK,OAAO,aAAa,CAAA;AAChE,EAAA,OAAO,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,GAAQ,MAAA;AAC7C;AAQO,SAAS,kBAAkB,GAAA,EAAkC;AAClE,EAAA,MAAM,CAAA,GAAI,GAAA;AACV,EAAA,MAAM,GAAA,GACJ,UAAA,CAAW,CAAA,EAAG,OAAA,EAAS,aAAa,KAAK,UAAA,CAAW,CAAA,EAAG,QAAA,EAAU,OAAA,EAAS,aAAa,CAAA;AACzF,EAAA,IAAI,GAAA,KAAQ,QAAW,OAAO,MAAA;AAC9B,EAAA,MAAM,OAAA,GAAU,OAAO,GAAG,CAAA;AAC1B,EAAA,OAAO,OAAO,QAAA,CAAS,OAAO,CAAA,IAAK,OAAA,IAAW,IAAI,OAAA,GAAU,MAAA;AAC9D;AAGO,IAAM,QAAA,GAAN,cAAuB,YAAA,CAAa;AAAA,EAIzC,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,IAAA,EAAe;AAC1D,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AACF;AAGO,IAAM,mBAAA,GAAN,cAAkC,QAAA,CAAS;AAAC;AAG5C,IAAM,eAAA,GAAN,cAA8B,QAAA,CAAS;AAAC;AAGxC,IAAM,aAAA,GAAN,cAA4B,QAAA,CAAS;AAAC;AAGtC,IAAM,cAAA,GAAN,cAA6B,QAAA,CAAS;AAAA,EAG3C,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,IAAA,EAAe,UAAA,EAAqB;AAC/E,IAAA,KAAA,CAAM,OAAA,EAAS,QAAQ,IAAI,CAAA;AAC3B,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAAA,EACpB;AACF;AAEA,SAAS,cAAA,CAAe,QAAgB,IAAA,EAAuB;AAC7D,EAAA,IAAI,IAAA,IAAQ,OAAO,IAAA,KAAS,QAAA,IAAY,WAAW,IAAA,EAAM;AACvD,IAAA,MAAM,MAAO,IAAA,CAA4B,KAAA;AACzC,IAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,IAAA,IAAI,GAAA,IAAO,OAAO,GAAA,KAAQ,QAAA,SAAiB,CAAA,mBAAA,EAAsB,IAAA,CAAK,SAAA,CAAU,GAAG,CAAC,CAAA,CAAA;AAAA,EACtF;AACA,EAAA,OAAO,2BAA2B,MAAM,CAAA,CAAA,CAAA;AAC1C;AAGO,SAAS,WAAA,CAAY,MAAA,EAAgB,IAAA,EAAe,OAAA,EAA6B;AACtF,EAAA,MAAM,OAAA,GAAU,cAAA,CAAe,MAAA,EAAQ,IAAI,CAAA;AAC3C,EAAA,QAAQ,MAAA;AAAQ,IACd,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,eAAA,CAAgB,OAAA,EAAS,MAAA,EAAQ,IAAI,CAAA;AAAA,IAClD,KAAK,GAAA;AAAA,IACL,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,mBAAA,CAAoB,OAAA,EAAS,MAAA,EAAQ,IAAI,CAAA;AAAA,IACtD,KAAK,GAAA;AACH,MAAA,OAAO,IAAI,aAAA,CAAc,OAAA,EAAS,MAAA,EAAQ,IAAI,CAAA;AAAA,IAChD,KAAK,GAAA,EAAK;AACR,MAAA,MAAM,GAAA,GAAM,OAAA,EAAS,GAAA,CAAI,aAAa,CAAA;AACtC,MAAA,MAAM,UAAA,GAAa,GAAA,IAAO,IAAA,GAAO,MAAA,CAAO,GAAG,CAAA,GAAI,GAAA;AAC/C,MAAA,OAAO,IAAI,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,IAAA,EAAM,OAAO,QAAA,CAAS,UAAU,CAAA,GAAI,UAAA,GAAa,MAAS,CAAA;AAAA,IACvG;AAAA,IACA;AACE,MAAA,OAAO,IAAI,QAAA,CAAS,OAAA,EAAS,MAAA,EAAQ,IAAI,CAAA;AAAA;AAE/C;;;ACnIO,IAAM,gBAAA,GAAmB;AAEhC,SAAS,SAAS,OAAA,EAA+C;AAC/D,EAAA,IAAI,OAAO,OAAA,KAAY,QAAA,SAAiB,MAAA,CAAO,IAAA,CAAK,SAAS,MAAM,CAAA;AACnE,EAAA,IAAI,MAAA,CAAO,QAAA,CAAS,OAAO,CAAA,EAAG,OAAO,OAAA;AACrC,EAAA,OAAO,MAAA,CAAO,KAAK,OAAO,CAAA;AAC5B;AAEA,SAAS,iBAAA,CAAkB,SAAuC,aAAA,EAA+B;AAC/F,EAAA,OAAO,SAAA,GAAY,UAAA,CAAW,QAAA,EAAU,aAAa,CAAA,CAAE,MAAA,CAAO,QAAA,CAAS,OAAO,CAAC,CAAA,CAAE,MAAA,CAAO,KAAK,CAAA;AAC/F;AAQO,SAAS,sBAAA,CACd,OAAA,EACA,eAAA,EACA,aAAA,EACS;AACT,EAAA,IAAI,CAAC,iBAAiB,OAAO,KAAA;AAC7B,EAAA,MAAM,WAAW,MAAA,CAAO,IAAA,CAAK,iBAAA,CAAkB,OAAA,EAAS,aAAa,CAAC,CAAA;AACtE,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,IAAA,CAAK,eAAe,CAAA;AAE5C,EAAA,IAAI,QAAA,CAAS,MAAA,KAAW,QAAA,CAAS,MAAA,EAAQ,OAAO,KAAA;AAChD,EAAA,OAAO,eAAA,CAAgB,UAAU,QAAQ,CAAA;AAC3C;AAQO,SAAS,aAAA,CACd,OAAA,EACA,eAAA,EACA,aAAA,EACgB;AAChB,EAAA,IAAI,CAAC,sBAAA,CAAuB,OAAA,EAAS,eAAA,EAAiB,aAAa,CAAA,EAAG;AACpE,IAAA,MAAM,IAAI,2BAA2B,+CAA+C,CAAA;AAAA,EACtF;AACA,EAAA,MAAM,IAAA,GAAO,OAAO,OAAA,KAAY,QAAA,GAAW,UAAU,QAAA,CAAS,OAAO,CAAA,CAAE,QAAA,CAAS,MAAM,CAAA;AACtF,EAAA,OAAO,IAAA,CAAK,MAAM,IAAI,CAAA;AACxB","file":"chunk-72DDDNF6.js","sourcesContent":["// Error and signal types for @simpleq/sdk.\n\n/** Base class for everything thrown by the SDK. Catch this to handle any SimpleQ error. */\nexport class SimpleQError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = this.constructor.name;\n  }\n}\n\n/** A network failure, timeout, or aborted request — retryable. */\nexport class SimpleQConnectionError extends SimpleQError {}\n\n/** Thrown by `verifyWebhook` when a webhook signature does not verify. */\nexport class SignatureVerificationError extends SimpleQError {}\n\nexport type BackpressureStatus = 429 | 503 | 529;\n\n/**\n * A backpressure signal — not a failure. Throw this from a standard-mode webhook handler to\n * tell the adapter to respond with `429`/`503`/`529` and a `Retry-After`. SimpleQ then holds\n * the job and redelivers it without burning a delivery attempt.\n */\nexport class SimpleQBackpressure extends SimpleQError {\n  /** Seconds to hold the job before redelivery. Omit to let SimpleQ pick its fallback. */\n  readonly retryAfter?: number;\n  /** HTTP status the adapter responds with. Defaults to `503`. */\n  readonly status: BackpressureStatus;\n\n  constructor(retryAfter?: number, options?: { status?: BackpressureStatus; reason?: string }) {\n    const detail = retryAfter != null ? ` (retry after ${retryAfter}s)` : '';\n    super(options?.reason ?? `SimpleQ backpressure${detail}`);\n    this.retryAfter = retryAfter;\n    this.status = options?.status ?? 503;\n  }\n\n  /**\n   * Build a backpressure signal directly from a provider error (Anthropic, OpenAI, any\n   * HTTP-shaped error). Reads `err.status` (429/503/529 pass through; anything else maps\n   * to 503) and the `Retry-After` header in seconds from `err.headers` or\n   * `err.response.headers` (plain object or Headers). When no header is present,\n   * `options.fallback` seconds is used; with neither, SimpleQ applies its own 60s hold.\n   */\n  static from(err: unknown, options?: { fallback?: number; reason?: string }): SimpleQBackpressure {\n    const e = err as { status?: unknown; message?: unknown } | null | undefined;\n    const status: BackpressureStatus =\n      e?.status === 429 || e?.status === 503 || e?.status === 529 ? e.status : 503;\n    const retryAfter = retryAfterSeconds(err) ?? options?.fallback;\n    const reason =\n      options?.reason ?? (typeof e?.message === 'string' && e.message ? e.message : undefined);\n    return new SimpleQBackpressure(retryAfter, { status, reason });\n  }\n}\n\nfunction readHeader(headers: unknown, name: string): string | undefined {\n  if (!headers || typeof headers !== 'object') return undefined;\n  if (typeof (headers as Headers).get === 'function') {\n    return (headers as Headers).get(name) ?? undefined;\n  }\n  const record = headers as Record<string, unknown>;\n  const value = record[name.toLowerCase()] ?? record['Retry-After'];\n  return typeof value === 'string' ? value : undefined;\n}\n\n/**\n * Read the `Retry-After` value, in **seconds**, from a provider error (Anthropic, OpenAI, any\n * HTTP-shaped error). Looks at `err.headers` and `err.response.headers` (plain object or a\n * `Headers` instance). Returns `undefined` when the header is absent or non-numeric (e.g. an\n * HTTP-date). Pair with `simpleq.defer` in ack mode: `defer(id, { retryAfter: retryAfterSeconds(err) ?? 10 })`.\n */\nexport function retryAfterSeconds(err: unknown): number | undefined {\n  const e = err as { headers?: unknown; response?: { headers?: unknown } } | null | undefined;\n  const raw =\n    readHeader(e?.headers, 'retry-after') ?? readHeader(e?.response?.headers, 'retry-after');\n  if (raw === undefined) return undefined;\n  const seconds = Number(raw);\n  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;\n}\n\n/** Any non-2xx response from the SimpleQ API. */\nexport class ApiError extends SimpleQError {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body: unknown) {\n    super(message);\n    this.status = status;\n    this.body = body;\n  }\n}\n\n/** `401`/`403` — the API key is missing, invalid, or revoked. */\nexport class AuthenticationError extends ApiError {}\n\n/** `400` — request validation failed. `body.error` carries the field-level details. */\nexport class ValidationError extends ApiError {}\n\n/** `404` — the queue or job was not found. */\nexport class NotFoundError extends ApiError {}\n\n/** `429` — rate limited. `retryAfter` is the `Retry-After` header in seconds, if present. */\nexport class RateLimitError extends ApiError {\n  readonly retryAfter?: number;\n\n  constructor(message: string, status: number, body: unknown, retryAfter?: number) {\n    super(message, status, body);\n    this.retryAfter = retryAfter;\n  }\n}\n\nfunction extractMessage(status: number, body: unknown): string {\n  if (body && typeof body === 'object' && 'error' in body) {\n    const err = (body as { error: unknown }).error;\n    if (typeof err === 'string') return err;\n    if (err && typeof err === 'object') return `Validation failed: ${JSON.stringify(err)}`;\n  }\n  return `SimpleQ API error (HTTP ${status})`;\n}\n\n/** Map an HTTP status + parsed body to the right ApiError subclass. */\nexport function mapApiError(status: number, body: unknown, headers?: Headers): ApiError {\n  const message = extractMessage(status, body);\n  switch (status) {\n    case 400:\n      return new ValidationError(message, status, body);\n    case 401:\n    case 403:\n      return new AuthenticationError(message, status, body);\n    case 404:\n      return new NotFoundError(message, status, body);\n    case 429: {\n      const raw = headers?.get('retry-after');\n      const retryAfter = raw != null ? Number(raw) : NaN;\n      return new RateLimitError(message, status, body, Number.isFinite(retryAfter) ? retryAfter : undefined);\n    }\n    default:\n      return new ApiError(message, status, body);\n  }\n}\n","// Standalone webhook verification — no API key or client required. Importable as\n// `@simpleq/sdk/webhooks` with only `node:crypto` pulled in.\nimport { createHmac, timingSafeEqual } from 'node:crypto';\nimport { SignatureVerificationError } from './errors.js';\nimport type { WebhookPayload } from './types.js';\n\n/** The header SimpleQ sends with every webhook delivery. */\nexport const SIGNATURE_HEADER = 'x-simpleq-signature';\n\nfunction toBuffer(rawBody: string | Buffer | Uint8Array): Buffer {\n  if (typeof rawBody === 'string') return Buffer.from(rawBody, 'utf8');\n  if (Buffer.isBuffer(rawBody)) return rawBody;\n  return Buffer.from(rawBody);\n}\n\nfunction expectedSignature(rawBody: string | Buffer | Uint8Array, signingSecret: string): string {\n  return 'sha256=' + createHmac('sha256', signingSecret).update(toBuffer(rawBody)).digest('hex');\n}\n\n/**\n * Verify the `x-simpleq-signature` header against the raw request body, in constant time.\n * Returns a boolean and never throws — a missing or malformed header simply returns `false`.\n *\n * Always pass the *raw* body bytes (a string or Buffer), never a re-serialized parsed object.\n */\nexport function verifyWebhookSignature(\n  rawBody: string | Buffer | Uint8Array,\n  signatureHeader: string | null | undefined,\n  signingSecret: string,\n): boolean {\n  if (!signatureHeader) return false;\n  const expected = Buffer.from(expectedSignature(rawBody, signingSecret));\n  const received = Buffer.from(signatureHeader);\n  // timingSafeEqual throws on differing lengths — guard before the constant-time compare.\n  if (expected.length !== received.length) return false;\n  return timingSafeEqual(expected, received);\n}\n\n/**\n * Verify the signature and return the parsed, typed webhook envelope (the equivalent of\n * Stripe's `constructEvent`). Throws `SignatureVerificationError` if the signature does\n * not match — the body is only parsed after verification passes, so a tampered payload\n * never reaches `JSON.parse`.\n */\nexport function verifyWebhook(\n  rawBody: string | Buffer | Uint8Array,\n  signatureHeader: string | null | undefined,\n  signingSecret: string,\n): WebhookPayload {\n  if (!verifyWebhookSignature(rawBody, signatureHeader, signingSecret)) {\n    throw new SignatureVerificationError('SimpleQ webhook signature verification failed');\n  }\n  const text = typeof rawBody === 'string' ? rawBody : toBuffer(rawBody).toString('utf8');\n  return JSON.parse(text) as WebhookPayload;\n}\n"]}

package/dist/errors-D7trszMq.d.cts

@@ -0,0 +1,66 @@
+/** Base class for everything thrown by the SDK. Catch this to handle any SimpleQ error. */
+declare class SimpleQError extends Error {
+    constructor(message: string);
+}
+/** A network failure, timeout, or aborted request — retryable. */
+declare class SimpleQConnectionError extends SimpleQError {
+}
+/** Thrown by `verifyWebhook` when a webhook signature does not verify. */
+declare class SignatureVerificationError extends SimpleQError {
+}
+type BackpressureStatus = 429 | 503 | 529;
+/**
+ * A backpressure signal — not a failure. Throw this from a standard-mode webhook handler to
+ * tell the adapter to respond with `429`/`503`/`529` and a `Retry-After`. SimpleQ then holds
+ * the job and redelivers it without burning a delivery attempt.
+ */
+declare class SimpleQBackpressure extends SimpleQError {
+    /** Seconds to hold the job before redelivery. Omit to let SimpleQ pick its fallback. */
+    readonly retryAfter?: number;
+    /** HTTP status the adapter responds with. Defaults to `503`. */
+    readonly status: BackpressureStatus;
+    constructor(retryAfter?: number, options?: {
+        status?: BackpressureStatus;
+        reason?: string;
+    });
+    /**
+     * Build a backpressure signal directly from a provider error (Anthropic, OpenAI, any
+     * HTTP-shaped error). Reads `err.status` (429/503/529 pass through; anything else maps
+     * to 503) and the `Retry-After` header in seconds from `err.headers` or
+     * `err.response.headers` (plain object or Headers). When no header is present,
+     * `options.fallback` seconds is used; with neither, SimpleQ applies its own 60s hold.
+     */
+    static from(err: unknown, options?: {
+        fallback?: number;
+        reason?: string;
+    }): SimpleQBackpressure;
+}
+/**
+ * Read the `Retry-After` value, in **seconds**, from a provider error (Anthropic, OpenAI, any
+ * HTTP-shaped error). Looks at `err.headers` and `err.response.headers` (plain object or a
+ * `Headers` instance). Returns `undefined` when the header is absent or non-numeric (e.g. an
+ * HTTP-date). Pair with `simpleq.defer` in ack mode: `defer(id, { retryAfter: retryAfterSeconds(err) ?? 10 })`.
+ */
+declare function retryAfterSeconds(err: unknown): number | undefined;
+/** Any non-2xx response from the SimpleQ API. */
+declare class ApiError extends SimpleQError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/** `401`/`403` — the API key is missing, invalid, or revoked. */
+declare class AuthenticationError extends ApiError {
+}
+/** `400` — request validation failed. `body.error` carries the field-level details. */
+declare class ValidationError extends ApiError {
+}
+/** `404` — the queue or job was not found. */
+declare class NotFoundError extends ApiError {
+}
+/** `429` — rate limited. `retryAfter` is the `Retry-After` header in seconds, if present. */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, body: unknown, retryAfter?: number);
+}
+
+export { ApiError as A, type BackpressureStatus as B, NotFoundError as N, RateLimitError as R, SignatureVerificationError as S, ValidationError as V, AuthenticationError as a, SimpleQBackpressure as b, SimpleQConnectionError as c, SimpleQError as d, retryAfterSeconds as r };

package/dist/errors-D7trszMq.d.ts

@@ -0,0 +1,66 @@
+/** Base class for everything thrown by the SDK. Catch this to handle any SimpleQ error. */
+declare class SimpleQError extends Error {
+    constructor(message: string);
+}
+/** A network failure, timeout, or aborted request — retryable. */
+declare class SimpleQConnectionError extends SimpleQError {
+}
+/** Thrown by `verifyWebhook` when a webhook signature does not verify. */
+declare class SignatureVerificationError extends SimpleQError {
+}
+type BackpressureStatus = 429 | 503 | 529;
+/**
+ * A backpressure signal — not a failure. Throw this from a standard-mode webhook handler to
+ * tell the adapter to respond with `429`/`503`/`529` and a `Retry-After`. SimpleQ then holds
+ * the job and redelivers it without burning a delivery attempt.
+ */
+declare class SimpleQBackpressure extends SimpleQError {
+    /** Seconds to hold the job before redelivery. Omit to let SimpleQ pick its fallback. */
+    readonly retryAfter?: number;
+    /** HTTP status the adapter responds with. Defaults to `503`. */
+    readonly status: BackpressureStatus;
+    constructor(retryAfter?: number, options?: {
+        status?: BackpressureStatus;
+        reason?: string;
+    });
+    /**
+     * Build a backpressure signal directly from a provider error (Anthropic, OpenAI, any
+     * HTTP-shaped error). Reads `err.status` (429/503/529 pass through; anything else maps
+     * to 503) and the `Retry-After` header in seconds from `err.headers` or
+     * `err.response.headers` (plain object or Headers). When no header is present,
+     * `options.fallback` seconds is used; with neither, SimpleQ applies its own 60s hold.
+     */
+    static from(err: unknown, options?: {
+        fallback?: number;
+        reason?: string;
+    }): SimpleQBackpressure;
+}
+/**
+ * Read the `Retry-After` value, in **seconds**, from a provider error (Anthropic, OpenAI, any
+ * HTTP-shaped error). Looks at `err.headers` and `err.response.headers` (plain object or a
+ * `Headers` instance). Returns `undefined` when the header is absent or non-numeric (e.g. an
+ * HTTP-date). Pair with `simpleq.defer` in ack mode: `defer(id, { retryAfter: retryAfterSeconds(err) ?? 10 })`.
+ */
+declare function retryAfterSeconds(err: unknown): number | undefined;
+/** Any non-2xx response from the SimpleQ API. */
+declare class ApiError extends SimpleQError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/** `401`/`403` — the API key is missing, invalid, or revoked. */
+declare class AuthenticationError extends ApiError {
+}
+/** `400` — request validation failed. `body.error` carries the field-level details. */
+declare class ValidationError extends ApiError {
+}
+/** `404` — the queue or job was not found. */
+declare class NotFoundError extends ApiError {
+}
+/** `429` — rate limited. `retryAfter` is the `Retry-After` header in seconds, if present. */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, body: unknown, retryAfter?: number);
+}
+
+export { ApiError as A, type BackpressureStatus as B, NotFoundError as N, RateLimitError as R, SignatureVerificationError as S, ValidationError as V, AuthenticationError as a, SimpleQBackpressure as b, SimpleQConnectionError as c, SimpleQError as d, retryAfterSeconds as r };