### Install Dependencies and Setup Environment

Source: https://github.com/theopenco/llmchat/blob/main/README.md

Installs project dependencies and copies the example environment file. Ensure you fill in the necessary keys in the .env file before running.

```sh
pnpm install
cp apps/api/.env.example apps/api/.env   # fill in keys before running
```

--------------------------------

### Start Development Server

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Builds the widget package and then starts the development servers for the API, dashboard, marketing, showcase, and Ploy dashboard.

```sh
pnpm dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Installs all necessary project dependencies using pnpm.

```sh
pnpm install
```

--------------------------------

### Start Development Server

Source: https://github.com/theopenco/llmchat/blob/main/README.md

Boots all projects (api, dashboard, marketing) together using Ploy. The api will be available on :8787, dashboard on :3001, and marketing on :3002.

```sh
pnpm dev                                 # = ploy dev — boots all apps
```

--------------------------------

### Configure Local API Environment

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Copies the example environment file for the API and prompts the user to fill in necessary keys.

```sh
cp apps/api/.env.example apps/api/.env
```

--------------------------------

### Install Clanker Support with a Script Tag

Source: https://github.com/theopenco/llmchat/blob/main/apps/marketing/content/blog/clanker-support-is-live-on-product-hunt.md

Add this single line of JavaScript to your HTML before the closing </body> tag to integrate Clanker Support. No additional build steps or packages are required.

```html
<script src="https://cdn.clanker.ai/clanker-support.js"></script>
```

--------------------------------

### SEO Configuration for Marketing Site

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Demonstrates SEO configurations for the marketing site, including sitemap generation, robots.txt, AI answer engine conventions (llms.txt), and JSON-LD structured data.

```typescript
export const llmsTxt = `User-agent: *
Allow: /

Sitemap: ${siteUrl}/sitemap.xml`;
```

--------------------------------

### Build Marketing Package

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Builds the @llmchat/marketing package, ensuring content collections compile before the Next.js build.

```sh
pnpm --filter @llmchat/marketing build
```

--------------------------------

### Build All Workspaces

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Executes the build process across all project workspaces using turbo.

```sh
pnpm build
```

--------------------------------

### Build Dashboard Package

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Builds the @llmchat/dashboard package using Next.js and includes a bundle-size check.

```sh
pnpm --filter @llmchat/dashboard build
```

--------------------------------

### Widget Configuration and Entry Points

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Details the Vite IIFE configuration for the widget, including output formats and dynamic imports. It outlines the three main entry points for the widget package: the main component, reusable primitives, and styles.

```typescript
export * from "./widget";
export * from "./chat";
export * from "./styles";
```

--------------------------------

### Run Tests

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Executes tests for the API, dashboard, marketing, shared, and widget packages using turbo and vitest.

```sh
pnpm test
```

--------------------------------

### Build Widget Package

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Builds the @llmchat/widget package using Vite into an IIFE library. The output is then embedded into the API's generated widget bundle.

```sh
pnpm --filter @llmchat/widget build
```

--------------------------------

### Generate Database Migrations

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Generates database migration files using drizzle-kit.

```sh
pnpm migrations
```

--------------------------------

### Embedding Support Widget with Plain Script

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Shows the self-dogfooding approach where the root layout embeds the Clanker Support widget using a plain async `<script>` tag. This is a deliberate choice to avoid issues with Next.js script optimization.

```html
<script async src="https://clanker.support/widget.js?project=..."></script>
```

--------------------------------

### Apply Database Migrations

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Applies pending database migrations using drizzle-kit.

```sh
pnpm migrate
```

--------------------------------

### Seed Local Database

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Seeds the local database with initial data for admin, workspace, and demo projects. This command is for local use only.

```sh
pnpm seed
```

--------------------------------

### Rate Limiting Configuration

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Illustrates the rate limiting strategy using fixed-window counters in the STATE binding for public API paths. It highlights per-IP global pre-lookup gates and per-project/per-IP gates for specific endpoints.

```typescript
STATE.json().incr("global:rate-limit:ip:" + ip).then(count => {
  if (count > 1000) {
    throw new RateLimitError();
  }
});
```

--------------------------------

### Embedding Widget Bundle

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Illustrates the process of embedding the built widget JavaScript file into the API project. This ensures the worker can serve the widget.js file without direct filesystem access.

```bash
node scripts/emit-api-asset.mjs
```

--------------------------------

### Regenerate Web-Search Models

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Regenerates the web-search model snapshot from the @llmgateway/models package.

```sh
pnpm gen:web-search-models
```

--------------------------------

### Run Linting Checks

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Performs linting checks across all workspaces using turbo and oxlint.

```sh
pnpm lint
```

--------------------------------

### Build API Package

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Builds the @llmchat/api package using tsc for type checking. The actual worker bundle is built by ploy at deploy time.

```sh
pnpm --filter @llmchat/api build
```

--------------------------------

### Format Code

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Applies code formatting across all workspaces using turbo and prettier.

```sh
pnpm format
```

--------------------------------

### Tailwind CSS Configuration with RGB Tokens

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Illustrates how design tokens are defined in Tailwind CSS using RGB values. This allows for dynamic alpha transparency control directly within Tailwind classes.

```css
--paper-1: 255 255 255; /* White */
--ink-1: 15 18 25; /* Near-black */
--accent-1: 91 33 245; /* Indigo */

.bg-paper-1 { background-color: rgb(var(--paper-1)); }
.text-ink-1 { color: rgb(var(--ink-1)); }
.bg-accent-1/70 { background-color: rgb(var(--accent-1) / 0.7); }
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Removes build artifacts including dist, .turbo, .next, and .ploy directories.

```sh
pnpm clean
```

--------------------------------

### Generate Database Migrations

Source: https://github.com/theopenco/llmchat/blob/main/README.md

Generates new SQL migration files from the Drizzle schema. These migrations are automatically applied by `ploy dev`.

```sh
pnpm migrations   # drizzle-kit generate (writes new SQL into apps/api/migrations)
```

--------------------------------

### Inbound Email Handling Logic

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Describes the process of handling inbound emails, including writing system messages, updating conversation timestamps, sending emails via Resend, and posting to Slack webhooks. It also covers parsing reply addresses and matching conversations.

```typescript
await project.notifyEmail(
  `New reply from ${message.senderName}`,
  `Reply-To: reply+${inboundEmailLocal}@${INBOUND_EMAIL_DOMAIN}`,
  body
);
await project.slackWebhookUrl?.fetch(slackPayload);
```

--------------------------------

### Widget Asset / Embed Endpoints

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoints for serving the compiled widget JavaScript bundle and the embeddable chat shell.

```APIDOC
## GET /widget.js

### Description
Serves the compiled IIFE JavaScript bundle for the widget.

### Method
GET

### Endpoint
/widget.js

### Response
#### Success Response (200)
- **Content** (file) - The JavaScript bundle.
- **Cache-Control** (string) - `public, max-age=300`

## GET /embed/:key

### Description
Serves a CSP-hardened full-page iframe chat shell.

### Method
GET

### Endpoint
/embed/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The embed key.

### Response
#### Success Response (200)
- **Content** (file) - The HTML content for the chat shell.

```

--------------------------------

### Public Widget Endpoints

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoints accessible to public widgets for interacting with the LLM and conversation management.

```APIDOC
## POST /v1/chat

### Description
Streams a UI message stream from the LLM to the embedded widget.

### Method
POST

### Endpoint
/v1/chat

### Request Body
- **message** (string) - Required - The user's message to the LLM.
- **conversationId** (string) - Optional - The ID of the conversation to continue.

### Response
#### Success Response (200)
- **stream** (ReadableStream) - A stream of messages from the LLM.

## POST /v1/escalate

### Description
Flips the conversation to escalated status, notifying relevant parties via email and Slack.

### Method
POST

### Endpoint
/v1/escalate

### Request Body
- **conversationId** (string) - Required - The ID of the conversation to escalate.

### Response
#### Success Response (200)
- **status** (string) - Indicates the escalation was successful.

## GET /v1/messages

### Description
Polls the conversation's messages for display in the widget.

### Method
GET

### Endpoint
/v1/messages

### Query Parameters
- **conversationId** (string) - Required - The ID of the conversation to retrieve messages from.

### Response
#### Success Response (200)
- **messages** (array) - A list of messages in the conversation.

## POST /v1/rating

### Description
Allows users to rate an individual assistant message with a thumbs up or down.

### Method
POST

### Endpoint
/v1/rating

### Request Body
- **messageId** (string) - Required - The ID of the message to rate.
- **rating** (string) - Required - The rating ('thumbs_up' or 'thumbs_down').

### Response
#### Success Response (200)
- **status** (string) - Indicates the rating was recorded.

## POST /v1/csat

### Description
Allows users to provide a 1-5 rating for the overall conversation.

### Method
POST

### Endpoint
/v1/csat

### Request Body
- **conversationId** (string) - Required - The ID of the conversation being rated.
- **rating** (integer) - Required - The conversation rating (1-5).

### Response
#### Success Response (200)
- **status** (string) - Indicates the CSAT rating was recorded.

## GET /v1/config/:key

### Description
Retrieves public widget branding configuration.

### Method
GET

### Endpoint
/v1/config/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The configuration key to retrieve.

### Response
#### Success Response (200)
- **value** (string) - The configuration value.

```

--------------------------------

### Billing Endpoints

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoints for managing billing, including checkout, customer portal, usage, and Stripe webhooks.

```APIDOC
## Billing API Group (`/billing/*`)

### Description
Manages billing-related operations such as checkout, customer portal access, and usage tracking.

### Endpoints
- `checkout`
- `portal`
- `usage` (dashboard-pinned, owner-gated)

## Billing Webhook (`/billing/webhook`)

### Description
Receives Stripe signature-verified webhook events for billing updates.

### Method
POST

### Endpoint
/billing/webhook

### Security
- No CORS.
- Stripe signature-verified raw signed body.

```

--------------------------------

### Community Links Definition

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Defines constants for community links used across the marketing site, such as GitHub repository, Discord server, and X (formerly Twitter) profile.

```typescript
export const GITHUB_URL = "https://github.com/theopenco/llmchat";
export const DISCORD_URL = "https://discord.gg/invite/...";
export const X_URL = "https://x.com/llmchat";
```

--------------------------------

### Auth Endpoints

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoints related to user authentication, including email/password and OAuth providers.

```APIDOC
## Auth API Group (`/api/auth/*`)

### Description
Handles authentication flows, including email/password login and OAuth provider integration.

### Method
Catch-all GET/POST

### Endpoint
/api/auth/*

### Details
- Supports Email+password, Google, and GitHub OAuth.
- Social providers are enabled based on `*_CLIENT_ID`/`*_CLIENT_SECRET` environment variables.
- Use `/api/oauth-providers` to check enabled providers.

```

--------------------------------

### Dashboard API Endpoints

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoints for managing account, workspaces, projects, conversations, and other dashboard-specific functionalities.

```APIDOC
## Dashboard API Group

### Description
These endpoints are for authenticated users accessing the dashboard and managing their projects and data.

### Authentication
Requires session and workspace authentication. Membership is asserted via the `x-workspace-id` header.

### Endpoint Groups
- `account`
- `workspaces`
- `projects` (including `/projects/usage`)
- `conversations` (list, stats, thread, reply, archive, read, tags, delete)
- `tags`
- `search` (⌘K palette)
- `system-prompts` (per-project prompt library + activate)
- `sources` (knowledge base: url/text/qa + promote/refresh)
- `oauth-providers`

```

--------------------------------

### Widget CSS as TS Template Literal

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Shows how widget CSS is embedded as a TypeScript template literal. This approach is used because Next.js does not support Vite's `?inline` syntax, and exporting a string works across bundlers.

```typescript
export const widgetStyles = `
:host {
  --widget-color: ${props.brandColor || "#000000"};
}
/* ... more styles */
`;
```

--------------------------------

### Inbound Email Webhook

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

Endpoint for receiving signed webhooks from Resend for inbound email replies.

```APIDOC
## Inbound Email Webhook (`/webhooks/inbound-email`)

### Description
Receives Svix-signed webhooks from Resend for processing inbound email replies.

### Method
POST

### Endpoint
/webhooks/inbound-email

### Security
- Svix-signed.

```

--------------------------------

### Health Check

Source: https://github.com/theopenco/llmchat/blob/main/AGENTS.md

A simple health check endpoint for the service.

```APIDOC
## GET /

### Description
Health check endpoint for the service.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **status** (string) - Indicates the service is healthy.

```

--------------------------------

### Public Widget Chat API

Source: https://github.com/theopenco/llmchat/blob/main/CLAUDE.md

Endpoints for interacting with the public chat widget, including streaming messages, escalating conversations, polling messages, and rating responses.

```APIDOC
## POST /v1/chat

### Description
Streams a UI message stream from the LLM to the embedded widget.

### Method
POST

### Endpoint
/v1/chat

### Parameters
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication and rate limiting.

### Request Body
- **message** (string) - Required - The user's message to the LLM.
- **conversationId** (string) - Optional - The ID of the conversation to continue.

### Response
#### Success Response (200)
- **stream** (ReadableStream) - A stream of UI messages from the LLM.

### Response Example
{
  "example": "(stream of messages)"
}
```

```APIDOC
## POST /v1/escalate

### Description
Flips the conversation to escalated status, notifying relevant parties via email and Slack.

### Method
POST

### Endpoint
/v1/escalate

### Parameters
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication.

### Request Body
- **conversationId** (string) - Required - The ID of the conversation to escalate.

### Response
#### Success Response (200)
- **status** (string) - Indicates the escalation was successful.

### Response Example
{
  "example": {
    "status": "escalated"
  }
}
```

```APIDOC
## GET /v1/messages

### Description
Polls the conversation's messages for display in the widget.

### Method
GET

### Endpoint
/v1/messages

### Parameters
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication.
- **conversationId** (string) - Required - The ID of the conversation to retrieve messages from.

### Response
#### Success Response (200)
- **messages** (array) - A list of messages in the conversation.

### Response Example
{
  "example": {
    "messages": [
      {
        "id": "msg_123",
        "role": "user",
        "content": "Hello"
      },
      {
        "id": "msg_456",
        "role": "assistant",
        "content": "Hi there!"
      }
    ]
  }
}
```

```APIDOC
## POST /v1/rating

### Description
Allows users to provide a thumbs up or down rating for a specific assistant message.

### Method
POST

### Endpoint
/v1/rating

### Parameters
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication.

### Request Body
- **messageId** (string) - Required - The ID of the assistant message to rate.
- **rating** (string) - Required - The rating, either 'thumbs_up' or 'thumbs_down'.

### Response
#### Success Response (200)
- **status** (string) - Indicates the rating was recorded.

### Response Example
{
  "example": {
    "status": "rated"
  }
}
```

```APIDOC
## POST /v1/csat

### Description
Allows users to provide a 1-5 conversation rating.

### Method
POST

### Endpoint
/v1/csat

### Parameters
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication.

### Request Body
- **conversationId** (string) - Required - The ID of the conversation to rate.
- **rating** (integer) - Required - The conversation rating from 1 to 5.

### Response
#### Success Response (200)
- **status** (string) - Indicates the CSAT rating was recorded.

### Response Example
{
  "example": {
    "status": "csat_rated"
  }
}
```

```APIDOC
## GET /v1/config/:key

### Description
Retrieves public widget branding configuration.

### Method
GET

### Endpoint
/v1/config/:key

### Parameters
#### Path Parameters
- **key** (string) - Required - The configuration key to retrieve.
#### Query Parameters
- **publicKey** (string) - Required - Per-project public key for authentication.

### Response
#### Success Response (200)
- **config** (object) - The branding configuration object.

### Response Example
{
  "example": {
    "config": {
      "brandColor": "#ffffff",
      "logoUrl": "https://example.com/logo.png"
    }
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.