@takeshape/purchase-order-chat 1.51.0-beta.1

package/README.md

@@ -0,0 +1,305 @@
+# @takeshape/purchase-order-chat
+
+A React component library for purchase order chat integration with BigCommerce storefronts.
+
+## Installation
+
+```bash
+npm install @takeshape/purchase-order-chat
+# or
+pnpm add @takeshape/purchase-order-chat
+# or
+yarn add @takeshape/purchase-order-chat
+```
+
+## Requirements
+
+- React 19+
+
+## Choosing an Import
+
+This library provides three 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 |
+| `@takeshape/purchase-order-chat/testing`  | Unit tests and Storybook   | Mock BigCommerce client             |
+
+**Default (recommended for most projects):**
+
+```tsx
+import { PurchaseOrderChatWidget } from "@takeshape/purchase-order-chat";
+```
+
+**For Tailwind v4 projects** (like Catalyst with Tailwind v4):
+
+```tsx
+import { PurchaseOrderChatWidget } from "@takeshape/purchase-order-chat/tailwind";
+```
+
+The default version wraps the component in a Shadow DOM with all styles bundled, ensuring no CSS conflicts with your existing styles.
+
+## Basic Usage
+
+The simplest way to integrate the component:
+
+```tsx
+import { PurchaseOrderChatWidget } from "@takeshape/purchase-order-chat";
+
+function App() {
+  return (
+    <PurchaseOrderChatWidget
+      takeshape={{
+        projectId: "your-project-id",
+        apiKey: "your-api-key",
+      }}
+      bigcommerce={{
+        endpoint: "https://store-{hash}.mybigcommerce.com/graphql",
+        storefrontToken: "your-storefront-token",
+        channelId: 1,
+      }}
+      onViewProduct={(product) => {
+        window.location.href = product.path || `/product/${product.sku}`;
+      }}
+    />
+  );
+}
+```
+
+## Catalyst (Next.js) Integration
+
+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";
+@source "../node_modules/@takeshape/purchase-order-chat/src";
+```
+
+### 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="container mx-auto px-4 py-8">
+      <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.
+
+### Stencil Themes
+
+For Stencil storefronts, use the built-in `stencilB2BJwt` function:
+
+```tsx
+import {
+  PurchaseOrderChatWidget,
+  stencilB2BJwt,
+} from "@takeshape/purchase-order-chat";
+
+<PurchaseOrderChatWidget
+  takeshape={{
+    projectId: "your-project-id",
+    apiKey: "your-api-key",
+  }}
+  bigcommerce={{
+    endpoint: "/graphql",
+    channelId: 1,
+    getB2BJwt: stencilB2BJwt,
+  }}
+/>;
+```
+
+### Custom Implementation
+
+For other platforms (like Catalyst/Next.js), 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. For Stencil, use `stencilB2BJwt`. |
+
+## Advanced Usage (Base Component)
+
+For advanced use cases requiring custom provider setup or client management, use `PurchaseOrderChat` with `TakeShapeConfigProvider`:
+
+```tsx
+import {
+  PurchaseOrderChat,
+  TakeShapeConfigProvider,
+  createBigCommerceClient,
+} from "@takeshape/purchase-order-chat/tailwind";
+
+const bigCommerceClient = createBigCommerceClient({
+  endpoint: "https://store-{hash}.mybigcommerce.com/graphql",
+  storefrontToken: "your-storefront-token",
+  channelId: 1,
+});
+
+function App() {
+  return (
+    <TakeShapeConfigProvider projectId="your-project-id" apiKey="your-api-key">
+      <PurchaseOrderChat
+        bigcommerce={{
+          client: bigCommerceClient,
+          onViewProduct: (product) => {
+            window.location.href = product.path || `/product/${product.sku}`;
+          },
+          onCheckout: (checkoutUrl) => {
+            window.location.href = checkoutUrl;
+          },
+        }}
+      />
+    </TakeShapeConfigProvider>
+  );
+}
+```
+
+For testing, import `createMockBigCommerceClient` from the `/testing` entry point:
+
+```tsx
+import { createMockBigCommerceClient } from "@takeshape/purchase-order-chat/testing";
+
+const mockClient = createMockBigCommerceClient();
+```
+
+## Styling
+
+### For Tailwind v4 Projects
+
+Configure Tailwind to scan the package source files:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@takeshape/purchase-order-chat/src";
+```
+
+### For Tailwind v3 or Non-Tailwind Projects
+
+Use the default import - styles are bundled in a Shadow DOM:
+
+```tsx
+import { PurchaseOrderChatWidget } from "@takeshape/purchase-order-chat";
+```