### Zendesk Channel and Client Setup

Source: https://flueframework.com/docs/ecosystem/channels/zendesk/index.md

Configure the Zendesk channel and create a project-owned Fetch client for interacting with the Zendesk API. This example shows basic setup and webhook handling for ticket creation events.

```typescript
import { createZendeskChannel } from '@flue/zendesk';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';
import { createZendeskClient } from '../zendesk-client.ts';

export const client = createZendeskClient({
  subdomain: process.env.ZENDESK_SUBDOMAIN!,
  email: process.env.ZENDESK_EMAIL!,
  apiToken: process.env.ZENDESK_API_TOKEN!,
});

export const channel = createZendeskChannel({
  signingSecret: process.env.ZENDESK_WEBHOOK_SIGNING_SECRET!,
  accountId: process.env.ZENDESK_ACCOUNT_ID!,
  async webhook({ payload }) {
    if (payload.type !== 'zen:event-type:ticket.created') return;
    const ticketId = ticketIdFromEvent(payload.subject, payload.detail);
    if (!ticketId) return;

    await dispatch(assistant, {
      id: channel.ticketKey({ accountId: payload.account_id, ticketId }),
      input: { type: `zendesk.${payload.type}`, eventId: payload.id, ticketId },
    });
  },
});
```

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

### Example: Initialize Flue for Node.js

Source: https://flueframework.com/docs/cli/init/index.md

This example shows how to run the `flue init` command to set up a project targeting a Node.js environment.

```bash
flue init --target node
```

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

### Basic Flue Build Examples

Source: https://flueframework.com/docs/cli/build

These examples demonstrate basic usage of the `flue build` command for different targets and configurations.

```bash
flue build --target node
```

```bash
flue build --target cloudflare --root ./my-app
```

```bash
flue build --target node --output ./build
```

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

### Install Flue and Initialize Target

Source: https://flueframework.com/docs/getting-started/quickstart

Install the Flue runtime and CLI, set up environment variables, and initialize your project's target configuration.

```bash
npm install @flue/runtime
npm install --save-dev @flue/cli
echo 'ANTHROPIC_API_KEY="your-api-key"' > .env
npx flue init --target node
```

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

### Install OpenTelemetry Adapter

Source: https://flueframework.com/docs/ecosystem/tooling/opentelemetry/index.md

Install the OpenTelemetry adapter and API alongside an SDK and exporter for your deployment target.

```bash
pnpm add @flue/opentelemetry @opentelemetry/api
```

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

### Import and DefineTool Example

Source: https://flueframework.com/docs/api/agent-api/index.md

An example demonstrating how to import the `defineTool` function and use it with Valibot for parameter validation.

```typescript
import { defineTool } from '@flue/runtime';
import * as v from 'valibot';

```

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

### Example: Initialize Flue for Cloudflare with Custom Root

Source: https://flueframework.com/docs/cli/init/index.md

This example demonstrates initializing a Flue project for a Cloudflare environment and specifying a custom root directory for the configuration file.

```bash
flue init --target cloudflare --root ./apps/assistant
```

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

### MySQL Adapter Configuration (Overview)

Source: https://flueframework.com/docs/ecosystem/databases/mysql/index.md

Example of configuring the MySQL adapter for Flue, using mysql2 for queries and transactions. This setup is for the Node.js target.

```typescript
import { mysql, type MysqlQuery } from '@flue/mysql';
import mysql2 from 'mysql2/promise';

const pool = mysql2.createPool(process.env.MYSQL_URL!);

const toRows = (result: unknown): Record<string, unknown>[] =>
  Array.isArray(result) ? result.map((row) => ({ ...row })) : [];

export default mysql({
  query: async (text, params = []) => {
    const [result] = await pool.execute(text, params);
    return toRows(result);
  },
  transaction: async <T>(fn: (tx: { query: MysqlQuery }) => Promise<T>) => {
    const connection = await pool.getConnection();
    // ...
  },
  close: () => pool.end(),
});
```

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

### Set Up Node.js Project

Source: https://flueframework.com/docs/ecosystem/deploy/node/index.md

Initialize a new Node.js project and install necessary Flue dependencies.

```bash
mkdir my-flue-server && cd my-flue-server
npm init -y
npm install @flue/runtime valibot
npm install -D @flue/cli
```

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

### Create an Agent with Virtual Sandbox and Shell Setup

Source: https://flueframework.com/docs/ecosystem/deploy/node/index.md

Configure an agent with a virtual sandbox that includes shell access for file operations and workspace setup.

```javascript
session.shell()
```

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

### MongoDB Adapter Setup with Official Driver

Source: https://flueframework.com/docs/ecosystem/databases/mongodb/index.md

Illustrates the basic setup of the @flue/mongodb adapter, connecting to MongoDB using environment variables for the URL and database name. It shows how the runner is passed to the mongodb() function.

```typescript
import { mongodb, type MongoOperations, type MongoRunner } from '@flue/mongodb';
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URL!);
await client.connect();

const db = client.db(process.env.MONGODB_DATABASE);
const runner: MongoRunner = {
  /* ... */
};

export default mongodb(runner);
```

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

### Install and Run Flue CLI

Source: https://flueframework.com/docs/cli/overview

Install the Flue CLI as a development dependency and invoke it using a package manager.

```bash
npm install --save-dev @flue/cli
npx flue dev
```

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

### Basic flue dev Usage

Source: https://flueframework.com/docs/cli/dev

Starts a local development server with default settings.

```bash
flue dev
```

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

### Interact with the Agent

Source: https://flueframework.com/docs/getting-started/quickstart/index.md

Example of an interactive session with the 'hello-world' agent. The agent responds to a user's prompt.

```bash
$ npx flue connect hello-world local
[flue] Connected to hello-world/local. Enter a prompt per line; Ctrl-D to exit.
Hello! What can you help me with?
{
  "text": "I can help answer questions, draft content, summarize information, and more."
}
```

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

### Run Development Server

Source: https://flueframework.com/docs/ecosystem/deploy/node/index.md

Start the development server for local development with `flue dev --target node`. This command loads .env, builds the project, and starts a server on port 3583 with hot reloading.

```bash
npx flue dev --target node
```

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

### Example Project Layout

Source: https://flueframework.com/docs/guide/project-layout

This is a typical directory structure for a Flue project, illustrating where different application components should be placed.

```tree
my-project/
├─ package.json
├─ flue.config.ts
├─ src/
│  ├─ app.ts
│  ├─ cloudflare.ts
│  ├─ agents/
│  │  └─ support-assistant.ts
│  ├─ workflows/
│  │  └─ summarize-ticket.ts
│  └─ channels/
│     └─ github.ts
└─ dist/
```

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

### Create Agent with Cloudflare Sandbox

Source: https://flueframework.com/docs/ecosystem/sandboxes/cloudflare/index.md

Example of creating an agent configured to use the Cloudflare Sandbox. This setup is suitable for agents needing git, package installation, or native binaries.

```typescript
export default createAgent<unknown, Env>(({ id, env }) => ({
  model: 'anthropic/claude-sonnet-4-6',
  sandbox: cloudflareSandbox(getSandbox(env.Sandbox, id)),
  cwd: '/workspace',
}));
```

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

### Detailed Telegram Channel Module Setup

Source: https://flueframework.com/docs/ecosystem/channels/telegram/index.md

A more comprehensive setup for the Telegram channel module, including type imports and handling for various message types within the webhook. This example assumes the presence of a `conversationFromMessage` helper function.

```typescript
import {
  createTelegramChannel,
  type TelegramConversationRef,
} from '@flue/telegram';
import {
  defineTool,
  dispatch,
} from '@flue/runtime';
import { Api } from 'grammy';
import type { Message } from 'grammy/types';
import assistant from '../agents/assistant.ts';

export const client = new Api(process.env.TELEGRAM_BOT_TOKEN!);

export const channel = createTelegramChannel({
  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET_TOKEN!,

  // Path: /channels/telegram/webhook
  async webhook({ update }) {
    const incoming = update.message ?? update.channel_post ?? update.business_message;
    if (incoming) {
      await dispatch(assistant, {
        id: channel.conversationKey(conversationFromMessage(incoming)),
        input: {
          type: 'telegram.message',
          updateId: update.update_id,
          message: incoming,
        },
      });
      return;
    }
  },
});
```

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

### Run Production Server

Source: https://flueframework.com/docs/ecosystem/deploy/node

Start the production-ready server after building the project. This requires sourcing environment variables from the .env file before execution.

```bash
set -a; source .env; set +a
node dist/server.mjs
```

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

### Invoke a workflow and get run details

Source: https://flueframework.com/docs/sdk/runs/index.md

Example of invoking a workflow named 'summarize' with a specific payload and capturing the resulting run object.

```typescript
const run = await client.workflows.invoke('summarize', {
  payload: { text: 'Hello' },
});
```

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

### Agent Stream with Tail Example

Source: https://flueframework.com/docs/api/streaming-protocol/index.md

Reads the last 100 events from an agent instance stream, starting from the beginning if fewer than 100 events exist.

```http
GET /agents/support/ticket-42?offset=-1&tail=100
```

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

### Workflow Run Stream with Tail Example

Source: https://flueframework.com/docs/api/streaming-protocol/index.md

Retrieves the last 100 events from a workflow run stream, starting from the beginning if fewer than 100 events exist.

```http
GET /runs/run_01JX...?offset=-1&tail=100
```

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

### Add Telegram Channel Blueprint

Source: https://flueframework.com/docs/ecosystem/channels/telegram/index.md

Use this command to add the Telegram channel blueprint to your Flue project, which installs necessary packages and configures basic setup.

```bash
flue add channel telegram
```

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

### Initialize Flue Project

Source: https://flueframework.com/docs/cli/overview

Initialize a new Flue project with a starter configuration file. Use the --target flag to specify the runtime environment (e.g., node).

```bash
npx flue init --target node
```

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

### List all documentation pages

Source: https://flueframework.com/docs/cli/docs/index.md

Run 'flue docs' with no arguments to print usage hints and the full page catalog. This is useful for understanding the available documentation.

```bash
flue docs
```

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

### harness.session() Method

Source: https://flueframework.com/docs/api/agent-api

Gets or creates a session within the harness. Defaults to the 'default' session. Framework-owned detached task sessions are reserved for names starting with 'task:'.

```typescript
session(name?: string): Promise<FlueSession>;
```

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

### Agent with Ticket-Scoped Tools

Source: https://flueframework.com/docs/guide/building-agents/index.md

Illustrates how an agent can be configured with tools specific to a particular agent ID, such as a support ticket. This example shows the setup for a support assistant agent.

```typescript
import { createAgent, type AgentRouteHandler } from '@flue/runtime';
import { createTicketTools } from '../shared/support-tickets.ts';

export const route: AgentRouteHandler = async (_c, next) => next();

```

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

### harness.session

Source: https://flueframework.com/docs/api/agent-api

Gets or creates a session within the harness. If no name is provided, it defaults to the 'default' session. Session names starting with 'task:' are reserved for framework-internal detached task sessions.

```APIDOC
## harness.session

### Description
Gets or creates a session in this harness. Defaults to the 'default' session. Names beginning with `task:` are reserved for framework-owned detached task sessions.

### Method
`session(name?: string): Promise<FlueSession>`
```

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

### Create Turso Database and Get Credentials

Source: https://flueframework.com/docs/ecosystem/databases/turso/index.md

Use the Turso CLI to create a new database and retrieve its URL and an auth token. These are necessary for configuring the client.

```bash
turso db create flue-agents
turso db show --url flue-agents      # → TURSO_DATABASE_URL (libsql://…)
turso db tokens create flue-agents   # → TURSO_AUTH_TOKEN
```

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

### Stream events from a deployed agent

Source: https://flueframework.com/docs/ecosystem/deploy/cloudflare/index.md

Use this GET request to stream events from a deployed agent. The `offset` parameter controls replay behavior: use `-1` to replay from the start or `now` for future events only.

```http
GET https://my-support-agent.<your-subdomain>.workers.dev/agents/chat/customer-123?offset=-1&live=sse
```

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

### Flue Init Command Synopsis

Source: https://flueframework.com/docs/cli/init/index.md

This is the general syntax for the `flue init` command, showing available options.

```bash
flue init --target <node|cloudflare> [--root <path>] [--force]
```

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

### Initialize Agent and Session Prompting

Source: https://flueframework.com/docs/guide/workflows/index.md

Shows how to initialize an agent and use a session to prompt it with incident details and then request recommendations. The response text is returned as the workflow result.

```typescript
import { createAgent, type FlueContext } from '@flue/runtime';

const investigator = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
}));

export async function run({ init, payload }: FlueContext<{ incident: string }>) {
  const harness = await init(investigator);
  const session = await harness.session();

  await session.prompt(`Analyze this incident:\n\n${payload.incident}`);
  const response = await session.prompt('Now recommend the next three actions.');

  return { recommendation: response.text };
}
```

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

### Initialize Agent with Tools and Run Session

Source: https://flueframework.com/docs/guide/tools/index.md

Initializes an agent with a set of tools and then starts a session to prompt the agent. Ensure to close the inventory after the session is complete.

```javascript
try {
    const harness = await init(agent, { tools: inventory.tools });
    const session = await harness.session();
    return await session.prompt(payload.question);
  } finally {
    await inventory.close();
  }
```

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

### Install Dependencies

Source: https://flueframework.com/docs/ecosystem/deploy/github-actions/index.md

Installs necessary packages for Flue agent development, including the runtime, CLI, and a schema validation library.

```bash
mkdir my-flue-project && cd my-flue-project
npm init -y
npm install @flue/runtime valibot
npm install -D @flue/cli
```

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

### Install Flue Postgres Adapter

Source: https://flueframework.com/docs/ecosystem/deploy/fly

Install the necessary npm package to enable Flue to use Postgres for data persistence.

```bash
npm install @flue/postgres
```

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

### Install Resend Channel

Source: https://flueframework.com/docs/ecosystem/channels/resend/index.md

Install the Resend channel blueprint into your Flue project. This command sets up the necessary configurations and dependencies.

```bash
flue add channel resend
```

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

### Valkey Adapter Initialization (Basic)

Source: https://flueframework.com/docs/ecosystem/databases/valkey

This code shows the basic initialization of the Valkey adapter using the official Redis client and `@flue/redis`. It connects to the Valkey instance via `VALKEY_URL` and exposes command and eval functions.

```typescript
import { redis } from '@flue/redis';
import { createClient } from 'redis';

const client = createClient({ url: process.env.VALKEY_URL });
await client.connect();

export default redis({
  command: (command, args = []) => client.sendCommand([command, ...args.map(String)]),
  eval: (script, keys, args = []) => client.eval(script, { keys, arguments: args.map(String) }),
  close: () => client.close(),
});
```

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

### Configure Turso Client with Environment Variables

Source: https://flueframework.com/docs/ecosystem/databases/turso/index.md

This code initializes the libSQL client using database URL and auth token from environment variables. Ensure TURSO_DATABASE_URL and TURSO_AUTH_TOKEN are set.

```typescript
import { libsql } from '@flue/libsql';
import { createClient, type ResultSet } from '@libsql/client';

const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

const toRows = (rs: ResultSet) =>
  rs.rows.map((row) => Object.fromEntries(rs.columns.map((column) => [column, row[column]])));

export default libsql({
  query: async (text, params = []) => toRows(await client.execute({ sql: text, args: params })),
  transaction: async (fn) => {
    const tx = await client.transaction('write');
    // ...
  },
  close: () => client.close(),
});
```

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

### Start local Cloudflare development server

Source: https://flueframework.com/docs/ecosystem/deploy/cloudflare/index.md

Starts a Cloudflare Workers development server with Vite integration, watching for changes.

```bash
npx flue dev --target cloudflare
```

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

### Valkey Adapter Initialization (with Pipeline)

Source: https://flueframework.com/docs/ecosystem/databases/valkey

This advanced initialization includes a pipeline helper for batching commands and handling errors. It uses the official Redis client and `@flue/redis` for integration.

```typescript
import { redis } from '@flue/redis';
import { createClient } from 'redis';

const client = createClient({ url: process.env.VALKEY_URL });
await client.connect();

export default redis({
  command: (command, args = []) => client.sendCommand([command, ...args.map(String)]),
  eval: (script, keys, args = []) =>
    client.eval(script, {
      keys,
      arguments: args.map(String),
    }),
  pipeline: async (commands) => {
    const multi = client.multi();
    for (const { command, args = [] } of commands) multi.addCommand([command, ...args.map(String)]);
    const results = await multi.exec();
    for (const result of results) if (result instanceof Error) throw result;
    return results;
  },
  close: () => client.close(),
});
```

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

### Start Workflow Run

Source: https://flueframework.com/docs/api/routing-api

Starts a workflow run. Returns stream coordinates upon admission or the result if 'wait=result' is specified.

```APIDOC
## POST /workflows/:name

### Description
Start an HTTP-exposed workflow run.

### Method
POST

### Endpoint
/workflows/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the workflow.

#### Query Parameters
- **wait** (string) - Optional - If set to 'result', waits for the workflow run to complete and returns the result. Any other value is rejected.

### Request Body
- The workflow’s JSON payload.

### Request Example
```json
{
  "input_data": "some value"
}
```

### Response
#### Success Response (202 Accepted)
- **runId** (string) - The ID of the workflow run.
- **streamUrl** (string) - URL to stream workflow run events.
- **offset** (string) - Opaque token representing the stream offset.

#### Success Response (200 OK) - with `?wait=result`
- **result** - The result of the workflow run.
- **runId** (string) - The ID of the workflow run.
- **streamUrl** (string) - URL to stream workflow run events.
- **offset** (string) - Opaque token representing the stream offset.

#### Response Example (202)
```json
{
  "runId": "run-12345",
  "streamUrl": "/streams/runs/run-12345/stream-token",
  "offset": "opaque-offset-token"
}
```

#### Response Example (200)
```json
{
  "result": {"status": "completed", "output": "success"},
  "runId": "run-12345",
  "streamUrl": "/streams/runs/run-12345/stream-token",
  "offset": "opaque-offset-token"
}
```

### Error Handling
- **400 Invalid Request** - If the `wait` query parameter has an invalid value.
```

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

### Create Notion Channel and Client

Source: https://flueframework.com/docs/ecosystem/channels/notion/index.md

Set up the Notion channel, project-owned client, and page identity helpers. This snippet demonstrates initializing the Notion client and creating the channel with webhook handling.

```typescript
import { Client } from '@notionhq/client';
import { createNotionChannel } from '@flue/notion';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';

export const client = new Client({ auth: process.env.NOTION_TOKEN! });

export const channel = createNotionChannel({
  verificationToken: process.env.NOTION_WEBHOOK_VERIFICATION_TOKEN!,
  async webhook({ event }) {
    if (event.type !== 'page.content_updated') return;

    await dispatch(assistant, {
      id: `notion-page:${encodeURIComponent(event.entity.id)}`,
      input: {
        type: `notion.${event.type}`,
        deliveryId: event.id,
        pageId: event.entity.id,
      },
    });
  },
});
```

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

### Typical Daytona Sandbox Integration with Flue

Source: https://flueframework.com/docs/ecosystem/sandboxes/daytona

This example demonstrates how to initialize a Daytona client, create a sandbox, and then integrate it with a Flue agent. Ensure the DAYTONA_API_KEY environment variable is set.

```typescript
import { Daytona } from '@daytona/sdk';
import { createAgent } from '@flue/runtime';
import { daytona } from '../sandboxes/daytona';

const client = new Daytona({ apiKey: env.DAYTONA_API_KEY });
const sandbox = await client.create();
const agent = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  sandbox: daytona(sandbox),
}));
```

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

### Start Agent Prompt

Source: https://flueframework.com/docs/api/routing-api

Starts a prompt on an HTTP-exposed agent instance. Returns stream coordinates upon admission or the result if 'wait=result' is specified.

```APIDOC
## POST /agents/:name/:id

### Description
Start a prompt on an HTTP-exposed agent instance.

### Method
POST

### Endpoint
/agents/:name/:id

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the agent.
- **id** (string) - Required - The ID of the agent instance.

#### Query Parameters
- **wait** (string) - Optional - If set to 'result', waits for the prompt to complete and returns the result. Any other value is rejected.

### Request Body
- **message** (string) - Required - The prompt message.
- **images** (array) - Optional - An array of image attachments. Each object should have `type: 'image'`, `data` (base64 encoded image content), and `mimeType`.

### Request Example
```json
{
  "message": "What is the weather today?",
  "images": [
    {
      "type": "image",
      "data": "/9j/4AAQSkZJRgABAQ...",
      "mimeType": "image/jpeg"
    }
  ]
}
```

### Response
#### Success Response (202 Accepted)
- **streamUrl** (string) - URL to stream agent events.
- **offset** (string) - Opaque token representing the stream offset.

#### Success Response (200 OK) - with `?wait=result`
- **result** - The result of the prompt.
- **streamUrl** (string) - URL to stream agent events.
- **offset** (string) - Opaque token representing the stream offset.

#### Response Example (202)
```json
{
  "streamUrl": "/streams/agents/agent-name/agent-id/stream-token",
  "offset": "opaque-offset-token"
}
```

#### Response Example (200)
```json
{
  "result": "The weather is sunny.",
  "streamUrl": "/streams/agents/agent-name/agent-id/stream-token",
  "offset": "opaque-offset-token"
}
```

### Error Handling
- **400 Invalid Request** - If the `wait` query parameter has an invalid value.
```

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

### Discord Channel Configuration and Interaction Handling

Source: https://flueframework.com/docs/ecosystem/channels/discord

This example shows how to configure the Discord REST client and create a Discord channel. It includes logic to handle a specific 'ask' command, dispatch it to an assistant agent, and respond to the interaction.

```typescript
import { REST } from '@discordjs/rest';
import { createDiscordChannel, type APIInteractionResponse } from '@flue/discord';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';

export const client = new REST({ version: '10' }).setToken(process.env.DISCORD_BOT_TOKEN!);

export const channel = createDiscordChannel({
  publicKey: process.env.DISCORD_PUBLIC_KEY!,
  async interactions({ interaction }) {
    if (interaction.type !== 2 || interaction.data.name !== 'ask') {
      return {
        type: 4,
        data: { content: 'Unsupported interaction.', flags: 64 },
      } satisfies APIInteractionResponse;
    }

    const destination = destinationFromInteraction(interaction);
    if (!destination || destination.type === 'private') {
      return {
        type: 4,
        data: { content: 'Unsupported interaction.', flags: 64 },
      } satisfies APIInteractionResponse;
    }

    await dispatch(assistant, {
      id: channel.conversationKey(destination),
      input: { type: 'discord.command.ask', interactionId: interaction.id },
    });
    return {
      type: 4,
      data: { content: 'Your request was accepted.', flags: 64 },
    } satisfies APIInteractionResponse;
  },
});
```

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

### Installing and Configuring Postgres Adapter

Source: https://flueframework.com/docs/ecosystem/deploy/fly/index.md

Install the Flue Postgres adapter using npm and configure your application to use the `DATABASE_URL` secret for database connections.

```bash
npm install @flue/postgres
```

```javascript
import { postgres } from '@flue/postgres';

export default postgres(process.env.DATABASE_URL!);
```

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

### Messenger Channel Setup and Webhook Handling

Source: https://flueframework.com/docs/ecosystem/channels/messenger

This snippet demonstrates how to create a Messenger channel, configure its webhook for receiving messages, and dispatch events to an assistant agent. It also includes setting up a Messenger client for outbound messages.

```typescript
import { createMessengerChannel, type MessengerConversationRef } from '@flue/messenger';
import { defineTool, dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';
import { MessengerClient } from '../messenger-client.ts';

export const client = new MessengerClient({
  pageId: process.env.MESSENGER_PAGE_ID!,
  pageAccessToken: process.env.MESSENGER_PAGE_ACCESS_TOKEN!,
  graphVersion: 'v25.0',
});

export const channel = createMessengerChannel({
  appSecret: process.env.MESSENGER_APP_SECRET!,
  verifyToken: process.env.MESSENGER_VERIFY_TOKEN!,
  pageId: process.env.MESSENGER_PAGE_ID!,

  // Paths: GET and POST /channels/messenger/webhook
  async webhook({ payload }) {
    for (const entry of payload.entry) {
      for (const event of entry.messaging ?? []) {
        // Echoes of the Page's own sends and other non-message events are
        // left to application policy.
        if (event.message === undefined || event.message.is_echo) continue;
        const conversation = channel.conversationRef(event);
        if (conversation === undefined || event.message.text === undefined) {
          continue;
        }
        await dispatch(assistant, {
          id: channel.conversationKey(conversation),
          input: {
            type: 'messenger.message',
            messageId: event.message.mid,
            text: event.message.text,
            attachmentTypes: (event.message.attachments ?? []).map((attachment) => attachment.type),
            quickReplyPayload: event.message.quick_reply?.payload,
          },
        });
      }
    }
  },
});

export function postMessage(ref: MessengerConversationRef) {
  return defineTool({
    name: 'post_messenger_message',
    description: 'Post to the Messenger conversation bound to this agent.',
    parameters: {
      type: 'object',
      properties: {
        text: { type: 'string', minLength: 1 },
      },
      required: ['text'],
      additionalProperties: false,
    },
    async execute({ text }) {
      const result = await client.messages.sendText({
        to: ref.participant,
        text,
      });
      return JSON.stringify({ messageId: result.messageId });
    },
  });
}

```

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

### Basic libSQL Adapter Configuration

Source: https://flueframework.com/docs/ecosystem/databases/libsql/index.md

An example of the basic libSQL adapter configuration, mapping client result sets to plain objects and serializing operations.

```typescript
import { libsql } from '@flue/libsql';
import { createClient, type ResultSet } from '@libsql/client';

const client = createClient({ url: process.env.LIBSQL_URL! });

export default libsql({
  query: (text, params = []) => {
    // await client.execute({ sql: text, args: params }))),
    // ...
  }
  transaction: (fn) => {
    // const tx = await client.transaction('write');
    // ...
  }
  close: () => client.close(),
});
```

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

### Twilio Status Callback URL Example

Source: https://flueframework.com/docs/ecosystem/channels/twilio/index.md

Example URL for publishing Twilio message delivery status. This URL should also be set as the 'StatusCallback' on outbound messages.

```http
https://example.com/channels/twilio/status
```

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

### Initialize Flue Agent with Daytona Sandbox

Source: https://flueframework.com/docs/ecosystem/sandboxes/daytona/index.md

This example shows how to import and use the Daytona adapter with Flue's `createAgent` function. Ensure the Daytona sandbox is initialized and passed to the `daytona` factory.

```typescript
import { Daytona } from '@daytona/sdk';
import { createAgent } from '@flue/runtime';
import { daytona } from '../sandboxes/daytona';


```

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

### Start Local Development Server

Source: https://flueframework.com/docs/cli/overview

Start the Flue development server in watch mode. This command builds the application locally and rebuilds as source files change.

```bash
npx flue dev
```

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

### Add Blueprint by Kind and URL with Print Option

Source: https://flueframework.com/docs/cli/add/index.md

Fetches a generic blueprint for a given kind and uses the provided URL as the coding agent's research starting point. The `--print` option outputs the raw Markdown to stdout.

```bash
flue add sandbox https://e2b.dev --print | claude
```

```bash
flue add channel https://provider.example/webhooks --print | codex
```

```bash
flue add database https://database.example/docs --print | codex
```

```bash
flue add tooling https://tool.example/docs --print | opencode
```

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

### createWhatsAppChannel()

Source: https://flueframework.com/docs/api/whatsapp-channel/index.md

Creates a WhatsApp channel, setting up GET /webhook for endpoint verification and POST /webhook for signed deliveries. It requires an appSecret for verification and a verifyToken for GET challenges.

```APIDOC
## `createWhatsAppChannel()`

```typescript
function createWhatsAppChannel<E extends Env = Env>(
  options: WhatsAppChannelOptions<E>,
): WhatsAppChannel<E>;
```

Creates `GET /webhook` for endpoint verification and `POST /webhook` for signed deliveries. This function initializes the WhatsApp channel with the provided options, including webhook handlers and security tokens.
```