@brinkcommerce/agentic-shopping-sdk 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -12,9 +12,7 @@ Node 20 or later. The SDK uses the global `fetch` and `crypto`, and older versio
 
 ## Why there are two halves
 
-A browser cannot call the agent. There are two reasons, and each one is enough on its own. The client secret that mints the bearer token must never reach a page. The agent endpoint also sends no CORS headers, so the browser would block the request even if the secret were public.
-
-Every deployment therefore looks like this:
+A browser cannot call the agent. The client secret that mints the bearer token must never reach a page, and the agent sends no CORS headers. So every deployment has a server in the middle:
 
 ```text
 browser  ──POST /api/chat──▶  your server  ──POST /invocations──▶  the agent
@@ -24,6 +22,74 @@ browser  ──POST /api/chat──▶  your server  ──POST /invocations─
 
 `@brinkcommerce/agentic-shopping-sdk/server` is the middle box. `@brinkcommerce/agentic-shopping-sdk` is what the browser imports. It holds no credentials and never calls the agent.
 
+## Quickstart
+
+Brink provides the four `AGENT_*` values. `storeGroupId` and `market` are the store your storefront is already rendering.
+
+```ts
+// lib/agent.ts — server only. Module scope, so one token serves every turn.
+import { AgentShoppingClient } from '@brinkcommerce/agentic-shopping-sdk/server'
+
+export const client = new AgentShoppingClient({
+  runtimeArn: process.env.AGENT_RUNTIME_ARN!,
+  tokenUrl: process.env.AGENT_TOKEN_URL!,
+  clientId: process.env.AGENT_CLIENT_ID!,
+  clientSecret: process.env.AGENT_CLIENT_SECRET!,
+})
+```
+
+```ts
+// app/api/chat/route.ts
+import { createChatRoute } from '@brinkcommerce/agentic-shopping-sdk/server'
+import { client } from '@/lib/agent'
+
+export const runtime = 'nodejs'
+export const maxDuration = 60
+export const POST = createChatRoute(client)
+```
+
+```ts
+// the browser
+import { parseWireEvents, createSessionId, isWireEvent } from '@brinkcommerce/agentic-shopping-sdk'
+
+const sessionId = createSessionId() // one per conversation, not one per mount
+
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ prompt, sessionId, storeGroupId, market }),
+})
+if (!response.ok || !response.body) throw new Error(`the turn failed: ${response.status}`)
+
+for await (const event of parseWireEvents(response.body)) {
+  if (isWireEvent(event, 'text')) appendText(event.content)
+  if (isWireEvent(event, 'products')) setProducts(event.products) // replaces, never appends
+  if (isWireEvent(event, 'done')) setDone()
+}
+```
+
+Then render the reply, with each card under the paragraph that names it:
+
+```tsx
+import { interleaveProducts, formatPrice } from '@brinkcommerce/agentic-shopping-sdk'
+
+const { segments } = interleaveProducts(text, products)
+
+segments.map((segment) =>
+  segment.type === 'text' ? (
+    <Markdown>{segment.content}</Markdown>
+  ) : (
+    <Card
+      key={segment.product.productId}
+      product={segment.product}
+      price={formatPrice(segment.product.salePriceAmount, segment.product.currencyCode, 'sv-SE')}
+    />
+  )
+)
+```
+
+That is a working integration. Everything below is the detail behind it, starting with the four traps that break one.
+
 ---
 
 ## Four things that break an integration
@@ -41,17 +107,6 @@ Each one fails quietly. None of them throws.
 
 ## Setup
 
-```ts
-import { AgentShoppingClient } from '@brinkcommerce/agentic-shopping-sdk/server'
-
-export const client = new AgentShoppingClient({
-  runtimeArn: process.env.AGENT_RUNTIME_ARN!,
-  tokenUrl: process.env.AGENT_TOKEN_URL!,
-  clientId: process.env.AGENT_CLIENT_ID!,
-  clientSecret: process.env.AGENT_CLIENT_SECRET!,
-})
-```
-
 Brink provides all four values. `scope` is optional and defaults to `agentic-shopping/invoke`.
 
 A runtime ARN looks like this:
@@ -72,14 +127,6 @@ The client mints a token on the first turn. It caches it in the process until a
 
 ## Next.js route handler
 
-```ts
-// app/api/chat/route.ts
-import { createChatRoute } from '@brinkcommerce/agentic-shopping-sdk/server'
-import { client } from '@/lib/agent'
-
-export const POST = createChatRoute(client)
-```
-
 `createChatRoute` takes a standard `Request` and returns a `Response`. It has no Next.js dependency, so it works in any framework with the same shape.
 
 Four things to get right in a Next.js handler:
@@ -244,17 +291,11 @@ One thing follows from that while a reply streams: a card stays in `unmatched` u
 
 ## The reply is markdown
 
-The agent writes markdown into `text`: `**bold**` around product names, and `##` headings on longer answers. That is all it writes today, and what it writes follows its own prompt rather than this SDK's version. It writes no tables, no bullet lists and no strikethrough, so a renderer plugin for those is provisioning for output that never comes.
+The agent writes markdown into `text`: `**bold**` around product names, and `##` headings on longer answers. No tables, no bullet lists and no strikethrough, so a renderer plugin for those has nothing to render.
 
 `interleaveProducts` returns data, not markup, so rendering is yours to do. Use a real markdown renderer rather than a regex.
 
-**A segment never carries half a markdown construct**, so you can send each one to a renderer on its own. A segment boundary is always a blank line, and the agent opens and closes `**bold**` on one line:
-
-```text
-**W SPRAY GORE TEX JACKET** [product:2212103-120] — 2,800 SEK
-```
-
-The exception is a markdown block that spans a blank line itself: a loose list, or a fenced block with an empty line in it. The agent writes neither today. If it starts, that block renders as two blocks.
+**A segment never carries half a markdown construct**, so you can send each one to a renderer on its own. A segment boundary is always a blank line, and the agent opens and closes `**bold**` on one line.
 
 Handle one more thing while a reply streams: a `**` whose closing pair has not arrived yet. Render the unclosed span as plain words, so only the weight arrives late. Hiding it instead makes words appear and disappear as the shopper reads. A marker is the opposite case. Keep it hidden until it closes, because a half-written marker is not text the shopper should ever see.
 
@@ -293,11 +334,9 @@ The cart is Brink's, not the agent's, so it is out of scope here. Use [`@brinkco
 
 Get one thing right at the handoff: **`productVariantId` is the only id `POST /sessions/items` accepts.** `productParentId` is for the PDP and `productId` is for variant lookups. Neither is ever a cart id. Falling back to one when no variant is selected is a guaranteed rejected add. Gate the add on a chosen variant instead.
 
-Wire the cart up properly and a shopper can go from question to purchase without leaving the conversation.
-
 ## Store context
 
-`storeGroupId` and `market` are the store group and market your storefront is already rendering. Send both on every turn. There is no default and no fallback, because a storefront that spans several store groups knows which one it is on before the chat opens.
+`storeGroupId` and `market` are the store group and market your storefront is already rendering. Send both on every turn. There is no default and no fallback.
 
 - **`storeGroupId`** is an opaque Brink id. The merchant picks it, and the agent matches it exactly, case included. Pass it whole and do not normalise it. It looks like `sail-racing-se`.
 - **`market`** is the store market's two-letter country code, which the agent upper-cases. `SE`, not `sv-SE` and not `Sweden`.
@@ -353,7 +392,7 @@ A cached token refused with a 401 is re-minted and the turn is retried once. A t
 
 So a browser has two failures to handle, and they look nothing alike. A 400 or a 502 is a JSON body with an `error` string, and there is no stream to read. A failed turn is an ordinary 200 stream carrying one apologetic sentence.
 
-**A failed turn is not an HTTP failure.** This is the one that surprises people. Four cases arrive as a `text` + `done` pair at **HTTP 200**: a turn that broke mid-answer, a request naming no store, a request naming a store the agent does not serve, and a store conflict. The protocol has no error channel. `response.ok` sees nothing but success, and the shopper gets one apologetic sentence where a reply should be.
+**A failed turn is not an HTTP failure.** Four cases arrive as a `text` + `done` pair at **HTTP 200**: a turn that broke mid-answer, a request naming no store, a request naming a store the agent does not serve, and a store conflict. The protocol has no error channel. `response.ok` sees nothing but success, and the shopper gets one apologetic sentence where a reply should be.
 
 The store cases are your bug rather than the shopper's, and this SDK makes them unrepresentable. `storeGroupId` and `market` are both required in `AskInput`, and `createChatRoute` rejects a payload missing either with a 400 rather than forwarding a request that would come back as one sentence.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brinkcommerce/agentic-shopping-sdk",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "TypeScript SDK for the Brink Commerce agentic shopping agent",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,8 @@
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js",
       "require": "./dist/server.cjs"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsup src/index.ts src/server.ts --format esm,cjs --dts --clean",