@adzenai/ai 1.1.1 → 1.2.1

package/README.md

@@ -51,8 +51,8 @@ dispatchPlacementEvents(events);
 | Path | Environment | Provides |
 | --- | --- | --- |
 | `@adzenai/ai` | Any | Core type re-exports (`AdzenPlacement`, `ProcessResponse`, `ProcessResponseAd`) |
-| `@adzenai/ai/copilotkit` | Server or client | `AdzenAsyncMiddleware`, `AdzenAsyncConfig` |
-| `@adzenai/ai/copilotkit/react` | Browser (React 18+) | `AdzenCard`, `useAdzenPlacement`, `dispatchPlacementEvent(s)` |
+| `@adzenai/ai/copilotkit` | Async: server or client. Stream: server only. | `AdzenAsyncMiddleware`, `AdzenAsyncConfig`, `AdzenStreamMiddleware`, `AdzenStreamConfig` |
+| `@adzenai/ai/copilotkit/react` | Browser (React 18+) | `AdzenCard`, `InlineAd`, `useAdzenPlacement`, `useAdzenInlineAds`, `buildInlineAdSegments`, `dispatchPlacementEvent(s)` |
 
 ## How It Works
 
@@ -66,19 +66,74 @@ Impression beacons are fired as client-side GET requests directly to the deliver
 
 The middleware is **additive only** — it never modifies, blocks, or delays the original event stream. All failures degrade silently.
 
+## Streaming Enrichment
+
+`AdzenStreamMiddleware` proxies the LLM response stream through Adzen's `/stream` endpoint for in-message ads, instead of waiting for the completed message. Tee the upstream response so one branch feeds AG-UI parsing and the other is piped to Adzen:
+
+```typescript
+const [parseBranch, proxyBranch] = res.body!.tee();
+
+for await (const evt of adzen.processStream(parseIntoAgUiEvents(parseBranch), {
+  prompt,
+  upstreamBody: proxyBranch,
+})) {
+  sendToClient(evt);
+}
+```
+
+**Server-side only (Node 18+).** It passes a `ReadableStream` as the fetch request body; browsers other than Chromium do not support this and coerce the stream to the string `"[object ReadableStream]"`. The SDK feature-detects and emits an `adzen_error` rather than sending a corrupted body.
+
+### Rendering inline ads
+
+Inline ads carry a `content_offset` — the number of message characters streamed before the ad arrived — so they render at that point in the text rather than at the end of the message. `getInlineAdSegments()` does the splitting:
+
+```tsx
+const { getInlineAdSegments } = useAdzenInlineAds();
+
+<div style={{ whiteSpace: "pre-wrap" }}>
+  {getInlineAdSegments(msg.id, msg.content).map((segment, i) =>
+    segment.kind === "text" ? (
+      <span key={i}>{segment.text}</span>
+    ) : (
+      <InlineAd key={segment.ad.ad_id} ad={segment.ad} />
+    ),
+  )}
+</div>
+```
+
+`InlineAd` renders as a plain text snippet — an "Ad" pill, the advertiser name, and the CTA as the only link (`[AD] Brooks Brothers clothing sale`) — and is block-level, so it appears on its own line directly below the text it follows. The advertiser text uses `creative.advertiser_name`, falling back to `creative.headline`.
+
+Anchors are snapped forward to the next paragraph break, so segments are always whole paragraphs and each one can be passed to a Markdown renderer (`<Markdown>{segment.text}</Markdown>`) without a split breaking `**bold text**`, a list, or a code fence.
+
+At most one ad is placed per paragraph break. Ads that would land on an already-used break move to the next free one (the end of the message counts as a slot), and any that still have nowhere to go are held back until the message grows, rather than stacking in one spot.
+
 ## Configuration
 
 ```typescript
 new AdzenAsyncMiddleware({
   apiKey: string;           // required — Adzen API key
-  endpointUrl?: string;     // default: "https://api.adzen.ai/v1/ai"
+  endpointUrl?: string;     // default: "https://api.adzen.ai/v1"
   timeoutMs?: number;       // default: 3000
   adUnitPosition?: string;  // default: "chin"
   location?: string;        // optional — DMA location code for geo-targeting
   conversationId?: string;  // optional — links impressions to conversation context
+  profileId?: string;       // optional — sent as X-Profile-Id where APIM does not inject it
 });
 ```
 
+`endpointUrl` is a base URL; the SDK appends `/process` and `/stream`. Include any environment-specific path prefix (such as `/ai` on stage and prod) in the value you pass.
+
+`AdzenStreamMiddleware` accepts the same options plus `prefetch` (POST `/process` with the prompt before opening the stream), `placementPollIntervalMs`, `sidecar`, and the `onInlineAd` / `onPlacement` / `onError` / `onStreamStart` / `onStreamEnd` callbacks.
+
+<!-- INTERNAL / DEBUGGING-MODE ONLY — do not surface in the public shared-vision/developer-docs.
+There is also an optional `headers` (`Record<string, string>`) option, merged into every outbound
+Adzen request (`/stream`, `/process`, placement polling) for internal debugging (e.g. `X-Adzen-Debug-*`).
+SDK-managed headers (auth, content-type, correlation IDs) always take precedence. -->
+
+
+
+The middleware never makes the assistant message wait on the ad pipeline: the prefetch is dispatched without being awaited, and content events are forwarded as they arrive whether or not an ad has been matched yet.
+
 ## License
 
 MIT

package/dist/copilotkit/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/copilotkit/index.ts
 var copilotkit_exports = {};
 __export(copilotkit_exports, {
-  AdzenAsyncMiddleware: () => AdzenAsyncMiddleware
+  AdzenAsyncMiddleware: () => AdzenAsyncMiddleware,
+  AdzenStreamMiddleware: () => AdzenStreamMiddleware
 });
 module.exports = __toCommonJS(copilotkit_exports);
 
@@ -63,7 +64,7 @@ var AdzenAsyncMiddleware = class {
   constructor(config) {
     this.config = {
       ...config,
-      endpointUrl: config.endpointUrl ?? "https://api.adzen.ai/v1/ai",
+      endpointUrl: config.endpointUrl ?? "https://api.adzen.ai/v1",
       timeoutMs: config.timeoutMs ?? 3e3,
       adUnitPosition: config.adUnitPosition ?? "chin"
     };
@@ -176,15 +177,17 @@ var AdzenAsyncMiddleware = class {
       };
       if (this.config.location) body.location = this.config.location;
       if (this.conversationId) body.conversation_id = this.conversationId;
+      const headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": this.config.apiKey,
+        // AI-API requires an Idempotency-Key on /process (400 otherwise).
+        // One per ad fetch — each completed message is a distinct request.
+        "Idempotency-Key": generateIdempotencyKey()
+      };
+      if (this.config.profileId) headers["X-Profile-Id"] = this.config.profileId;
       const res = await fetch(`${this.config.endpointUrl}/process`, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-API-Key": this.config.apiKey,
-          // AI-API requires an Idempotency-Key on /process (400 otherwise).
-          // One per ad fetch — each completed message is a distinct request.
-          "Idempotency-Key": generateIdempotencyKey()
-        },
+        headers,
         body: JSON.stringify(body),
         signal: controller.signal
       });
@@ -229,8 +232,476 @@ var AdzenAsyncMiddleware = class {
     };
   }
 };
+
+// src/copilotkit/AdzenStreamClient.ts
+var import_core = require("@adzenai/core");
+
+// src/copilotkit/parseSSE.ts
+async function* parseSSE(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let currentEvent;
+  let dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop();
+      for (const raw of lines) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line === "") {
+          if (dataLines.length > 0) {
+            yield { event: currentEvent, data: dataLines.join("\n") };
+            dataLines = [];
+            currentEvent = void 0;
+          }
+          continue;
+        }
+        if (line.startsWith(":")) continue;
+        const colonIdx = line.indexOf(":");
+        if (colonIdx === -1) continue;
+        const field = line.slice(0, colonIdx);
+        const value2 = line.slice(colonIdx + 1).replace(/^ /, "");
+        switch (field) {
+          case "data":
+            dataLines.push(value2);
+            break;
+          case "event":
+            currentEvent = value2;
+            break;
+        }
+      }
+    }
+    if (dataLines.length > 0) {
+      yield { event: currentEvent, data: dataLines.join("\n") };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/copilotkit/AdzenStreamClient.ts
+var DEFAULT_ENDPOINT = "https://api.adzen.ai/v1";
+var DEFAULT_TIMEOUT_MS = 3e3;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var SUPPORTS_REQUEST_STREAMS = (() => {
+  try {
+    let duplexAccessed = false;
+    const hasContentType = new Request("http://localhost", {
+      method: "POST",
+      body: new ReadableStream(),
+      get duplex() {
+        duplexAccessed = true;
+        return "half";
+      }
+    }).headers.has("Content-Type");
+    return duplexAccessed && !hasContentType;
+  } catch {
+    return false;
+  }
+})();
+var AdzenStreamClient = class {
+  endpointUrl;
+  apiKey;
+  timeoutMs;
+  location;
+  profileId;
+  placementPollIntervalMs;
+  prefetchEnabled;
+  sidecarEnabled;
+  customHeaders;
+  conversationId;
+  abortController = null;
+  placementEndpoint = null;
+  pollTimer = null;
+  streamEnded = false;
+  inlineAdQueue = [];
+  streamPromise = null;
+  prefetchPromise = null;
+  onInlineAd;
+  onPlacement;
+  onError;
+  onStreamStart;
+  onStreamEnd;
+  constructor(config) {
+    this.endpointUrl = config.endpointUrl ?? DEFAULT_ENDPOINT;
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.location = config.location;
+    this.profileId = config.profileId;
+    this.placementPollIntervalMs = config.placementPollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.prefetchEnabled = config.prefetch ?? false;
+    this.sidecarEnabled = config.sidecar ?? true;
+    this.customHeaders = config.headers ?? {};
+    this.conversationId = config.conversationId ?? (0, import_core.uuidv4)();
+    this.onInlineAd = config.onInlineAd;
+    this.onPlacement = config.onPlacement;
+    this.onError = config.onError;
+    this.onStreamStart = config.onStreamStart;
+    this.onStreamEnd = config.onStreamEnd;
+  }
+  getConversationId() {
+    return this.conversationId;
+  }
+  setConversationId(id) {
+    this.conversationId = id;
+  }
+  /**
+   * Dispatches the prefetch without waiting for it.
+   *
+   * The request leaves before `connect()` opens `/stream`, which is all the
+   * 2-step chained flow needs — the two calls are correlated server-side by
+   * `conversation_id`. Awaiting the response here would stall the assistant
+   * message behind a full ad-matching round trip while the LLM keeps
+   * streaming, so the buffered tokens would then arrive in one burst.
+   */
+  startPrefetch(prompt) {
+    if (!this.prefetchEnabled) return;
+    this.prefetchPromise = this.prefetchProcess(prompt);
+  }
+  /**
+   * 2-step chained flow: POST /process with the user prompt and
+   * conversationId. Awaits the response (or timeout) but discards the
+   * result. If it fails, logs and continues — the stream will proceed
+   * in degraded mode.
+   */
+  async prefetchProcess(prompt) {
+    if (!this.prefetchEnabled) return;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const body = {
+        content: prompt,
+        message_id: (0, import_core.uuidv4)(),
+        conversation_id: this.conversationId
+      };
+      if (this.location) body.location = this.location;
+      const headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": this.apiKey,
+        "Idempotency-Key": (0, import_core.uuidv4)()
+      };
+      if (this.profileId) headers["X-Profile-Id"] = this.profileId;
+      await fetch(`${this.endpointUrl}/process`, {
+        method: "POST",
+        headers: this.mergeHeaders(headers),
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch {
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /**
+   * Opens a streaming POST to /stream, piping the upstream LLM response
+   * body directly. The API reads the raw LLM stream in real time and
+   * sends SSE ad events back on the response side.
+   *
+   * @param messageId  Unique ID for this assistant message
+   * @param body       The upstream LLM response body (one branch of a tee)
+   */
+  connect(messageId, body) {
+    this.streamEnded = false;
+    this.inlineAdQueue = [];
+    this.placementEndpoint = null;
+    this.streamPromise = null;
+    this.abortController = new AbortController();
+    if (!SUPPORTS_REQUEST_STREAMS) {
+      this.streamEnded = true;
+      this.onError?.({
+        type: "adzen_error",
+        code: "request_streams_unsupported",
+        message: "This runtime cannot send a ReadableStream as a request body, so the LLM stream cannot be proxied. Run AdzenStreamMiddleware server-side (Node 18+) \u2014 browsers other than Chromium do not support fetch upload streams."
+      });
+      void body.cancel().catch(() => {
+      });
+      return;
+    }
+    const headers = {
+      "Content-Type": "application/octet-stream",
+      "X-API-Key": this.apiKey,
+      "Idempotency-Key": (0, import_core.uuidv4)(),
+      "X-Message-Id": messageId,
+      "X-Conversation-Id": this.conversationId
+    };
+    if (this.profileId) headers["X-Profile-Id"] = this.profileId;
+    if (this.location) headers["X-Location"] = this.location;
+    this.streamPromise = this.executeStreamFetch(body, this.mergeHeaders(headers));
+  }
+  /**
+   * Waits for the SSE response stream from the API to finish, along with any
+   * prefetch still in flight. Neither can reject — both swallow their errors.
+   */
+  async finalize() {
+    await Promise.all([this.prefetchPromise, this.streamPromise]);
+  }
+  /**
+   * Merges caller-provided passthrough headers with the SDK's fixed headers.
+   * Fixed headers are spread last so SDK-managed keys (auth, content-type,
+   * correlation IDs) always win over any passthrough value.
+   */
+  mergeHeaders(fixed) {
+    return { ...this.customHeaders, ...fixed };
+  }
+  async executeStreamFetch(body, headers) {
+    const timeout = setTimeout(
+      () => this.abortController?.abort(),
+      this.timeoutMs
+    );
+    try {
+      const res = await fetch(`${this.endpointUrl}/stream`, {
+        method: "POST",
+        headers,
+        body,
+        signal: this.abortController?.signal,
+        // @ts-expect-error -- required for streaming request bodies (Node/undici)
+        duplex: "half"
+      });
+      clearTimeout(timeout);
+      if (!res.ok || !res.body) return;
+      await this.readStream(res.body);
+    } catch {
+      clearTimeout(timeout);
+    }
+  }
+  /** Drains and returns any queued inline ad events. */
+  drainInlineAds() {
+    const ads = this.inlineAdQueue.splice(0);
+    return ads;
+  }
+  /** Cancels pending requests and cleans up state. */
+  abort() {
+    this.abortController?.abort();
+    this.stopPolling();
+    this.streamEnded = true;
+  }
+  /** Polls the placement endpoint once. Called on an interval internally. */
+  async pollPlacements() {
+    if (!this.sidecarEnabled || !this.placementEndpoint) return;
+    try {
+      const res = await fetch(this.placementEndpoint, {
+        method: "GET",
+        headers: this.mergeHeaders({ "X-API-Key": this.apiKey })
+      });
+      if (!res.ok) return;
+      const data = await res.json();
+      for (const placement of data.placements) {
+        this.onPlacement?.(placement);
+      }
+    } catch {
+    }
+  }
+  async readStream(body) {
+    try {
+      for await (const frame of parseSSE(body)) {
+        if (this.abortController?.signal.aborted) break;
+        this.handleFrame(frame.event, frame.data);
+      }
+    } catch {
+    } finally {
+      this.streamEnded = true;
+      this.stopPolling();
+    }
+  }
+  handleFrame(event, data) {
+    switch (event) {
+      case "adzen_stream_start": {
+        try {
+          const parsed = JSON.parse(data);
+          const evt = { type: "adzen_stream_start", ...parsed };
+          this.placementEndpoint = parsed.placement_endpoint;
+          this.onStreamStart?.(evt);
+          this.startPolling();
+        } catch {
+        }
+        break;
+      }
+      case "adzen_inline": {
+        try {
+          const ad = JSON.parse(data);
+          this.inlineAdQueue.push(ad);
+          this.onInlineAd?.(ad);
+        } catch {
+        }
+        break;
+      }
+      case "adzen_error": {
+        try {
+          const parsed = JSON.parse(data);
+          this.onError?.({ type: "adzen_error", ...parsed });
+        } catch {
+        }
+        break;
+      }
+      case "adzen_stream_end": {
+        try {
+          const parsed = JSON.parse(data);
+          const evt = { type: "adzen_stream_end", ...parsed };
+          this.onStreamEnd?.(evt);
+        } catch {
+        }
+        this.streamEnded = true;
+        this.stopPolling();
+        break;
+      }
+      default: {
+        if (event?.startsWith("adzen_debug_")) break;
+        break;
+      }
+    }
+  }
+  startPolling() {
+    if (!this.sidecarEnabled) return;
+    if (this.pollTimer || !this.placementEndpoint) return;
+    this.pollTimer = setInterval(
+      () => this.pollPlacements(),
+      this.placementPollIntervalMs
+    );
+  }
+  stopPolling() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+};
+
+// src/copilotkit/streamMiddleware.ts
+var AdzenStreamMiddleware = class {
+  config;
+  adUnitPosition;
+  constructor(config) {
+    this.config = config;
+    this.adUnitPosition = config.adUnitPosition ?? "chin";
+  }
+  async *processStream(events, options) {
+    const sidecarPlacements = [];
+    let client = null;
+    let currentMessageId = "";
+    let contentOffset = 0;
+    const onPlacement = (record) => {
+      sidecarPlacements.push(this.mapPlacementRecord(record, currentMessageId));
+    };
+    const onError = (error) => {
+      console.warn(`[adzen-stream] ${error.code}: ${error.message}`);
+    };
+    for await (const event of events) {
+      const type = String(event.type ?? "");
+      switch (type) {
+        case "RUN_STARTED":
+        case "RunStarted": {
+          const threadId = String(event.threadId ?? "");
+          client = new AdzenStreamClient({
+            ...this.config,
+            conversationId: threadId || this.config.conversationId,
+            onPlacement,
+            onError
+          });
+          if (this.config.prefetch && options?.prompt) {
+            client.startPrefetch(options.prompt);
+          }
+          yield event;
+          break;
+        }
+        case "TEXT_MESSAGE_START":
+        case "TextMessageStart": {
+          currentMessageId = String(event.messageId ?? "");
+          contentOffset = 0;
+          if (client && options?.upstreamBody) {
+            client.connect(currentMessageId, options.upstreamBody);
+          }
+          yield event;
+          break;
+        }
+        case "TEXT_MESSAGE_CONTENT":
+        case "TextMessageContent": {
+          yield event;
+          contentOffset += String(event.delta ?? "").length;
+          if (client) {
+            for (const ad of client.drainInlineAds()) {
+              yield this.makeInlineAdEvent(ad, currentMessageId, contentOffset);
+            }
+          }
+          break;
+        }
+        case "TEXT_MESSAGE_END":
+        case "TextMessageEnd": {
+          if (client) {
+            await client.finalize();
+            for (const ad of client.drainInlineAds()) {
+              yield this.makeInlineAdEvent(ad, currentMessageId, contentOffset);
+            }
+          }
+          yield event;
+          break;
+        }
+        case "RUN_FINISHED":
+        case "RunFinished": {
+          if (client) {
+            await client.pollPlacements();
+            client.abort();
+          }
+          for (const placement of sidecarPlacements) {
+            yield this.makePlacementEvent(placement, placement.ad_id);
+          }
+          yield event;
+          break;
+        }
+        default:
+          yield event;
+      }
+    }
+  }
+  /**
+   * Wraps an inline ad as an AG-UI custom event anchored to `contentOffset`,
+   * the number of message characters emitted before the ad arrived. Clients
+   * use it to render the ad directly after that content instead of at the
+   * end of the message.
+   */
+  makeInlineAdEvent(ad, messageId, contentOffset) {
+    const value = {
+      ...ad,
+      message_id: messageId,
+      content_offset: contentOffset
+    };
+    return {
+      type: "CUSTOM_EVENT",
+      name: "adzen_inline_ad",
+      messageId,
+      value
+    };
+  }
+  makePlacementEvent(placement, adId) {
+    return {
+      type: "CUSTOM_EVENT",
+      name: "adzen_placement",
+      messageId: adId,
+      value: {
+        ...placement,
+        message_id: placement.ad_id
+      }
+    };
+  }
+  mapPlacementRecord(record, messageId) {
+    return {
+      ad_id: String(record.ad_id),
+      advertiser_name: "",
+      headline: record.headline,
+      cta_text: record.cta_text,
+      destination_url: record.destination_url,
+      adUnitPosition: record.placement || this.adUnitPosition,
+      render_impression_url: record.tracking.impression_url,
+      view_impression_url: record.tracking.impression_url
+    };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AdzenAsyncMiddleware
+  AdzenAsyncMiddleware,
+  AdzenStreamMiddleware
 });
 //# sourceMappingURL=index.cjs.map