@ably/ai-transport 0.0.1 → 0.2.0

package/dist/utils.d.ts

@@ -7,11 +7,21 @@
  */
 import type * as Ably from 'ably';
 /**
- * Extract extras.headers from an Ably InboundMessage.
+ * Extract the transport-tier headers (`extras.ai.transport`) from an Ably
+ * InboundMessage. These are the generic transport headers (run/stream/identity/
+ * branching), set and read by the transport layer.
  * @param message - The Ably message to extract headers from.
- * @returns The headers record, or an empty object if absent.
+ * @returns The transport headers record, or an empty object if absent.
  */
-export declare const getHeaders: (message: Ably.InboundMessage) => Record<string, string>;
+export declare const getTransportHeaders: (message: Ably.InboundMessage) => Record<string, string>;
+/**
+ * Extract the codec-tier headers (`extras.ai.codec`) from an Ably
+ * InboundMessage. These are the codec's own headers, with no prefix — the
+ * tier isolates them from transport headers.
+ * @param message - The Ably message to extract headers from.
+ * @returns The codec headers record, or an empty object if absent.
+ */
+export declare const getCodecHeaders: (message: Ably.InboundMessage) => Record<string, string>;
 /**
  * Parse a JSON string, returning undefined on failure.
  * @param value - The JSON string to parse.
@@ -26,13 +36,6 @@ export declare const parseJson: (value: string | undefined) => unknown;
  * @param value - The value to set.
  */
 export declare const setIfPresent: (headers: Record<string, string>, key: string, value: unknown) => void;
-/**
- * Set multiple headers at once, skipping entries whose values are undefined or null.
- * Each value is converted using the same rules as {@link setIfPresent}.
- * @param headers - The headers object to mutate.
- * @param entries - Key-value pairs to set.
- */
-export declare const setHeadersIfPresent: (headers: Record<string, string>, entries: Record<string, unknown>) => void;
 /**
  * Merge two header records into a new object. Later values override earlier ones.
  * Undefined inputs are treated as empty.
@@ -47,19 +50,24 @@ export declare const mergeHeaders: (base: Record<string, string> | undefined, ov
  * @returns True if "true", false for any other string, or undefined if absent.
  */
 export declare const parseBool: (value: string | undefined) => boolean | undefined;
+/** A record carrying an optional Ably `serial`, orderable by {@link compareBySerial}. */
+interface HasSerial {
+    /** Ably serial, or undefined if the server has not yet assigned one. */
+    readonly serial?: string;
+}
 /**
- * Build a domain headers record from key-value pairs. Each key is automatically
- * prefixed with {@link DOMAIN_HEADER_PREFIX}. Values that are undefined or null
- * are skipped; strings are set directly; booleans, numbers, and objects are
- * converted using the same rules as {@link setIfPresent}.
- * @param entries - Unprefixed key-value pairs (e.g. `{ toolCallId: 'tc-1' }` becomes `{ 'x-domain-toolCallId': 'tc-1' }`).
- * @returns A new headers record with prefixed keys.
+ * Comparator that orders records by their Ably `serial` ascending
+ * (chronological). Serials are lexicographically comparable; records whose
+ * serial is undefined sort last. Pass directly to `Array.prototype.sort`.
+ * @param a - First record to compare.
+ * @param b - Second record to compare.
+ * @returns Negative if `a` precedes `b`, positive if `a` follows `b`, 0 if equal.
  */
-export declare const domainHeaders: (entries: Record<string, unknown>) => Record<string, string>;
+export declare const compareBySerial: (a: HasSerial, b: HasSerial) => number;
 /**
- * Read a domain header value from a headers record.
- * @param headers - The headers record to read from.
- * @param key - The unprefixed domain key (e.g. `'toolCallId'` reads `'x-domain-toolCallId'`).
+ * Read a domain header value from a codec-tier headers record.
+ * @param headers - The codec headers record to read from.
+ * @param key - The domain key (e.g. `'toolCallId'`).
  * @returns The header value, or undefined if absent.
  */
 export declare const getDomainHeader: (headers: Record<string, string>, key: string) => string | undefined;
@@ -94,7 +102,7 @@ export interface DomainHeaderReader {
     str(key: string): string | undefined;
     /** Read a domain header as a string, falling back to a default if absent. */
     strOr(key: string, fallback: string): string;
-    /** Read a domain header as a boolean ("true"/"false"), or undefined if absent. */
+    /** Read a domain header as a boolean: `true` only for the exact string "true", `false` for any other present value, or undefined if absent. */
     bool(key: string): boolean | undefined;
     /** Read a domain header as parsed JSON, or undefined if absent or invalid. */
     json(key: string): unknown;
@@ -121,7 +129,8 @@ export interface DomainHeaderWriter {
     build(): Record<string, string>;
 }
 /**
- * Create a {@link DomainHeaderWriter} for building a domain headers record.
- * @returns A fluent builder that prefixes each key with the domain header prefix.
+ * Create a {@link DomainHeaderWriter} for building a codec-tier headers record.
+ * @returns A fluent builder that accumulates codec headers under their bare keys.
  */
 export declare const headerWriter: () => DomainHeaderWriter;
+export {};