@dregs/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+The first release. A server-side client for tracking events and reading scores, ported from the
+reference [Python SDK](https://github.com/dregs-sdk/dregs-sdk-python).
+
+### Added
+
+- A `Dregs` client, authenticating with a credential's `sk_` secret key against a configurable
+  base URL. Every method returns a promise; there is no separate async client.
+- `track()` for recording backend events against an identity, always sending an idempotency `id`
+  so a retry cannot double-count.
+- `identities.get()`, `identities.scores()`, `identities.analysis()`, and `identities.analyze()`.
+- Typed errors for 400, 401, 402, 403, 404, 429, and 5xx, plus connection and timeout failures,
+  all deriving from `DregsError`.
+- Automatic retries with exponential backoff and full jitter, honouring `Retry-After`.
+- `verifyWebhook()` for checking a webhook's signature and rejecting replays, exported from the
+  package root and from the `@dregs/sdk/webhooks` subpath.
+- ESM and CommonJS builds with generated declarations for both, and no runtime dependencies.
+
+[Unreleased]: https://github.com/dregs-sdk/dregs-sdk-typescript/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dregs-sdk/dregs-sdk-typescript/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dregs
+
+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,287 @@
+# Dregs TypeScript SDK
+
+[![npm](https://img.shields.io/npm/v/@dregs/sdk.svg)](https://www.npmjs.com/package/@dregs/sdk)
+[![Node](https://img.shields.io/node/v/@dregs/sdk.svg)](https://www.npmjs.com/package/@dregs/sdk)
+[![License](https://img.shields.io/npm/l/@dregs/sdk.svg)](LICENSE)
+
+The official TypeScript client for [Dregs](https://dregs.com), which scores the users of your application
+for fraud and abuse across four categories: humanity, authenticity, uniqueness, and behavior.
+
+Send events from your backend, read back the scores and the observations behind them.
+
+```bash
+npm install @dregs/sdk
+```
+
+Node 20 or newer. No runtime dependencies: the SDK calls the runtime's own `fetch`.
+
+> This is the **server-side** SDK, which authenticates with a secret key and can read scores.
+> The browser tracking script is a separate package, [`dregs`](https://www.npmjs.com/package/dregs),
+> and uses the public key. You will usually want both: the tracker in the browser, this on your
+> backend.
+
+## Getting started
+
+You need the **secret key** from an API credential, which you will find under **Settings → Credentials**
+in the Dregs dashboard. It starts with `sk_`. The `pk_` public key is for the browser tracker and cannot
+read identities or scores.
+
+```ts
+import { Dregs } from '@dregs/sdk';
+
+const client = new Dregs({ secretKey: process.env.DREGS_SECRET_KEY });
+```
+
+The key is read from `DREGS_SECRET_KEY` when you do not pass one, so `new Dregs()` on its own is usually
+enough. Build one at startup and keep it; there is nothing to close.
+
+CommonJS works too:
+
+```js
+const { Dregs } = require('@dregs/sdk');
+```
+
+## Tracking events
+
+```ts
+await client.track('user.signup', {
+  identity: 'user_12345',
+  data: { plan: 'pro', referrer: 'partner-x' },
+  identityData: { email: 'ada@example.com', name: 'Ada Lovelace' },
+});
+```
+
+`identity` is your own id for the user — the same one you pass to `dregs.identify()` in the browser
+tracker, and the one you look scores up by. It is required: a server-side event carries no device
+signature, so the identity is the only thing tying the event to a user.
+
+`identityData` carries attributes of the _user_ rather than the event. The analyzers lean on these
+heavily, so send them whenever you have them. Name the keys the way your application already does and
+map them to Dregs's canonical fields under **Settings → Mappings**; the same goes for event names.
+
+### Idempotency
+
+Every event is sent with an `id`, which makes ingestion idempotent: reposting the same id returns the
+original event instead of recording a second one. Pass the id your application already has, and a retry
+after a timeout can never double-count.
+
+```ts
+await client.track('purchase', { identity: 'user_12345', eventId: `order-${order.id}` });
+```
+
+When you omit it the SDK generates one, which is what makes its own retries safe.
+
+### What comes back
+
+```ts
+const result = await client.track('user.signup', { identity: 'user_12345' });
+
+result.accepted; // true when Dregs recorded the event
+result.id; // the event's id
+```
+
+`accepted` is `false` in the uncommon case where Dregs accepts the request without recording
+an event. Failures that are yours to act on throw instead — see [Errors](#errors).
+
+## Reading scores
+
+```ts
+const scores = await client.identities.scores('user_12345');
+
+scores.humanity; // 85
+scores.authenticity; // 72
+scores.uniqueness; // 91
+scores.behavior; // 68
+```
+
+This is the cheap read and the one most integrations want. A category Dregs has not scored yet reads as
+`null`, and a brand-new identity comes back empty. `Scores` is an array, so you can iterate, map, and
+destructure it as usual.
+
+Scoring is **asynchronous**. Scores appear moments after the events that move them, not in the same
+breath, so read them at a decision point rather than immediately after a `track()` call.
+
+```ts
+if (scores.authenticity !== null && scores.authenticity < 40) {
+  await holdForReview('user_12345');
+}
+```
+
+### Seeing exactly why
+
+The scores are the summary; the observations are the evidence. When you need to show or log _why_ an
+identity scored the way it did, ask for the analysis.
+
+```ts
+const analysis = await client.identities.analysis('user_12345');
+
+for (const observation of analysis.observations) {
+  console.log(`${observation.label}: ${observation.explanation} (value ${observation.value})`);
+}
+```
+
+Each observation carries the analyzer that produced it, a `value` from 0.0 (suspicious) to 1.0
+(legitimate), a `confidence`, a `weight`, and the counts behind the finding in `metadata`. `analysis()`
+throws `NotFoundError` until the identity has been analyzed at least once.
+
+### The whole identity
+
+```ts
+const identity = await client.identities.get('user_12345');
+
+identity.displayEmail; // "ada@example.com"
+identity.humanityScore; // 85
+identity.badges; // [{ name: "Account Takeover Suspected", ... }]
+identity.data; // every attribute you have sent
+```
+
+### Forcing a rescore
+
+```ts
+await client.identities.analyze('user_12345');
+```
+
+This queues the work and resolves; it does not wait for the cycle to finish. Dregs rescores on its own
+as events arrive, so you rarely need this outside of a support or backfill flow.
+
+## Errors
+
+```ts
+import { DregsError, NotFoundError, QuotaExceededError, RateLimitError } from '@dregs/sdk';
+
+try {
+  await client.track('user.signup', { identity: 'user_12345' });
+} catch (error) {
+  if (error instanceof QuotaExceededError) {
+    // over the monthly event limit; the event was not queued
+  } else if (error instanceof RateLimitError) {
+    // ingesting too fast; error.retryAfter when the server said how long
+  } else if (error instanceof DregsError) {
+    // anything else this library throws
+  } else {
+    throw error;
+  }
+}
+```
+
+| Error                   | When                                               |
+| ----------------------- | -------------------------------------------------- |
+| `BadRequestError`       | 400, the event was malformed                       |
+| `AuthenticationError`   | 401, the secret key was not recognized             |
+| `QuotaExceededError`    | 402, the account is over its monthly event limit   |
+| `PermissionDeniedError` | 403, the credential may not do this                |
+| `NotFoundError`         | 404, no such identity, or it has not been analyzed |
+| `RateLimitError`        | 429, too many requests                             |
+| `ServerError`           | 5xx                                                |
+| `DregsTimeoutError`     | the request timed out                              |
+| `DregsConnectionError`  | the request never reached Dregs                    |
+
+All of them derive from `DregsError`. Those that reached the API also carry `statusCode`, `body`, and
+`requestId`; `error.message` is the message the API sent, and `error.toString()` prefixes it with the
+status and the request id, which is the form worth putting in a log line.
+
+Arguments the SDK can reject without asking Dregs — a missing identity, an event id over 64 characters,
+a `pk_` key — throw a plain `TypeError` before anything is sent.
+
+### Retries
+
+Connection failures, timeouts, 408s, 429s, and 5xx are retried automatically with exponential backoff and
+full jitter, honouring `Retry-After` when the server sends one. Two retries by default:
+
+```ts
+const client = new Dregs({ maxRetries: 5 }); // or 0 to handle it yourself
+```
+
+## Promises, not an async twin
+
+There is one `Dregs` class and every method returns a promise. JavaScript has no meaningful sync/async
+split, so unlike the Python SDK there is no async client to choose between — `await` everything.
+
+## Webhooks
+
+Dregs signs every webhook with the channel's signing secret. Verify it against the **raw request body**
+before acting on the payload — a re-serialized object will not match, because key order and whitespace
+change.
+
+```ts
+import express from 'express';
+import { verifyWebhook, WebhookVerificationError } from '@dregs/sdk/webhooks';
+
+app.post('/webhooks/dregs', express.raw({ type: 'application/json' }), (req, res) => {
+  let event;
+
+  try {
+    event = verifyWebhook({
+      payload: req.body, // the Buffer, not req.body parsed as JSON
+      signature: req.header('X-Dregs-Signature') ?? '',
+      secret: process.env.DREGS_WEBHOOK_SECRET!,
+    });
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) {
+      return res.sendStatus(400);
+    }
+
+    throw error;
+  }
+
+  handle(event);
+
+  res.sendStatus(204);
+});
+```
+
+`express.raw()` matters: the default `express.json()` hands you a parsed object and the original bytes are
+gone. The helpers are exported from the package root as well, so `import { verifyWebhook } from '@dregs/sdk'`
+works if you would rather not reach for the subpath.
+
+`verifyWebhook` also rejects payloads older than five minutes as replays; pass `tolerance: null` to skip
+that if you are deduplicating on the event id yourself. The signing secret is shown once, when you create
+the webhook channel, and is not your API secret key.
+
+## Configuration
+
+```ts
+const client = new Dregs({
+  secretKey: undefined, // defaults to $DREGS_SECRET_KEY
+  baseUrl: undefined, // defaults to $DREGS_BASE_URL, then https://dregs.com/api
+  timeout: 10_000, // milliseconds
+  maxRetries: 2,
+  fetch: undefined, // bring your own fetch for a proxy agent, custom TLS, or instrumentation
+});
+```
+
+## Type checking
+
+The package ships generated declarations for both the ESM and CommonJS entry points, so there is no
+`@types/dregs` to install and every public type is exported. Responses are plain readonly objects; each
+one also keeps the body it was built from in `raw`, so a field Dregs adds after this release is reachable
+without waiting for an SDK upgrade.
+
+```ts
+import type { Analysis, Category, Identity, Observation, Score, TrackResult } from '@dregs/sdk';
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:
+
+```bash
+npm ci
+npm test
+npm run lint
+npm run typecheck
+npm run build
+```
+
+`npm ci` installs exactly what `package-lock.json` pins and fails if the lock is out of step, so the same
+commands produce the same environment locally and in CI.
+
+## Links
+
+- [Dregs manual](https://dregs.com/manual/) and [REST API reference](https://dregs.com/manual/api/)
+- [Dregs MCP server](https://github.com/dregs-sdk/dregs-mcp), for connecting AI agents to your data
+- [Security policy](SECURITY.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/chunk-AIUWT3Z7.js

@@ -0,0 +1,149 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/webhooks.ts
+
+// src/errors.ts
+var DregsError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = new.target.name;
+  }
+};
+var DregsConnectionError = class extends DregsError {
+};
+var DregsTimeoutError = class extends DregsConnectionError {
+};
+var WebhookVerificationError = class extends DregsError {
+};
+var DregsAPIError = class extends DregsError {
+  /** The HTTP status code. */
+  statusCode;
+  /** The parsed JSON body, or `null` when the response was not JSON. */
+  body;
+  /**
+   * Value of the `X-Request-Id` response header, when present.
+   *
+   * Quote it when you report a problem: it is what lets Dregs find your exact request.
+   */
+  requestId;
+  constructor(message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.statusCode = options.statusCode;
+    this.body = options.body ?? null;
+    this.requestId = options.requestId ?? null;
+  }
+  toString() {
+    const suffix = this.requestId ? ` (request ${this.requestId})` : "";
+    return `${this.name}: HTTP ${this.statusCode}: ${this.message}${suffix}`;
+  }
+};
+var BadRequestError = class extends DregsAPIError {
+};
+var AuthenticationError = class extends DregsAPIError {
+};
+var QuotaExceededError = class extends DregsAPIError {
+};
+var PermissionDeniedError = class extends DregsAPIError {
+};
+var NotFoundError = class extends DregsAPIError {
+};
+var RateLimitError = class extends DregsAPIError {
+  /**
+   * Seconds to wait before retrying, from the `Retry-After` header when the response carried a
+   * numeric one, and `null` otherwise.
+   */
+  retryAfter;
+  constructor(message, options = {}) {
+    super(message, { ...options, statusCode: options.statusCode ?? 429 });
+    this.retryAfter = options.retryAfter ?? null;
+  }
+};
+var ServerError = class extends DregsAPIError {
+};
+var STATUS_ERRORS = {
+  400: BadRequestError,
+  401: AuthenticationError,
+  402: QuotaExceededError,
+  403: PermissionDeniedError,
+  404: NotFoundError
+};
+function errorForStatus(statusCode) {
+  const mapped = STATUS_ERRORS[statusCode];
+  if (mapped) {
+    return mapped;
+  }
+  return statusCode >= 500 ? ServerError : DregsAPIError;
+}
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "X-Dregs-Signature";
+var TIMESTAMP_HEADER = "X-Dregs-Timestamp";
+var EVENT_HEADER = "X-Dregs-Event";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function computeWebhookSignature(payload, secret) {
+  return createHmac("sha256", secret).update(toBytes(payload)).digest("hex");
+}
+function verifyWebhookSignature(payload, signature, secret) {
+  if (!signature || !secret) {
+    return false;
+  }
+  const expected = Buffer.from(computeWebhookSignature(payload, secret), "utf8");
+  const received = Buffer.from(signature.trim(), "utf8");
+  return expected.length === received.length && timingSafeEqual(expected, received);
+}
+function verifyWebhook(options) {
+  const { payload, signature, secret, tolerance = DEFAULT_TOLERANCE_SECONDS, now } = options;
+  if (!verifyWebhookSignature(payload, signature, secret)) {
+    throw new WebhookVerificationError(
+      "The webhook signature did not match. Check that you are verifying the raw request body rather than a re-serialized copy, and that the signing secret belongs to the channel that sent this delivery."
+    );
+  }
+  let event;
+  try {
+    event = JSON.parse(toText(payload));
+  } catch (cause) {
+    throw new WebhookVerificationError(
+      `The webhook body was not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+  }
+  if (typeof event !== "object" || event === null || Array.isArray(event)) {
+    throw new WebhookVerificationError("The webhook body was not a JSON object.");
+  }
+  const body = event;
+  if (tolerance !== null && tolerance !== void 0) {
+    checkFreshness(body, tolerance, now);
+  }
+  return body;
+}
+function checkFreshness(event, tolerance, now) {
+  const raw = event.timestamp;
+  if (typeof raw !== "string" || !raw) {
+    throw new WebhookVerificationError(
+      "The webhook carried no timestamp, so it cannot be checked for replay. Pass tolerance: null if you are deduplicating deliveries some other way."
+    );
+  }
+  const sent = new Date(raw);
+  if (Number.isNaN(sent.getTime())) {
+    throw new WebhookVerificationError(
+      `The webhook timestamp was unreadable: ${JSON.stringify(raw)}`
+    );
+  }
+  const age = Math.abs(((now ?? /* @__PURE__ */ new Date()).getTime() - sent.getTime()) / 1e3);
+  if (age > tolerance) {
+    throw new WebhookVerificationError(
+      `The webhook timestamp is ${age.toFixed(0)}s away from now, beyond the ${tolerance}s tolerance. Treating it as a replay.`
+    );
+  }
+}
+function toBytes(payload) {
+  return typeof payload === "string" ? Buffer.from(payload, "utf8") : Buffer.from(payload);
+}
+function toText(payload) {
+  return typeof payload === "string" ? payload : Buffer.from(payload).toString("utf8");
+}
+
+export { AuthenticationError, BadRequestError, DEFAULT_TOLERANCE_SECONDS, DregsAPIError, DregsConnectionError, DregsError, DregsTimeoutError, EVENT_HEADER, NotFoundError, PermissionDeniedError, QuotaExceededError, RateLimitError, SIGNATURE_HEADER, ServerError, TIMESTAMP_HEADER, WebhookVerificationError, computeWebhookSignature, errorForStatus, verifyWebhook, verifyWebhookSignature };
+//# sourceMappingURL=chunk-AIUWT3Z7.js.map
+//# sourceMappingURL=chunk-AIUWT3Z7.js.map

package/dist/chunk-AIUWT3Z7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/webhooks.ts"],"names":[],"mappings":"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","file":"chunk-AIUWT3Z7.js","sourcesContent":["/**\n * Errors thrown by the Dregs SDK.\n *\n * Everything this library throws derives from {@link DregsError}, so a caller that only wants a\n * coarse \"the Dregs call failed\" branch can catch that one class. Errors that came back from the\n * API carry the HTTP status and the parsed body; errors that never reached the API (DNS failure,\n * connection refused, timeout) derive from {@link DregsConnectionError} instead.\n *\n * @module\n */\n\n/**\n * Base class for everything this library throws.\n *\n * `instanceof DregsError` is the one check that catches every failure mode, including webhook\n * verification and transport failures that never produced an HTTP status.\n */\nexport class DregsError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n\n    // Subclassing a built-in loses the prototype link under a downlevelled target, so pin it\n    // back on. Without this, `err instanceof RateLimitError` can quietly answer false.\n    Object.setPrototypeOf(this, new.target.prototype);\n\n    this.name = new.target.name;\n  }\n}\n\n/** The request never reached Dregs: DNS, TCP, TLS, or a dropped connection. */\nexport class DregsConnectionError extends DregsError {}\n\n/** The request was still outstanding when the configured timeout elapsed. */\nexport class DregsTimeoutError extends DregsConnectionError {}\n\n/** An incoming webhook did not verify against the channel's signing secret. */\nexport class WebhookVerificationError extends DregsError {}\n\n/** The fields carried by every error that reached the API and came back an error. */\nexport interface DregsAPIErrorOptions {\n  /** The HTTP status code. */\n  statusCode: number;\n  /** The parsed JSON body, or `null` when the response was not JSON. */\n  body?: unknown;\n  /** Value of the `X-Request-Id` response header, when the response carried one. */\n  requestId?: string | null;\n  /** The underlying cause, when there is one worth keeping. */\n  cause?: unknown;\n}\n\n/**\n * Dregs answered, and the answer was an error.\n *\n * `message` is the human-readable message the API sent, so `err.message` reads the way a JS\n * caller expects. `toString()` prefixes it with the status and the request id, which is the form\n * worth putting in a log line when you open a support ticket.\n */\nexport class DregsAPIError extends DregsError {\n  /** The HTTP status code. */\n  readonly statusCode: number;\n\n  /** The parsed JSON body, or `null` when the response was not JSON. */\n  readonly body: unknown;\n\n  /**\n   * Value of the `X-Request-Id` response header, when present.\n   *\n   * Quote it when you report a problem: it is what lets Dregs find your exact request.\n   */\n  readonly requestId: string | null;\n\n  constructor(message: string, options: DregsAPIErrorOptions) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n\n    this.statusCode = options.statusCode;\n    this.body = options.body ?? null;\n    this.requestId = options.requestId ?? null;\n  }\n\n  override toString(): string {\n    const suffix = this.requestId ? ` (request ${this.requestId})` : '';\n\n    return `${this.name}: HTTP ${this.statusCode}: ${this.message}${suffix}`;\n  }\n}\n\n/**\n * 400. The request was malformed or missing something Dregs requires.\n *\n * For event ingestion this most often means the event carried neither an identity nor a device,\n * or the body failed validation.\n */\nexport class BadRequestError extends DregsAPIError {}\n\n/** 401. The secret key was missing, unrecognized, revoked, or expired. */\nexport class AuthenticationError extends DregsAPIError {}\n\n/**\n * 402. The account is over its monthly event limit and ingestion is refused.\n *\n * Events are not queued while an account is over its limit, so the caller decides whether to drop\n * the event or hold it. The limit resets with the billing period; upgrading the plan clears it\n * immediately.\n */\nexport class QuotaExceededError extends DregsAPIError {}\n\n/** 403. The credential authenticated but is not allowed to do this. */\nexport class PermissionDeniedError extends DregsAPIError {}\n\n/** 404. No such identity, or no analysis has been run for it yet. */\nexport class NotFoundError extends DregsAPIError {}\n\n/** The fields carried by a 429, on top of the usual API error fields. */\nexport interface RateLimitErrorOptions extends Omit<DregsAPIErrorOptions, 'statusCode'> {\n  statusCode?: number;\n  /** Seconds to wait before retrying, from the `Retry-After` header. */\n  retryAfter?: number | null;\n}\n\n/**\n * 429. The credential exceeded its request rate limit.\n *\n * The client retries these on its own; you only see one when the retries were exhausted or turned\n * off. Wait {@link RateLimitError.retryAfter} seconds before trying again when it is set.\n */\nexport class RateLimitError extends DregsAPIError {\n  /**\n   * Seconds to wait before retrying, from the `Retry-After` header when the response carried a\n   * numeric one, and `null` otherwise.\n   */\n  readonly retryAfter: number | null;\n\n  constructor(message: string, options: RateLimitErrorOptions = {}) {\n    super(message, { ...options, statusCode: options.statusCode ?? 429 });\n\n    this.retryAfter = options.retryAfter ?? null;\n  }\n}\n\n/** 5xx. Something went wrong inside Dregs. These are retried automatically. */\nexport class ServerError extends DregsAPIError {}\n\nconst STATUS_ERRORS: Readonly<\n  Record<number, new (message: string, options: DregsAPIErrorOptions) => DregsAPIError>\n> = {\n  400: BadRequestError,\n  401: AuthenticationError,\n  402: QuotaExceededError,\n  403: PermissionDeniedError,\n  404: NotFoundError,\n};\n\n/**\n * Returns the error class that represents `statusCode`.\n *\n * 429 is deliberately absent from the table: it needs the `Retry-After` header, so the client\n * builds a {@link RateLimitError} directly rather than going through here.\n */\nexport function errorForStatus(\n  statusCode: number,\n): new (message: string, options: DregsAPIErrorOptions) => DregsAPIError {\n  const mapped = STATUS_ERRORS[statusCode];\n\n  if (mapped) {\n    return mapped;\n  }\n\n  return statusCode >= 500 ? ServerError : DregsAPIError;\n}\n","/**\n * Verifying webhooks Dregs sends you.\n *\n * Dregs signs every webhook with the channel's signing secret: `X-Dregs-Signature` is the\n * hex-encoded HMAC-SHA256 of the raw request body. Verify it before you act on the payload, and\n * verify it against the bytes you received rather than a re-serialized object, because\n * re-serializing changes key order and whitespace and will not match.\n *\n * ```ts\n * import { verifyWebhook } from '@dregs/sdk/webhooks';\n *\n * app.post('/webhooks/dregs', express.raw({ type: 'application/json' }), (req, res) => {\n *   const event = verifyWebhook({\n *     payload: req.body, // the Buffer, not req.body parsed as JSON\n *     signature: req.header('X-Dregs-Signature') ?? '',\n *     secret: process.env.DREGS_WEBHOOK_SECRET!,\n *   });\n *\n *   handle(event);\n * });\n * ```\n *\n * The signing secret is shown once, when you create the webhook channel. It is not your API\n * secret key: one authenticates you to Dregs, the other proves a payload came from Dregs.\n *\n * @module\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\nimport { WebhookVerificationError } from './errors.js';\n\n/** The header carrying the hex-encoded HMAC-SHA256 of the raw body. */\nexport const SIGNATURE_HEADER = 'X-Dregs-Signature';\n\n/** The header carrying the delivery's timestamp. */\nexport const TIMESTAMP_HEADER = 'X-Dregs-Timestamp';\n\n/** The header naming the event type. */\nexport const EVENT_HEADER = 'X-Dregs-Event';\n\n/** How far out of date a webhook's timestamp may be before {@link verifyWebhook} rejects it. */\nexport const DEFAULT_TOLERANCE_SECONDS = 300;\n\n/**\n * A raw webhook body.\n *\n * A `Buffer` or `Uint8Array` is what you want: the bytes exactly as received. A string is\n * accepted for frameworks that hand you the raw text, and is hashed as UTF-8.\n */\nexport type WebhookPayload = string | Uint8Array;\n\n/** A verified webhook body: `event`, `timestamp`, and the payload for that event. */\nexport type WebhookEvent = Record<string, unknown>;\n\n/** The arguments to {@link verifyWebhook}. */\nexport interface VerifyWebhookOptions {\n  /** The raw request body, exactly as received. Not a parsed object. */\n  payload: WebhookPayload;\n\n  /** The `X-Dregs-Signature` header. */\n  signature: string;\n\n  /** The channel's signing secret. */\n  secret: string;\n\n  /**\n   * How many seconds out of date the payload's own `timestamp` may be before it is treated as a\n   * replay. Defaults to 300. Pass `null` to skip the check, which you should only do if you are\n   * deduplicating on the event id yourself.\n   *\n   * The timestamp is inside the signed body, so an attacker cannot alter it without breaking\n   * the signature.\n   */\n  tolerance?: number | null;\n\n  /** The current time. For tests. */\n  now?: Date;\n}\n\n/** Returns the hex-encoded HMAC-SHA256 of `payload` under `secret`. */\nexport function computeWebhookSignature(payload: WebhookPayload, secret: string): string {\n  return createHmac('sha256', secret).update(toBytes(payload)).digest('hex');\n}\n\n/**\n * Returns whether `signature` matches `payload`.\n *\n * The comparison is constant-time. Prefer {@link verifyWebhook}, which also rejects replays and\n * hands back the parsed event; reach for this one only when you need the boolean.\n */\nexport function verifyWebhookSignature(\n  payload: WebhookPayload,\n  signature: string,\n  secret: string,\n): boolean {\n  if (!signature || !secret) {\n    return false;\n  }\n\n  const expected = Buffer.from(computeWebhookSignature(payload, secret), 'utf8');\n  const received = Buffer.from(signature.trim(), 'utf8');\n\n  // timingSafeEqual throws on a length mismatch rather than returning false, and a wrong-length\n  // signature is wrong regardless; the length is not a secret.\n  return expected.length === received.length && timingSafeEqual(expected, received);\n}\n\n/**\n * Verifies a webhook and returns its parsed body.\n *\n * @returns The parsed webhook body: `event`, `timestamp`, and the payload for that event.\n * @throws {WebhookVerificationError} The signature did not match, the body was not a JSON\n *   object, or the payload is older than the tolerance. Answer 400 and do not act on it.\n */\nexport function verifyWebhook(options: VerifyWebhookOptions): WebhookEvent {\n  const { payload, signature, secret, tolerance = DEFAULT_TOLERANCE_SECONDS, now } = options;\n\n  if (!verifyWebhookSignature(payload, signature, secret)) {\n    throw new WebhookVerificationError(\n      'The webhook signature did not match. Check that you are verifying the raw request body ' +\n        'rather than a re-serialized copy, and that the signing secret belongs to the channel ' +\n        'that sent this delivery.',\n    );\n  }\n\n  let event: unknown;\n\n  try {\n    event = JSON.parse(toText(payload));\n  } catch (cause) {\n    throw new WebhookVerificationError(\n      `The webhook body was not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,\n      { cause },\n    );\n  }\n\n  if (typeof event !== 'object' || event === null || Array.isArray(event)) {\n    throw new WebhookVerificationError('The webhook body was not a JSON object.');\n  }\n\n  const body = event as WebhookEvent;\n\n  if (tolerance !== null && tolerance !== undefined) {\n    checkFreshness(body, tolerance, now);\n  }\n\n  return body;\n}\n\nfunction checkFreshness(event: WebhookEvent, tolerance: number, now: Date | undefined): void {\n  const raw = event.timestamp;\n\n  if (typeof raw !== 'string' || !raw) {\n    throw new WebhookVerificationError(\n      'The webhook carried no timestamp, so it cannot be checked for replay. Pass ' +\n        'tolerance: null if you are deduplicating deliveries some other way.',\n    );\n  }\n\n  const sent = new Date(raw);\n\n  if (Number.isNaN(sent.getTime())) {\n    throw new WebhookVerificationError(\n      `The webhook timestamp was unreadable: ${JSON.stringify(raw)}`,\n    );\n  }\n\n  const age = Math.abs(((now ?? new Date()).getTime() - sent.getTime()) / 1000);\n\n  if (age > tolerance) {\n    throw new WebhookVerificationError(\n      `The webhook timestamp is ${age.toFixed(0)}s away from now, beyond the ${tolerance}s ` +\n        'tolerance. Treating it as a replay.',\n    );\n  }\n}\n\nfunction toBytes(payload: WebhookPayload): Buffer {\n  return typeof payload === 'string' ? Buffer.from(payload, 'utf8') : Buffer.from(payload);\n}\n\nfunction toText(payload: WebhookPayload): string {\n  return typeof payload === 'string' ? payload : Buffer.from(payload).toString('utf8');\n}\n"]}