@ably/ai-transport 0.0.1

package/src/errors.ts

@@ -0,0 +1,58 @@
+import * as Ably from 'ably';
+
+/**
+ * Error codes for the AI Transport SDK.
+ */
+export enum ErrorCode {
+  /**
+   * The request was invalid.
+   */
+  BadRequest = 40000,
+
+  /**
+   * Invalid argument provided.
+   */
+  InvalidArgument = 40003,
+
+  // 104000 - 104999 are reserved for AI Transport SDK errors
+
+  /**
+   * 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison
+export const errorInfoIs = (errorInfo: Ably.ErrorInfo, error: ErrorCode): boolean => errorInfo.code === error;

package/src/event-emitter.ts

@@ -0,0 +1,103 @@
+/**
+ * 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';
+
+import type { Logger } from './logger.js';
+
+/** 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;
+}
+
+/**
+ * Bridge from our {@link Logger} to the Ably EventEmitter's internal logger
+ * contract. Ably's EventEmitter calls `logger.logAction(level, action, message)`
+ * when a listener throws — we route that to our Logger's `error` method.
+ * @param logger - The application logger to delegate to.
+ * @returns An object satisfying the Ably EventEmitter's logger interface.
+ */
+const toAblyLogger = (logger: Logger): unknown => ({
+  logAction: (_level: number, action: string, message?: string) => {
+    logger.error(action, { detail: message });
+  },
+  shouldLog: () => true,
+});
+
+// CAST: Access Ably's internal EventEmitter constructor. Not publicly exported
+// but available to other Ably SDKs. The logger parameter ensures listener
+// exceptions are caught and logged rather than crashing.
+const InternalEventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> = (
+  Ably.Realtime as unknown as { EventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> }
+).EventEmitter;
+
+/**
+ * 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 class EventEmitter<EventsMap> extends InternalEventEmitter<EventsMap> {
+  /**
+   * Create a new EventEmitter.
+   * @param logger - Application logger. Listener exceptions are logged at error level.
+   */
+  constructor(logger: Logger) {
+    super(toAblyLogger(logger));
+  }
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+// Core transport
+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';
+
+// Core codec
+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';
+
+// Constants
+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';
+
+// Utilities
+export type { DomainHeaderReader, DomainHeaderWriter, Stripped } from './utils.js';
+export { getHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined } from './utils.js';
+
+// Event emitter
+export { EventEmitter } from './event-emitter.js';
+
+// Errors
+export { ErrorCode, errorInfoIs } from './errors.js';
+
+// Logger
+export type { LogContext, Logger, LoggerOptions, LogHandler } from './logger.js';
+export { consoleLogger, LogLevel, makeLogger } from './logger.js';

package/src/logger.ts

@@ -0,0 +1,241 @@
+import * as Ably from 'ably';
+
+import { ErrorCode } from './errors.js';
+
+/**
+ * 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 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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 const consoleLogger = (message: string, level: LogLevel, context?: LogContext) => {
+  const contextString = context ? `, context: ${JSON.stringify(context)}` : '';
+  const formattedMessage = `[${new Date().toISOString()}] ${level.valueOf().toUpperCase()} ably-ai-transport: ${message}${contextString}`;
+
+  switch (level) {
+    case LogLevel.Trace:
+    case LogLevel.Debug: {
+      console.log(formattedMessage);
+      break;
+    }
+    case LogLevel.Info: {
+      console.info(formattedMessage);
+      break;
+    }
+    case LogLevel.Warn: {
+      console.warn(formattedMessage);
+      break;
+    }
+    case LogLevel.Error: {
+      console.error(formattedMessage);
+      break;
+    }
+    case LogLevel.Silent: {
+      break;
+    }
+  }
+};
+
+/**
+ * Options for creating a logger.
+ */
+export interface LoggerOptions {
+  logHandler?: LogHandler;
+  logLevel: LogLevel;
+}
+
+export const makeLogger = (options: LoggerOptions): Logger => {
+  const logHandler = options.logHandler ?? consoleLogger;
+
+  return new DefaultLogger(logHandler, options.logLevel);
+};
+
+/**
+ * A convenient list of log levels as numbers that can be used for easier comparison.
+ */
+enum LogLevelNumber {
+  Trace = 0,
+  Debug = 1,
+  Info = 2,
+  Warn = 3,
+  Error = 4,
+  Silent = 5,
+}
+
+/**
+ * A mapping of log levels to their numeric equivalents.
+ */
+const logLevelNumberMap = new Map<LogLevel, LogLevelNumber>([
+  [LogLevel.Trace, LogLevelNumber.Trace],
+  [LogLevel.Debug, LogLevelNumber.Debug],
+  [LogLevel.Info, LogLevelNumber.Info],
+  [LogLevel.Warn, LogLevelNumber.Warn],
+  [LogLevel.Error, LogLevelNumber.Error],
+  [LogLevel.Silent, LogLevelNumber.Silent],
+]);
+
+/**
+ * A default logger implementation.
+ */
+class DefaultLogger implements Logger {
+  private readonly _handler: LogHandler;
+  private readonly _levelNumber: LogLevelNumber;
+  private readonly _context?: LogContext;
+
+  constructor(handler: LogHandler, level: LogLevel, context?: LogContext) {
+    this._handler = handler;
+    this._context = context;
+
+    const levelNumber = logLevelNumberMap.get(level);
+    if (levelNumber === undefined) {
+      throw new Ably.ErrorInfo(`unable to create logger; invalid log level: ${level}`, ErrorCode.InvalidArgument, 400);
+    }
+
+    this._levelNumber = levelNumber;
+  }
+
+  trace(message: string, context?: LogContext): void {
+    this._write(message, LogLevel.Trace, LogLevelNumber.Trace, context);
+  }
+
+  debug(message: string, context?: LogContext): void {
+    this._write(message, LogLevel.Debug, LogLevelNumber.Debug, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    this._write(message, LogLevel.Info, LogLevelNumber.Info, context);
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this._write(message, LogLevel.Warn, LogLevelNumber.Warn, context);
+  }
+
+  error(message: string, context?: LogContext): void {
+    this._write(message, LogLevel.Error, LogLevelNumber.Error, context);
+  }
+
+  withContext(context: LogContext): Logger {
+    // Get the original log level by finding the key in logLevelNumberMap that matches this._levelNumber
+    const originalLevel =
+      [...logLevelNumberMap.entries()].find(([, value]) => value === this._levelNumber)?.[0] ?? LogLevel.Error;
+
+    return new DefaultLogger(this._handler, originalLevel, this._mergeContext(context));
+  }
+
+  private _write(message: string, level: LogLevel, levelNumber: LogLevelNumber, context?: LogContext): void {
+    if (levelNumber >= this._levelNumber) {
+      this._handler(message, level, this._mergeContext(context));
+    }
+  }
+
+  private _mergeContext(context?: LogContext): LogContext | undefined {
+    if (!this._context) {
+      return context ?? undefined;
+    }
+
+    return context ? { ...this._context, ...context } : this._context;
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,11 @@
+export { useAblyMessages } from './use-ably-messages.js';
+export { useActiveTurns } from './use-active-turns.js';
+export { useClientTransport } from './use-client-transport.js';
+export type { ConversationTreeHandle } from './use-conversation-tree.js';
+export { useConversationTree } from './use-conversation-tree.js';
+export { useEdit } from './use-edit.js';
+export type { HistoryHandle } from './use-history.js';
+export { useHistory } from './use-history.js';
+export { useMessages } from './use-messages.js';
+export { useRegenerate } from './use-regenerate.js';
+export { useSend } from './use-send.js';

package/src/react/use-ably-messages.ts

@@ -0,0 +1,37 @@
+/**
+ * useAblyMessages — reactive raw Ably message log from a ClientTransport.
+ *
+ * Returns the accumulated raw Ably InboundMessages in chronological order,
+ * including both live messages (from the channel subscription) and
+ * history-loaded messages (from transport.history() calls).
+ *
+ * Subscribes to the transport's "ably-message" event and re-reads the
+ * list on each update.
+ */
+
+import type * as Ably from 'ably';
+import { useEffect, useState } from 'react';
+
+import type { ClientTransport } from '../core/transport/types.js';
+
+/**
+ * Subscribe to raw Ably message updates from a client transport.
+ * @param transport - The client transport to observe.
+ * @returns The accumulated raw Ably messages in chronological order.
+ */
+export const useAblyMessages = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage>,
+): Ably.InboundMessage[] => {
+  const [messages, setMessages] = useState<Ably.InboundMessage[]>(() => transport.getAblyMessages());
+
+  useEffect(() => {
+    setMessages(transport.getAblyMessages());
+
+    const unsub = transport.on('ably-message', () => {
+      setMessages(transport.getAblyMessages());
+    });
+    return unsub;
+  }, [transport]);
+
+  return messages;
+};

package/src/react/use-active-turns.ts

@@ -0,0 +1,61 @@
+/**
+ * useActiveTurns: reactive view of active turns on the channel,
+ * keyed by clientId.
+ *
+ * Subscribes to transport turn lifecycle events and maintains a
+ * Map<clientId, Set<turnId>> that updates on every turn start/end.
+ *
+ * Generic — works with any codec, not tied to Vercel types.
+ */
+
+import { useEffect, useState } from 'react';
+
+import { EVENT_TURN_START } from '../constants.js';
+import type { ClientTransport, TurnLifecycleEvent } from '../core/transport/types.js';
+
+/**
+ * Returns a reactive Map of all active turns on the channel, keyed by clientId.
+ * Updates when turns start or end.
+ * @param transport - The client transport to observe, or null/undefined if not yet available.
+ * @returns A Map where keys are clientIds and values are Sets of active turnIds.
+ */
+export const useActiveTurns = <TEvent, TMessage>(
+  transport: ClientTransport<TEvent, TMessage> | null | undefined,
+): Map<string, Set<string>> => {
+  const [turns, setTurns] = useState<Map<string, Set<string>>>(() => new Map());
+
+  useEffect(() => {
+    if (!transport) return;
+
+    // Initialize from current state
+    setTurns(transport.getActiveTurnIds());
+
+    const unsubscribe = transport.on('turn', (event: TurnLifecycleEvent) => {
+      setTurns((prev) => {
+        const next = new Map(prev);
+
+        if (event.type === EVENT_TURN_START) {
+          const set = new Set(next.get(event.clientId) ?? []);
+          set.add(event.turnId);
+          next.set(event.clientId, set);
+        } else {
+          const set = next.get(event.clientId);
+          if (set) {
+            set.delete(event.turnId);
+            if (set.size === 0) {
+              next.delete(event.clientId);
+            } else {
+              next.set(event.clientId, new Set(set));
+            }
+          }
+        }
+
+        return next;
+      });
+    });
+
+    return unsubscribe;
+  }, [transport]);
+
+  return turns;
+};

package/src/react/use-client-transport.ts

@@ -0,0 +1,37 @@
+/**
+ * useClientTransport: creates and memoizes a core ClientTransport instance
+ * across renders.
+ *
+ * Stores the instance in a ref so the same transport is returned on every render.
+ * The transport manages its own Ably channel subscription in the constructor —
+ * this hook adds no subscription logic.
+ *
+ * The hook does NOT auto-close the transport on unmount. Channel lifecycle is
+ * managed by the Ably provider (useChannel), which detaches the channel and
+ * clears all subscriptions. Auto-closing would break React Strict Mode
+ * (double-mount calls close() on the first cleanup, leaving a dead transport
+ * on the second mount). Call transport.close() explicitly if you need to tear
+ * down the transport independently of the channel lifecycle.
+ */
+
+import { useRef } from 'react';
+
+import { createClientTransport } from '../core/transport/client-transport.js';
+import type { ClientTransport, ClientTransportOptions } from '../core/transport/types.js';
+
+/**
+ * Create and memoize a {@link ClientTransport} across renders.
+ * @param options - Configuration for the client transport.
+ * @returns The memoized transport instance.
+ */
+export const useClientTransport = <TEvent, TMessage>(
+  options: ClientTransportOptions<TEvent, TMessage>,
+): ClientTransport<TEvent, TMessage> => {
+  const transportRef = useRef<ClientTransport<TEvent, TMessage> | null>(null);
+
+  if (transportRef.current === null) {
+    transportRef.current = createClientTransport(options);
+  }
+
+  return transportRef.current;
+};