@hivemagnus/hive-common 0.0.0-stage → 0.2.0

package/dist/context/index.js

@@ -0,0 +1,191 @@
+/**
+ * Request context: request IDs, W3C trace context, idempotency keys and an
+ * AsyncLocalStorage-scoped context that loggers and outbound clients read.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { HIVE_HEADERS } from '../contracts/index.js';
+import { HiveError } from '../errors/index.js';
+export { HIVE_HEADERS } from '../contracts/index.js';
+/** Read one header. A repeated header (array value) is treated as absent: it is ambiguous. */
+export function readHeader(headers, name) {
+    const lower = name.toLowerCase();
+    let value;
+    if (typeof headers === 'function')
+        value = headers(lower);
+    else if (typeof headers.get === 'function')
+        value = headers.get(lower);
+    else {
+        const record = headers;
+        value = record[lower];
+        if (value === undefined) {
+            const key = Object.keys(record).find(candidate => candidate.toLowerCase() === lower);
+            value = key === undefined ? undefined : record[key];
+        }
+    }
+    if (Array.isArray(value))
+        return value.length === 1 && typeof value[0] === 'string' ? value[0] : undefined;
+    return typeof value === 'string' ? value : undefined;
+}
+// ---------------------------------------------------------------------------------------
+// Request IDs
+/** Up to 128 printable characters that are safe in logs and headers. */
+export const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:@/+=-]{1,128}$/;
+export function isValidRequestId(value) {
+    return typeof value === 'string' && REQUEST_ID_PATTERN.test(value);
+}
+export function generateRequestId() {
+    return globalThis.crypto.randomUUID();
+}
+/**
+ * The inbound request ID: `x-request-id`, else `x-hive-request-id`, else `x-correlation-id`.
+ * An invalid value (too long, unsafe characters) is ignored rather than propagated.
+ */
+export function readRequestId(headers) {
+    for (const name of [HIVE_HEADERS.requestId, ...HIVE_HEADERS.requestIdAliases]) {
+        const value = readHeader(headers, name)?.trim();
+        if (isValidRequestId(value))
+            return value;
+    }
+    return undefined;
+}
+/** The inbound request ID, or a new one. */
+export function resolveRequestId(headers, generate = generateRequestId) {
+    return readRequestId(headers) ?? generate();
+}
+const HEX = /^[0-9a-f]+$/;
+const isZero = (value) => /^0+$/.test(value);
+/** Parse a `traceparent` header per W3C Trace Context. Returns undefined when it is invalid. */
+export function parseTraceparent(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const header = value.trim();
+    if (header.length < 55)
+        return undefined;
+    const version = header.slice(0, 2);
+    if (!HEX.test(version) || version === 'ff')
+        return undefined;
+    // Version 00 is exactly 55 characters; later versions may append fields after a dash.
+    if (version === '00' ? header.length !== 55 : header.length > 55 && header[55] !== '-')
+        return undefined;
+    const [, traceId, spanId, flags] = header.slice(0, 55).split('-');
+    if (header[2] !== '-' || header[35] !== '-' || header[52] !== '-')
+        return undefined;
+    if (!traceId || !spanId || !flags)
+        return undefined;
+    if (traceId.length !== 32 || !HEX.test(traceId) || isZero(traceId))
+        return undefined;
+    if (spanId.length !== 16 || !HEX.test(spanId) || isZero(spanId))
+        return undefined;
+    if (flags.length !== 2 || !HEX.test(flags))
+        return undefined;
+    return { version, traceId, spanId, flags, sampled: (Number.parseInt(flags, 16) & 1) === 1 };
+}
+export function isValidTraceparent(value) {
+    return parseTraceparent(value) !== undefined;
+}
+function randomHex(bytes) {
+    const buffer = new Uint8Array(bytes);
+    // A zero ID is invalid; regenerate in the vanishingly rare case it occurs.
+    do
+        globalThis.crypto.getRandomValues(buffer);
+    while (buffer.every(byte => byte === 0));
+    return Array.from(buffer, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+export function generateTraceId() {
+    return randomHex(16);
+}
+export function generateSpanId() {
+    return randomHex(8);
+}
+export function formatTraceparent(trace) {
+    const flags = trace.flags ?? (trace.sampled === false ? '00' : '01');
+    const header = `00-${trace.traceId}-${trace.spanId}-${flags}`;
+    if (!parseTraceparent(header))
+        throw new TypeError('Invalid trace context');
+    return header;
+}
+/** A new root trace context. */
+export function generateTraceparent(options = {}) {
+    const sampled = options.sampled ?? true;
+    return { version: '00', traceId: generateTraceId(), spanId: generateSpanId(), flags: sampled ? '01' : '00', sampled };
+}
+/** A child span: same trace and flags, new span ID, always version 00 on output. */
+export function childTraceparent(parent) {
+    return { version: '00', traceId: parent.traceId, spanId: generateSpanId(), flags: parent.flags, sampled: parent.sampled };
+}
+// ---------------------------------------------------------------------------------------
+// Idempotency keys
+/** 1-255 visible ASCII characters. */
+export const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7e]{1,255}$/;
+/**
+ * The `Idempotency-Key` header, also accepting `x-idempotency-key`. Returns undefined when
+ * neither is present. Throws a 400 HiveError when the value is malformed or the two headers
+ * disagree, because silently picking one could apply a write twice.
+ */
+export function readIdempotencyKey(headers) {
+    const values = [HIVE_HEADERS.idempotencyKey, ...HIVE_HEADERS.idempotencyKeyAliases]
+        .map(name => readHeader(headers, name))
+        .filter((value) => value !== undefined)
+        .map(value => value.trim());
+    if (!values.length)
+        return undefined;
+    const [first] = values;
+    if (values.some(value => value !== first)) {
+        throw new HiveError('invalid_idempotency_key', 'Idempotency-Key and X-Idempotency-Key disagree', { status: 400 });
+    }
+    if (!IDEMPOTENCY_KEY_PATTERN.test(first)) {
+        throw new HiveError('invalid_idempotency_key', 'Idempotency-Key must be 1-255 visible ASCII characters', { status: 400 });
+    }
+    return first;
+}
+/** Like `readIdempotencyKey()`, but a missing key is a 428 error. */
+export function requireIdempotencyKey(headers) {
+    const key = readIdempotencyKey(headers);
+    if (key === undefined)
+        throw new HiveError('idempotency_key_required', 'This request requires an Idempotency-Key header', { status: 428 });
+    return key;
+}
+export function createRequestContext(headers, options = {}) {
+    const trust = options.trustInbound ?? true;
+    const trustRequestId = options.trustInboundRequestId ?? trust;
+    const trustTrace = options.trustInboundTrace ?? trust;
+    const requestId = (trustRequestId ? readRequestId(headers) : undefined) ?? (options.generateRequestId ?? generateRequestId)();
+    const parentTrace = trustTrace ? parseTraceparent(readHeader(headers, HIVE_HEADERS.traceparent)) : undefined;
+    const rawState = parentTrace ? readHeader(headers, HIVE_HEADERS.tracestate)?.trim() : undefined;
+    // eslint-disable-next-line no-control-regex
+    const tracestate = rawState && rawState.length <= 512 && !/[\u0000-\u001f\u007f]/.test(rawState) ? rawState : undefined;
+    return {
+        requestId,
+        trace: parentTrace ? childTraceparent(parentTrace) : generateTraceparent(),
+        parentTrace,
+        tracestate,
+        startedAt: (options.now ?? Date.now)(),
+        bindings: {},
+    };
+}
+const storage = new AsyncLocalStorage();
+/** Run `fn` with `context` as the current request context. */
+export function runWithRequestContext(context, fn) {
+    return storage.run(context, fn);
+}
+/** The current request context, or undefined outside a request. */
+export function getRequestContext() {
+    return storage.getStore();
+}
+/** The current request ID, or undefined outside a request. */
+export function currentRequestId() {
+    return storage.getStore()?.requestId;
+}
+/**
+ * Headers to send to a peer service so it joins this request: `x-request-id`, `traceparent`
+ * (with this service's span as the parent) and `tracestate`. Empty outside a request.
+ */
+export function outboundHeaders(context = getRequestContext()) {
+    if (!context)
+        return {};
+    return {
+        [HIVE_HEADERS.requestId]: context.requestId,
+        [HIVE_HEADERS.traceparent]: formatTraceparent(context.trace),
+        ...(context.tracestate ? { [HIVE_HEADERS.tracestate]: context.tracestate } : {}),
+    };
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Isomorphic suite contracts: types and small, dependency-free validators.
+ *
+ * Nothing in this module may import a Node built-in, a framework or a runtime dependency,
+ * because the browser UI vendors it. Validators return a result instead of throwing so
+ * they can be used on untrusted input without try/catch.
+ */
+export type ValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+/** Header names used across the suite. Lowercase, as HTTP/2 and fetch normalise them. */
+export declare const HIVE_HEADERS: {
+    readonly requestId: "x-request-id";
+    /** Accepted on inbound requests for compatibility; never sent. */
+    readonly requestIdAliases: readonly ["x-hive-request-id", "x-correlation-id"];
+    readonly traceparent: "traceparent";
+    readonly tracestate: "tracestate";
+    readonly idempotencyKey: "idempotency-key";
+    /** Accepted on inbound requests for compatibility; never sent. */
+    readonly idempotencyKeyAliases: readonly ["x-idempotency-key"];
+};
+/** The body of every suite error response: `{ error: { code, message, requestId?, details? } }`. */
+export interface ErrorBody {
+    /** Stable, machine-readable code such as `not_found` or `invalid_token`. */
+    readonly code: string;
+    /** Human-readable message. Never contains secrets or internal stack traces. */
+    readonly message: string;
+    readonly requestId?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface ErrorEnvelope {
+    readonly error: ErrorBody;
+}
+export declare function isErrorEnvelope(value: unknown): value is ErrorEnvelope;
+/** A cursor-paginated list: `nextCursor` is null on the last page. */
+export interface Page<T> {
+    readonly data: readonly T[];
+    readonly nextCursor: string | null;
+}
+export declare function isPage(value: unknown): value is Page<unknown>;
+/** A suite identifier segment: node IDs, profile names and actor IDs. */
+export declare const IDENTIFIER_PATTERN: RegExp;
+/** `<nodeId>~<profile>`, both identifier segments. */
+export declare const AGENT_REF_PATTERN: RegExp;
+/** A product ID as the Hive Registry stores it. */
+export declare const PRODUCT_ID_PATTERN: RegExp;
+export interface AgentIdentity {
+    /** `<nodeId>~<profile>` */
+    readonly agentRef: string;
+    readonly actorId: string;
+}
+export declare function isIdentifier(value: unknown): value is string;
+export declare function isAgentRef(value: unknown): value is string;
+export declare function isProductId(value: unknown): value is string;
+export declare function parseAgentRef(value: string): {
+    readonly nodeId: string;
+    readonly profile: string;
+} | undefined;
+export declare function formatAgentRef(nodeId: string, profile: string): string;
+export declare function validateAgentIdentity(value: unknown): ValidationResult<AgentIdentity>;
+export declare const HIVE_EVENT_VERSION = 1;
+export declare const HIVE_EVENT_SEVERITIES: readonly ["info", "warning", "critical"];
+export type HiveEventSeverity = (typeof HIVE_EVENT_SEVERITIES)[number];
+/** HiveEvent v1: one notable thing that happened in a product, linking back to it. */
+export interface HiveEvent {
+    /** Globally unique and stable; consumers deduplicate on it. */
+    readonly id: string;
+    /** Product ID of the emitter, as the Hive Registry names it. */
+    readonly product: string;
+    /** Dotted, lowercase event type, for example `agent.task.failed`. */
+    readonly type: string;
+    readonly severity: HiveEventSeverity;
+    readonly title: string;
+    readonly summary: string;
+    /** RFC 3339 timestamp in UTC (`Z`). */
+    readonly occurredAt: string;
+    readonly subject?: {
+        readonly actorId?: string;
+        readonly agentRef?: string;
+        readonly nodeId?: string;
+    };
+    /** Where a person can see the event: a same-origin console path of a product. */
+    readonly link: {
+        readonly product: string;
+        readonly path: string;
+    };
+    /** The emitter's own reference to the record behind the event. */
+    readonly sourceRef?: string;
+}
+export declare const HIVE_EVENT_LIMITS: {
+    readonly id: 128;
+    readonly type: 100;
+    readonly title: 200;
+    readonly summary: 2000;
+    readonly path: 1024;
+    readonly sourceRef: 256;
+};
+/** True for an RFC 3339 UTC timestamp that names a real instant. */
+export declare function isRfc3339Utc(value: unknown): value is string;
+/** A same-origin path: starts with one `/`, no scheme, no backslash, no control characters. */
+export declare function isSameOriginPath(value: unknown): value is string;
+export interface HiveEventValidationOptions {
+    /** Reject unknown fields instead of dropping them. Producers should validate strictly. */
+    readonly strict?: boolean;
+}
+/**
+ * Validate a HiveEvent v1. The returned value is a fresh object holding only known fields,
+ * so a consumer never passes along data it did not validate.
+ */
+export declare function validateHiveEvent(value: unknown, options?: HiveEventValidationOptions): ValidationResult<HiveEvent>;
+export declare function isHiveEvent(value: unknown): value is HiveEvent;
+/** Validate a feed page of HiveEvents. Any invalid event fails the whole page. */
+export declare function validateHiveEventPage(value: unknown, options?: HiveEventValidationOptions): ValidationResult<Page<HiveEvent>>;

package/dist/contracts/index.js

@@ -0,0 +1,228 @@
+/**
+ * Isomorphic suite contracts: types and small, dependency-free validators.
+ *
+ * Nothing in this module may import a Node built-in, a framework or a runtime dependency,
+ * because the browser UI vendors it. Validators return a result instead of throwing so
+ * they can be used on untrusted input without try/catch.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------------------
+// Headers
+/** Header names used across the suite. Lowercase, as HTTP/2 and fetch normalise them. */
+export const HIVE_HEADERS = {
+    requestId: 'x-request-id',
+    /** Accepted on inbound requests for compatibility; never sent. */
+    requestIdAliases: ['x-hive-request-id', 'x-correlation-id'],
+    traceparent: 'traceparent',
+    tracestate: 'tracestate',
+    idempotencyKey: 'idempotency-key',
+    /** Accepted on inbound requests for compatibility; never sent. */
+    idempotencyKeyAliases: ['x-idempotency-key'],
+};
+export function isErrorEnvelope(value) {
+    if (!isRecord(value) || !isRecord(value['error']))
+        return false;
+    const error = value['error'];
+    return typeof error['code'] === 'string' && error['code'].length > 0
+        && typeof error['message'] === 'string'
+        && (error['requestId'] === undefined || typeof error['requestId'] === 'string')
+        && (error['details'] === undefined || isRecord(error['details']));
+}
+export function isPage(value) {
+    return isRecord(value) && Array.isArray(value['data'])
+        && (value['nextCursor'] === null || (typeof value['nextCursor'] === 'string' && value['nextCursor'].length > 0));
+}
+// ---------------------------------------------------------------------------------------
+// Identifiers
+/** A suite identifier segment: node IDs, profile names and actor IDs. */
+export const IDENTIFIER_PATTERN = /^[a-z0-9_-]{2,32}$/;
+/** `<nodeId>~<profile>`, both identifier segments. */
+export const AGENT_REF_PATTERN = /^([a-z0-9_-]{2,32})~([a-z0-9_-]{2,32})$/;
+/** A product ID as the Hive Registry stores it. */
+export const PRODUCT_ID_PATTERN = /^[a-z][a-z0-9-]{0,47}$/;
+export function isIdentifier(value) {
+    return typeof value === 'string' && IDENTIFIER_PATTERN.test(value);
+}
+export function isAgentRef(value) {
+    return typeof value === 'string' && AGENT_REF_PATTERN.test(value);
+}
+export function isProductId(value) {
+    return typeof value === 'string' && PRODUCT_ID_PATTERN.test(value);
+}
+export function parseAgentRef(value) {
+    const match = AGENT_REF_PATTERN.exec(value);
+    return match ? { nodeId: match[1], profile: match[2] } : undefined;
+}
+export function formatAgentRef(nodeId, profile) {
+    if (!isIdentifier(nodeId) || !isIdentifier(profile))
+        throw new TypeError('nodeId and profile must match [a-z0-9_-]{2,32}');
+    return `${nodeId}~${profile}`;
+}
+export function validateAgentIdentity(value) {
+    if (!isRecord(value))
+        return { ok: false, issues: ['$: expected an object'] };
+    const issues = [];
+    if (!isAgentRef(value['agentRef']))
+        issues.push('agentRef: expected <nodeId>~<profile> matching [a-z0-9_-]{2,32}');
+    if (!isIdentifier(value['actorId']))
+        issues.push('actorId: expected [a-z0-9_-]{2,32}');
+    return issues.length ? { ok: false, issues } : { ok: true, value: { agentRef: value['agentRef'], actorId: value['actorId'] } };
+}
+// ---------------------------------------------------------------------------------------
+// HiveEvent v1
+export const HIVE_EVENT_VERSION = 1;
+export const HIVE_EVENT_SEVERITIES = ['info', 'warning', 'critical'];
+export const HIVE_EVENT_LIMITS = {
+    id: 128,
+    type: 100,
+    title: 200,
+    summary: 2000,
+    path: 1024,
+    sourceRef: 256,
+};
+const EVENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const EVENT_TYPE_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
+const RFC3339_UTC = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?Z$/;
+// Control characters other than tab and newline never belong in display text.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+/** True for an RFC 3339 UTC timestamp that names a real instant. */
+export function isRfc3339Utc(value) {
+    if (typeof value !== 'string')
+        return false;
+    const match = RFC3339_UTC.exec(value);
+    if (!match)
+        return false;
+    const [, year, month, day, hour, minute, second] = match.map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+        && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second;
+}
+/** A same-origin path: starts with one `/`, no scheme, no backslash, no control characters. */
+export function isSameOriginPath(value) {
+    return typeof value === 'string' && value.length <= HIVE_EVENT_LIMITS.path && /^\/(?![/\\])/.test(value)
+        && !value.includes('\\') && !CONTROL_CHARACTERS.test(value) && !/\s/.test(value);
+}
+function text(value, field, min, max, issues) {
+    if (typeof value !== 'string') {
+        issues.push(`${field}: expected a string`);
+        return false;
+    }
+    if (value.length < min || value.length > max) {
+        issues.push(`${field}: expected ${min}-${max} characters`);
+        return false;
+    }
+    if (CONTROL_CHARACTERS.test(value)) {
+        issues.push(`${field}: must not contain control characters`);
+        return false;
+    }
+    return true;
+}
+const EVENT_FIELDS = new Set(['id', 'product', 'type', 'severity', 'title', 'summary', 'occurredAt', 'subject', 'link', 'sourceRef']);
+const SUBJECT_FIELDS = new Set(['actorId', 'agentRef', 'nodeId']);
+const LINK_FIELDS = new Set(['product', 'path']);
+function unknownFields(value, known, prefix, issues) {
+    for (const key of Object.keys(value))
+        if (!known.has(key))
+            issues.push(`${prefix}${key}: unknown field`);
+}
+/**
+ * Validate a HiveEvent v1. The returned value is a fresh object holding only known fields,
+ * so a consumer never passes along data it did not validate.
+ */
+export function validateHiveEvent(value, options = {}) {
+    if (!isRecord(value))
+        return { ok: false, issues: ['$: expected an object'] };
+    const issues = [];
+    if (options.strict)
+        unknownFields(value, EVENT_FIELDS, '', issues);
+    const { id, product, type, severity, title, summary, occurredAt, subject, link, sourceRef } = value;
+    if (text(id, 'id', 1, HIVE_EVENT_LIMITS.id, issues) && !EVENT_ID_PATTERN.test(id))
+        issues.push('id: expected [A-Za-z0-9._:-]');
+    if (!isProductId(product))
+        issues.push('product: expected a product ID');
+    if (text(type, 'type', 1, HIVE_EVENT_LIMITS.type, issues) && !EVENT_TYPE_PATTERN.test(type))
+        issues.push('type: expected a dotted lowercase type');
+    if (!HIVE_EVENT_SEVERITIES.includes(severity))
+        issues.push('severity: expected info, warning or critical');
+    text(title, 'title', 1, HIVE_EVENT_LIMITS.title, issues);
+    text(summary, 'summary', 0, HIVE_EVENT_LIMITS.summary, issues);
+    if (!isRfc3339Utc(occurredAt))
+        issues.push('occurredAt: expected an RFC 3339 UTC timestamp');
+    let cleanSubject;
+    if (subject !== undefined) {
+        if (!isRecord(subject))
+            issues.push('subject: expected an object');
+        else {
+            if (options.strict)
+                unknownFields(subject, SUBJECT_FIELDS, 'subject.', issues);
+            cleanSubject = {};
+            if (subject['actorId'] !== undefined) {
+                if (isIdentifier(subject['actorId']))
+                    cleanSubject.actorId = subject['actorId'];
+                else
+                    issues.push('subject.actorId: expected [a-z0-9_-]{2,32}');
+            }
+            if (subject['agentRef'] !== undefined) {
+                if (isAgentRef(subject['agentRef']))
+                    cleanSubject.agentRef = subject['agentRef'];
+                else
+                    issues.push('subject.agentRef: expected <nodeId>~<profile>');
+            }
+            if (subject['nodeId'] !== undefined) {
+                if (isIdentifier(subject['nodeId']))
+                    cleanSubject.nodeId = subject['nodeId'];
+                else
+                    issues.push('subject.nodeId: expected [a-z0-9_-]{2,32}');
+            }
+        }
+    }
+    if (!isRecord(link))
+        issues.push('link: expected an object');
+    else {
+        if (options.strict)
+            unknownFields(link, LINK_FIELDS, 'link.', issues);
+        if (!isProductId(link['product']))
+            issues.push('link.product: expected a product ID');
+        if (!isSameOriginPath(link['path']))
+            issues.push('link.path: expected a same-origin path starting with /');
+    }
+    if (sourceRef !== undefined)
+        text(sourceRef, 'sourceRef', 1, HIVE_EVENT_LIMITS.sourceRef, issues);
+    if (issues.length)
+        return { ok: false, issues };
+    const linkRecord = link;
+    const event = {
+        id: id,
+        product: product,
+        type: type,
+        severity: severity,
+        title: title,
+        summary: summary,
+        occurredAt: occurredAt,
+        ...(cleanSubject ? { subject: cleanSubject } : {}),
+        link: { product: linkRecord['product'], path: linkRecord['path'] },
+        ...(sourceRef !== undefined ? { sourceRef: sourceRef } : {}),
+    };
+    return { ok: true, value: event };
+}
+export function isHiveEvent(value) {
+    return validateHiveEvent(value).ok;
+}
+/** Validate a feed page of HiveEvents. Any invalid event fails the whole page. */
+export function validateHiveEventPage(value, options = {}) {
+    if (!isPage(value))
+        return { ok: false, issues: ['$: expected { data: [], nextCursor: string | null }'] };
+    const data = [];
+    const issues = [];
+    value.data.forEach((item, index) => {
+        const result = validateHiveEvent(item, options);
+        if (result.ok)
+            data.push(result.value);
+        else
+            issues.push(...result.issues.map(issue => `data[${index}].${issue}`));
+    });
+    return issues.length ? { ok: false, issues } : { ok: true, value: { data, nextCursor: value.nextCursor } };
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The suite error envelope, `HiveError`, and `parseHiveError()`, which turns any error
+ * response a suite product has ever sent into one `HiveError`.
+ *
+ * Isomorphic: no Node built-ins, so the browser UI can use it.
+ */
+import type { ErrorEnvelope } from '../contracts/index.js';
+export type { ErrorBody, ErrorEnvelope } from '../contracts/index.js';
+export { isErrorEnvelope } from '../contracts/index.js';
+/** The default code for an HTTP status, for example `not_found` for 404. */
+export declare function defaultCodeForStatus(status: number): string;
+/** The default message for an HTTP status. */
+export declare function defaultMessageForStatus(status: number): string;
+/** The legacy body shape a parsed error came from. */
+export type HiveErrorShape = 'envelope' | 'magnus' | 'oathweave' | 'oauth' | 'code' | 'string' | 'fastapi' | 'fastapi-validation' | 'mattermost' | 'message' | 'text' | 'empty' | 'unknown';
+export interface HiveErrorOptions {
+    readonly status?: number;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly requestId?: string;
+    /** Extra response headers, such as `WWW-Authenticate` or `Retry-After`. */
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly cause?: unknown;
+    readonly shape?: HiveErrorShape;
+}
+/** An error that knows its HTTP status, stable code and safe message. */
+export declare class HiveError extends Error {
+    readonly name: string;
+    readonly code: string;
+    readonly status: number;
+    readonly details: Readonly<Record<string, unknown>> | undefined;
+    readonly requestId: string | undefined;
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    /** Set by `parseHiveError()`: the legacy body shape it recognised. */
+    readonly shape: HiveErrorShape | undefined;
+    constructor(code: string, message: string, options?: HiveErrorOptions);
+    /** True when `error` is a HiveError with this code (case-insensitive), across package copies. */
+    static is(error: unknown, code?: string): error is HiveError;
+    toJSON(): ErrorEnvelope;
+    static badRequest(message?: string, details?: Record<string, unknown>): HiveError;
+    static validation(message: string, issues: readonly unknown[]): HiveError;
+    static unauthorized(message?: string): HiveError;
+    static forbidden(message?: string): HiveError;
+    static notFound(message?: string): HiveError;
+    static conflict(message?: string, details?: Record<string, unknown>): HiveError;
+    static rateLimited(retryAfterSeconds?: number): HiveError;
+    static unavailable(message?: string): HiveError;
+    static internal(message?: string, cause?: unknown): HiveError;
+}
+/** True for any HiveError, including one created by another copy of this package. */
+export declare function isHiveError(value: unknown): value is HiveError;
+/** Build `{ error: { code, message, requestId?, details? } }`. */
+export declare function errorEnvelope(code: string, message: string, extra?: {
+    readonly requestId?: string | undefined;
+    readonly details?: Readonly<Record<string, unknown>> | undefined;
+}): ErrorEnvelope;
+export interface ErrorResponse {
+    readonly status: number;
+    readonly body: ErrorEnvelope;
+    /** Lowercase header names, including `content-type` and `cache-control`. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+export interface ToErrorResponseOptions {
+    readonly requestId?: string | undefined;
+    /**
+     * Called for anything that is not a HiveError, before it is replaced by a generic 500.
+     * Use it to log the original error; its message is never sent to the client.
+     */
+    readonly onUnexpected?: (error: unknown) => void;
+}
+/**
+ * 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 declare function toErrorResponse(error: unknown, options?: ToErrorResponseOptions): ErrorResponse;
+export interface ParseHiveErrorOptions {
+    /** Used when the body carries no request ID, typically the response's `x-request-id`. */
+    readonly requestId?: string | undefined;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * 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 declare function parseHiveError(status: number, body: unknown, options?: ParseHiveErrorOptions): HiveError;
+/** Read a fetch `Response` and normalise it with `parseHiveError()`. Never throws on a bad body. */
+export declare function parseHiveErrorResponse(response: Response): Promise<HiveError>;