;
};
export const llmPrompt = `Build a complete, runnable Next.js AI chat storefront that lets users discover products through conversation and purchase them using Rye's Universal Checkout API and Stripe for payment. Use the official Rye TypeScript SDK (checkout-intents) for all Rye API calls.
## What Rye Does
Rye is a commerce API that lets you sell products from any merchant (Amazon, Shopify, etc.) in your app. You provide a product URL and buyer details, Rye fetches pricing/shipping from the merchant, and you confirm with a Stripe payment token to place the order.
## Tech Stack
- Next.js App Router with TypeScript and Tailwind CSS
- checkout-intents SDK (npm install checkout-intents) for Rye API calls
- Vercel AI SDK (ai, @ai-sdk/openai, @ai-sdk/react) for streaming chat with tool-calling
- Stripe Elements (@stripe/stripe-js, @stripe/react-stripe-js) for card tokenization
- cheerio and react-markdown for parsing and rendering
## Environment Variables
OPENAI_API_KEY=sk-...
CHECKOUT_INTENTS_API_KEY=
CHECKOUT_INTENTS_BASE_URL=https://staging.api.rye.com
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51LgDhrHGDlstla3fdqlULAne0rAf4Ho6aBV2cobkYQ4m863Sy0W8DNu2HOnUeYTQzQnE4DZGyzvCB8Yzl1r38isl00H9sVKEMu
## Architecture
IMPORTANT: All Rye SDK calls MUST happen server-side. Never import or use the checkout-intents SDK in client components — the API key must stay on the server.
- Frontend (client components): Chat UI, checkout modal, Stripe CardElement. Calls internal Next.js API routes via fetch.
- Backend (Next.js Route Handlers in app/api/): Uses the checkout-intents SDK to talk to Rye. The API key never leaves the server.
- Stripe's publishable key (NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY) is the only key safe for the client.
## Rye SDK Setup (server-side only, e.g. lib/rye.ts)
import CheckoutIntents from 'checkout-intents';
const client = new CheckoutIntents(); // reads CHECKOUT_INTENTS_API_KEY from env automatically
## Buyer Schema — EXACT FIELDS REQUIRED BY THE SDK
The checkout-intents SDK exports a Buyer type. You MUST use these exact field names (camelCase) — any deviation will cause a 422 validation error:
interface Buyer {
firstName: string; // required
lastName: string; // required
email: string; // required
phone: string; // required — plain string, e.g. "1234567890"
address1: string; // required
address2?: string; // optional
city: string; // required
province: string; // required — e.g. "NY", "CA" for US states
country: string; // required — 2-letter ISO code, e.g. "US"
postalCode: string; // required
}
Do NOT rename these fields (e.g. do not use "state" instead of "province", "zip" instead of "postalCode", "addressLine1" instead of "address1"). The buyer form in the UI must collect these exact fields and pass them unchanged to the SDK.
## Project Structure
app/
layout.tsx
page.tsx
api/
chat/route.ts — streaming chat endpoint with tool-calling (server-side)
checkout/create-intent/route.ts — POST: creates Rye checkout intent using SDK (server-side)
checkout/confirm-intent/route.ts — POST: confirms intent with Stripe token using SDK (server-side)
checkout/get-intent/route.ts — GET: retrieves intent state using SDK (server-side)
components/
Chat.tsx — main chat component with checkout modal state (client)
ChatInput.tsx — text input for sending messages (client)
CheckoutModal.tsx — modal: buyer form → order summary → Stripe card → confirmation (client)
messages/
Message.tsx — renders text and tool-result message parts (client)
ProductGalleryMessage.tsx — renders product cards with Buy buttons (client)
lib/
rye.ts — Rye SDK client instance and helper functions (SERVER-SIDE ONLY)
types.ts — ShoppingProduct interface
tools/
amazon.ts — Amazon product search tool (server-side, scrapes search results)
## Rye SDK Usage in Route Handlers (lib/rye.ts — SERVER-SIDE ONLY)
import CheckoutIntents from 'checkout-intents';
const client = new CheckoutIntents();
// Create checkout intent and poll until offer is ready
export async function createAndWaitForOffer(buyer, productUrl) {
return await client.checkoutIntents.createAndPoll({
buyer, productUrl, quantity: 1,
});
// Returns intent with state "awaiting_confirmation" and offer details:
// intent.offer.cost: { subtotal, tax, total } (each with amountSubunits, currencyCode)
// intent.offer.shipping: { availableOptions, selectedOptionId }
}
// Confirm with Stripe token and poll until completed
export async function confirmAndWaitForCompletion(intentId, stripeToken) {
return await client.checkoutIntents.confirmAndPoll(intentId, {
paymentMethod: { stripeToken, type: 'stripe_token' },
});
// Returns intent with state "completed" or "failed"
}
// Get current intent state
export async function getIntent(intentId) {
return await client.checkoutIntents.retrieve(intentId);
}
// Look up product details by URL
export async function lookupProduct(url) {
return await client.products.lookup({ url });
}
## AI SDK v6 — CRITICAL
In AI SDK v6, convertToModelMessages is ASYNC. You MUST await it:
messages: await convertToModelMessages(messages) // CORRECT
messages: convertToModelMessages(messages) // WRONG — causes "messages do not match ModelMessage[] schema" error
Also: toUIMessageStreamResponse() is the correct response method when using useChat.
## Stripe CardElement — CRITICAL: Prevent Unmounting
The Stripe Elements provider and CardElement MUST stay mounted throughout the entire checkout flow. If the CardElement is conditionally rendered (e.g. only shown during the payment step), it will unmount and Stripe will throw: "We could not retrieve data from the specified Element."
FIX: Always render the CardElement inside the Elements provider, but use CSS (display: none or a hidden class) to hide it during non-payment steps. Do NOT use conditional rendering ({step === 'payment' && }) — instead use:
. Also ensure the stripePromise is created once at module scope (const stripePromise = loadStripe(...)) and not recreated on re-renders.
## Key Features to Implement
1. Streaming chat using Vercel AI SDK useChat hook with tool-calling support
2. Server-side Amazon product search tool that returns product name, price, image, rating, and full product detail URL (https://www.amazon.com/dp/ASIN format)
3. Product gallery message component showing product cards with "Buy" buttons in the chat — this is the ONLY way products should be rendered. The LLM's system prompt should instruct it to NOT re-list products as text or markdown after the search tool returns results (e.g. set the system prompt to: "You are a helpful AI shopping assistant. When the searchProducts tool returns results, they will be displayed as interactive product cards automatically — do NOT list the products again in your text response. Just provide a brief conversational comment like 'Here are some options I found!' and let the product cards speak for themselves.")
4. Checkout modal flow: buyer info form → client calls /api/checkout/create-intent → server uses SDK to poll for offer → show order summary (subtotal, shipping, tax, total) → collect card via Stripe CardElement → client calls /api/checkout/confirm-intent → server uses SDK to confirm → show success/failure
5. Stripe CardElement integration using Rye's publishable key for card tokenization (client-side only). The CardElement must always be mounted (use CSS to hide/show) — never conditionally render it.
6. Auto-scroll chat, loading states, error handling
7. ALL Rye SDK calls happen in Route Handlers or lib/rye.ts — client components only call /api/ routes
## Amazon Search Tool
The server-side tool accepts a query string, fetches the Amazon search results page, and parses product data using cheerio. It MUST extract full Amazon product detail URLs in the format https://www.amazon.com/dp/ASIN (e.g. https://www.amazon.com/dp/B0CX23V2ZK). Extract the URL from the product link's href attribute — Amazon search result links contain the /dp/ASIN path. Never return just "https://www.amazon.com" as a product URL — every product must have its complete detail page URL with the /dp/ASIN path so that Rye can look up the product. The tool returns structured ShoppingProduct[] results with fields: name, price, imageUrl, rating, url.
## Product Display Rules — CRITICAL
When the search tool returns products, they MUST ONLY be displayed as product cards with a "Buy" button via the ProductGalleryMessage component (rendered from the tool-result message part). The LLM MUST NOT also list the products again as text, markdown links, or a numbered list with "View on Amazon" links. After the tool returns results, the assistant should only provide a brief conversational message (e.g. "Here are some options I found!") — the product gallery component already shows all the product details. Do NOT duplicate product information in the text response.
Generate the complete application with all files. Include a README with setup and run instructions. Make sure the .gitignore includes .env and .env.* so secrets are never committed to version control. After generating the code, ask the user for their Rye API key and OpenAI API key so you can update the .env or .env.local file with the actual CHECKOUT_INTENTS_API_KEY and OPENAI_API_KEY values. Also confirm which environment they want to use (staging or production) so you can set CHECKOUT_INTENTS_BASE_URL accordingly.`;
Learn how to build an agentic checkout flow: discover product URLs in chat, capture buyer identity, tokenize card details with Stripe, and confirm a Rye Checkout Intent to place the order.
## Who this is for
Developers building AI chat interfaces where users can buy physical products across Amazon, Shopify, and beyond. We’ll use the [Vercel AI SDK](https://ai-sdk.dev/docs/introduction) for tool-calling, [Stripe Elements](https://docs.stripe.com/payments/elements) for card collection, and Universal Checkout API for submitting orders via Checkout Intents.
## What you'll build
A minimal Next.js app with a streaming chat. The assistant can:
1. Search Amazon (and the wider web) to surface real product URLs.
2. Show a Buy button next to results.
3. Open a modal that collects buyer identity (name, email, phone) and creates a Checkout Intent with Rye.
4. Collect card details using Stripe Card Element and tokenize on the client.
5. Confirm the Checkout Intent by sending the Stripe token to Rye, which places the order on the third‑party site.
We'll do this with clean file boundaries so you can drop this into an existing project.
## See Rye in Action
Watch a complete order flow — from product URL to purchase confirmation — all without leaving your app.
```mermaid theme={null}
sequenceDiagram
autonumber
actor User as End User (Browser)
participant Stripe as Stripe
participant Next as Next.js
participant Rye as Rye API
participant Merchant as Merchant (Amazon/Shopify)
User->>Next: "Find stainless steel bottle under $30"
Next-->>User: Streaming chat + product gallery
User->>Next: Click "Buy" (opens modal)
User->>Next: Submit Buyer Info + Product URL
Next->>Rye: POST /checkout-intents {buyer, productUrl}
Rye->>Merchant: Fetch price/availability/shipping
Merchant-->>Rye: Offer (subtotal, tax, shipping)
Rye-->>Next: Checkout Intent(state=retrieving_offer)
Next-->>User: Show Order Summary when awaiting_confirmation
User->>Stripe: Enter card in Card Element
Stripe-->>User: payment method (token)
User->>Next: POST /confirm-intent (checkoutIntentId, token)
Next->>Rye: POST /checkout-intents/:id/confirm (token)
Rye->>Merchant: Place order
Merchant-->>Rye: Order result
Rye-->>Next: CheckoutIntent(state=completed|failed)
Next-->>User: "Order placed!"
```
You can follow along step-by-step, or [clone the demo repo](https://github.com/cjavdev/rye-ai-chatbot) to run the example.
## Assumptions
* Next.js App Router on Node 18+.
* You have a Rye API key and will start in staging.
* You have Rye's Stripe publishable key
* Staging: `pk_test_51LgDhrHGDlstla3fdqlULAne0rAf4Ho6aBV2cobkYQ4m863Sy0W8DNu2HOnUeYTQzQnE4DZGyzvCB8Yzl1r38isl00H9sVKEMu`
* We'll use the [AI SDK's tool-calling](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling) with OpenAI, but you can use a different LLM provider if you'd like.
## Project structure
This is the general structure of the application and how we'll organize our files.
```
app/
layout.tsx
page.tsx
api/
chat/route.ts
checkout/create-intent/route.ts
checkout/confirm-intent/route.ts
checkout/get-intent/route.ts
components/
Chat.tsx
ChatInput.tsx
CheckoutModal.tsx
messages/
Message.tsx
ProductGalleryMessage.tsx
lib/
rye.ts
types.ts
tools/
amazon.ts
```
If you prefer server actions instead of route handlers, you can mirror the same logic in `app/actions.tsx`.
## Setup
Create the starter template:
```bash theme={null}
npx create-next-app@latest
```
These are the options we'll use for the demo:
```bash theme={null}
Need to install the following packages:
create-next-app@15.5.0
Ok to proceed? (y) y
✔ What is your project named? … my-app
✔ Would you like to use TypeScript? … Yes
✔ Which linter would you like to use? › None
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like your code inside a `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to use Turbopack? (recommended) … No
✔ Would you like to customize the import alias (`@/*` by default)? … Yes
Creating a new Next.js app in /Users/cjav_dev/repos/rye/demo-test/my-app.
```
### Add dependencies
First, install libraries for working with LLMs:
```bash theme={null}
npm install ai @ai-sdk/openai @ai-sdk/react zod
```
Next, we'll install some libraries for collecting payment methods:
```bash theme={null}
npm install @stripe/stripe-js @stripe/react-stripe-js
```
We'll use these tools for working rendering markdown and parsing HTML.
```bash theme={null}
npm install cheerio react-markdown
```
### Set environment variables
Create a `.env` file with these environment variables set.
| | |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENAI_API_KEY` | [https://platform.openai.com/settings/organization/api-keys](https://platform.openai.com/settings/organization/api-keys) |
| `RYE_API_KEY` | [https://staging.console.rye.com/account](https://staging.console.rye.com/account) |
| `RYE_API_BASE` | Either [https://staging.console.rye.com/account](https://staging.console.rye.com/account) or [https://console.rye.com/account](https://console.rye.com/account) |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Use Rye's Stripe Publishable Key. |
```bash theme={null}
// .env
OPENAI_API_KEY=sk-...
RYE_API_KEY=U... # https://staging.console.rye.com/account or https://console.rye.com/account
RYE_API_BASE=https://staging.api.rye.com
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51LgDhrHGDlstla3fdqlULAne0rAf4Ho6aBV2cobkYQ4m863Sy0W8DNu2HOnUeYTQzQnE4DZGyzvCB8Yzl1r38isl00H9sVKEMu
```
At this point, you should be able to run `npm run dev` and load the starter app in the browser.
## 1. Create a basic AI Chat app
We'll build this chat-based storefront incrementally, starting with a basic AI chat interface that we'll progressively enhance with commerce capabilities. This approach allows us to establish the core conversational flow first, then layer on product search tools, checkout flows, and payment processing. By the end, you'll have a complete chat experience where users can discover products through natural conversation, review detailed offers with real-time shipping and tax calculations, and complete purchases seamlessly—all powered by Rye's commerce infrastructure.
### Set up minimal layout
Before we dive into chat components, let's set up a minimal layout.
```ts app/layout.tsx theme={null}
import "./globals.css";
import Link from 'next/link'
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
Rye Demo
{children}
);
}
```
```ts app/page.tsx theme={null}
import Chat from "./components/Chat";
export default function Home() {
return (
);
}
```
### Set up the chat API endpoint
To connect our chat interface to an AI model, we need to set up a server-side API route that handles streaming responses from OpenAI's GPT-5. This endpoint will process incoming messages, send them to the language model, and stream back responses that our client-side chat components can display in real-time.
While we're starting with basic chat functionality, this foundation is designed to easily accommodate tools for product search and other enhanced features later.
```ts app/api/chat/route.ts theme={null}
import { openai } from '@ai-sdk/openai';
import {
convertToModelMessages,
InferUITools,
stepCountIs,
streamText,
UIDataTypes,
UIMessage,
} from 'ai';
// TODO: Add tools to handle product discovery.
const tools = {};
export type UseChatToolsMessage = UIMessage<
never,
UIDataTypes,
InferUITools
>;
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-5'),
system: `You are a helpful AI assistant that can search for products on Amazon and assist with various tasks.`,
messages: await convertToModelMessages(messages),
stopWhen: stepCountIs(3), // multi-steps for server-side tools
tools,
});
return result.toUIMessageStreamResponse({
originalMessages: messages
});
}
```
### Build the chat interface
The chat components handle user input, display responses, and provide the foundation for our upcoming product search and checkout features. For now, they manage basic messaging—we'll add search results, Buy buttons, and checkout modals next.
The Chat component will eventually manage our Checkout Modal and rendering fulfillment messages, but to start it'll contain a stream of messages.
The `useChat` hook allows us to connect to the Next.js server endpoint that calls the LLM provider.
```ts app/components/Chat.tsx theme={null}
'use client';
import ChatInput from './ChatInput';
import Message from './messages/Message';
import { useChat } from '@ai-sdk/react';
import {
DefaultChatTransport,
lastAssistantMessageIsCompleteWithToolCalls,
} from 'ai';
import { UseChatToolsMessage } from '@/app/api/chat/route';
import { useEffect, useRef, useState } from 'react';
export default function Chat() {
const messagesEndRef = useRef(null);
const { messages, sendMessage, addToolResult, status } =
useChat({
transport: new DefaultChatTransport({ api: '/api/chat' }),
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});
useEffect(() => {
messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
}, [messages]);
return (
);
}
```
The `ChatInput` component provides a text area for users to type and submit messages.
```ts app/components/ChatInput.tsx theme={null}
import { useState } from 'react';
export default function ChatInput({
status,
onSubmit,
}: {
status: string;
onSubmit: (text: string) => void;
}) {
const [text, setText] = useState('');
return (
