honk-me 0.1.0

package/dist/cjs/validate.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.byteLength = exports.LIMITS = void 0;
+exports.checkIdempotencyKey = checkIdempotencyKey;
+exports.buildBody = buildBody;
+exports.validUrl = validUrl;
+const errors_js_1 = require("./errors.js");
+const types_js_1 = require("./types.js");
+/** Limits from contracts/openapi.yaml (and the server's validator). */
+exports.LIMITS = {
+    bodyBytes: 16 * 1024,
+    messageBytes: 8192,
+    title: 160,
+    source: 64,
+    environment: 32,
+    channel: 64,
+    groupKey: 128,
+    urlBytes: 2048,
+    metadataKeys: 16,
+    metadataValue: 512,
+    ttlMin: 60,
+    ttlMax: 86400,
+    idempotencyKey: 128,
+};
+// camelCase SDK field → snake_case wire field, in a stable order.
+const FIELDS = {
+    title: 'title',
+    message: 'message',
+    severity: 'severity',
+    priority: 'priority',
+    category: 'category',
+    source: 'source',
+    environment: 'environment',
+    channel: 'channel',
+    groupKey: 'group_key',
+    eventType: 'event_type',
+    occurredAt: 'occurred_at',
+    url: 'url',
+    imageUrl: 'image_url',
+    metadata: 'metadata',
+    ttlSeconds: 'ttl_seconds',
+    sourceSequence: 'source_sequence',
+};
+const WIRE_TO_FIELD = Object.fromEntries(Object.entries(FIELDS).map(([k, v]) => [v, k]));
+// Go's unicode.IsControl (C0, DEL, C1) plus the Unicode line/paragraph separators, as on the server.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+const CONTROL_EXCEPT_BREAKS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/;
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+const METADATA_KEY = /^[A-Za-z0-9_.-]{1,64}$/;
+const IDEMPOTENCY_KEY = /^[\x21-\x7e]{1,128}$/;
+const encoder = new TextEncoder();
+const byteLength = (s) => encoder.encode(s).length;
+exports.byteLength = byteLength;
+const codePoints = (s) => {
+    let n = 0;
+    for (const _ of s)
+        n++;
+    return n;
+};
+const isBlank = (v) => v === undefined || v === null || v === '';
+/** Checks an Idempotency-Key: 1–128 printable ASCII characters (0x21–0x7E). */
+function checkIdempotencyKey(key) {
+    if (typeof key !== 'string' || !IDEMPOTENCY_KEY.test(key)) {
+        throw new errors_js_1.HonkValidationError('Invalid idempotency key: use 1–128 printable ASCII characters without spaces, e.g. "request-4812"', { local: true, code: 'validation_failed', fields: [{ field: 'Idempotency-Key', code: 'invalid_format', message: '1-128 printable ASCII characters' }] });
+    }
+    return key;
+}
+/**
+ * Turns a message into the wire object of `POST /v1/messages`, applying `defaults` and (unless
+ * `validate` is false) the cheap checks the server would apply anyway. Throws HonkValidationError
+ * listing every invalid field.
+ */
+function buildBody(input, defaults = {}, validate = true) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new errors_js_1.HonkValidationError('Invalid Honk message: expected an object like { title, message }', {
+            local: true,
+            code: 'validation_failed',
+            fields: [{ field: 'body', code: 'invalid_format', message: 'must be an object' }],
+        });
+    }
+    const errors = [];
+    const add = (field, code, message) => errors.push({ field, code, message });
+    const msg = input;
+    for (const key of Object.keys(msg)) {
+        if (!(key in FIELDS)) {
+            const hint = WIRE_TO_FIELD[key] ? ` (use ${WIRE_TO_FIELD[key]})` : '';
+            add(key, 'not_allowed', `unknown field${hint}`);
+        }
+    }
+    const value = (name) => {
+        const v = msg[name];
+        if (!isBlank(v))
+            return v;
+        if (name === 'source' || name === 'environment' || name === 'channel') {
+            const d = defaults[name];
+            return isBlank(d) ? undefined : d;
+        }
+        return undefined;
+    };
+    const body = {};
+    for (const name of Object.keys(FIELDS)) {
+        const v = value(name);
+        if (v === undefined)
+            continue;
+        const wire = FIELDS[name];
+        if (name === 'occurredAt') {
+            if (v instanceof Date) {
+                if (Number.isNaN(v.getTime()))
+                    add(wire, 'invalid_format', 'must be a valid date');
+                else
+                    body[wire] = v.toISOString();
+                continue;
+            }
+            if (validate && (typeof v !== 'string' || !RFC3339.test(v.trim()))) {
+                add(wire, 'invalid_format', 'must be a Date or an RFC 3339 timestamp like 2026-10-01T21:10:00Z');
+                continue;
+            }
+        }
+        // Horn aliases (and any case) become the canonical value, even with validate: false, so
+        // the idempotency payload is canonical and older servers understand it.
+        body[wire] = name === 'severity' && typeof v === 'string' ? ((0, types_js_1.normalizeSeverity)(v) ?? v) : v;
+    }
+    if (validate) {
+        checkMessage(body, add);
+    }
+    else if (msg.message === undefined || msg.message === null) {
+        add('message', 'required', 'message is required');
+    }
+    if (errors.length === 0) {
+        const size = (0, exports.byteLength)(JSON.stringify(body));
+        if (size > exports.LIMITS.bodyBytes)
+            add('body', 'too_long', `the JSON body is ${size} bytes; Honk accepts at most 16 KiB`);
+    }
+    if (errors.length > 0) {
+        const summary = errors.map((e) => `${e.field} ${e.message}`).join('; ');
+        throw new errors_js_1.HonkValidationError(`Invalid Honk message: ${summary}`, { local: true, code: 'validation_failed', fields: errors });
+    }
+    return body;
+}
+function checkMessage(b, add) {
+    const m = b.message;
+    if (m === undefined)
+        add('message', 'required', 'message is required');
+    else if (typeof m !== 'string')
+        add('message', 'invalid_format', 'must be a string');
+    else if ((0, exports.byteLength)(m) > exports.LIMITS.messageBytes)
+        add('message', 'too_long', `must be at most ${exports.LIMITS.messageBytes} bytes of UTF-8 (got ${(0, exports.byteLength)(m)})`);
+    else if (m.trim() === '')
+        add('message', 'too_short', 'must not be blank');
+    else if (CONTROL_EXCEPT_BREAKS.test(m))
+        add('message', 'invalid_format', 'must not contain control characters other than line breaks and tabs');
+    shortText(b, 'title', exports.LIMITS.title, add);
+    shortText(b, 'source', exports.LIMITS.source, add);
+    shortText(b, 'environment', exports.LIMITS.environment, add);
+    shortText(b, 'channel', exports.LIMITS.channel, add);
+    shortText(b, 'group_key', exports.LIMITS.groupKey, add);
+    if (b.severity !== undefined && (typeof b.severity !== 'string' || !types_js_1.SEVERITIES.includes(b.severity))) {
+        const aliases = Object.entries(types_js_1.SEVERITY_ALIASES).map(([alias, canonical]) => `${alias} (${canonical})`);
+        add('severity', 'invalid_enum', `must be one of ${aliases.join(', ')}`);
+    }
+    oneOf(b, 'priority', types_js_1.PRIORITIES, add);
+    oneOf(b, 'event_type', types_js_1.EVENT_TYPES, add);
+    oneOf(b, 'category', types_js_1.CATEGORIES, add);
+    const seq = b.source_sequence;
+    if (seq !== undefined && (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0)) {
+        add('source_sequence', 'out_of_range', 'must be an integer between 0 and 2^53-1');
+    }
+    if (b.group_key === undefined) {
+        if (b.event_type === 'recovery')
+            add('group_key', 'requires_group_key', 'recovery events require group_key');
+        if (seq !== undefined)
+            add('source_sequence', 'requires_group_key', 'source_sequence requires group_key');
+    }
+    if (b.url !== undefined && !validUrl(b.url, false)) {
+        add('url', 'invalid_format', 'must be an https URL without credentials, at most 2048 bytes');
+    }
+    if (b.image_url !== undefined && !validUrl(b.image_url, true)) {
+        add('image_url', 'invalid_format', 'must be an https URL without credentials or fragment, at most 2048 bytes');
+    }
+    const md = b.metadata;
+    if (md !== undefined) {
+        if (typeof md !== 'object' || md === null || Array.isArray(md)) {
+            add('metadata', 'invalid_format', 'must be an object of strings, numbers and booleans');
+        }
+        else {
+            const entries = Object.entries(md);
+            if (entries.length > exports.LIMITS.metadataKeys)
+                add('metadata', 'too_long', `at most ${exports.LIMITS.metadataKeys} keys`);
+            for (const [k, v] of entries) {
+                const field = `metadata.${k}`;
+                if (!METADATA_KEY.test(k))
+                    add(field, 'invalid_format', 'keys must match [A-Za-z0-9_.-]{1,64}');
+                else if (typeof v === 'string') {
+                    if (codePoints(v) > exports.LIMITS.metadataValue || CONTROL_EXCEPT_BREAKS.test(v)) {
+                        add(field, 'invalid_format', `strings must be at most ${exports.LIMITS.metadataValue} characters without control characters`);
+                    }
+                }
+                else if (typeof v === 'number') {
+                    if (!Number.isFinite(v))
+                        add(field, 'invalid_format', 'numbers must be finite');
+                }
+                else if (typeof v !== 'boolean') {
+                    add(field, 'invalid_format', 'values must be strings, numbers or booleans');
+                }
+            }
+        }
+    }
+    const ttl = b.ttl_seconds;
+    if (ttl !== undefined && (typeof ttl !== 'number' || !Number.isInteger(ttl) || ttl < exports.LIMITS.ttlMin || ttl > exports.LIMITS.ttlMax)) {
+        add('ttl_seconds', 'out_of_range', `must be an integer between ${exports.LIMITS.ttlMin} and ${exports.LIMITS.ttlMax}`);
+    }
+}
+function shortText(b, field, max, add) {
+    const v = b[field];
+    if (v === undefined)
+        return;
+    if (typeof v !== 'string')
+        return add(field, 'invalid_format', 'must be a string');
+    const s = v.trim();
+    if (s === '')
+        add(field, 'too_short', 'must not be empty');
+    else if (codePoints(s) > max)
+        add(field, 'too_long', `must be at most ${max} characters`);
+    else if (CONTROL.test(s))
+        add(field, 'invalid_format', 'must not contain control characters or line breaks');
+}
+function oneOf(b, field, allowed, add) {
+    const v = b[field];
+    if (v !== undefined && (typeof v !== 'string' || !allowed.includes(v))) {
+        add(field, 'invalid_enum', `must be one of ${allowed.join(', ')}`);
+    }
+}
+/** Syntactic check matching the server: https, a host, no credentials, no spaces/backslashes, ≤ 2048 bytes. */
+function validUrl(raw, image) {
+    if (typeof raw !== 'string')
+        return false;
+    const s = raw.trim();
+    if (s === '' || (0, exports.byteLength)(s) > exports.LIMITS.urlBytes || CONTROL.test(s) || /[ \\]/.test(s))
+        return false;
+    if (!/^https:\/\//i.test(s))
+        return false;
+    if (image && s.includes('#'))
+        return false;
+    const rest = s.slice('https://'.length);
+    const authority = rest.split(/[/?#]/, 1)[0] ?? '';
+    if (authority === '' || authority.includes('@'))
+        return false;
+    let host = authority;
+    let port = '';
+    if (authority.startsWith('[')) {
+        const end = authority.indexOf(']');
+        if (end < 0)
+            return false;
+        host = authority.slice(0, end + 1);
+        const after = authority.slice(end + 1);
+        if (after !== '' && !after.startsWith(':'))
+            return false;
+        port = after.slice(1);
+    }
+    else {
+        const i = authority.lastIndexOf(':');
+        if (i >= 0) {
+            host = authority.slice(0, i);
+            port = authority.slice(i + 1);
+        }
+    }
+    if (host === '' || host === '[]')
+        return false;
+    if (port !== '' && (!/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535))
+        return false;
+    return true;
+}

package/dist/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// Generated from package.json by scripts/build.mjs on every build. Do not edit: change
+// "version" in package.json instead.
+exports.VERSION = '0.1.0';

package/dist/esm/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/esm/client.js

@@ -0,0 +1,329 @@
+import { HonkAuthError, HonkConflictError, HonkError, HonkNetworkError, HonkQuotaError, HonkServerError, HonkTimeoutError, HonkValidationError, } from './errors.js';
+import { uuidv7 } from './uuid.js';
+import { buildBody, checkIdempotencyKey } from './validate.js';
+import { VERSION } from './version.js';
+export { 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. */
+export 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' });
+ * ```
+ */
+export 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}${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(buildBody(message, this.defaults, this.validate));
+        const idempotencyKey = options.idempotencyKey === undefined ? await uuidv7() : 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 HonkQuotaError || failure instanceof HonkServerError))
+                    throw failure;
+            }
+            catch (err) {
+                if (err instanceof HonkError && !(err instanceof HonkQuotaError || err instanceof HonkServerError))
+                    throw err;
+                if (signal?.aborted)
+                    throw signal.reason;
+                failure = err instanceof 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);
+        }
+    }
+}
+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 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 HonkValidationError(list ? `${label} (${list})` : label, { ...init, fields });
+    }
+    if (s === 401 || s === 403)
+        return new HonkAuthError(label, init);
+    if (s === 409)
+        return new HonkConflictError(label, init);
+    if (s === 429)
+        return new HonkQuotaError(label, init);
+    if (s >= 500)
+        return new HonkServerError(label, init);
+    if (s >= 300 && s < 400) {
+        const to = res.headers.get('location');
+        return new HonkError(`Honk answered ${s} redirect${to ? ` to ${to}` : ''}; set url to the final https address`, init);
+    }
+    if (s === 404)
+        return new HonkError(`${label} (is url the base address of your Honk server?)`, init);
+    return new HonkError(label, init);
+}
+function networkError(err, idempotencyKey, attempts) {
+    if (err instanceof TimeoutSignalError) {
+        return new 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 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;
+}