@ably/ai-transport 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ably/ai-transport",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Ably transport and codecs for building AI applications with Ably.",
   "type": "module",
   "main": "dist/ably-ai-transport.umd.cjs",
@@ -46,13 +46,15 @@
     "prepare": "npm run build",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .; (npm run format > /dev/null)",
-    "format": "prettier --list-different --write src demo/vercel/react/*/src",
-    "format:check": "prettier --check src demo/vercel/react/*/src",
+    "format": "prettier --list-different --write .",
+    "format:check": "prettier --check .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:integration": "vitest run --config vitest.config.integration.ts",
     "check:error-codes": "tsx scripts/validate-error-codes.ts",
-    "precommit": "npm run format:check && npm run lint && npm run typecheck"
+    "precommit": "npm run format:check && npm run lint && npm run typecheck",
+    "docs": "typedoc",
+    "docs:lint": "typedoc --emit none"
   },
   "files": [
     "dist/**",
@@ -94,28 +96,32 @@
     }
   },
   "devDependencies": {
-    "@eslint/compat": "^1.2.7",
+    "@ai-sdk/react": "^3.0.151",
+    "@eslint/compat": "^2.0.5",
     "@eslint/eslintrc": "^3.3.0",
-    "@eslint/js": "^9.12.0",
+    "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
-    "@typescript-eslint/eslint-plugin": "^8.26.1",
-    "@typescript-eslint/parser": "^8.26.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "@vitest/coverage-v8": "^4.1.2",
     "ai": "^6.0.137",
-    "eslint": "^9.31.0",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jsdoc": "^60.7.0",
+    "eslint": "^10.2.0",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-jsdoc": "^62.9.0",
     "eslint-plugin-prefer-arrow-functions": "^3.6.2",
-    "eslint-plugin-security": "^3.0.1",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-unicorn": "^61.0.2",
-    "globals": "^16.0.0",
+    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "globals": "^17.5.0",
     "jiti": "^2.6.1",
     "jsdom": "^29.0.1",
     "prettier": "^3.5.3",
     "tsx": "^4.21.0",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.26.1",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-no-inherit": "^1.5.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.2",
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.1.0"

package/src/constants.ts

@@ -22,6 +22,9 @@ export const HEADER_STATUS = 'x-ably-status';
 /** Header: stream identity. Set by the encoder on every streamed message; read by the decoder to correlate streams. */
 export const HEADER_STREAM_ID = 'x-ably-stream-id';
 
+/** Header: marks a message as a discrete message part (from writeMessages). Set by publishDiscreteBatch; not set on lifecycle events from publishDiscrete. */
+export const HEADER_DISCRETE = 'x-ably-discrete';
+
 // ---------------------------------------------------------------------------
 // Identity headers (used by transport for turn correlation)
 // ---------------------------------------------------------------------------
@@ -38,6 +41,9 @@ export const HEADER_TURN_CLIENT_ID = 'x-ably-turn-client-id';
 /** Header: message role (e.g. "user", "assistant"). */
 export const HEADER_ROLE = 'x-ably-role';
 
+/** Header: the msg-id of the existing message this Ably message amends. Present on cross-turn amendment events. */
+export const HEADER_AMEND = 'x-ably-amend';
+
 // ---------------------------------------------------------------------------
 // Cancel headers
 // ---------------------------------------------------------------------------

package/src/core/codec/encoder.ts

@@ -11,7 +11,7 @@
 
 import * as Ably from 'ably';
 
-import { HEADER_MSG_ID, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID } from '../../constants.js';
+import { HEADER_DISCRETE, HEADER_MSG_ID, HEADER_STATUS, HEADER_STREAM, HEADER_STREAM_ID } from '../../constants.js';
 import { ErrorCode } from '../../errors.js';
 import type { Logger } from '../../logger.js';
 import { mergeHeaders } from '../../utils.js';
@@ -129,6 +129,13 @@ class DefaultEncoderCore implements EncoderCore {
     this._assertNotClosed();
     this._logger?.trace('DefaultEncoderCore.publishDiscreteBatch();', { count: payloads.length });
     const msgs = payloads.map((p) => this._buildDiscreteMessage(p, opts));
+    // Mark batch-published payloads as discrete message parts (from writeMessages).
+    // The decoder relies on this header to distinguish message parts from lifecycle
+    // events that also happen to be discrete (x-ably-stream: false).
+    for (const msg of msgs) {
+      // CAST: extras is built by _buildDiscreteMessage with a known { headers } shape.
+      (msg.extras as { headers: Record<string, string> }).headers[HEADER_DISCRETE] = 'true';
+    }
     return this._writer.publish(msgs);
   }
 
@@ -154,6 +161,7 @@ class DefaultEncoderCore implements EncoderCore {
     const result = await this._writer.publish(msg);
     const serial = result.serials[0];
 
+    // Spec: AIT-CD2a
     if (!serial) {
       throw new Ably.ErrorInfo(
         `unable to start stream; no serial returned for stream '${payload.name}' (streamId: ${streamId})`,
@@ -181,6 +189,7 @@ class DefaultEncoderCore implements EncoderCore {
   // Spec: AIT-CD3
   appendStream(streamId: string, data: string): void {
     this._assertNotClosed();
+    // Spec: AIT-CD3a
     const tracker = this._trackers.get(streamId);
     if (!tracker) {
       throw new Ably.ErrorInfo(

package/src/core/codec/types.ts

@@ -203,6 +203,19 @@ export interface MessageAccumulator<TEvent, TMessage> {
   processOutputs(outputs: DecoderOutput<TEvent, TMessage>[]): void;
   /** Apply an external update to a message (e.g. from an update callback). */
   updateMessage(message: TMessage): void;
+  /**
+   * Ensure the accumulator is ready to process events for the given message.
+   * If not already active, creates internal tracking state from the message.
+   * If already active, syncs internal state with the provided message
+   * (picking up external changes like cross-turn amendments).
+   * Idempotent — safe to call before every processOutputs.
+   */
+  initMessage(messageId: string, message: TMessage): void;
+  /**
+   * Mark a message as completed. Removes it from active tracking so it
+   * appears in {@link completedMessages}. No-op if not active.
+   */
+  completeMessage(messageId: string): void;
   /** All messages accumulated so far (in-progress and completed). */
   readonly messages: TMessage[];
   /** Only messages whose streams have finished. */
@@ -223,6 +236,12 @@ export interface EncoderOptions {
   extras?: Extras;
   /** Hook called before each Ably message is published. Mutate the message in place to add transport-level headers. */
   onMessage?: (message: Ably.Message) => void;
+  /**
+   * Domain-level message identity. Domain encoders use this as a fallback
+   * messageId when a lifecycle chunk (e.g. `start`) does not provide one,
+   * ensuring useChat and the transport accumulator assign the same ID.
+   */
+  messageId?: string;
 }
 
 /**
@@ -243,7 +262,4 @@ export interface Codec<TEvent, TMessage> {
 
   /** Whether an event signals stream completion (finish, error, abort). */
   isTerminal(event: TEvent): boolean;
-
-  /** Return a stable key for a message (used by MessageStore for upsert/delete). */
-  getMessageKey(message: TMessage): string;
 }