@adzenai/ai 1.1.0 → 1.2.0

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,67 @@ 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`, and the `onInlineAd` / `onPlacement` / `onError` / `onStreamStart` / `onStreamEnd` callbacks.
+
+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