npm package: @original-land/shopify-headless-chatbot
Description: Shopify Headless Chatbot
Author: Original Land SA
Latest version: 0.2.5

# Shopify Headless Chatbot

A ready-to-use chat widget component for Shopify Hydrogen storefronts with built-in customer order tracking and context integration.

## Installation

```bash
npm install @original-land/shopify-headless-chatbot
```

## Usage

### 1. Import the ChatWidget component

In your Hydrogen project, import the `ChatWidget` component inside the `<App />` component in the `root.tsx` file:

```typescript
import { ChatWidget } from '@original-land/shopify-headless-chatbot';

export default function App() {
  return (
    <html>
      <head>{/* ... */}</head>
      <body>
        {/* ... other components ... */}
        
        {/* Add the ChatWidget */}
        <ChatWidget />
        <Scripts />
      </body>
    </html>
  );
}
```

### 2. Configure API endpoints

In your Hydrogen project, create the files to re-export the API loaders:

#### Endpoint for widget data

```typescript
// app/routes/api.original.widget-data.ts
export { dataLoader as loader } from "@original-land/shopify-headless-chatbot";
```

This will automatically create the `/api/original/widget-data` endpoint that the `ChatWidget` component uses to retrieve customer order data.

#### Endpoint for the Customer Account API URL

```typescript
// app/routes/api.original.widget-url.ts
export { urlLoader as loader } from "@original-land/shopify-headless-chatbot";
```

This will create the `/api/original/widget-url` endpoint that returns the URL configured in the `PUBLIC_ORIGINAL_URL_WIDGET_SCRIPT` environment variable.

### 3. Configure Content Security Policy

To allow loading the widget script, you must add the script domain to the Content Security Policy in the `entry.server.tsx` file:

```typescript
// app/entry.server.tsx
import {createContentSecurityPolicy} from '@shopify/hydrogen';

const {nonce, header, NonceProvider} = createContentSecurityPolicy({
  scriptSrc: [
    "'self'",
    'https://cdn.shopify.com',
    // Add the following domain
    'https://ai-dashboard.original.land', 
  ],
  defaultSrc: [
    "'self'",
    'https://cdn.shopify.com',
    // Add the following domain
    'https://static.noku.io', 
  ],
  connectSrc: [
    "'self'",
    'https://cdn.shopify.com',
    // Add the following domain
    'https://ai-api.original.land',
  ],
  mediaSrc: [
    "'self'",
    'https://cdn.shopify.com',
    // Add the following domain and blob, data
    'https://static.noku.io',
    'blob:',
    'data:',
  ],
});
```

**Note**: The `ChatWidget` component uses the Hydrogen `Script` component that automatically adds the necessary `nonce` for Content Security Policy.

## Features

- 🚀 TypeScript support with full type definitions
- 📦 ESM and CommonJS module formats
- 🛠 Built for modern JavaScript environments
- 🔌 Easy integration with Shopify headless commerce
- 💬 Ready-to-use chat widget component
- 🛒 Automatic order information display for logged-in customers

## Development

### Prerequisites

- Node.js (see `.nvmrc` for version)
- pnpm

### Setup

1. Clone the repository

```bash
git clone https://github.com/noku-team/shopify-headless-chatbot.git
cd shopify-headless-chatbot
```

2. Install dependencies

```bash
pnpm install
```

### Scripts

- `pnpm build` - Build the library for production
- `pnpm lint` - Type-check the code with TypeScript
- `pnpm release` - Build and publish the package

### Building

The project uses [tsup](https://tsup.egoist.dev/) to bundle the TypeScript code into both CommonJS and ESM formats with TypeScript declarations.

```bash
pnpm build
```

## Publishing

This project uses [Changesets](https://github.com/changesets/changesets) for version management and automated publishing via GitHub Actions.

### Release Process

1. Create a changeset:

```bash
npx changeset
```

2. Commit the changeset and merge to `main`

3. The CI pipeline will automatically:
   - Version the package
   - Update the CHANGELOG
   - Publish to npm
   - Create a GitHub release

## Project Structure

```text
shopify-headless-chatbot/
├── index.ts              # Main entry point
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── .changeset/           # Changeset configuration
└── .github/
    └── workflows/        # CI/CD workflows
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © Original Land SA

## Author

Original Land SA

---

Built with ❤️ for the Shopify ecosystem