@ably/ai-transport 0.0.1

package/dist/core/transport/types.d.ts

@@ -0,0 +1,407 @@
+import { Logger } from '../../logger.js';
+import { Codec } from '../codec/types.js';
+/**
+ * Core transport types, parameterized by codec event and message types.
+ *
+ * These types define the contract for both client and server transport
+ * implementations, independent of which codec (Vercel AI SDK, etc.) is used.
+ */
+import type * as Ably from 'ably';
+/** Why a turn ended. */
+export type TurnEndReason = 'complete' | 'cancelled' | 'error';
+/** Filter for cancel operations. At most one field should be set. */
+export interface CancelFilter {
+    /** Cancel a specific turn by ID. */
+    turnId?: string;
+    /** Cancel all turns belonging to the sender's clientId. */
+    own?: boolean;
+    /** Cancel all turns belonging to a specific clientId. */
+    clientId?: string;
+    /** Cancel all turns on the channel. */
+    all?: boolean;
+}
+/**
+ * Passed to the server's `onCancel` hook for authorization decisions.
+ * The hook inspects the incoming cancel message and decides whether to
+ * allow each matched turn to be aborted.
+ */
+export interface CancelRequest {
+    /** The raw Ably message that carried the cancel signal. */
+    message: Ably.InboundMessage;
+    /** The parsed cancel scope from the message headers. */
+    filter: CancelFilter;
+    /** Which active turnIds would be cancelled if allowed. */
+    matchedTurnIds: string[];
+    /** Map of turnId to the ownerClientId for the matched turns. */
+    turnOwners: Map<string, string>;
+}
+/** A domain message paired with its Ably transport headers. Used on the read path to snapshot conversation state (e.g. for HTTP POST bodies). */
+export interface MessageWithHeaders<TMessage> {
+    /** The domain message. */
+    message: TMessage;
+    /** Ably headers associated with this message (transport metadata, domain headers). */
+    headers?: Record<string, string>;
+}
+/** Options for creating a server transport. */
+export interface ServerTransportOptions<TEvent, TMessage> {
+    /** The Ably channel to publish to. Must match the client's channel. */
+    channel: Ably.RealtimeChannel;
+    /** The codec to use for encoding events and messages. */
+    codec: Codec<TEvent, TMessage>;
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+    /**
+     * Called with non-fatal transport-level errors not scoped to any turn.
+     * Examples: cancel listener subscription failure, channel attach errors.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}
+/** Options for addMessages — per-operation overrides for message identity and branching. */
+export interface AddMessageOptions {
+    /** The user's clientId for attribution. */
+    clientId?: string;
+    /** The msg-id of the immediately preceding message in this branch. */
+    parent?: string | null;
+    /** The msg-id of the message this one replaces (creates a fork). */
+    forkOf?: string;
+}
+/** Result of publishing user messages via addMessages. */
+export interface AddMessagesResult {
+    /** The `x-ably-msg-id` of each published message, in order. */
+    msgIds: string[];
+}
+/** Options for streamResponse — per-operation overrides for the assistant message. */
+export interface StreamResponseOptions {
+    /** The msg-id of the immediately preceding message in this branch. */
+    parent?: string | null;
+    /** The msg-id of the message this response replaces (for regeneration). */
+    forkOf?: string;
+}
+/** The result of streaming a response through the encoder. */
+export interface StreamResult {
+    /** Why the stream ended. */
+    reason: TurnEndReason;
+}
+/** Options passed to newTurn for configuring the turn lifecycle. */
+export interface NewTurnOptions<TEvent> {
+    /** The turn identifier (generated by the client transport or the server). */
+    turnId: string;
+    /** The user's clientId for attribution. */
+    clientId?: string;
+    /**
+     * The msg-id of the immediately preceding message in this branch.
+     * Used as the default parent for user messages (via addMessages) and
+     * assistant messages (via streamResponse) when not overridden per-operation.
+     */
+    parent?: string | null;
+    /**
+     * The msg-id of the message this turn replaces (creates a fork).
+     * Stamped on user messages (for edits) or assistant messages
+     * (for regeneration).
+     */
+    forkOf?: string;
+    /**
+     * Called before each Ably message is published in this turn.
+     * Mutate the Ably message in place to add custom extras.headers.
+     */
+    onMessage?: (message: Ably.Message) => void;
+    /**
+     * Called when the turn's stream is aborted (by cancel or server).
+     * Receives a write function to publish final events before the abort finalises.
+     */
+    onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>;
+    /**
+     * Called when a cancel message arrives matching this turn.
+     * Return true to allow cancellation (fires abortSignal, stream aborts).
+     * Return false to reject (cancel ignored, stream continues).
+     * If not provided, all cancels are accepted.
+     */
+    onCancel?: (request: CancelRequest) => Promise<boolean>;
+    /**
+     * Called with non-fatal errors scoped to this turn. Examples: turn-start
+     * publish failure, encoder recovery failure, stream encoding errors.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}
+/** A server-side turn with explicit lifecycle methods. */
+export interface Turn<TEvent, TMessage> {
+    /** The turn's unique identifier. */
+    readonly turnId: string;
+    /** Abort signal scoped to this turn. Fires when a cancel event arrives for this turnId. */
+    readonly abortSignal: AbortSignal;
+    /** Publish turn-start event to the channel. Must be called before addMessages or streamResponse. */
+    start(): Promise<void>;
+    /**
+     * Publish user messages to the channel, scoped to this turn.
+     * Each message is published with its own headers (including `x-ably-msg-id`
+     * for optimistic reconciliation with the client's inserts). Per-message
+     * headers from `MessageWithHeaders` override transport-generated defaults.
+     * @returns The msg-ids of all published messages, in order.
+     */
+    addMessages(messages: MessageWithHeaders<TMessage>[], options?: AddMessageOptions): Promise<AddMessagesResult>;
+    /**
+     * Pipe a ReadableStream through the encoder to the channel.
+     * Returns when the stream completes, is cancelled, or errors.
+     * Does NOT call end() — the caller must call end() after streamResponse returns.
+     */
+    streamResponse(stream: ReadableStream<TEvent>, options?: StreamResponseOptions): Promise<StreamResult>;
+    /** Publish turn-end event to the channel and clean up. */
+    end(reason: TurnEndReason): Promise<void>;
+}
+/** Server-side transport that manages turn lifecycles over an Ably channel. */
+export interface ServerTransport<TEvent, TMessage> {
+    /**
+     * Create a new turn. Synchronous — no channel activity until start() is called.
+     * The turn is registered for cancel routing immediately so that early cancels
+     * fire the abort signal.
+     */
+    newTurn(options: NewTurnOptions<TEvent>): Turn<TEvent, TMessage>;
+    /** Unsubscribe from cancel messages, abort all active turns, and clean up. */
+    close(): void;
+}
+/** Options for creating a client transport. */
+export interface ClientTransportOptions<TEvent, TMessage> {
+    /** The Ably channel to receive responses on and publish cancel signals to. */
+    channel: Ably.RealtimeChannel;
+    /** The codec to use for encoding/decoding. */
+    codec: Codec<TEvent, TMessage>;
+    /** The client's identity. Sent to the server in the POST body. */
+    clientId?: string;
+    /** Server endpoint URL for the HTTP POST. Defaults to `"/api/chat"`. */
+    api?: string;
+    /** Headers for the HTTP POST. Function form for dynamic values (e.g. auth tokens). */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Additional body fields merged into the HTTP POST. Function form for dynamic values. */
+    body?: Record<string, unknown> | (() => Record<string, unknown>);
+    /** Fetch credentials mode for the HTTP POST. */
+    credentials?: RequestCredentials;
+    /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Initial messages to seed the conversation tree with. Forms a linear chain. */
+    messages?: TMessage[];
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/** Per-send options for customizing the HTTP POST and branching metadata. */
+export interface SendOptions {
+    /** Additional fields merged into the HTTP POST body. */
+    body?: Record<string, unknown>;
+    /** Additional headers for the HTTP POST. */
+    headers?: Record<string, string>;
+    /**
+     * The msg-id of the message this send replaces (fork).
+     * Set for regeneration (forkOf an assistant message) or
+     * edit (forkOf a user message).
+     */
+    forkOf?: string;
+    /**
+     * The msg-id of the message that precedes this one in the
+     * conversation thread. Null means the message is a root.
+     * If omitted, auto-computed from the last message in the tree.
+     */
+    parent?: string | null;
+}
+/** A structured event describing a turn starting or ending. */
+export type TurnLifecycleEvent = {
+    type: 'x-ably-turn-start';
+    turnId: string;
+    clientId: string;
+} | {
+    type: 'x-ably-turn-end';
+    turnId: string;
+    clientId: string;
+    reason: TurnEndReason;
+};
+/** A handle to an active client-side turn, returned by `send()`, `regenerate()`, and `edit()`. */
+export interface ActiveTurn<TEvent> {
+    /** The decoded event stream for this turn. */
+    stream: ReadableStream<TEvent>;
+    /** The turn's unique identifier. */
+    turnId: string;
+    /** Cancel this specific turn. Publishes a cancel message and closes the local stream. */
+    cancel(): Promise<void>;
+}
+/** Options for closing a client transport. */
+export interface CloseOptions {
+    /** Cancel in-progress turns before closing. Publishes a cancel message to the channel. */
+    cancel?: CancelFilter;
+}
+/** A page of decoded messages from channel history. */
+export interface PaginatedMessages<TMessage> {
+    /** Decoded messages in chronological order (oldest first). */
+    items: TMessage[];
+    /** Headers for each item, parallel to `items`. Used by the transport to populate the tree. */
+    itemHeaders?: Record<string, string>[];
+    /** Ably serial for each item, parallel to `items`. Used by the transport for tree ordering. */
+    itemSerials?: string[];
+    /** Raw Ably messages that produced this page, in chronological order. */
+    rawMessages?: Ably.InboundMessage[];
+    /** Whether there are older pages available. */
+    hasNext(): boolean;
+    /** Fetch the next (older) page. Returns undefined if no more pages. */
+    next(): Promise<PaginatedMessages<TMessage> | undefined>;
+}
+/** Options for loading channel history. */
+export interface LoadHistoryOptions {
+    /** Max messages per page. Default: 100. */
+    limit?: number;
+}
+/** A node in the conversation tree, representing a single domain message. */
+export interface ConversationNode<TMessage> {
+    /** The domain message. */
+    message: TMessage;
+    /** The x-ably-msg-id of this node — primary key in the tree. */
+    msgId: string;
+    /** Parent node's msg-id (x-ably-parent), or undefined for root messages. */
+    parentId: string | undefined;
+    /** The msg-id this node forks from (x-ably-fork-of), or undefined if first version. */
+    forkOf: string | undefined;
+    /** Full Ably headers for this message. */
+    headers: Record<string, string>;
+    /**
+     * Ably serial for this message. Lexicographically comparable for total order.
+     * Used to sort siblings deterministically regardless of delivery/history order.
+     * Absent for optimistic messages (set when the server relay arrives).
+     */
+    serial: string | undefined;
+}
+/**
+ * Materializes a branching conversation tree from a flat oplog.
+ *
+ * Owns the conversation state — `flatten()` returns the linear message list
+ * for the currently selected branches. The transport's `getMessages()` delegates
+ * to `flatten()`.
+ */
+export interface ConversationTree<TMessage> {
+    /**
+     * Flatten the tree along the currently selected branches into
+     * a linear message list. This is what getMessages() returns.
+     */
+    flatten(): TMessage[];
+    /**
+     * Get all messages that are siblings (alternatives) at a given
+     * fork point. Returns an array ordered chronologically by serial.
+     * The message identified by msgId is always included.
+     */
+    getSiblings(msgId: string): TMessage[];
+    /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
+    hasSiblings(msgId: string): boolean;
+    /** Get the index of the currently selected sibling at a fork point. */
+    getSelectedIndex(msgId: string): number;
+    /**
+     * Select a sibling at a fork point by index. Updates the active branch.
+     * Calling flatten() after this returns the new linear thread.
+     * Index is clamped to `[0, siblings.length - 1]`.
+     */
+    select(msgId: string, index: number): void;
+    /** Get a node by msgId, or undefined if not found. */
+    getNode(msgId: string): ConversationNode<TMessage> | undefined;
+    /**
+     * Get a node by codec message key (e.g. UIMessage.id), or undefined if
+     * not found. Uses a secondary index since the tree is keyed by x-ably-msg-id.
+     */
+    getNodeByKey(key: string): ConversationNode<TMessage> | undefined;
+    /** Get the stored headers for a node by msgId, or undefined if not found. */
+    getHeaders(msgId: string): Record<string, string> | undefined;
+    /**
+     * Insert or update a message in the tree. Reads parent/forkOf from the
+     * provided headers. If the message already exists (by msgId), updates
+     * it in place. The optional serial is the Ably message serial used for
+     * deterministic sibling ordering.
+     */
+    upsert(msgId: string, message: TMessage, headers: Record<string, string>, serial?: string): void;
+    /** Remove a message from the tree. */
+    delete(msgId: string): void;
+}
+/** Entry in the StreamRouter's turn map. Not part of the public API. */
+export interface TurnEntry<TEvent> {
+    /** The ReadableStream controller for this turn. */
+    controller: ReadableStreamDefaultController<TEvent>;
+    /** The turn's unique identifier. */
+    turnId: string;
+}
+/** Client-side transport that manages conversation state over an Ably channel. */
+export interface ClientTransport<TEvent, TMessage> {
+    /**
+     * Send one or more messages and start a new turn. Returns a handle to the
+     * active turn with the decoded event stream and a cancel function.
+     *
+     * The HTTP POST is fire-and-forget — the returned stream is available
+     * immediately. If the POST fails, the error is surfaced via `on("error")`.
+     */
+    send(messages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    /**
+     * Regenerate an assistant message. Creates a new turn that forks the
+     * target message with no new user messages. Automatically computes
+     * `forkOf`, `parent`, and truncated `history` from the tree.
+     *
+     * Pass `options.body.history` to override the default truncated history.
+     */
+    regenerate(messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    /**
+     * Edit a user message. Creates a new turn that forks the target message
+     * with replacement content. Automatically computes `forkOf`, `parent`,
+     * and `history` from the tree.
+     */
+    edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
+    /**
+     * Access the conversation tree for branch navigation.
+     * The tree is updated in real-time by the transport's channel subscription.
+     */
+    getTree(): ConversationTree<TMessage>;
+    /** Cancel turns matching the filter. Defaults to `{ own: true }` (all own turns). */
+    cancel(filter?: CancelFilter): Promise<void>;
+    /**
+     * Returns a promise that resolves when all active turns matching the filter
+     * have completed. Resolves immediately if no matching turns are active.
+     * Defaults to `{ own: true }`.
+     */
+    waitForTurn(filter?: CancelFilter): Promise<void>;
+    /**
+     * Subscribe to message store changes or raw Ably message additions.
+     * The handler is called with no arguments — call `getMessages()` or
+     * `getAblyMessages()` for the current state. Returns an unsubscribe function.
+     */
+    on(event: 'message' | 'ably-message', handler: () => void): () => void;
+    /** Subscribe to turn lifecycle events (start, end). Returns an unsubscribe function. */
+    on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
+    /**
+     * Subscribe to non-fatal transport errors. These indicate something went
+     * wrong but the transport is still operational. Returns an unsubscribe function.
+     */
+    on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
+    /**
+     * Get the accumulated raw Ably messages, in chronological order.
+     * Includes both live messages and history-loaded messages.
+     */
+    getAblyMessages(): Ably.InboundMessage[];
+    /** Get all currently active turns, keyed by clientId. */
+    getActiveTurnIds(): Map<string, Set<string>>;
+    /** Get Ably headers associated with a message via the conversation tree. */
+    getMessageHeaders(message: TMessage): Record<string, string> | undefined;
+    /** Get the current message list (follows selected branches). Updated by message lifecycle events. */
+    getMessages(): TMessage[];
+    /**
+     * Snapshot the current message list as message + headers pairs.
+     * Convenience for building the `history` body field in HTTP POSTs.
+     */
+    getMessagesWithHeaders(): MessageWithHeaders<TMessage>[];
+    /**
+     * Load a page of conversation history from the channel, decoded through
+     * the transport's codec. Uses `untilAttach` for gapless continuity with
+     * the live subscription.
+     *
+     * History messages are inserted into the conversation tree and trigger
+     * a notification. Returns a PaginatedMessages handle — call `next()`
+     * for older pages.
+     */
+    history(options?: LoadHistoryOptions): Promise<PaginatedMessages<TMessage>>;
+    /**
+     * Tear down the transport: unsubscribe from the channel, close active
+     * streams, clear all handlers, and prevent further operations.
+     *
+     * Pass `cancel` to publish a cancel message before closing. Without it,
+     * only local state is torn down (the server keeps streaming).
+     */
+    close(options?: CloseOptions): Promise<void>;
+}

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+import * as Ably from 'ably';
+/**
+ * Error codes for the AI Transport SDK.
+ */
+export declare enum ErrorCode {
+    /**
+     * The request was invalid.
+     */
+    BadRequest = 40000,
+    /**
+     * Invalid argument provided.
+     */
+    InvalidArgument = 40003,
+    /**
+     * Encoder recovery failed after flush — one or more updateMessage calls
+     * could not recover a failed append pipeline.
+     */
+    EncoderRecoveryFailed = 104000,
+    /**
+     * A transport-level channel subscription callback threw unexpectedly.
+     */
+    TransportSubscriptionError = 104001,
+    /**
+     * Cancel listener or onCancel hook threw while processing a cancel message.
+     */
+    CancelListenerError = 104002,
+    /**
+     * A turn lifecycle event (turn-start or turn-end) failed to publish.
+     */
+    TurnLifecycleError = 104003,
+    /**
+     * An operation was attempted on a transport that has already been closed.
+     */
+    TransportClosed = 104004,
+    /**
+     * The HTTP POST to the server endpoint failed (network error or non-2xx response).
+     */
+    TransportSendFailed = 104005
+}
+/**
+ * Returns true if the {@link Ably.ErrorInfo} code matches the provided ErrorCode value.
+ * @param errorInfo The error info to check.
+ * @param error The error code to compare against.
+ * @returns true if the error code matches, false otherwise.
+ */
+export declare const errorInfoIs: (errorInfo: Ably.ErrorInfo, error: ErrorCode) => boolean;

package/dist/event-emitter.d.ts

@@ -0,0 +1,65 @@
+import { Logger } from './logger.js';
+/**
+ * Type-safe EventEmitter wrapping Ably's internal EventEmitter.
+ *
+ * Takes a single `EventsMap` type parameter — an interface mapping event names
+ * to payload types — rather than Ably's three type parameters. Adapted from
+ * the ably-chat-js SDK.
+ *
+ * ```ts
+ * interface MyEvents {
+ *   reaction: { emoji: string };
+ *   status: { online: boolean };
+ * }
+ *
+ * const emitter = new EventEmitter<MyEvents>(logger);
+ * emitter.on('reaction', (event) => console.log(event.emoji));
+ * emitter.emit('reaction', { emoji: '👍' });
+ * ```
+ */
+import * as Ably from 'ably';
+/** Callback receiving a union of all possible event payloads. */
+type Callback<EventsMap> = (arg: EventsMap[keyof EventsMap]) => void;
+/** Callback receiving the payload for a single event type. */
+type CallbackSingle<K> = (arg: K) => void;
+/**
+ * Type-safe interface for the Ably EventEmitter, parameterized by an EventsMap
+ * that maps event names to their payload types.
+ */
+interface InterfaceEventEmitter<EventsMap> extends Ably.EventEmitter<Callback<EventsMap>, void, keyof EventsMap> {
+    /** Emit an event with a type-safe payload. Payload is optional for `undefined`-typed events. */
+    emit<K extends keyof EventsMap>(event: K, ...args: EventsMap[K] extends undefined ? [EventsMap[K]?] : [EventsMap[K]]): void;
+    /** Subscribe to a single event with a typed callback. */
+    on<K extends keyof EventsMap>(event: K, callback: CallbackSingle<EventsMap[K]>): void;
+    /** Subscribe to two events with a union-typed callback. */
+    on<K1 extends keyof EventsMap, K2 extends keyof EventsMap>(events: [K1, K2], callback: CallbackSingle<EventsMap[K1] | EventsMap[K2]>): void;
+    /** Subscribe to three events with a union-typed callback. */
+    on<K1 extends keyof EventsMap, K2 extends keyof EventsMap, K3 extends keyof EventsMap>(events: [K1, K2, K3], callback: CallbackSingle<EventsMap[K1] | EventsMap[K2] | EventsMap[K3]>): void;
+    /** Subscribe to an array of events. */
+    on(events: (keyof EventsMap)[], callback: Callback<EventsMap>): void;
+    /** Subscribe to all events. */
+    on(callback: Callback<EventsMap>): void;
+    /** Unsubscribe a callback from a specific event. */
+    off<K extends keyof EventsMap>(event: K, listener: CallbackSingle<EventsMap[K]>): void;
+    /** Unsubscribe a callback from all events, or remove all listeners if no callback provided. */
+    off(listener?: Callback<EventsMap>): void;
+}
+declare const InternalEventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap>;
+/**
+ * Type-safe EventEmitter based on Ably's internal EventEmitter.
+ *
+ * Provides the same semantics as {@link Ably.EventEmitter} (error isolation
+ * between listeners, synchronous dispatch) but with a single `EventsMap` type
+ * parameter for ergonomic type safety.
+ *
+ * Requires a {@link Logger} so that listener exceptions are routed through
+ * the application's logging infrastructure rather than silently swallowed.
+ */
+export declare class EventEmitter<EventsMap> extends InternalEventEmitter<EventsMap> {
+    /**
+     * Create a new EventEmitter.
+     * @param logger - Application logger. Listener exceptions are logged at error level.
+     */
+    constructor(logger: Logger);
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, ConversationNode, ConversationTree, LoadHistoryOptions, MessageWithHeaders, NewTurnOptions, PaginatedMessages, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Turn, TurnEndReason, TurnLifecycleEvent, } from './core/transport/index.js';
+export { buildTransportHeaders, createClientTransport, createServerTransport } from './core/transport/index.js';
+export type { ChannelWriter, Codec, DecoderCore, DecoderCoreHooks, DecoderCoreOptions, DecoderOutput, DiscreteEncoder, EncoderCore, EncoderCoreOptions, EncoderOptions, Extras, LifecycleTracker, MessageAccumulator, MessagePayload, PhaseConfig, StreamDecoder, StreamEncoder, StreamPayload, StreamTrackerState, WriteOptions, } from './core/codec/index.js';
+export { createDecoderCore, createEncoderCore, createLifecycleTracker, eventOutput } from './core/codec/index.js';
+export { DOMAIN_HEADER_PREFIX, EVENT_ABORT, EVENT_CANCEL, EVENT_ERROR, EVENT_TURN_END, EVENT_TURN_START, HEADER_CANCEL_ALL, HEADER_CANCEL_CLIENT_ID, HEADER_CANCEL_OWN, HEADER_CANCEL_TURN_ID, HEADER_FORK_OF, HEADER_MSG_ID, HEADER_PARENT, HEADER_ROLE, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID, HEADER_TURN_CLIENT_ID, HEADER_TURN_ID, HEADER_TURN_REASON, } from './constants.js';
+export type { DomainHeaderReader, DomainHeaderWriter, Stripped } from './utils.js';
+export { getHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined } from './utils.js';
+export { EventEmitter } from './event-emitter.js';
+export { ErrorCode, errorInfoIs } from './errors.js';
+export type { LogContext, Logger, LoggerOptions, LogHandler } from './logger.js';
+export { consoleLogger, LogLevel, makeLogger } from './logger.js';

package/dist/logger.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Structured logger with leveled output and hierarchical context.
+ * Implementations filter messages by level and delegate to a {@link LogHandler}.
+ */
+export interface Logger {
+    /**
+     * Log a message at the trace level.
+     * @param message The message to log.
+     * @param context The context of the log message as key-value pairs.
+     */
+    trace(message: string, context?: LogContext): void;
+    /**
+     * Log a message at the debug level.
+     * @param message The message to log.
+     * @param context The context of the log message as key-value pairs.
+     */
+    debug(message: string, context?: LogContext): void;
+    /**
+     * Log a message at the info level.
+     * @param message The message to log.
+     * @param context The context of the log message as key-value pairs.
+     */
+    info(message: string, context?: LogContext): void;
+    /**
+     * Log a message at the warn level.
+     * @param message The message to log.
+     * @param context The context of the log message as key-value pairs.
+     */
+    warn(message: string, context?: LogContext): void;
+    /**
+     * Log a message at the error level.
+     * @param message The message to log.
+     * @param context The context of the log message as key-value pairs.
+     */
+    error(message: string, context?: LogContext): void;
+    /**
+     * Creates a new logger with a context that will be merged with any context provided to individual log calls.
+     * The context will be overridden by any matching keys in the individual log call's context.
+     * @param context The context to use for all log calls.
+     * @returns A new logger instance with the context.
+     */
+    withContext(context: LogContext): Logger;
+}
+/**
+ * Represents the different levels of logging that can be used.
+ */
+export declare enum LogLevel {
+    /**
+     * Something routine and expected has occurred. This level will provide logs for the vast majority of operations
+     * and function calls.
+     */
+    Trace = "trace",
+    /**
+     * Development information, messages that are useful when trying to debug library behavior,
+     * but superfluous to normal operation.
+     */
+    Debug = "debug",
+    /**
+     * Informational messages. Operationally significant to the library but not out of the ordinary.
+     */
+    Info = "info",
+    /**
+     * Anything that is not immediately an error, but could cause unexpected behavior in the future. For example,
+     * passing an invalid value to an option. Indicates that some action should be taken to prevent future errors.
+     */
+    Warn = "warn",
+    /**
+     * A given operation has failed and cannot be automatically recovered. The error may threaten the continuity
+     * of operation.
+     */
+    Error = "error",
+    /**
+     * No logging will be performed.
+     */
+    Silent = "silent"
+}
+/**
+ * Represents the context of a log message.
+ * It is an object of key-value pairs that can be used to provide additional context to a log message.
+ */
+export type LogContext = Record<string, any>;
+/**
+ * A function that can be used to handle log messages.
+ * @param message The message to log.
+ * @param level The log level of the message.
+ * @param context The context of the log message as key-value pairs.
+ */
+export type LogHandler = (message: string, level: LogLevel, context?: LogContext) => void;
+/**
+ * A simple console logger that logs messages to the console.
+ * @param message The message to log.
+ * @param level The log level of the message.
+ * @param context - The context of the log message as key-value pairs.
+ */
+export declare const consoleLogger: (message: string, level: LogLevel, context?: LogContext) => void;
+/**
+ * Options for creating a logger.
+ */
+export interface LoggerOptions {
+    logHandler?: LogHandler;
+    logLevel: LogLevel;
+}
+export declare const makeLogger: (options: LoggerOptions) => Logger;