honk-me 0.1.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,84 @@
+export type ErrorKind = 'validation' | 'auth' | 'quota' | 'conflict' | 'network' | 'timeout' | 'server' | 'http';
+/** One invalid field, as reported by the server (`error.fields[]`) or by local validation. */
+export interface FieldError {
+    /** Wire name, e.g. `group_key`, `metadata.region`, `Idempotency-Key`, `body`. */
+    field: string;
+    /** `required`, `too_long`, `too_short`, `invalid_enum`, `invalid_format`, `out_of_range`, `not_allowed`, `requires_group_key`, … */
+    code: string;
+    message?: string;
+}
+export interface HonkErrorInit {
+    status?: number;
+    code?: string;
+    requestId?: string;
+    idempotencyKey?: string;
+    attempts?: number;
+    retryAfter?: number;
+    fields?: FieldError[];
+    body?: unknown;
+    cause?: unknown;
+}
+/**
+ * Base class of every error thrown by `send()`. Check `kind` (or `instanceof`) to decide what to do:
+ * `retryable` errors can be retried later with the same `idempotencyKey` without creating duplicates.
+ */
+export declare class HonkError extends Error {
+    readonly kind: ErrorKind;
+    /** HTTP status, when the server answered. */
+    readonly status?: number;
+    /** API error code (`invalid_key`, `quota_exceeded`, …) or `network_error` / `timeout`. */
+    readonly code?: string;
+    /** Server request id (`req_…`), useful in bug reports. */
+    readonly requestId?: string;
+    /** The Idempotency-Key that was used. Retry later with the same key to stay duplicate-free. */
+    readonly idempotencyKey?: string;
+    /** Number of HTTP attempts made (0 when the message was rejected locally). */
+    readonly attempts: number;
+    /** Seconds the server asked to wait (`Retry-After`), when present. */
+    readonly retryAfter?: number;
+    /** Parsed error body, when the server answered with JSON. */
+    readonly body?: unknown;
+    constructor(message: string, init?: HonkErrorInit);
+    /** True when sending the same event again later (same idempotency key) may succeed. */
+    get retryable(): boolean;
+}
+/** The message is invalid: rejected locally before sending, or by the server (400, 413, 415, 422). Fix the message. */
+export declare class HonkValidationError extends HonkError {
+    readonly kind: 'validation';
+    readonly fields: FieldError[];
+    /** True when the SDK rejected the message before any request was made. */
+    readonly local: boolean;
+    constructor(message: string, init?: HonkErrorInit & {
+        local?: boolean;
+    });
+}
+/** 401/403: invalid or revoked key, `priority_not_allowed` (urgent without allow_urgent), suspended project/workspace. */
+export declare class HonkAuthError extends HonkError {
+    readonly kind: 'auth';
+    constructor(message: string, init?: HonkErrorInit);
+}
+/** 429: `quota_exceeded` (daily messages_per_day, until UTC midnight) or `rate_limited`, after retries. See `retryAfter`. */
+export declare class HonkQuotaError extends HonkError {
+    readonly kind: 'quota';
+    constructor(message: string, init?: HonkErrorInit);
+}
+/** 409 `idempotency_conflict`: this idempotency key was already used with a different payload in the last 24 h. */
+export declare class HonkConflictError extends HonkError {
+    readonly kind: 'conflict';
+    constructor(message: string, init?: HonkErrorInit);
+}
+/** The server could not be reached (or the connection broke) on every attempt until the deadline. */
+export declare class HonkNetworkError extends HonkError {
+    readonly kind: 'network' | 'timeout';
+    constructor(message: string, init?: HonkErrorInit);
+}
+/** An attempt timed out and no later attempt succeeded before the deadline. The event may or may not have been stored. */
+export declare class HonkTimeoutError extends HonkNetworkError {
+    readonly kind: 'timeout';
+    constructor(message: string, init?: HonkErrorInit);
+}
+/** 5xx on every attempt until the deadline (e.g. `503 unavailable`). */
+export declare class HonkServerError extends HonkError {
+    readonly kind: 'server';
+    constructor(message: string, init?: HonkErrorInit);
+}

package/dist/esm/errors.js

@@ -0,0 +1,97 @@
+/**
+ * Base class of every error thrown by `send()`. Check `kind` (or `instanceof`) to decide what to do:
+ * `retryable` errors can be retried later with the same `idempotencyKey` without creating duplicates.
+ */
+export class HonkError extends Error {
+    kind = 'http';
+    /** HTTP status, when the server answered. */
+    status;
+    /** API error code (`invalid_key`, `quota_exceeded`, …) or `network_error` / `timeout`. */
+    code;
+    /** Server request id (`req_…`), useful in bug reports. */
+    requestId;
+    /** The Idempotency-Key that was used. Retry later with the same key to stay duplicate-free. */
+    idempotencyKey;
+    /** Number of HTTP attempts made (0 when the message was rejected locally). */
+    attempts;
+    /** Seconds the server asked to wait (`Retry-After`), when present. */
+    retryAfter;
+    /** Parsed error body, when the server answered with JSON. */
+    body;
+    constructor(message, init = {}) {
+        super(message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = 'HonkError';
+        this.status = init.status;
+        this.code = init.code;
+        this.requestId = init.requestId;
+        this.idempotencyKey = init.idempotencyKey;
+        this.attempts = init.attempts ?? 0;
+        this.retryAfter = init.retryAfter;
+        this.body = init.body;
+    }
+    /** True when sending the same event again later (same idempotency key) may succeed. */
+    get retryable() {
+        return this.kind === 'network' || this.kind === 'timeout' || this.kind === 'server' || this.kind === 'quota';
+    }
+}
+/** The message is invalid: rejected locally before sending, or by the server (400, 413, 415, 422). Fix the message. */
+export class HonkValidationError extends HonkError {
+    kind = 'validation';
+    fields;
+    /** True when the SDK rejected the message before any request was made. */
+    local;
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkValidationError';
+        this.fields = init.fields ?? [];
+        this.local = init.local ?? false;
+    }
+}
+/** 401/403: invalid or revoked key, `priority_not_allowed` (urgent without allow_urgent), suspended project/workspace. */
+export class HonkAuthError extends HonkError {
+    kind = 'auth';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkAuthError';
+    }
+}
+/** 429: `quota_exceeded` (daily messages_per_day, until UTC midnight) or `rate_limited`, after retries. See `retryAfter`. */
+export class HonkQuotaError extends HonkError {
+    kind = 'quota';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkQuotaError';
+    }
+}
+/** 409 `idempotency_conflict`: this idempotency key was already used with a different payload in the last 24 h. */
+export class HonkConflictError extends HonkError {
+    kind = 'conflict';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkConflictError';
+    }
+}
+/** The server could not be reached (or the connection broke) on every attempt until the deadline. */
+export class HonkNetworkError extends HonkError {
+    kind = 'network';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkNetworkError';
+    }
+}
+/** An attempt timed out and no later attempt succeeded before the deadline. The event may or may not have been stored. */
+export class HonkTimeoutError extends HonkNetworkError {
+    kind = 'timeout';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkTimeoutError';
+    }
+}
+/** 5xx on every attempt until the deadline (e.g. `503 unavailable`). */
+export class HonkServerError extends HonkError {
+    kind = 'server';
+    constructor(message, init = {}) {
+        super(message, init);
+        this.name = 'HonkServerError';
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export { Honk, VERSION, parseRetryAfter } from './client.js';
+export { HonkError, HonkValidationError, HonkAuthError, HonkQuotaError, HonkConflictError, HonkNetworkError, HonkTimeoutError, HonkServerError, type ErrorKind, type FieldError, } from './errors.js';
+export { buildBody, LIMITS } from './validate.js';
+export { uuidv7 } from './uuid.js';
+export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, type SeverityAlias, type SeverityInput, type Priority, type EventType, type Category, type MetadataValue, type Message, type Defaults, type HonkOptions, type SendOptions, type HelperOptions, type SendResult, } from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { Honk, VERSION, parseRetryAfter } from './client.js';
+export { HonkError, HonkValidationError, HonkAuthError, HonkQuotaError, HonkConflictError, HonkNetworkError, HonkTimeoutError, HonkServerError, } from './errors.js';
+export { buildBody, LIMITS } from './validate.js';
+export { uuidv7 } from './uuid.js';
+export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, } from './types.js';

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/dist/esm/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Canonical severity, lowest to highest. `error` and `critical` raise the effective priority to
+ * at least `high`. Inputs also accept the horn aliases of the Honk scale ({@link SeverityAlias}).
+ */
+export type Severity = 'info' | 'success' | 'warning' | 'error' | 'critical';
+/** The Honk scale: light (info), beep (success), loud (warning), long (error), blast (critical). */
+export type SeverityAlias = 'light' | 'beep' | 'loud' | 'long' | 'blast';
+/** Any accepted spelling of a severity: canonical or horn alias, lower, Capitalized or UPPER case. */
+export type SeverityInput = Severity | SeverityAlias | Capitalize<Severity | SeverityAlias> | Uppercase<Severity | SeverityAlias>;
+/**
+ * Severity constants. The horn names are aliases of the canonical values:
+ * `Severity.Loud === Severity.Warning === 'warning'`.
+ */
+export declare const Severity: {
+    readonly Light: 'info';
+    readonly Beep: 'success';
+    readonly Loud: 'warning';
+    readonly Long: 'error';
+    readonly Blast: 'critical';
+    readonly Info: 'info';
+    readonly Success: 'success';
+    readonly Warning: 'warning';
+    readonly Error: 'error';
+    readonly Critical: 'critical';
+};
+/** Horn alias → canonical severity. */
+export declare const SEVERITY_ALIASES: Readonly<Record<SeverityAlias, Severity>>;
+/**
+ * Returns the canonical severity for a canonical value or horn alias (case-insensitive), or
+ * undefined when it is neither: `normalizeSeverity('LOUD') === 'warning'`.
+ */
+export declare function normalizeSeverity(value: string): Severity | undefined;
+/** Declared priority. `urgent` needs an ingestion key with `allow_urgent`. */
+export type Priority = 'low' | 'normal' | 'high' | 'urgent';
+/** `problem` opens an incident for its group; `recovery` closes it (both need `groupKey`). */
+export type EventType = 'event' | 'problem' | 'recovery';
+/** Category taxonomy v1. */
+export type Category = 'infrastructure' | 'security' | 'backups' | 'deployments' | 'payments' | 'customers' | 'sales' | 'automation' | 'personal' | 'other';
+export declare const SEVERITIES: readonly Severity[];
+export declare const PRIORITIES: readonly Priority[];
+export declare const EVENT_TYPES: readonly EventType[];
+export declare const CATEGORIES: readonly Category[];
+export type MetadataValue = string | number | boolean;
+/**
+ * One event for `POST /v1/messages`. Only `message` is required. Fields are camelCase here and
+ * sent as the snake_case names of the API (`groupKey` → `group_key`). Empty optional strings
+ * and `null`/`undefined` are omitted.
+ */
+export interface Message {
+    /** Plain text, 1–8192 bytes of UTF-8. Line breaks and tabs are allowed. */
+    message: string;
+    /** ≤ 160 characters, one line. Defaults to the first line of `message`. */
+    title?: string | null;
+    /**
+     * Default `light` (info). Horn names or canonical values, case-insensitive: `light`/`info`,
+     * `beep`/`success`, `loud`/`warning`, `long`/`error`, `blast`/`critical`. Sent canonical.
+     */
+    severity?: SeverityInput | null;
+    /** Default `normal`. */
+    priority?: Priority | null;
+    category?: Category | null;
+    /** ≤ 64 characters. Default `api` (or the client's `defaults.source`). */
+    source?: string | null;
+    /** ≤ 32 characters. Default `default` (or the client's `defaults.environment`). */
+    environment?: string | null;
+    /** ≤ 64 characters. Default `general` (or the client's `defaults.channel`). */
+    channel?: string | null;
+    /**
+     * ≤ 128 characters. Messages with the same key (per environment, source and channel) form one
+     * group: one push, then calm updates. Use one key per customer request (`requests/<id>`), a
+     * shared key only for repeats of the same problem.
+     */
+    groupKey?: string | null;
+    /** Default `event`. `recovery` requires `groupKey`. */
+    eventType?: EventType | null;
+    /** When it happened at the source (informational). A Date or an RFC 3339 string. */
+    occurredAt?: Date | string | null;
+    /** HTTPS link shown as "Open link". No credentials. ≤ 2048 bytes. */
+    url?: string | null;
+    /** HTTPS image fetched by the server after ingestion. No credentials or fragment. ≤ 2048 bytes. */
+    imageUrl?: string | null;
+    /** ≤ 16 keys matching `[A-Za-z0-9_.-]{1,64}`; values are strings (≤ 512 chars), numbers or booleans. */
+    metadata?: Record<string, MetadataValue> | null;
+    /** Push lifetime, 60–86400 seconds. Default 3600. */
+    ttlSeconds?: number | null;
+    /** Monotonic counter per source stream (0 … 2^53-1) for problem/recovery ordering. Requires `groupKey`. */
+    sourceSequence?: number | null;
+}
+/** Values applied when a message leaves the field unset. */
+export interface Defaults {
+    source?: string | null;
+    environment?: string | null;
+    channel?: string | null;
+}
+export interface HonkOptions {
+    /** Base URL of your Honk server, e.g. `https://honk.example.com`. */
+    url: string;
+    /** Project ingestion key `honk_…`. Server-side only: never ship it to a browser. */
+    key: string;
+    /** Timeout of one HTTP attempt. Default 5000 ms. */
+    timeoutMs?: number;
+    /** Retries after the first attempt (network errors, 429 and 5xx only). Default 4. */
+    retries?: number;
+    /** Total time budget for `send()`, waits included. Default 30000 ms. */
+    deadlineMs?: number;
+    /** Applied to every message that does not set these fields. */
+    defaults?: Defaults;
+    /** Validate messages locally before sending. Default `true`. The server always validates. */
+    validate?: boolean;
+    /** Exponential backoff with full jitter: attempt n waits random(0, min(maxMs, baseMs·2ⁿ)). Default 500 / 8000 ms. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
+    };
+    /** Custom fetch (proxies, instrumentation). Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Appended to the User-Agent header. */
+    userAgent?: string;
+}
+export interface SendOptions {
+    /**
+     * Stable key for this event (1–128 printable ASCII characters), e.g. `request-4812`. Reused on
+     * every retry. Default: a new UUIDv7 per `send()` call.
+     */
+    idempotencyKey?: string;
+    /** Cancels the call (including retries and waits). */
+    signal?: AbortSignal;
+}
+/** Message fields and send options together, for the helper methods. */
+export type HelperOptions = Partial<Omit<Message, 'message' | 'title'>> & SendOptions;
+export interface SendResult {
+    /** Message id (`msg_…`). The original id when `duplicate` is true. */
+    id: string;
+    /** True when this idempotency key was already accepted with the same payload (within 24 h). */
+    duplicate: boolean;
+    /** When the server accepted the message (the first time, for a duplicate). */
+    receivedAt: Date;
+}

package/dist/esm/types.js

@@ -0,0 +1,49 @@
+/**
+ * Severity constants. The horn names are aliases of the canonical values:
+ * `Severity.Loud === Severity.Warning === 'warning'`.
+ */
+export const Severity = {
+    Light: 'info',
+    Beep: 'success',
+    Loud: 'warning',
+    Long: 'error',
+    Blast: 'critical',
+    Info: 'info',
+    Success: 'success',
+    Warning: 'warning',
+    Error: 'error',
+    Critical: 'critical',
+};
+/** Horn alias → canonical severity. */
+export const SEVERITY_ALIASES = {
+    light: 'info',
+    beep: 'success',
+    loud: 'warning',
+    long: 'error',
+    blast: 'critical',
+};
+/**
+ * Returns the canonical severity for a canonical value or horn alias (case-insensitive), or
+ * undefined when it is neither: `normalizeSeverity('LOUD') === 'warning'`.
+ */
+export function normalizeSeverity(value) {
+    const v = value.trim().toLowerCase();
+    if (SEVERITIES.includes(v))
+        return v;
+    return SEVERITY_ALIASES[v];
+}
+export const SEVERITIES = ['info', 'success', 'warning', 'error', 'critical'];
+export const PRIORITIES = ['low', 'normal', 'high', 'urgent'];
+export const EVENT_TYPES = ['event', 'problem', 'recovery'];
+export const CATEGORIES = [
+    'infrastructure',
+    'security',
+    'backups',
+    'deployments',
+    'payments',
+    'customers',
+    'sales',
+    'automation',
+    'personal',
+    'other',
+];

package/dist/esm/uuid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a new UUIDv7 (RFC 9562): 48-bit Unix milliseconds, then 74 random bits. Time-ordered
+ * and unique, so it doubles as an idempotency key you can store before sending.
+ */
+export declare function uuidv7(now?: number): Promise<string>;

package/dist/esm/uuid.js

@@ -0,0 +1,37 @@
+let nodeRandomFill;
+async function randomBytes(n) {
+    const buf = new Uint8Array(n);
+    const webCrypto = globalThis.crypto;
+    if (webCrypto?.getRandomValues) {
+        webCrypto.getRandomValues(buf);
+        return buf;
+    }
+    // Node 18 has no global `crypto` unless --experimental-global-webcrypto is set.
+    if (!nodeRandomFill) {
+        const nodeCrypto = await import('node:crypto');
+        nodeRandomFill = (b) => nodeCrypto.randomFillSync(b);
+    }
+    nodeRandomFill(buf);
+    return buf;
+}
+/**
+ * Returns a new UUIDv7 (RFC 9562): 48-bit Unix milliseconds, then 74 random bits. Time-ordered
+ * and unique, so it doubles as an idempotency key you can store before sending.
+ */
+export async function uuidv7(now = Date.now()) {
+    const b = await randomBytes(16);
+    const ms = Math.max(0, Math.floor(now));
+    // 48-bit big-endian timestamp (split to stay within safe integer bit operations).
+    const hi = Math.floor(ms / 2 ** 16);
+    const lo = ms % 2 ** 16;
+    b[0] = (hi >>> 24) & 0xff;
+    b[1] = (hi >>> 16) & 0xff;
+    b[2] = (hi >>> 8) & 0xff;
+    b[3] = hi & 0xff;
+    b[4] = (lo >>> 8) & 0xff;
+    b[5] = lo & 0xff;
+    b[6] = (b[6] & 0x0f) | 0x70; // version 7
+    b[8] = (b[8] & 0x3f) | 0x80; // variant 10
+    const hex = Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/dist/esm/validate.d.ts

@@ -0,0 +1,28 @@
+import { type Defaults, type Message } from './types.js';
+/** Limits from contracts/openapi.yaml (and the server's validator). */
+export declare const LIMITS: {
+    readonly bodyBytes: number;
+    readonly messageBytes: 8192;
+    readonly title: 160;
+    readonly source: 64;
+    readonly environment: 32;
+    readonly channel: 64;
+    readonly groupKey: 128;
+    readonly urlBytes: 2048;
+    readonly metadataKeys: 16;
+    readonly metadataValue: 512;
+    readonly ttlMin: 60;
+    readonly ttlMax: 86400;
+    readonly idempotencyKey: 128;
+};
+export declare const byteLength: (s: string) => number;
+/** Checks an Idempotency-Key: 1–128 printable ASCII characters (0x21–0x7E). */
+export declare function checkIdempotencyKey(key: unknown): string;
+/**
+ * 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.
+ */
+export declare function buildBody(input: Message, defaults?: Defaults, validate?: boolean): Record<string, unknown>;
+/** Syntactic check matching the server: https, a host, no credentials, no spaces/backslashes, ≤ 2048 bytes. */
+export declare function validUrl(raw: unknown, image: boolean): boolean;