@hivemagnus/hive-common 0.0.0-stage → 0.2.0

package/dist/errors/index.js

@@ -0,0 +1,309 @@
+export { isErrorEnvelope } from '../contracts/index.js';
+/** Default code and message for each status this package produces or parses. */
+const STATUS_DEFAULTS = {
+    400: ['bad_request', 'The request is not valid'],
+    401: ['unauthorized', 'Authentication is required'],
+    403: ['forbidden', 'This action is not allowed'],
+    404: ['not_found', 'The resource was not found'],
+    405: ['method_not_allowed', 'The method is not allowed'],
+    406: ['not_acceptable', 'The requested representation is not available'],
+    408: ['request_timeout', 'The request took too long'],
+    409: ['conflict', 'The request conflicts with the current state'],
+    410: ['gone', 'The resource is no longer available'],
+    412: ['precondition_failed', 'A precondition failed'],
+    413: ['too_large', 'The request is too large'],
+    415: ['unsupported_media_type', 'The media type is not supported'],
+    422: ['invalid_request', 'The request could not be processed'],
+    428: ['precondition_required', 'A precondition is required'],
+    429: ['rate_limited', 'Too many requests'],
+    500: ['internal', 'An internal error occurred'],
+    501: ['not_implemented', 'This is not implemented'],
+    502: ['bad_gateway', 'An upstream service failed'],
+    503: ['unavailable', 'The service is unavailable'],
+    504: ['gateway_timeout', 'An upstream service timed out'],
+};
+/** The default code for an HTTP status, for example `not_found` for 404. */
+export function defaultCodeForStatus(status) {
+    return STATUS_DEFAULTS[status]?.[0] ?? (status >= 500 ? 'internal' : 'bad_request');
+}
+/** The default message for an HTTP status. */
+export function defaultMessageForStatus(status) {
+    return STATUS_DEFAULTS[status]?.[1] ?? (status >= 500 ? 'An internal error occurred' : 'The request failed');
+}
+const HIVE_ERROR_BRAND = Symbol.for('@hivemagnus/hive-common/HiveError');
+/** An error that knows its HTTP status, stable code and safe message. */
+export class HiveError extends Error {
+    name = 'HiveError';
+    code;
+    status;
+    details;
+    requestId;
+    headers;
+    /** Set by `parseHiveError()`: the legacy body shape it recognised. */
+    shape;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        const status = options.status ?? 500;
+        if (!Number.isInteger(status) || status < 400 || status > 599)
+            throw new RangeError('HiveError status must be 400-599');
+        this.code = code;
+        this.status = status;
+        this.details = options.details;
+        this.requestId = options.requestId;
+        this.headers = options.headers;
+        this.shape = options.shape;
+        Object.defineProperty(this, HIVE_ERROR_BRAND, { value: true });
+    }
+    /** True when `error` is a HiveError with this code (case-insensitive), across package copies. */
+    static is(error, code) {
+        if (!isHiveError(error))
+            return false;
+        return code === undefined || error.code.toLowerCase() === code.toLowerCase();
+    }
+    toJSON() {
+        return errorEnvelope(this.code, this.message, {
+            ...(this.requestId ? { requestId: this.requestId } : {}),
+            ...(this.details ? { details: this.details } : {}),
+        });
+    }
+    static badRequest(message = defaultMessageForStatus(400), details) {
+        return new HiveError('bad_request', message, { status: 400, ...(details ? { details } : {}) });
+    }
+    static validation(message, issues) {
+        return new HiveError('validation_failed', message, { status: 422, details: { issues } });
+    }
+    static unauthorized(message = defaultMessageForStatus(401)) {
+        return new HiveError('unauthorized', message, { status: 401, headers: { 'www-authenticate': 'Bearer' } });
+    }
+    static forbidden(message = defaultMessageForStatus(403)) {
+        return new HiveError('forbidden', message, { status: 403 });
+    }
+    static notFound(message = defaultMessageForStatus(404)) {
+        return new HiveError('not_found', message, { status: 404 });
+    }
+    static conflict(message = defaultMessageForStatus(409), details) {
+        return new HiveError('conflict', message, { status: 409, ...(details ? { details } : {}) });
+    }
+    static rateLimited(retryAfterSeconds) {
+        return new HiveError('rate_limited', defaultMessageForStatus(429), {
+            status: 429,
+            ...(retryAfterSeconds !== undefined ? { headers: { 'retry-after': String(Math.max(0, Math.ceil(retryAfterSeconds))) } } : {}),
+        });
+    }
+    static unavailable(message = defaultMessageForStatus(503)) {
+        return new HiveError('unavailable', message, { status: 503 });
+    }
+    static internal(message = defaultMessageForStatus(500), cause) {
+        return new HiveError('internal', message, { status: 500, ...(cause !== undefined ? { cause } : {}) });
+    }
+}
+/** True for any HiveError, including one created by another copy of this package. */
+export function isHiveError(value) {
+    return value instanceof HiveError
+        || (value instanceof Error && value[HIVE_ERROR_BRAND] === true);
+}
+/** Build `{ error: { code, message, requestId?, details? } }`. */
+export function errorEnvelope(code, message, extra = {}) {
+    const error = { code, message };
+    if (extra.requestId)
+        error.requestId = extra.requestId;
+    if (extra.details && Object.keys(extra.details).length)
+        error.details = extra.details;
+    return { error };
+}
+/**
+ * Turn any thrown value into a status, envelope body and headers. A HiveError keeps its code,
+ * message and details; anything else becomes a generic `internal` 500, so internal messages
+ * and stack traces never reach a client.
+ */
+export function toErrorResponse(error, options = {}) {
+    let hive;
+    if (isHiveError(error))
+        hive = error;
+    else {
+        options.onUnexpected?.(error);
+        hive = HiveError.internal();
+    }
+    const requestId = options.requestId ?? hive.requestId;
+    return {
+        status: hive.status,
+        body: errorEnvelope(hive.code, hive.message, { requestId, details: hive.details }),
+        headers: {
+            ...lowercaseKeys(hive.headers),
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            ...(requestId ? { 'x-request-id': requestId } : {}),
+        },
+    };
+}
+function lowercaseKeys(headers) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers ?? {}))
+        result[key.toLowerCase()] = value;
+    return result;
+}
+// ---------------------------------------------------------------------------------------
+// Parsing
+const MAX_MESSAGE = 1000;
+const MAX_CODE = 128;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Collapse whitespace, drop control characters and bound the length of remote text. */
+function cleanText(value, max = MAX_MESSAGE) {
+    // eslint-disable-next-line no-control-regex
+    const cleaned = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+}
+/** A remote code is kept as sent (products compare against their own codes), but bounded and safe. */
+function cleanCode(value) {
+    const cleaned = value.trim().replace(/[^A-Za-z0-9_.:-]+/g, '_').replace(/^_+|_+$/g, '').slice(0, MAX_CODE);
+    return cleaned || undefined;
+}
+/** A single token with no spaces is a code (`UNAUTHORIZED`, `invalid_grant`); prose is a message. */
+function looksLikeCode(value) {
+    return /^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(value.trim());
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function validStatus(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 400 && value <= 599;
+}
+function stringField(record, ...keys) {
+    for (const key of keys)
+        if (nonEmptyString(record[key]))
+            return record[key];
+    return undefined;
+}
+function fastApiIssues(detail) {
+    const issues = detail.slice(0, 50).map(item => {
+        if (!isRecord(item))
+            return { path: '$', message: typeof item === 'string' ? cleanText(item, 300) : 'Invalid value' };
+        const loc = Array.isArray(item['loc']) ? item['loc'].filter(part => typeof part === 'string' || typeof part === 'number') : [];
+        const path = loc.length ? loc.join('.') : '$';
+        const message = nonEmptyString(item['msg']) ? cleanText(item['msg'], 300) : 'Invalid value';
+        return { path: cleanText(path, 200), message, ...(nonEmptyString(item['type']) ? { type: cleanText(item['type'], 100) } : {}) };
+    });
+    const first = issues[0];
+    const message = first ? `${first.path}: ${first.message}${issues.length > 1 ? ` (and ${issues.length - 1} more)` : ''}` : 'The request is not valid';
+    return { message: cleanText(message), issues };
+}
+function parseObject(body) {
+    const error = body['error'];
+    // {error:{code,message,...}} and Magnus {success:false,error:{...}}
+    if (isRecord(error)) {
+        const details = isRecord(error['details']) ? error['details'] : undefined;
+        return {
+            shape: body['success'] === false ? 'magnus' : 'envelope',
+            code: stringField(error, 'code', 'type'),
+            message: stringField(error, 'message', 'detail'),
+            requestId: stringField(error, 'requestId', 'request_id') ?? stringField(body, 'requestId', 'request_id'),
+            details: details ?? (error['details'] !== undefined ? { value: error['details'] } : undefined),
+        };
+    }
+    if (nonEmptyString(error)) {
+        // OAuth 2.0: {error, error_description?, error_uri?}
+        if (nonEmptyString(body['error_description'])) {
+            return { shape: 'oauth', code: error, message: body['error_description'] };
+        }
+        if (looksLikeCode(error)) {
+            // Oathweave {error:CODE, message}; Embermend {error:CODE}; bare OAuth {error:"invalid_grant"}
+            if (nonEmptyString(body['message']))
+                return { shape: 'oathweave', code: error, message: body['message'], requestId: stringField(body, 'requestId') };
+            return { shape: 'code', code: error };
+        }
+        // Emberpath, HiveSkills, Cindertrace: {error:"human text"}
+        return { shape: 'string', message: error, requestId: stringField(body, 'requestId', 'request_id') };
+    }
+    // HiveMem / FastAPI
+    const detail = body['detail'];
+    if (nonEmptyString(detail))
+        return { shape: 'fastapi', message: detail };
+    if (Array.isArray(detail)) {
+        const { message, issues } = fastApiIssues(detail);
+        return { shape: 'fastapi-validation', code: 'validation_failed', message, details: { issues } };
+    }
+    if (isRecord(detail)) {
+        return { shape: 'fastapi', code: stringField(detail, 'code', 'error'), message: stringField(detail, 'message', 'msg', 'detail') };
+    }
+    // Mattermost: {id, message, detailed_error, request_id, status_code}
+    if (nonEmptyString(body['id']) && nonEmptyString(body['message']) && ('status_code' in body || 'request_id' in body)) {
+        return {
+            shape: 'mattermost',
+            code: body['id'],
+            message: body['message'],
+            requestId: stringField(body, 'request_id'),
+            status: validStatus(body['status_code']) ? body['status_code'] : undefined,
+        };
+    }
+    if (nonEmptyString(body['message'])) {
+        return { shape: 'message', code: stringField(body, 'code'), message: body['message'], requestId: stringField(body, 'requestId', 'request_id') };
+    }
+    return { shape: 'unknown', code: stringField(body, 'code') };
+}
+function looksLikeHtml(value) {
+    return /^\s*<(?:!doctype|html|head|body|\?xml)\b/i.test(value);
+}
+function parseBody(body) {
+    if (body === undefined || body === null)
+        return { shape: 'empty' };
+    if (typeof body === 'string' || body instanceof Uint8Array || body instanceof ArrayBuffer) {
+        const textBody = typeof body === 'string' ? body : new TextDecoder().decode(body);
+        if (!textBody.trim())
+            return { shape: 'empty' };
+        try {
+            const json = JSON.parse(textBody);
+            if (isRecord(json))
+                return parseObject(json);
+            if (typeof json === 'string' && json.trim())
+                return { shape: 'text', message: json };
+            return { shape: 'unknown' };
+        }
+        catch {
+            // HTML error pages from proxies carry nothing useful and may carry internals.
+            return looksLikeHtml(textBody) ? { shape: 'text' } : { shape: 'text', message: textBody };
+        }
+    }
+    if (isRecord(body))
+        return parseObject(body);
+    return { shape: 'unknown' };
+}
+/**
+ * Normalise any suite error response into a HiveError. `body` may be the raw text, bytes or
+ * already-parsed JSON. Recognises every legacy shape in the suite (see `HiveErrorShape`); the
+ * remote code is kept as sent and the recognised shape is on `error.shape`.
+ *
+ * `status` is the HTTP status. When it is not 400-599, a Mattermost `status_code` is used,
+ * otherwise 502: a non-error status with an error body means the upstream misbehaved.
+ */
+export function parseHiveError(status, body, options = {}) {
+    const parsed = parseBody(body);
+    const effectiveStatus = validStatus(status) ? status : parsed.status ?? 502;
+    const code = (parsed.code !== undefined ? cleanCode(parsed.code) : undefined) ?? defaultCodeForStatus(effectiveStatus);
+    const message = parsed.message !== undefined && cleanText(parsed.message) ? cleanText(parsed.message) : defaultMessageForStatus(effectiveStatus);
+    const requestId = parsed.requestId !== undefined ? cleanText(parsed.requestId, 128) : options.requestId;
+    return new HiveError(code, message, {
+        status: effectiveStatus,
+        shape: parsed.shape,
+        ...(parsed.details ? { details: parsed.details } : {}),
+        ...(requestId ? { requestId } : {}),
+        ...(options.headers ? { headers: options.headers } : {}),
+    });
+}
+/** Read a fetch `Response` and normalise it with `parseHiveError()`. Never throws on a bad body. */
+export async function parseHiveErrorResponse(response) {
+    let body = '';
+    try {
+        body = await response.text();
+    }
+    catch {
+        body = '';
+    }
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    const retryAfter = response.headers.get('retry-after');
+    return parseHiveError(response.status, body, {
+        ...(requestId ? { requestId } : {}),
+        ...(retryAfter ? { headers: { 'retry-after': retryAfter } } : {}),
+    });
+}

package/dist/events/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * HiveEvent feeds and the ChatterMost notifier. The HiveEvent schema and validator live in
+ * `/contracts` (isomorphic); this module re-exports them.
+ */
+import { type HiveEvent, type Page } from '../contracts/index.js';
+export { HIVE_EVENT_LIMITS, HIVE_EVENT_SEVERITIES, HIVE_EVENT_VERSION, isHiveEvent, validateHiveEvent, validateHiveEventPage, type HiveEvent, type HiveEventSeverity, type Page, } from '../contracts/index.js';
+export declare const HIVE_EVENTS_PATH = "/v1/hive/events";
+export interface FeedQuery {
+    /** Opaque cursor from a previous page's `nextCursor`; undefined for the first page. */
+    readonly after: string | undefined;
+    readonly limit: number;
+}
+export interface FeedQueryOptions {
+    readonly defaultLimit?: number;
+    readonly maxLimit?: number;
+}
+/** Read `after` and `limit` from a query. Throws a 400 HiveError on malformed values. */
+export declare function parseFeedQuery(query: URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>, options?: FeedQueryOptions): FeedQuery;
+/**
+ * Build a feed page. Pass up to `limit + 1` items read after the cursor, in feed order; the
+ * extra item only tells whether there is a next page and is not returned.
+ */
+export declare function feedPage<T>(items: readonly T[], limit: number, cursorOf: (item: T) => string): Page<T>;
+/** Encode a cursor position as an opaque base64url string. Isomorphic. */
+export declare function encodeCursor(position: Readonly<Record<string, string | number>>): string;
+/** Decode a cursor from `encodeCursor()`. Throws a 400 HiveError when it was tampered with. */
+export declare function decodeCursor(cursor: string): Record<string, string | number>;
+/** Remembers which event IDs were delivered. Implement it over Redis or SQL to share across replicas. */
+export interface DedupeStore {
+    /** Atomically claim `key`. Resolve true if it was not claimed (and is now), false if it already was. */
+    claim(key: string, ttlMs: number): boolean | Promise<boolean>;
+    /** Release a claim after a failed delivery so the event can be sent again. */
+    release(key: string): void | Promise<void>;
+}
+/** An in-memory DedupeStore with TTL and a size bound. Per process only. */
+export declare class MemoryDedupeStore implements DedupeStore {
+    #private;
+    constructor(options?: {
+        readonly maxEntries?: number;
+        readonly now?: () => number;
+    });
+    claim(key: string, ttlMs: number): boolean;
+    release(key: string): void;
+    get size(): number;
+}
+export interface MattermostWebhookPayload {
+    readonly text: string;
+    readonly username?: string;
+    readonly icon_url?: string;
+    readonly channel?: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+}
+export interface ChatterMostNotifierOptions {
+    /** The incoming-webhook URL. It is a secret: it is never logged or included in errors. */
+    readonly webhookUrl: string;
+    /** Absolute console origin used to turn `link.path` into a clickable URL, e.g. `https://hive.example.com`. */
+    readonly linkBaseUrl?: string;
+    readonly username?: string;
+    readonly iconUrl?: string;
+    readonly channel?: string;
+    readonly fetch?: typeof fetch;
+    /** Per-attempt timeout. 5000 ms. */
+    readonly timeoutMs?: number;
+    /** Retries after the first attempt. 3. */
+    readonly retries?: number;
+    /** First backoff delay; doubles per retry with jitter. 500 ms. */
+    readonly backoffMs?: number;
+    readonly maxBackoffMs?: number;
+    readonly dedupe?: DedupeStore;
+    /** How long a delivered event ID is remembered. 24 hours. */
+    readonly dedupeTtlMs?: number;
+    /** Replace the default message formatting. */
+    readonly format?: (event: HiveEvent) => MattermostWebhookPayload;
+    /** Allow `http:` webhook URLs on loopback, for tests. */
+    readonly allowInsecureLoopback?: boolean;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly random?: () => number;
+}
+export type NotifyResult = {
+    readonly status: 'sent';
+    readonly attempts: number;
+} | {
+    readonly status: 'duplicate';
+    readonly attempts: 0;
+} | {
+    readonly status: 'failed';
+    readonly attempts: number;
+    readonly error: string;
+    readonly httpStatus?: number;
+};
+/** The default message: severity icon, product and title, summary, and a link. */
+export declare function formatChatterMostMessage(event: HiveEvent, options?: {
+    readonly linkBaseUrl?: string;
+}): string;
+/**
+ * Posts HiveEvents to a Mattermost-compatible incoming webhook (ChatterMost). One-way
+ * announcements only. Each event ID is delivered at most once per dedupe window; failures
+ * release the claim so a later call can retry.
+ */
+export declare class ChatterMostNotifier {
+    #private;
+    constructor(options: ChatterMostNotifierOptions);
+    /** The webhook body for an event. */
+    payload(event: HiveEvent): MattermostWebhookPayload;
+    /** Validate and deliver one event. Never throws for delivery failures; it reports them. */
+    notify(input: HiveEvent): Promise<NotifyResult>;
+}

package/dist/events/index.js

@@ -0,0 +1,232 @@
+/**
+ * HiveEvent feeds and the ChatterMost notifier. The HiveEvent schema and validator live in
+ * `/contracts` (isomorphic); this module re-exports them.
+ */
+import { validateHiveEvent, } from '../contracts/index.js';
+import { HiveError } from '../errors/index.js';
+import { endpointProblem } from '../oathweave/endpoint.js';
+import { redactText } from '../log/redact.js';
+export { HIVE_EVENT_LIMITS, HIVE_EVENT_SEVERITIES, HIVE_EVENT_VERSION, isHiveEvent, validateHiveEvent, validateHiveEventPage, } from '../contracts/index.js';
+// ---------------------------------------------------------------------------------------
+// Feed: GET /v1/hive/events?after=<cursor>&limit=<n>
+export const HIVE_EVENTS_PATH = '/v1/hive/events';
+/** Read `after` and `limit` from a query. Throws a 400 HiveError on malformed values. */
+export function parseFeedQuery(query, options = {}) {
+    const read = (name) => {
+        if (query instanceof URLSearchParams) {
+            const values = query.getAll(name);
+            if (values.length > 1)
+                throw new HiveError('invalid_query', `${name} must be given once`, { status: 400 });
+            return values[0];
+        }
+        const value = query[name];
+        if (Array.isArray(value)) {
+            if (value.length > 1)
+                throw new HiveError('invalid_query', `${name} must be given once`, { status: 400 });
+            return value[0];
+        }
+        return value;
+    };
+    const defaultLimit = options.defaultLimit ?? 50;
+    const maxLimit = options.maxLimit ?? 200;
+    const rawLimit = read('limit');
+    let limit = defaultLimit;
+    if (rawLimit !== undefined && rawLimit !== '') {
+        if (!/^\d{1,6}$/.test(rawLimit) || Number(rawLimit) < 1) {
+            throw new HiveError('invalid_query', `limit must be an integer from 1 to ${maxLimit}`, { status: 400 });
+        }
+        limit = Math.min(Number(rawLimit), maxLimit);
+    }
+    const after = read('after');
+    if (after !== undefined && after !== '' && !/^[A-Za-z0-9._~:-]{1,512}$/.test(after)) {
+        throw new HiveError('invalid_query', 'after must be a cursor from a previous page', { status: 400 });
+    }
+    return { after: after || undefined, limit };
+}
+/**
+ * Build a feed page. Pass up to `limit + 1` items read after the cursor, in feed order; the
+ * extra item only tells whether there is a next page and is not returned.
+ */
+export function feedPage(items, limit, cursorOf) {
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new RangeError('limit must be a positive integer');
+    const data = items.slice(0, limit);
+    const last = data.at(-1);
+    return { data, nextCursor: items.length > limit && last !== undefined ? cursorOf(last) : null };
+}
+/** Encode a cursor position as an opaque base64url string. Isomorphic. */
+export function encodeCursor(position) {
+    const bytes = new TextEncoder().encode(JSON.stringify(position));
+    let binary = '';
+    bytes.forEach(byte => { binary += String.fromCharCode(byte); });
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Decode a cursor from `encodeCursor()`. Throws a 400 HiveError when it was tampered with. */
+export function decodeCursor(cursor) {
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(cursor))
+            throw new Error('not base64url');
+        const binary = atob(cursor.replace(/-/g, '+').replace(/_/g, '/'));
+        const value = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, char => char.charCodeAt(0))));
+        if (!value || typeof value !== 'object' || Array.isArray(value)
+            || !Object.values(value).every(item => typeof item === 'string' || typeof item === 'number'))
+            throw new Error('not a position');
+        return value;
+    }
+    catch {
+        throw new HiveError('invalid_cursor', 'The cursor is not valid', { status: 400 });
+    }
+}
+/** An in-memory DedupeStore with TTL and a size bound. Per process only. */
+export class MemoryDedupeStore {
+    #entries = new Map();
+    #max;
+    #now;
+    constructor(options = {}) {
+        this.#max = options.maxEntries ?? 10_000;
+        this.#now = options.now ?? Date.now;
+    }
+    claim(key, ttlMs) {
+        const now = this.#now();
+        const expiresAt = this.#entries.get(key);
+        if (expiresAt !== undefined && expiresAt > now)
+            return false;
+        this.#entries.delete(key);
+        if (this.#entries.size >= this.#max) {
+            for (const [entry, expiry] of this.#entries)
+                if (expiry <= now)
+                    this.#entries.delete(entry);
+            while (this.#entries.size >= this.#max)
+                this.#entries.delete(this.#entries.keys().next().value);
+        }
+        this.#entries.set(key, now + ttlMs);
+        return true;
+    }
+    release(key) {
+        this.#entries.delete(key);
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}
+const SEVERITY_ICON = {
+    info: ':information_source:',
+    warning: ':warning:',
+    critical: ':rotating_light:',
+};
+/** Neutralise Markdown and mentions in event text so a product cannot ping a channel or forge links. */
+function escapeMarkdown(value) {
+    return value
+        .replace(/[\\`*_~[\]()#>|]/g, char => `\\${char}`)
+        .replace(/@(?=[A-Za-z0-9])/g, '@​')
+        .replace(/<!/g, '<​!');
+}
+/** The default message: severity icon, product and title, summary, and a link. */
+export function formatChatterMostMessage(event, options = {}) {
+    const title = `${SEVERITY_ICON[event.severity]} **${escapeMarkdown(event.product)}: ${escapeMarkdown(event.title)}**`;
+    const summary = event.summary ? `\n${escapeMarkdown(event.summary)}` : '';
+    let link = '';
+    if (options.linkBaseUrl) {
+        const url = new URL(event.link.path, options.linkBaseUrl);
+        link = `\n[Open in ${escapeMarkdown(event.link.product)}](${url.href.replace(/[()]/g, encodeURIComponent)})`;
+    }
+    else
+        link = `\n${escapeMarkdown(event.link.product)}: \`${event.link.path.replace(/`/g, '')}\``;
+    return `${title}${summary}${link}`.slice(0, 16_000);
+}
+function retryAfterMs(response) {
+    const value = response.headers.get('retry-after');
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+/**
+ * Posts HiveEvents to a Mattermost-compatible incoming webhook (ChatterMost). One-way
+ * announcements only. Each event ID is delivered at most once per dedupe window; failures
+ * release the claim so a later call can retry.
+ */
+export class ChatterMostNotifier {
+    #options;
+    #fetch;
+    #dedupe;
+    #sleep;
+    #random;
+    constructor(options) {
+        const problem = endpointProblem(options.webhookUrl, { allowInsecureLoopback: options.allowInsecureLoopback ?? false });
+        // The URL is a secret, so the error describes the problem without echoing it.
+        if (problem)
+            throw new TypeError(`ChatterMost webhookUrl ${problem}`);
+        if (options.linkBaseUrl !== undefined && endpointProblem(options.linkBaseUrl, { allowInsecureLoopback: true })) {
+            throw new TypeError('ChatterMost linkBaseUrl must be an https origin');
+        }
+        this.#options = options;
+        this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+        this.#dedupe = options.dedupe ?? new MemoryDedupeStore();
+        this.#sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+        this.#random = options.random ?? Math.random;
+    }
+    /** The webhook body for an event. */
+    payload(event) {
+        if (this.#options.format)
+            return this.#options.format(event);
+        return {
+            text: formatChatterMostMessage(event, this.#options.linkBaseUrl ? { linkBaseUrl: this.#options.linkBaseUrl } : {}),
+            ...(this.#options.username ? { username: this.#options.username } : {}),
+            ...(this.#options.iconUrl ? { icon_url: this.#options.iconUrl } : {}),
+            ...(this.#options.channel ? { channel: this.#options.channel } : {}),
+            props: { hive_event: { id: event.id, product: event.product, type: event.type, severity: event.severity } },
+        };
+    }
+    /** Validate and deliver one event. Never throws for delivery failures; it reports them. */
+    async notify(input) {
+        const validation = validateHiveEvent(input);
+        if (!validation.ok)
+            throw HiveError.validation('The event is not a valid HiveEvent', validation.issues);
+        const event = validation.value;
+        const key = `hive-event:${event.product}:${event.id}`;
+        if (!await this.#dedupe.claim(key, this.#options.dedupeTtlMs ?? 24 * 60 * 60_000))
+            return { status: 'duplicate', attempts: 0 };
+        const body = JSON.stringify(this.payload(event));
+        const retries = this.#options.retries ?? 3;
+        const base = this.#options.backoffMs ?? 500;
+        const max = this.#options.maxBackoffMs ?? 8_000;
+        let lastError = 'failed';
+        let lastStatus;
+        let attempts = 0;
+        for (let attempt = 1; attempt <= retries + 1; attempt++) {
+            attempts = attempt;
+            let wait;
+            try {
+                const response = await this.#fetch(this.#options.webhookUrl, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body,
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(this.#options.timeoutMs ?? 5_000),
+                });
+                void response.body?.cancel().catch(() => undefined);
+                if (response.ok)
+                    return { status: 'sent', attempts: attempt };
+                lastStatus = response.status;
+                lastError = `HTTP ${response.status}`;
+                // Other 4xx mean the request itself is wrong; repeating it cannot help.
+                if (response.status !== 408 && response.status !== 429 && response.status < 500)
+                    break;
+                wait = retryAfterMs(response);
+            }
+            catch (error) {
+                lastStatus = undefined;
+                lastError = error instanceof Error && error.name === 'TimeoutError' ? 'timeout' : 'network error';
+            }
+            if (attempt <= retries) {
+                const backoff = Math.min(max, base * 2 ** (attempt - 1));
+                await this.#sleep(Math.min(max, wait ?? Math.round(backoff * (0.5 + this.#random() / 2))));
+            }
+        }
+        await this.#dedupe.release(key);
+        return { status: 'failed', attempts, error: redactText(lastError), ...(lastStatus !== undefined ? { httpStatus: lastStatus } : {}) };
+    }
+}