honk-me 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `honk-me` (npm) are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-04
+
+### Added
+- `Honk` client for `POST /v1/messages` with every field of the v1 ingestion API
+  (including `imageUrl`), camelCase in, snake_case on the wire.
+- Automatic UUIDv7 `Idempotency-Key` (or your own), reused on every retry.
+- Retries for network errors, timeouts, 429 and 5xx with exponential backoff, full jitter,
+  `Retry-After` and a total deadline.
+- Typed errors: `HonkValidationError`, `HonkAuthError`, `HonkQuotaError`,
+  `HonkConflictError`, `HonkNetworkError`, `HonkTimeoutError`, `HonkServerError`.
+- Local validation of limits, enums and https-only URLs, with every invalid field reported.
+- Helpers `problem`, `recovery`, `info`, `success`, `warning`, `error`, `critical`;
+  `Honk.fromEnv()`.
+- ESM + CommonJS builds with TypeScript types, zero runtime dependencies; Node 18+, Bun, Deno.
+- The Honk scale: severity horn aliases `light` (info), `beep` (success), `loud` (warning),
+  `long` (error), `blast` (critical), case-insensitive and always sent canonical; `Severity`
+  constants (`Severity.Loud === 'warning'`), `normalizeSeverity()` and the `light`, `beep`,
+  `loud`, `long`, `blast` helpers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Honk contributors
+
+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,224 @@
+# honk-me
+
+[![CI](https://github.com/honk-me/honk-node/actions/workflows/ci.yml/badge.svg)](https://github.com/honk-me/honk-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/honk-me)](https://www.npmjs.com/package/honk-me)
+
+Official Node.js / TypeScript client for [Honk](https://honk-me.app), the inbox that turns
+events from your apps, scripts, cron jobs and CI into calm, grouped push notifications on your
+phone.
+
+- Zero runtime dependencies. ESM, CommonJS and TypeScript types.
+- Node 18+ (global `fetch`). Also works on Bun and Deno (`npm:honk-me`).
+- Retries with backoff, `Retry-After`, a total deadline and an idempotency key on every send,
+  so a retry never creates a duplicate.
+
+> **Keep the key on the server.** A Honk ingestion key (`honk_…`) lets anyone post into your
+> project. Use this package in back-end code, functions and scripts only. Never bundle it
+> into a browser, mobile or desktop front end, and never commit it. Read it from the
+> environment.
+
+## Install
+
+```sh
+npm install honk-me
+```
+
+Create a project and an ingestion key at [honk-me.app](https://honk-me.app). Its
+*Integrations* page generates ready-to-paste code for this package.
+
+## Quick start
+
+```js
+import { Honk } from 'honk-me';
+
+const honk = new Honk({ url: process.env.HONK_URL, key: process.env.HONK_KEY });
+await honk.beep('Backup finished', 'nightly pg_dump took 42 s');
+```
+
+`Honk.fromEnv()` reads `HONK_URL`, `HONK_KEY` and the optional `HONK_SOURCE`,
+`HONK_ENVIRONMENT` and `HONK_CHANNEL` defaults. CommonJS:
+`const { Honk } = require('honk-me')`.
+
+## The Honk scale
+
+Every severity has a horn name. Use either; the SDK always sends the canonical value.
+
+| Horn | Severity | Helper | Constant |
+|---|---|---|---|
+| light honk | `light` (info) | `honk.light(title, message, opts)` | `Severity.Light` |
+| beep-beep | `beep` (success) | `honk.beep(…)` | `Severity.Beep` |
+| loud honk | `loud` (warning) | `honk.loud(…)` | `Severity.Loud` |
+| long honk | `long` (error) | `honk.long(…)` | `Severity.Long` |
+| blast | `blast` (critical) | `honk.blast(…)` | `Severity.Blast` |
+
+`severity: 'loud'`, `'LOUD'` and `'warning'` are the same event (also for idempotency).
+`long` and `blast` push at least as `high` priority. `info()`, `success()`, `warning()`,
+`error()` and `critical()` remain as synonyms; `normalizeSeverity('Blast') === 'critical'`.
+
+## Recipe: notify me when a customer asks for something
+
+Give each request its own group (`requests/<id>`) and its own idempotency key. Two different
+customers never fold into one notification, and a retried webhook or job never buzzes twice.
+
+```js
+import { Honk } from 'honk-me';
+
+const honk = Honk.fromEnv(); // create once, reuse (keep-alive)
+
+export async function onCustomerRequest(req) {
+  // ...save the request first, then notify without blocking the response:
+  honk
+    .send(
+      {
+        title: `New request: ${req.subject}`.slice(0, 160),
+        message: `${req.name} (${req.company}) asked: ${req.body}`.slice(0, 2000),
+        priority: 'high', // push right away
+        category: 'customers',
+        channel: 'requests',
+        groupKey: `requests/${req.id}`, // one group per request
+        url: `https://shop.example.com/admin/requests/${req.id}`, // https only, shown as "Open link"
+        metadata: { request_id: String(req.id) },
+      },
+      { idempotencyKey: `request-${req.id}` }, // same request, same key: never a duplicate
+    )
+    .catch((err) => console.warn('honk:', err.message)); // never fail the customer's request
+}
+```
+
+In a queue worker (BullMQ, SQS, …) `await` the call and let the job retry on
+`err.retryable`, keeping the same `idempotencyKey`.
+
+## Grouping in three lines
+
+Messages with the same `groupKey` (per project, environment, source and channel) form one
+group: the first one pushes, repeats update it calmly instead of buzzing again. Use one key
+per customer request (`requests/<id>`), and a shared key only for repeats of the same problem
+(`queue/failed-jobs`). `problem`/`recovery` pairs need a `groupKey`.
+
+## Sending
+
+```ts
+honk.send(message, { idempotencyKey?, signal? }) // → Promise<{ id, duplicate, receivedAt }>
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `message` | string | **required**, 1–8192 bytes UTF-8, line breaks allowed |
+| `title` | string | ≤ 160 chars, one line; default: first line of `message` |
+| `severity` | `light` `beep` `loud` `long` `blast` (or the canonical names, any case) | default `light`; `long`/`blast` push at least as `high` |
+| `priority` | `low` `normal` `high` `urgent` | default `normal`; `urgent` needs a key with *allow urgent* |
+| `category` | `infrastructure` `security` `backups` `deployments` `payments` `customers` `sales` `automation` `personal` `other` | |
+| `source` / `environment` / `channel` | string | ≤ 64 / 32 / 64 chars; default `api` / `default` / `general` or the client `defaults` |
+| `groupKey` | string | ≤ 128 chars |
+| `eventType` | `event` `problem` `recovery` | `recovery` needs `groupKey` |
+| `occurredAt` | `Date` or RFC 3339 string | informational |
+| `url` | string | `https://` only, no credentials |
+| `imageUrl` | string | `https://` only, no credentials or `#fragment`; fetched by the server afterwards |
+| `metadata` | `Record<string, string \| number \| boolean>` | ≤ 16 keys `[A-Za-z0-9_.-]{1,64}`, strings ≤ 512 chars |
+| `ttlSeconds` | integer | push lifetime 60–86400, default 3600 |
+| `sourceSequence` | integer | 0 … 2^53-1, needs `groupKey`; a delayed recovery never closes a newer problem |
+
+Fields are camelCase in this SDK and sent with the API's snake_case names. `null`, `undefined`
+and empty optional strings are omitted. A resolved promise means Honk **durably stored** the
+message (`202`); it does not mean a push was delivered or read.
+
+Helpers (the last argument takes any message field plus `idempotencyKey` and `signal`):
+
+```js
+await honk.loud('Disk 91%', '/var on app-01', { groupKey: 'disk/app-01/var' });
+await honk.light('Deploy started', 'v4.2.0 to production', { channel: 'deploys' });
+await honk.beep(title, message, opts); await honk.long(title, message, opts); await honk.blast(title, message, opts);
+await honk.problem('db/backup', 'Backup failed', 'pg_dump exited with 1');      // a long honk by default
+await honk.recovery('db/backup', 'Backup OK', 'pg_dump finished in 41 s');      // a beep by default
+```
+
+### Options
+
+```js
+new Honk({
+  url: 'https://honk.example.com', // base URL of your server
+  key: 'honk_…',                  // project ingestion key
+  timeoutMs: 5000,                // per attempt
+  retries: 4,                     // after the first attempt
+  deadlineMs: 30000,              // total, waits included
+  defaults: { source: 'billing-api', environment: 'production', channel: 'payments' },
+  validate: true,                 // local checks before sending (the server always validates)
+  backoff: { baseMs: 500, maxMs: 8000 },
+  fetch: customFetch,             // e.g. undici with a proxy agent
+});
+```
+
+## Retries and idempotency, guaranteed
+
+- Every `send()` carries an `Idempotency-Key`: yours, or a fresh UUIDv7. **The same key is
+  reused on every retry.** Within 24 h Honk answers a replay with the original id and
+  `duplicate: true`, so a lost response never creates a second message.
+- Only network errors, timeouts, `429` and `5xx` are retried, with exponential backoff and
+  full jitter (`random(0, min(8 s, 0.5 s·2ⁿ))`), never sooner than the server's `Retry-After`.
+- Everything stops at `deadlineMs`: if the next wait would cross it (for example a daily quota
+  that resets at midnight), the error is thrown at once with `retryAfter`.
+- `4xx` other than `429` are never retried: fix the request instead.
+- Short per-attempt timeouts; Node's `fetch` keeps connections alive, so create one `Honk`
+  per process and reuse it.
+- Pass your own stable key (`request-4812`, `deploy-${sha}`) to stay duplicate-free across
+  process restarts and job retries. Reusing a key with a *different* payload is a conflict.
+
+## Errors
+
+Every error is a `HonkError` with `kind`, `status`, `code`, `requestId`, `idempotencyKey`,
+`attempts`, `retryAfter` and `retryable`.
+
+| Class | `kind` | When | What to do |
+|---|---|---|---|
+| `HonkValidationError` | `validation` | rejected locally (`local: true`) or `400`/`413`/`415`/`422`; `fields` lists every problem | fix the message |
+| `HonkAuthError` | `auth` | `401 invalid_key`, `403 priority_not_allowed`, `project_suspended`, `workspace_suspended` | fix the key or the priority |
+| `HonkQuotaError` | `quota` | `429 quota_exceeded` (daily, resets at UTC midnight) or `rate_limited`, after retries | retry after `retryAfter` seconds |
+| `HonkConflictError` | `conflict` | `409 idempotency_conflict`: same key, different payload | use a new key, or send the original payload |
+| `HonkNetworkError` | `network` | unreachable on every attempt | retry later, same key |
+| `HonkTimeoutError` | `timeout` | attempts timed out; the message may or may not be stored | retry later, same key |
+| `HonkServerError` | `server` | `5xx` on every attempt | retry later, same key |
+
+```js
+import { HonkError, HonkValidationError } from 'honk-me';
+
+try {
+  await honk.send(msg, { idempotencyKey: `order-${order.id}-failed` });
+} catch (err) {
+  if (err instanceof HonkValidationError) logger.error(err.fields);   // a bug: don't retry
+  else if (err instanceof HonkError && err.retryable) queue.retryLater(err.idempotencyKey, err.retryAfter);
+  else throw err;
+}
+```
+
+`kind` is also handy when two copies of the package are loaded and `instanceof` can fail.
+
+## Bun and Deno
+
+```ts
+import { Honk } from 'npm:honk-me'; // Deno
+const honk = new Honk({ url: Deno.env.get('HONK_URL')!, key: Deno.env.get('HONK_KEY')! });
+```
+
+Bun: `bun add honk-me`, then use it as in Node.
+
+## Development
+
+```sh
+npm install
+npm test                 # build + unit tests (mock server) + CommonJS smoke test
+npm run typecheck        # also checks the published .d.ts from ESM and CJS consumers
+HONK_URL=… HONK_KEY=… npm run test:integration   # against a real server (use a test project's key)
+```
+
+The version lives in `package.json`; the build regenerates `src/version.ts` (`VERSION`, the
+User-Agent) from it. Releases: push a tag `vX.Y.Z` matching `package.json` and the release
+workflow publishes to npm with provenance (see `CHANGELOG.md`).
+
+## Links
+
+- [honk-me.app](https://honk-me.app): the Honk inbox (web, iPhone).
+- Other SDKs: [PHP / Laravel](https://github.com/honk-me/honk-php),
+  [Go + CLI](https://github.com/honk-me/honk-go), [Swift](https://github.com/honk-me/honk-swift),
+  [Kotlin / Java](https://github.com/honk-me/honk-kotlin).
+
+MIT License.

package/dist/cjs/client.d.ts

@@ -0,0 +1,58 @@
+import type { Defaults, HelperOptions, HonkOptions, Message, SendOptions, SendResult } from './types.js';
+import { VERSION } from './version.js';
+export { VERSION };
+/** Seconds from a Retry-After header (delta-seconds or HTTP date), or undefined. */
+export declare function parseRetryAfter(value: string | null, now?: number): number | undefined;
+/**
+ * Client for `POST /v1/messages`. Create one per process and reuse it (connections are kept alive).
+ *
+ * ```ts
+ * const honk = new Honk({ url: process.env.HONK_URL!, key: process.env.HONK_KEY! });
+ * await honk.send({ title: 'Backup finished', message: 'nightly pg_dump took 42 s', severity: 'success' });
+ * ```
+ */
+export declare class Honk {
+    #private;
+    readonly url: string;
+    readonly timeoutMs: number;
+    readonly retries: number;
+    readonly deadlineMs: number;
+    readonly defaults: Readonly<Defaults>;
+    readonly validate: boolean;
+    constructor(options: HonkOptions);
+    /**
+     * Reads `HONK_URL`, `HONK_KEY` and optionally `HONK_SOURCE`, `HONK_ENVIRONMENT`, `HONK_CHANNEL`
+     * from the environment. `options` override them.
+     */
+    static fromEnv(options?: Partial<HonkOptions>): Honk;
+    /**
+     * Sends one event. Resolves once Honk has durably stored it (`202`), which does not mean a push
+     * was delivered. Retries network errors, 429 and 5xx with the same Idempotency-Key until
+     * `retries` or `deadlineMs` runs out, then throws a {@link HonkError}.
+     */
+    send(message: Message, options?: SendOptions): Promise<SendResult>;
+    /** A `problem` for `groupKey` (opens or continues an incident). Severity defaults to `long` (error). */
+    problem(groupKey: string, title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A `recovery` for `groupKey` (closes its open incident). Severity defaults to `beep` (success). */
+    recovery(groupKey: string, title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A light honk (severity info). */
+    light(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A beep-beep (severity success). */
+    beep(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A loud honk (severity warning). */
+    loud(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A long honk (severity error; pushes at least as high priority). */
+    long(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** A blast (severity critical; pushes at least as high priority). */
+    blast(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** Synonym of {@link light}. */
+    info(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** Synonym of {@link beep}. */
+    success(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** Synonym of {@link loud}. */
+    warning(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** Synonym of {@link long}. */
+    error(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+    /** Synonym of {@link blast}. */
+    critical(title: string | null, message: string, options?: HelperOptions): Promise<SendResult>;
+}

package/dist/cjs/client.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Honk = exports.VERSION = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+const errors_js_1 = require("./errors.js");
+const uuid_js_1 = require("./uuid.js");
+const validate_js_1 = require("./validate.js");
+const version_js_1 = require("./version.js");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRIES = 4;
+const DEFAULT_DEADLINE_MS = 30_000;
+const DEFAULT_BACKOFF_BASE_MS = 500;
+const DEFAULT_BACKOFF_MAX_MS = 8_000;
+/** Seconds from a Retry-After header (delta-seconds or HTTP date), or undefined. */
+function parseRetryAfter(value, now = Date.now()) {
+    if (value === null)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number(v);
+    const at = Date.parse(v);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - now) / 1000));
+}
+class TimeoutSignal {
+}
+/**
+ * Client for `POST /v1/messages`. Create one per process and reuse it (connections are kept alive).
+ *
+ * ```ts
+ * const honk = new Honk({ url: process.env.HONK_URL!, key: process.env.HONK_KEY! });
+ * await honk.send({ title: 'Backup finished', message: 'nightly pg_dump took 42 s', severity: 'success' });
+ * ```
+ */
+class Honk {
+    url;
+    timeoutMs;
+    retries;
+    deadlineMs;
+    defaults;
+    validate;
+    #key;
+    #fetch;
+    #backoffBase;
+    #backoffMax;
+    #userAgent;
+    constructor(options) {
+        if (options === null || typeof options !== 'object')
+            throw new TypeError('Honk: pass options like { url, key }');
+        this.url = normalizeUrl(options.url);
+        this.#key = normalizeKey(options.key);
+        this.timeoutMs = positive(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');
+        this.deadlineMs = positive(options.deadlineMs, DEFAULT_DEADLINE_MS, 'deadlineMs');
+        this.retries = options.retries ?? DEFAULT_RETRIES;
+        if (!Number.isInteger(this.retries) || this.retries < 0)
+            throw new TypeError('Honk: retries must be an integer ≥ 0');
+        this.#backoffBase = positive(options.backoff?.baseMs, DEFAULT_BACKOFF_BASE_MS, 'backoff.baseMs');
+        this.#backoffMax = positive(options.backoff?.maxMs, DEFAULT_BACKOFF_MAX_MS, 'backoff.maxMs');
+        this.defaults = Object.freeze({ ...(options.defaults ?? {}) });
+        this.validate = options.validate ?? true;
+        const f = options.fetch ?? globalThis.fetch;
+        if (typeof f !== 'function')
+            throw new TypeError('Honk: no fetch available; use Node 18+ or pass options.fetch');
+        this.#fetch = f;
+        this.#userAgent = `honk-me-node/${version_js_1.VERSION}${options.userAgent ? ` ${options.userAgent}` : ''}`;
+    }
+    /**
+     * Reads `HONK_URL`, `HONK_KEY` and optionally `HONK_SOURCE`, `HONK_ENVIRONMENT`, `HONK_CHANNEL`
+     * from the environment. `options` override them.
+     */
+    static fromEnv(options = {}) {
+        const env = (name) => {
+            const g = globalThis;
+            return g.process?.env?.[name] ?? g.Deno?.env?.get(name);
+        };
+        return new Honk({
+            ...options,
+            url: options.url ?? env('HONK_URL') ?? '',
+            key: options.key ?? env('HONK_KEY') ?? '',
+            defaults: {
+                source: env('HONK_SOURCE'),
+                environment: env('HONK_ENVIRONMENT'),
+                channel: env('HONK_CHANNEL'),
+                ...options.defaults,
+            },
+        });
+    }
+    /**
+     * Sends one event. Resolves once Honk has durably stored it (`202`), which does not mean a push
+     * was delivered. Retries network errors, 429 and 5xx with the same Idempotency-Key until
+     * `retries` or `deadlineMs` runs out, then throws a {@link HonkError}.
+     */
+    async send(message, options = {}) {
+        const body = JSON.stringify((0, validate_js_1.buildBody)(message, this.defaults, this.validate));
+        const idempotencyKey = options.idempotencyKey === undefined ? await (0, uuid_js_1.uuidv7)() : (0, validate_js_1.checkIdempotencyKey)(options.idempotencyKey);
+        const signal = options.signal;
+        const started = Date.now();
+        const deadline = started + this.deadlineMs;
+        for (let attempt = 1;; attempt++) {
+            signal?.throwIfAborted();
+            let failure;
+            try {
+                const res = await this.#post(body, idempotencyKey, Math.max(1, Math.min(this.timeoutMs, deadline - Date.now())), signal);
+                if (res.status >= 200 && res.status < 300)
+                    return accepted(res, idempotencyKey, attempt);
+                failure = errorFor(res, idempotencyKey, attempt);
+                if (!(failure instanceof errors_js_1.HonkQuotaError || failure instanceof errors_js_1.HonkServerError))
+                    throw failure;
+            }
+            catch (err) {
+                if (err instanceof errors_js_1.HonkError && !(err instanceof errors_js_1.HonkQuotaError || err instanceof errors_js_1.HonkServerError))
+                    throw err;
+                if (signal?.aborted)
+                    throw signal.reason;
+                failure = err instanceof errors_js_1.HonkError ? err : networkError(err, idempotencyKey, attempt);
+            }
+            if (attempt > this.retries)
+                throw failure;
+            const jitter = Math.random() * Math.min(this.#backoffMax, this.#backoffBase * 2 ** (attempt - 1));
+            const wait = Math.max(jitter, (failure.retryAfter ?? 0) * 1000);
+            if (Date.now() + wait >= deadline)
+                throw failure;
+            await sleep(wait, signal);
+        }
+    }
+    /** A `problem` for `groupKey` (opens or continues an incident). Severity defaults to `long` (error). */
+    problem(groupKey, title, message, options = {}) {
+        return this.#helper({ ...options, severity: options.severity ?? 'error', groupKey, eventType: 'problem' }, title, message);
+    }
+    /** A `recovery` for `groupKey` (closes its open incident). Severity defaults to `beep` (success). */
+    recovery(groupKey, title, message, options = {}) {
+        return this.#helper({ ...options, severity: options.severity ?? 'success', groupKey, eventType: 'recovery' }, title, message);
+    }
+    /** A light honk (severity info). */
+    light(title, message, options = {}) {
+        return this.#severity('info', title, message, options);
+    }
+    /** A beep-beep (severity success). */
+    beep(title, message, options = {}) {
+        return this.#severity('success', title, message, options);
+    }
+    /** A loud honk (severity warning). */
+    loud(title, message, options = {}) {
+        return this.#severity('warning', title, message, options);
+    }
+    /** A long honk (severity error; pushes at least as high priority). */
+    long(title, message, options = {}) {
+        return this.#severity('error', title, message, options);
+    }
+    /** A blast (severity critical; pushes at least as high priority). */
+    blast(title, message, options = {}) {
+        return this.#severity('critical', title, message, options);
+    }
+    /** Synonym of {@link light}. */
+    info(title, message, options = {}) {
+        return this.#severity('info', title, message, options);
+    }
+    /** Synonym of {@link beep}. */
+    success(title, message, options = {}) {
+        return this.#severity('success', title, message, options);
+    }
+    /** Synonym of {@link loud}. */
+    warning(title, message, options = {}) {
+        return this.#severity('warning', title, message, options);
+    }
+    /** Synonym of {@link long}. */
+    error(title, message, options = {}) {
+        return this.#severity('error', title, message, options);
+    }
+    /** Synonym of {@link blast}. */
+    critical(title, message, options = {}) {
+        return this.#severity('critical', title, message, options);
+    }
+    #severity(severity, title, message, options) {
+        return this.#helper({ ...options, severity }, title, message);
+    }
+    #helper(options, title, message) {
+        const { idempotencyKey, signal, ...fields } = options;
+        return this.send({ ...fields, title, message }, { idempotencyKey, signal });
+    }
+    async #post(body, idempotencyKey, timeoutMs, signal) {
+        const controller = new AbortController();
+        const timeout = new TimeoutSignal();
+        const timer = setTimeout(() => controller.abort(timeout), timeoutMs);
+        const onAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const res = await this.#fetch(`${this.url}/v1/messages`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.#key}`,
+                    'idempotency-key': idempotencyKey,
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                    'user-agent': this.#userAgent,
+                },
+                body,
+                redirect: 'manual',
+                signal: controller.signal,
+            });
+            const text = await res.text();
+            return { status: res.status, headers: res.headers, text };
+        }
+        catch (err) {
+            if (controller.signal.reason === timeout)
+                throw new TimeoutSignalError(timeoutMs);
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+exports.Honk = Honk;
+class TimeoutSignalError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`attempt timed out after ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+    }
+}
+function accepted(res, idempotencyKey, attempts) {
+    const data = parseJson(res.text);
+    if (!data || typeof data.id !== 'string') {
+        throw new errors_js_1.HonkError(`Honk answered ${res.status} without a message id`, { status: res.status, idempotencyKey, attempts, body: data ?? res.text });
+    }
+    const receivedAt = typeof data.received_at === 'string' ? new Date(data.received_at) : new Date(Number.NaN);
+    return { id: data.id, duplicate: data.duplicate === true, receivedAt };
+}
+function errorFor(res, idempotencyKey, attempts) {
+    const data = parseJson(res.text);
+    const e = data?.error;
+    const code = typeof e?.code === 'string' ? e.code : undefined;
+    const detail = typeof e?.message === 'string' ? e.message : res.text.slice(0, 200).trim() || `HTTP ${res.status}`;
+    const init = {
+        status: res.status,
+        code,
+        requestId: typeof e?.request_id === 'string' ? e.request_id : (res.headers.get('x-request-id') ?? undefined),
+        idempotencyKey,
+        attempts,
+        retryAfter: parseRetryAfter(res.headers.get('retry-after')),
+        body: data ?? (res.text || undefined),
+    };
+    const s = res.status;
+    const label = `Honk ${s}${code ? ` ${code}` : ''}: ${detail}`;
+    if (s === 400 || s === 413 || s === 415 || s === 422) {
+        const fields = Array.isArray(e?.fields) ? e.fields : [];
+        const list = fields.map((f) => `${f.field} ${f.message ?? f.code}`).join('; ');
+        return new errors_js_1.HonkValidationError(list ? `${label} (${list})` : label, { ...init, fields });
+    }
+    if (s === 401 || s === 403)
+        return new errors_js_1.HonkAuthError(label, init);
+    if (s === 409)
+        return new errors_js_1.HonkConflictError(label, init);
+    if (s === 429)
+        return new errors_js_1.HonkQuotaError(label, init);
+    if (s >= 500)
+        return new errors_js_1.HonkServerError(label, init);
+    if (s >= 300 && s < 400) {
+        const to = res.headers.get('location');
+        return new errors_js_1.HonkError(`Honk answered ${s} redirect${to ? ` to ${to}` : ''}; set url to the final https address`, init);
+    }
+    if (s === 404)
+        return new errors_js_1.HonkError(`${label} (is url the base address of your Honk server?)`, init);
+    return new errors_js_1.HonkError(label, init);
+}
+function networkError(err, idempotencyKey, attempts) {
+    if (err instanceof TimeoutSignalError) {
+        return new errors_js_1.HonkTimeoutError(`Honk did not answer: ${err.message} (the event may or may not have been stored; retrying with the same idempotency key is safe)`, {
+            code: 'timeout',
+            idempotencyKey,
+            attempts,
+            cause: err,
+        });
+    }
+    const cause = err?.cause;
+    const reason = cause?.code ?? cause?.message ?? err?.message ?? String(err);
+    return new errors_js_1.HonkNetworkError(`Could not reach Honk: ${reason}`, { code: 'network_error', idempotencyKey, attempts, cause: err });
+}
+function parseJson(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function normalizeUrl(url) {
+    if (typeof url !== 'string' || url.trim() === '') {
+        throw new TypeError('Honk: url is required (the base address of your Honk server, e.g. https://honk.example.com; is HONK_URL set?)');
+    }
+    let u = url.trim().replace(/\/+$/, '');
+    u = u.replace(/\/v1\/messages$/, '');
+    if (!/^https?:\/\/[^/]+/i.test(u))
+        throw new TypeError(`Honk: url must start with https:// (got ${JSON.stringify(url)})`);
+    return u;
+}
+function normalizeKey(key) {
+    if (typeof key !== 'string' || key.trim() === '') {
+        throw new TypeError('Honk: key is required (a project ingestion key honk_…; is HONK_KEY set?)');
+    }
+    const k = key.trim();
+    if (!/^honk_[\x21-\x7e]+$/.test(k)) {
+        throw new TypeError('Honk: key must be a project ingestion key starting with honk_ (create one under Project → Keys)');
+    }
+    return k;
+}
+function positive(v, def, name) {
+    if (v === undefined)
+        return def;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0)
+        throw new TypeError(`Honk: ${name} must be a positive number of milliseconds`);
+    return v;
+}