@takeshape/purchase-order-chat 1.51.0 → 1.52.1

package/README.md

@@ -1,72 +1,77 @@
 # @takeshape/purchase-order-chat
 
-A React component library for purchase order chat integration with BigCommerce storefronts.
+A React component library for purchase order chat integration with BigCommerce Catalyst storefronts.
 
-## Installation
+## Catalyst Quick Start
+
+### Install
+
+From your Catalyst project's `core` directory:
 
 ```bash
-npm install @takeshape/purchase-order-chat
-# or
 pnpm add @takeshape/purchase-order-chat
-# or
-yarn 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 three entry points:
+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 |
-| `@takeshape/purchase-order-chat/testing` | Unit tests and Storybook | Mock BigCommerce client |
+| 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):**
-```tsx
-import { PurchaseOrderChatWidget } from '@takeshape/purchase-order-chat';
-```
+### 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.
 
-**For Tailwind v4 projects** (like Catalyst with Tailwind v4):
 ```tsx
-import { PurchaseOrderChatWidget } from '@takeshape/purchase-order-chat/tailwind';
+import { PurchaseOrderChat } from "@takeshape/purchase-order-chat";
 ```
 
-The default version wraps the component in a Shadow DOM with all styles bundled, ensuring no CSS conflicts with your existing styles.
-
-## Basic Usage
+### Advanced, for Tailwind v4 projects
 
-The simplest way to integrate the component:
+This gives you more control, and allows for more efficient style generation.
 
 ```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}`;
-      }}
-    />
-  );
-}
+import { PurchaseOrderChat } from "@takeshape/purchase-order-chat/tailwind";
 ```
 
-## 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
@@ -82,7 +87,10 @@ 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";
+/* 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
@@ -90,7 +98,7 @@ Add the library's source files to your Tailwind config:
 Create `app/api/bigcommerce/graphql/route.ts`:
 
 ```typescript
-import { NextRequest, NextResponse } from 'next/server';
+import { NextRequest, NextResponse } from "next/server";
 
 const BIGCOMMERCE_STORE_HASH = process.env.BIGCOMMERCE_STORE_HASH;
 const BIGCOMMERCE_STOREFRONT_TOKEN = process.env.BIGCOMMERCE_STOREFRONT_TOKEN;
@@ -98,8 +106,8 @@ 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 }
+      { errors: [{ message: "BigCommerce configuration missing" }] },
+      { status: 500 },
     );
   }
 
@@ -107,13 +115,13 @@ export async function POST(request: NextRequest) {
   const response = await fetch(
     `https://store-${BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/graphql`,
     {
-      method: 'POST',
+      method: "POST",
       headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${BIGCOMMERCE_STOREFRONT_TOKEN}`,
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${BIGCOMMERCE_STOREFRONT_TOKEN}`,
       },
       body: JSON.stringify(body),
-    }
+    },
   );
 
   const data = await response.json();
@@ -126,24 +134,24 @@ export async function POST(request: NextRequest) {
 Create `app/[locale]/(default)/purchase-order-agent/page.tsx`:
 
 ```tsx
-'use client';
+"use client";
 
-import { useRouter } from '~/i18n/routing';
-import { PurchaseOrderChatWidget } from '@takeshape/purchase-order-chat/tailwind';
+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">
+    <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!
+          apiKey: process.env.NEXT_PUBLIC_TAKESHAPE_API_KEY!,
         }}
         bigcommerce={{
-          endpoint: '/api/bigcommerce/graphql',
-          channelId: Number(process.env.NEXT_PUBLIC_BIGCOMMERCE_CHANNEL_ID)
+          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)}
@@ -170,29 +178,7 @@ The widget is now available at `/purchase-order-agent`.
 
 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:
+To do this, you'll need implement your own token fetcher:
 
 ```tsx
 const getB2BJwt = async (channelId: number) => {
@@ -207,101 +193,31 @@ const getB2BJwt = async (channelId: number) => {
 
 ### 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 |
+| 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'` |
+| 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';
-```
-
-## License
-
-MIT
+| 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. |

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { JSX } from 'react/jsx-runtime';
+
+export declare interface BigCommerceConfigProps {
+    /** GraphQL endpoint URL (absolute or relative for proxy) */
+    endpoint: string;
+    /** Storefront API token. Optional when using a proxy that handles authentication server-side. */
+    storefrontToken?: string;
+    /** BigCommerce channel ID */
+    channelId: number;
+    /** B2B JWT fetcher. Receives channelId and returns a B2B storefront token. For Stencil, use `stencilB2BJwt`. */
+    getB2BJwt?: (channelId: number) => Promise<string | null>;
+}
+
+export declare interface CartItem extends Product {
+    quantity: number;
+    status: 'matched' | 'price-mismatch' | 'unavailable' | 'pending';
+    poPriceValue?: number;
+    poPriceCurrencyCode?: string;
+    catalogPriceCurrencyCode?: string;
+    bcLineItemEntityId?: string;
+}
+
+export declare interface Product {
+    id: string;
+    sku: string;
+    name: string;
+    path?: string;
+    price?: number;
+    imageUrl?: string;
+    availableQuantity?: number;
+    isInStock?: boolean;
+    productEntityId?: number;
+    variantEntityId?: number;
+    defaultImage?: {
+        urlTemplate?: string;
+    };
+}
+
+export declare function PurchaseOrderAgent(props: PurchaseOrderAgentProps): JSX.Element;
+
+export declare type PurchaseOrderAgentProps = Omit<PurchaseOrderChatWidgetProps, 'onViewProduct' | 'onCheckout'> & {
+    productPath?: string | false;
+    checkoutUrl?: string | false;
+};
+
+export declare interface PurchaseOrderChatWidgetProps {
+    /** TakeShape API configuration */
+    takeshape: TakeShapeConfigProps;
+    /** BigCommerce storefront configuration */
+    bigcommerce: BigCommerceConfigProps;
+    /** TakeShape agent name. Defaults to 'bigcommercePurchaseOrderAgent'. */
+    agentName?: string;
+    /** TakeShape input name. Defaults to 'bigcommercePurchaseOrderAgent'. */
+    inputName?: string;
+    /** Called when user clicks to view a product */
+    onViewProduct?: (product: {
+        productEntityId?: number;
+        sku: string;
+        name: string;
+        path?: string;
+    }) => void;
+    /** Called when checkout is initiated. If not provided, defaults to window.location.href redirect. */
+    onCheckout?: (checkoutUrl: string) => void | Promise<void>;
+    /** CSS class for the container */
+    className?: string;
+    /** When true, launches ChatView in a fullscreen modal on transition to ready state */
+    expandOnReady?: boolean;
+}
+
+export declare interface TakeShapeConfigProps {
+    projectId: string;
+    apiKey: string;
+    origin?: string;
+    sseOrigin?: string;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,22 @@
+'use client';
+import { jsx as e } from "react/jsx-runtime";
+import { r as o } from "./purchase-order-chat-wrapper-CWQKcJDM.js";
+import { PurchaseOrderChat as c } from "./shadow.js";
+function n(r) {
+  return /* @__PURE__ */ e(
+    c,
+    {
+      ...r,
+      onViewProduct: (t) => {
+        r.productPath !== !1 && (window.location.href = r.productPath ? o(r.productPath, t) : t.path || `/product/${t.sku}`);
+      },
+      onCheckout: (t) => {
+        r.checkoutUrl !== !1 && (window.location.href = r.checkoutUrl || t);
+      }
+    }
+  );
+}
+export {
+  n as PurchaseOrderAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.tsx"],"sourcesContent":["'use client';\n\n// Default entry point - Exports Shadow DOM wrapper with bundled CSS (works everywhere)\n// For Tailwind v4 projects, use @takeshape/purchase-order-chat/tailwind\n\nimport { resolveProductPath } from './lib/utils.js';\nimport { PurchaseOrderChat as ShadowPurchaseOrderChat } from './shadow.js';\nimport type { PurchaseOrderChatWidgetProps } from './types.js';\n\nexport type {\n  BigCommerceConfigProps,\n  CartItem,\n  Product,\n  PurchaseOrderChatWidgetProps,\n  TakeShapeConfigProps\n} from './types.js';\n\nexport type PurchaseOrderAgentProps = Omit<\n  PurchaseOrderChatWidgetProps,\n  'onViewProduct' | 'onCheckout'\n> & {\n  productPath?: string | false;\n  checkoutUrl?: string | false;\n};\n\nexport function PurchaseOrderAgent(props: PurchaseOrderAgentProps) {\n  return (\n    <ShadowPurchaseOrderChat\n      {...props}\n      onViewProduct={(product) => {\n        if (props.productPath === false) return;\n\n        window.location.href = props.productPath\n          ? resolveProductPath(props.productPath, product)\n          : product.path || `/product/${product.sku}`;\n      }}\n      onCheckout={(checkoutUrl) => {\n        if (props.checkoutUrl === false) return;\n\n        window.location.href = props.checkoutUrl || checkoutUrl;\n      }}\n    />\n  );\n}\n"],"names":["PurchaseOrderAgent","props","jsx","ShadowPurchaseOrderChat","product","resolveProductPath","checkoutUrl"],"mappings":";;;AAyBO,SAASA,EAAmBC,GAAgC;AACjE,SACE,gBAAAC;AAAA,IAACC;AAAAA,IAAA;AAAA,MACE,GAAGF;AAAA,MACJ,eAAe,CAACG,MAAY;AAC1B,QAAIH,EAAM,gBAAgB,OAE1B,OAAO,SAAS,OAAOA,EAAM,cACzBI,EAAmBJ,EAAM,aAAaG,CAAO,IAC7CA,EAAQ,QAAQ,YAAYA,EAAQ,GAAG;AAAA,MAC7C;AAAA,MACA,YAAY,CAACE,MAAgB;AAC3B,QAAIL,EAAM,gBAAgB,OAE1B,OAAO,SAAS,OAAOA,EAAM,eAAeK;AAAA,MAC9C;AAAA,IAAA;AAAA,EAAA;AAGN;"}