@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:

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:

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.

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

Advanced, for Tailwind v4 projects

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

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

pnpm add @takeshape/purchase-order-chat

2. Configure Tailwind

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

/* 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:

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:

"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:

# 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:

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. |