npm package: @takeshape/purchase-order-chat
Description: BigCommerce purchase order chat UI components
Latest version: 1.60.1

# @takeshape/purchase-order-chat

A React component library for purchase order chat integration with BigCommerce Catalyst storefronts.

## Catalyst Quick Start

### Install

From your Catalyst project's `core` directory:

```bash
pnpm add @takeshape/purchase-order-chat
```

### Create a page

Create a new `page.tsx` somewhere, e.g. `app/[locale]/(default)/purchase-order-agent/page.tsx`

Copy and paste the following, and fill in the the required values:

```tsx
import { PurchaseOrderAgent } from "@takeshape/purchase-order-chat";

export default async function Page() {
  return (
    <div className="min-h-[800px] container mx-auto px-4 py-8 items-center justify-center flex">
      <PurchaseOrderAgent
        takeshape={{
          projectId: "your-project-id",
          apiKey: "your-api-key",
        }}
        bigcommerce={{
          endpoint: "https://store-{hash}.mybigcommerce.com/graphql",
          storefrontToken: "your-storefront-token",
          channelId: 1,
        }}
        productPath="/product/:sku"
        checkoutUrl="https://mysite.com/after-checkout"
      />
    </div>
  );
}
```

## Requirements

- React 19+
- Node 24+

## Choosing an Import

This library provides two entry points:

| Import                                    | Use Case                   | CSS Handling                        |
| ----------------------------------------- | -------------------------- | ----------------------------------- |
| `@takeshape/purchase-order-chat`          | Default - works everywhere | Shadow DOM with bundled CSS         |
| `@takeshape/purchase-order-chat/tailwind` | Tailwind v4 projects       | Integrates with your Tailwind setup |

### Default (recommended for most projects)

The default version wraps the component in a Shadow DOM with all styles bundled, ensuring no CSS conflicts with your existing styles.

```tsx
import { PurchaseOrderChat } from "@takeshape/purchase-order-chat";
```

### Advanced, for Tailwind v4 projects

This gives you more control, and allows for more efficient style generation.

```tsx
import { PurchaseOrderChat } from "@takeshape/purchase-order-chat/tailwind";
```

For BigCommerce Catalyst storefronts, the recommended approach uses a proxy API route to avoid CORS issues and keep your storefront token server-side.

### 1. Install the package

```bash
pnpm add @takeshape/purchase-order-chat
```

### 2. Configure Tailwind

Add the library's source files to your Tailwind config:

```css
/* In your global CSS file */
@import "tailwindcss";
/* Add these imports */
@import "@takeshape/purchase-order-chat/theme.css";
@import "@takeshape/purchase-order-chat/utilities.css";
@import "@takeshape/purchase-order-chat/sources.css";
```

### 3. Create a BigCommerce proxy route

Create `app/api/bigcommerce/graphql/route.ts`:

```typescript
import { NextRequest, NextResponse } from "next/server";

const BIGCOMMERCE_STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH;
const BIGCOMMERCE_STOREFRONT_TOKEN = process.env.BIGCOMMERCE_STOREFRONT_TOKEN;

export async function POST(request: NextRequest) {
  if (!BIGCOMMERCE_STORE_HASH || !BIGCOMMERCE_STOREFRONT_TOKEN) {
    return NextResponse.json(
      { errors: [{ message: "BigCommerce configuration missing" }] },
      { status: 500 },
    );
  }

  const body = await request.json();
  const response = await fetch(
    `https://store-${BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/graphql`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${BIGCOMMERCE_STOREFRONT_TOKEN}`,
      },
      body: JSON.stringify(body),
    },
  );

  const data = await response.json();
  return NextResponse.json(data, { status: response.status });
}
```

### 4. Create the page

Create `app/[locale]/(default)/purchase-order-agent/page.tsx`:

```tsx
"use client";

import { useRouter } from "~/i18n/routing";
import { PurchaseOrderChatWidget } from "@takeshape/purchase-order-chat/tailwind";

export default function PurchaseOrderAgentPage() {
  const router = useRouter();

  return (
    <div className="min-h-[800px] container mx-auto px-4 py-8 items-center justify-center flex">
      <PurchaseOrderChatWidget
        takeshape={{
          projectId: process.env.NEXT_PUBLIC_TAKESHAPE_PROJECT_ID!,
          apiKey: process.env.NEXT_PUBLIC_TAKESHAPE_API_KEY!,
        }}
        bigcommerce={{
          endpoint: "/api/bigcommerce/graphql",
          channelId: Number(process.env.NEXT_PUBLIC_BIGCOMMERCE_CHANNEL_ID),
        }}
        onViewProduct={(product) => product.path && router.push(product.path)}
        onCheckout={(checkoutUrl) => router.push(checkoutUrl)}
      />
    </div>
  );
}
```

### 5. Add environment variables

Add to your `.env.local`:

```bash
# TakeShape Configuration
NEXT_PUBLIC_TAKESHAPE_PROJECT_ID=your-project-id
NEXT_PUBLIC_TAKESHAPE_API_KEY=your-api-key
NEXT_PUBLIC_BIGCOMMERCE_CHANNEL_ID=1
```

The widget is now available at `/purchase-order-agent`.

## B2B Edition Support

For BigCommerce B2B Edition stores, you can enable B2B features (company addresses, B2B checkout) by providing a `getB2BJwt` callback.

To do this, you'll need implement your own token fetcher:

```tsx
const getB2BJwt = async (channelId: number) => {
  const response = await fetch(`/api/b2b/token?channelId=${channelId}`);
  if (!response.ok) return null;
  const { token } = await response.json();
  return token;
};
```

## Props Reference

### PurchaseOrderChatWidgetProps

| Prop            | Type                                     | Required | Description                                                                    |
| --------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `takeshape`     | `TakeShapeConfigProps`                   | Yes      | TakeShape API configuration                                                    |
| `bigcommerce`   | `BigCommerceConfigProps`                 | Yes      | BigCommerce storefront configuration                                           |
| `agentName`     | `string`                                 | No       | TakeShape agent name. Defaults to `'bigcommercePurchaseOrderAgent'`            |
| `inputName`     | `string`                                 | No       | TakeShape input name. Defaults to `'bigcommercePurchaseOrderAgent'`            |
| `onViewProduct` | `(product) => void`                      | No       | Called when user clicks to view a product                                      |
| `onCheckout`    | `(checkoutUrl) => void \| Promise<void>` | No       | Called when checkout is initiated. Defaults to `window.location.href` redirect |
| `className`     | `string`                                 | No       | CSS class for the container                                                    |
| `expandOnReady` | `boolean`                                | No       | Auto-expand to fullscreen modal when ready                                     |

### TakeShapeConfigProps

| Prop        | Type     | Required | Description                                                        |
| ----------- | -------- | -------- | ------------------------------------------------------------------ |
| `projectId` | `string` | Yes      | TakeShape project ID                                               |
| `apiKey`    | `string` | Yes      | TakeShape API key                                                  |
| `origin`    | `string` | No       | TakeShape API origin URL. Defaults to `'https://api.takeshape.io'` |
| `sseOrigin` | `string` | No       | TakeShape SSE origin URL. Defaults to `'https://api.takeshape.io'` |

### BigCommerceConfigProps

| Prop              | Type                                             | Required | Description                                                        |
| ----------------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------ |
| `endpoint`        | `string`                                         | Yes      | GraphQL endpoint URL (absolute or relative for proxy)              |
| `storefrontToken` | `string`                                         | No       | Storefront API token. Optional when using a proxy                  |
| `channelId`       | `number`                                         | Yes      | BigCommerce channel ID                                             |
| `getB2BJwt`       | `(channelId: number) => Promise<string \| null>` | No       | B2B JWT fetcher. Receives channelId, returns B2B storefront token. |