### Google OAuth Credentials Setup

Source: https://github.com/jonesphillip/weft/blob/main/README.md

This snippet details the steps for setting up Google OAuth credentials in the Google Cloud Console. It includes enabling necessary APIs, configuring the consent screen, and creating OAuth client IDs for web applications, specifying authorized JavaScript origins and redirect URIs for development and production.

```bash
# Example of adding authorized origins and redirect URIs in Google Cloud Console
# Authorized JavaScript origins:
# http://localhost:5174 (development)
# https://weft.<your-subdomain>.workers.dev (production)

# Authorized redirect URIs:
# http://localhost:5174/google/callback (development)
# https://weft.<your-subdomain>.workers.dev/google/callback (production)

# Copy Client ID and Client Secret to your .env file
```

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

### List GitHub Repositories

Source: https://context7.com/jonesphillip/weft/llms.txt

Fetches a list of accessible GitHub repositories for the authenticated user. This GET request uses the board ID to identify the associated credentials. The response includes repository details like ID, name, and owner.

```typescript
// List user's repositories with stored credentials
const reposResponse = await fetch('/api/boards/board-uuid/github/repos');
const repos = await reposResponse.json();
// {
//   success: true,
//   data: [
//     {
//       id: 123456,
//       name: "my-repo",
//       fullName: "user/my-repo",
//       owner: "user",
//       private: false,
//       defaultBranch: "main",
//       description: "My repository"
//     }
//   ]
// }
```

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

### Initiate GitHub OAuth Flow

Source: https://context7.com/jonesphillip/weft/llms.txt

Starts the OAuth process for GitHub integration by obtaining an authorization URL. The user is then redirected to GitHub for authentication and authorization. A board ID is required for this request.

```typescript
// Get GitHub OAuth authorization URL
const githubOAuthUrl = await fetch(
  '/api/github/oauth/url?boardId=board-uuid'
);
const { data } = await githubOAuthUrl.json();

// Redirect to GitHub authorization
window.location.href = data.url;
```

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

### Workflow Execution - Agent Task Processing API

Source: https://context7.com/jonesphillip/weft/llms.txt

APIs for starting, managing, and monitoring AI agent workflows, including automatic checkpointing and resumption.

```APIDOC
## POST /api/boards/{boardId}/tasks/{taskId}/generate-plan

### Description
Generates and starts a workflow plan for a given task. This initiates the AI agent's process.

### Method
POST

### Endpoint
/api/boards/{boardId}/tasks/{taskId}/generate-plan

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier for the board.
- **taskId** (string) - Required - The unique identifier for the task.

### Request Example
(No request body needed for this endpoint)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains details about the generated plan.
  - **id** (string) - The unique identifier for the plan.
  - **taskId** (string) - The ID of the associated task.
  - **boardId** (string) - The ID of the associated board.
  - **status** (string) - The current status of the workflow plan (e.g., 'running').
  - **summary** (string | null) - A summary of the workflow, if available.
  - **steps** (array) - An array representing the steps in the workflow.
  - **currentStepIndex** (integer) - The index of the current step being executed.
  - **createdAt** (string) - The timestamp when the plan was created.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "plan-uuid",
    "taskId": "task-uuid",
    "boardId": "board-uuid",
    "status": "running",
    "summary": null,
    "steps": [],
    "currentStepIndex": 0,
    "createdAt": "2024-01-08T00:00:00Z"
  }
}
```

## GET /api/boards/{boardId}/plans/{planId}/logs

### Description
Retrieves workflow logs in real-time for a specific plan.

### Method
GET

### Endpoint
/api/boards/{boardId}/plans/{planId}/logs

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier for the board.
- **planId** (string) - Required - The unique identifier for the plan.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of logs to retrieve.
- **offset** (integer) - Optional - The number of logs to skip before returning results.

### Request Example
(No request body needed for this endpoint)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - An array of log objects.
  - **id** (string) - The unique identifier for the log entry.
  - **planId** (string) - The ID of the plan the log belongs to.
  - **level** (string) - The log level (e.g., 'info').
  - **message** (string) - The log message.
  - **timestamp** (string) - The timestamp when the log was created.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "log-uuid",
      "planId": "plan-uuid",
      "level": "info",
      "message": "Agent thinking: I need to search Gmail for Q4 reports",
      "timestamp": "2024-01-08T00:00:00Z"
    }
  ]
}
```

## POST /api/boards/{boardId}/plans/{planId}/checkpoint

### Description
Manages workflow checkpoints, allowing for approval or requesting changes before proceeding.

### Method
POST

### Endpoint
/api/boards/{boardId}/plans/{planId}/checkpoint

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier for the board.
- **planId** (string) - Required - The unique identifier for the plan.

#### Request Body
- **action** (string) - Required - The action to perform ('approve' or 'request_changes').
- **feedback** (string) - Required - User feedback regarding the checkpoint.
- **data** (object) - Optional - Additional data to be passed when requesting changes.

### Request Example
```json
{
  "action": "approve",
  "feedback": "Looks good, proceed with sending"
}
```

### Request Example
```json
{
  "action": "request_changes",
  "feedback": "Change the email subject line",
  "data": {
    "subject": "Updated subject line"
  }
}
```

### Response
#### Success Response (200)
(No specific response body defined, implies success upon completion)

## POST /api/boards/{boardId}/plans/{planId}/cancel

### Description
Cancels a running workflow.

### Method
POST

### Endpoint
/api/boards/{boardId}/plans/{planId}/cancel

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier for the board.
- **planId** (string) - Required - The unique identifier for the plan.

### Request Example
(No request body needed for this endpoint)

### Response
#### Success Response (200)
(No specific response body defined, implies success upon completion)
```

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

### Connect to MCP Server and Fetch Tools

Source: https://context7.com/jonesphillip/weft/llms.txt

Connects to a registered MCP server and retrieves a list of available tools. This involves a POST request to the server's connect endpoint. The response contains tool information, including names and descriptions.

```typescript
// Connect to MCP server and fetch available tools
const connectResponse = await fetch(
  '/api/boards/board-uuid/mcp-servers/server-uuid/connect',
  { method: 'POST' }
);
const tools = await connectResponse.json();
// {
//   success: true,
//   data: {
//     status: "connected",
//     toolCount: 5,
//     tools: [
//       { name: "query_database", description: "Execute SQL query" },
//       { name: "list_tables", description: "List all tables" }
//     ]
//   }
// }
```

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

### Manage Boards: Create, Read, Update, Delete (TypeScript)

Source: https://context7.com/jonesphillip/weft/llms.txt

This snippet demonstrates how to interact with the board management API endpoints. It covers creating new boards, retrieving board details, updating board names, and deleting boards. These operations utilize persistent storage via Durable Objects.

```typescript
const response = await fetch('/api/boards', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'My Project Board' })
});

const result = await response.json();
// {
//   success: true,
//   data: {
//     id: "uuid",
//     name: "My Project Board",
//     ownerId: "user-id",
//     createdAt: "2024-01-08T00:00:00Z",
//     updatedAt: "2024-01-08T00:00:00Z",
//     columns: [],
//     tasks: []
//   }
// }

// Get board with all columns and tasks
const boardResponse = await fetch('/api/boards/uuid');
const board = await boardResponse.json();

// Update board name
await fetch('/api/boards/uuid', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Updated Board Name' })
});

// Delete board
await fetch('/api/boards/uuid', { method: 'DELETE' });
```

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

### Project Structure Overview

Source: https://github.com/jonesphillip/weft/blob/main/README.md

This snippet provides an overview of the Weft project's directory structure. It categorizes files related to the worker, handlers, services, integrations, and the React frontend components, context, and API clients.

```tree
worker/
├── index.ts              # HTTP routing and auth
├── handlers/             # Request handlers
├── services/             # Business logic
├── workflows/            # Cloudflare Workflows (agent loop)
├── mcp/                  # MCP server registry
├── google/               # Google integrations (Gmail, Docs, Sheets)
└── github/               # GitHub integration

src/
├── components/           # React components
├── context/              # React context providers
├── hooks/                # Custom hooks
└── api/                  # API client
```

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

### Frontend API Client Integration with TypeScript

Source: https://context7.com/jonesphillip/weft/llms.txt

This TypeScript code demonstrates how to use a frontend API client for type-safe interactions. It covers authentication, creating and managing boards, columns, and tasks, adding and connecting MCP servers, and initiating and resolving workflow plans.

```typescript
import * as api from './api/client';

// Authentication
const { data: user } = await api.getMe();
// { id: "user-id", email: "user@example.com", logoutUrl: "..." }

// Create board and task
const { data: board } = await api.createBoard('My Board');
const { data: column } = await api.createColumn(board.id, 'In Progress');
const { data: task } = await api.createTask(board.id, {
  columnId: column.id,
  title: 'Analyze sales data and create report',
  description: 'Pull Q4 data from sheets and summarize trends',
  priority: 'high'
});

// Move task
await api.moveTask(board.id, task.id, column.id, 0);

// Add MCP server
const { data: mcpServer } = await api.createMCPServer(board.id, {
  name: 'Custom API',
  type: 'remote',
  endpoint: 'https://api.example.com/mcp',
  authType: 'bearer',
  credentialId: 'cred-uuid',
  transportType: 'streamable-http'
});

// Connect and fetch tools
const { data: connection } = await api.connectMCPServer(board.id, mcpServer.id);
console.log(`Connected with ${connection.toolCount} tools`);

// Start workflow
const { data: plan } = await api.generateWorkflowPlan(board.id, task.id);

// Resolve approval checkpoint
await api.resolveWorkflowCheckpoint(board.id, plan.id, {
  action: 'approve',
  feedback: 'Approved'
});

// Get workflow logs
const { data: logs } = await api.getWorkflowLogs(board.id, plan.id, {
  limit: 100,
  offset: 0
});

```

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

### Deploy Secrets to Cloudflare

Source: https://github.com/jonesphillip/weft/blob/main/README.md

This snippet shows how to set environment secrets for Cloudflare deployment using the 'wrangler' CLI. It covers encryption keys and OAuth client IDs/secrets for integrations. Ensure you generate the ENCRYPTION_KEY using openssl.

```bash
npx wrangler secret put ENCRYPTION_KEY --env production
npx wrangler secret put GOOGLE_CLIENT_ID --env production
npx wrangler secret put GOOGLE_CLIENT_SECRET --env production
npx wrangler secret put GITHUB_CLIENT_ID --env production
npx wrangler secret secret PUT GITHUB_CLIENT_SECRET --env production

npm run deploy:prod
```

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

### Implement Slack MCP Server with TypeScript

Source: https://context7.com/jonesphillip/weft/llms.txt

This TypeScript code defines a custom HostedMCP server for Slack integration, allowing messages to be sent to Slack channels. It uses Zod for schema validation and the fetch API to interact with the Slack API. The server is then registered within an AccountMCPRegistry.

```typescript
import { HostedMCPServer, type MCPToolSchema, type MCPToolCallResult } from './mcp/MCPClient';
import { z } from 'zod';

// Define tool schemas with Zod
const tools = {
  sendSlackMessage: {
    description: 'Send message to Slack channel',
    input: z.object({
      channel: z.string().describe('Channel ID or name'),
      message: z.string().describe('Message text'),
      threadTs: z.string().optional().describe('Thread timestamp for replies')
    })
  }
};

// Implement MCP server
export class SlackMCPServer extends HostedMCPServer {
  readonly name = 'Slack';
  readonly description = 'Send messages to Slack channels';

  private accessToken: string;

  constructor(accessToken: string) {
    super();
    this.accessToken = accessToken;
  }

  getTools(): MCPToolSchema[] {
    return Object.entries(tools).map(([name, schema]) => ({
      name,
      description: schema.description,
      inputSchema: schema.input
    }));
  }

  async callTool(name: string, args: Record<string, unknown>): Promise<MCPToolCallResult> {
    if (name === 'sendSlackMessage') {
      const { channel, message, threadTs } = tools.sendSlackMessage.input.parse(args);

      const response = await fetch('https://slack.com/api/chat.postMessage', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          channel,
          text: message,
          thread_ts: threadTs
        })
      });

      const result = await response.json();

      if (!result.ok) {
        return this.errorContent(`Slack API error: ${result.error}`);
      }

      return {
        content: [{
          type: 'text',
          text: `Message sent to ${channel}. Timestamp: ${result.ts}`
        }],
        structuredContent: result
      };
    }

    return this.errorContent(`Unknown tool: ${name}`);
  }
}

// Register in AccountMCPRegistry
const slackAccount: AccountDefinition = {
  id: 'slack',
  name: 'Slack',
  credentialType: 'slack_oauth',
  authType: 'oauth',
  mcps: [{
    id: 'slack',
    name: 'Slack',
    serverName: 'Slack',
    description: 'Send messages to Slack channels',
    factory: (credentials) => new SlackMCPServer(credentials.accessToken!),
    artifactType: 'other'
  }]
};

```

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

### Configure Cloudflare Access Authentication

Source: https://github.com/jonesphillip/weft/blob/main/README.md

This snippet demonstrates configuring Cloudflare Access for authentication. It involves setting up secrets for audience and team name, and updating the wrangler.jsonc configuration file to enable 'access' mode. This is for multi-user or login-protected deployments.

```bash
npx wrangler secret put ACCESS_AUD --env production
npx wrangler secret put ACCESS_TEAM --env production
```

```jsonc
"env": {
  "production": {
    "vars": {
      "AUTH_MODE": "access",
      // ...
    }
  }
}
```

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

### GitHub OAuth Integration API

Source: https://context7.com/jonesphillip/weft/llms.txt

Endpoints for connecting a GitHub account, enabling operations on repositories, issues, and pull requests through OAuth.

```APIDOC
## GET /api/github/oauth/url

### Description
Retrieves the authorization URL for initiating the GitHub OAuth 2.0 flow.

### Method
GET

### Endpoint
/api/github/oauth/url

### Parameters
#### Query Parameters
- **boardId** (string) - Required - The unique identifier for the board.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object)
  - **url** (string) - The GitHub OAuth authorization URL.

#### Response Example
```json
{
  "success": true,
  "data": {
    "url": "https://github.com/login/oauth/authorize?..."
  }
}
```

## POST /api/github/oauth/exchange

### Description
Exchanges the authorization code received after user consent for GitHub access tokens.

### Method
POST

### Endpoint
/api/github/oauth/exchange

### Parameters
#### Request Body
- **code** (string) - Required - The authorization code received from GitHub redirect.
- **boardId** (string) - Required - The unique identifier for the board.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

## GET /api/boards/{board-uuid}/github/repos

### Description
Lists the repositories associated with the authenticated GitHub account for a given board.

### Method
GET

### Endpoint
/api/boards/{board-uuid}/github/repos

### Parameters
#### Path Parameters
- **board-uuid** (string) - Required - The unique identifier for the board.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - A list of GitHub repositories.
  - **id** (integer) - The unique ID of the repository.
  - **name** (string) - The name of the repository.
  - **fullName** (string) - The full name of the repository (owner/name).
  - **owner** (string) - The owner of the repository.
  - **private** (boolean) - Indicates if the repository is private.
  - **defaultBranch** (string) - The default branch of the repository.
  - **description** (string) - A description of the repository.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": 123456,
      "name": "my-repo",
      "fullName": "user/my-repo",
      "owner": "user",
      "private": false,
      "defaultBranch": "main",
      "description": "My repository"
    }
  ]
}
```
```

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

### Manage Tasks: Create, Move, Update (TypeScript)

Source: https://context7.com/jonesphillip/weft/llms.txt

This section details the API calls for managing tasks within a board. It includes creating new tasks with details like title and priority, moving tasks between columns, and updating existing task information. These operations are crucial for workflow management.

```typescript
// Create a task in a specific column
const taskResponse = await fetch('/api/boards/board-uuid/tasks', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    columnId: 'column-uuid',
    title: 'Send quarterly report emails',
    description: 'Draft and send Q4 reports to all stakeholders',
    priority: 'high'
  })
});

const task = await taskResponse.json();
// {
//   success: true,
//   data: {
//     id: "task-uuid",
//     columnId: "column-uuid",
//     boardId: "board-uuid",
//     title: "Send quarterly report emails",
//     description: "Draft and send Q4 reports to all stakeholders",
//     priority: "high",
//     position: 0,
//     createdAt: "2024-01-08T00:00:00Z",
//     updatedAt: "2024-01-08T00:00:00Z"
//   }
// }

// Move task to different column
await fetch('/api/boards/board-uuid/tasks/task-uuid/move', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    columnId: 'new-column-uuid',
    position: 0
  })
});

// Update task details
await fetch('/api/boards/board-uuid/tasks/task-uuid', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Updated task title',
    priority: 'medium'
  })
});
```

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

### Real-Time Board Updates via WebSocket - TypeScript

Source: https://context7.com/jonesphillip/weft/llms.txt

This snippet shows how to establish a WebSocket connection to receive real-time updates for board activities, including task creation, updates, workflow progress, checkpoints, and completion. It utilizes the standard WebSocket API in TypeScript.

```typescript
// Connect to WebSocket for real-time board updates
const ws = new WebSocket(
  `wss://your-worker.workers.dev/api/ws?boardId=board-uuid`
);

ws.onopen = () => {
  console.log('Connected to board updates');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'task_created') {
    console.log('New task:', message.data);
    // { id: "task-uuid", title: "New task", columnId: "col-uuid", ... }
  }

  if (message.type === 'task_updated') {
    console.log('Task updated:', message.data);
  }

  if (message.type === 'workflow_step') {
    console.log('Workflow step:', message.data);
    // { 
    //   planId: "plan-uuid",
    //   step: {
    //     id: "step-uuid",
    //     name: "Send email",
    //     type: "tool",
    //     status: "running",
    //     toolName: "sendEmail"
    //   }
    // }
  }

  if (message.type === 'workflow_checkpoint') {
    console.log('Approval required:', message.data);
    // { 
    //   planId: "plan-uuid",
    //   approvalMessage: "About to send email to 5 recipients",
    //   approvalData: { to: "user@example.com", subject: "...", body: "..." }
    // }
  }

  if (message.type === 'workflow_complete') {
    console.log('Workflow finished:', message.data);
    // { planId: "plan-uuid", status: "completed", result: {...} }
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from board updates');
};

```

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

### Initiate Google OAuth Flow

Source: https://context7.com/jonesphillip/weft/llms.txt

Initiates the OAuth flow for Google services by fetching an authorization URL. This URL is used to redirect the user to the Google consent screen. Dependencies include a valid board ID.

```typescript
// Get Google OAuth authorization URL
const oauthUrlResponse = await fetch(
  '/api/google/oauth/url?boardId=board-uuid'
);
const { data } = await oauthUrlResponse.json();
// { success: true, data: { url: "https://accounts.google.com/o/oauth2/v2/auth?..." } }

// Redirect user to OAuth consent screen
window.location.href = data.url;
```

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

### MCP Server Registration API

Source: https://context7.com/jonesphillip/weft/llms.txt

Endpoints for managing remote MCP servers, allowing extension of agent capabilities with custom tools. This includes adding new servers, connecting to them to fetch tools, and updating their configurations.

```APIDOC
## POST /api/boards/{board-uuid}/mcp-servers

### Description
Adds a new remote MCP server to the specified board.

### Method
POST

### Endpoint
/api/boards/{board-uuid}/mcp-servers

### Parameters
#### Path Parameters
- **board-uuid** (string) - Required - The unique identifier for the board.

#### Request Body
- **name** (string) - Required - The name of the MCP server.
- **type** (string) - Required - The type of MCP server (e.g., 'remote').
- **endpoint** (string) - Required - The URL of the MCP server.
- **authType** (string) - Required - The authentication type (e.g., 'bearer').
- **credentialId** (string) - Required - The ID of the credential to use.
- **transportType** (string) - Required - The transport type (e.g., 'streamable-http').

### Request Example
```json
{
  "name": "Database Tools",
  "type": "remote",
  "endpoint": "https://mcp-server.example.com",
  "authType": "bearer",
  "credentialId": "cred-uuid",
  "transportType": "streamable-http"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains details about the registered MCP server.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "server-uuid",
    "name": "Database Tools",
    "type": "remote",
    "endpoint": "https://mcp-server.example.com"
  }
}
```

## POST /api/boards/{board-uuid}/mcp-servers/{server-uuid}/connect

### Description
Connects to a specific MCP server and fetches the available tools.

### Method
POST

### Endpoint
/api/boards/{board-uuid}/mcp-servers/{server-uuid}/connect

### Parameters
#### Path Parameters
- **board-uuid** (string) - Required - The unique identifier for the board.
- **server-uuid** (string) - Required - The unique identifier for the MCP server.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the connection status and a list of available tools.
  - **status** (string) - The connection status (e.g., "connected").
  - **toolCount** (integer) - The number of available tools.
  - **tools** (array) - A list of tools with their name and description.
    - **name** (string) - The name of the tool.
    - **description** (string) - A description of the tool.

#### Response Example
```json
{
  "success": true,
  "data": {
    "status": "connected",
    "toolCount": 5,
    "tools": [
      { "name": "query_database", "description": "Execute SQL query" },
      { "name": "list_tables", "description": "List all tables" }
    ]
  }
}
```

## POST /api/boards/{board-uuid}/mcp-servers/account

### Description
Adds a built-in MCP server, such as GitHub, associated with a specific account.

### Method
POST

### Endpoint
/api/boards/{board-uuid}/mcp-servers/account

### Parameters
#### Path Parameters
- **board-uuid** (string) - Required - The unique identifier for the board.

#### Request Body
- **accountId** (string) - Required - The ID of the account (e.g., 'github').
- **mcpId** (string) - Required - The ID of the MCP server to associate.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

## PUT /api/boards/{board-uuid}/mcp-servers/{server-uuid}

### Description
Updates the configuration of an existing MCP server.

### Method
PUT

### Endpoint
/api/boards/{board-uuid}/mcp-servers/{server-uuid}

### Parameters
#### Path Parameters
- **board-uuid** (string) - Required - The unique identifier for the board.
- **server-uuid** (string) - Required - The unique identifier for the MCP server.

#### Request Body
- **enabled** (boolean) - Optional - Whether the MCP server is enabled.
- **status** (string) - Optional - The status of the MCP server (e.g., 'connected').

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

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

### Board Management API

Source: https://context7.com/jonesphillip/weft/llms.txt

Endpoints for creating, retrieving, updating, and deleting task boards. Boards are persisted using Durable Objects.

```APIDOC
## POST /api/boards

### Description
Creates a new task board.

### Method
POST

### Endpoint
/api/boards

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new board.

### Request Example
```json
{
  "name": "My Project Board"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the newly created board.
  - **id** (string) - The unique identifier for the board.
  - **name** (string) - The name of the board.
  - **ownerId** (string) - The ID of the user who owns the board.
  - **createdAt** (string) - The timestamp when the board was created.
  - **updatedAt** (string) - The timestamp when the board was last updated.
  - **columns** (array) - An array of columns in the board.
  - **tasks** (array) - An array of tasks in the board.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "My Project Board",
    "ownerId": "user-id",
    "createdAt": "2024-01-08T00:00:00Z",
    "updatedAt": "2024-01-08T00:00:00Z",
    "columns": [],
    "tasks": []
  }
}
```

## GET /api/boards/:boardId

### Description
Retrieves a specific board along with all its columns and tasks.

### Method
GET

### Endpoint
/api/boards/:boardId

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the board, including columns and tasks.

### Response Example
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "My Project Board",
    "ownerId": "user-id",
    "createdAt": "2024-01-08T00:00:00Z",
    "updatedAt": "2024-01-08T00:00:00Z",
    "columns": [...],
    "tasks": [...]
  }
}
```

## PUT /api/boards/:boardId

### Description
Updates an existing board. Currently only supports updating the board's name.

### Method
PUT

### Endpoint
/api/boards/:boardId

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board to update.
#### Request Body
- **name** (string) - Required - The new name for the board.

### Response
#### Success Response (200)
Indicates a successful update. The response body is typically empty or a confirmation message.

## DELETE /api/boards/:boardId

### Description
Deletes a specific board.

### Method
DELETE

### Endpoint
/api/boards/:boardId

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board to delete.

### Response
#### Success Response (200)
Indicates a successful deletion. The response body is typically empty or a confirmation message.
```

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

### WebSocket - Real-Time Updates API

Source: https://context7.com/jonesphillip/weft/llms.txt

Provides real-time updates for board changes, including tasks and workflow status, via WebSocket.

```APIDOC
## WebSocket /api/ws?boardId={boardId}

### Description
Establishes a WebSocket connection to receive real-time updates for a specific board. Clients can subscribe to various event types like task creation, updates, and workflow progress.

### Method
WebSocket Connection

### Endpoint
/api/ws

### Parameters
#### Query Parameters
- **boardId** (string) - Required - The unique identifier of the board to subscribe to.

### Request Example
(Client initiates connection using WebSocket API)

### Response
#### Event Types (onmessage)
- **task_created**: New task created on the board. `data` contains task details.
- **task_updated**: An existing task was updated. `data` contains updated task details.
- **workflow_step**: A step in a workflow has progressed. `data` contains step information.
- **workflow_checkpoint**: A workflow requires approval at a checkpoint. `data` contains approval details and data.
- **workflow_complete**: A workflow has finished execution. `data` contains completion status and results.

#### Response Example (Example for `task_created` event)
```json
{
  "type": "task_created",
  "data": {
    "id": "task-uuid",
    "title": "New task",
    "columnId": "col-uuid",
    "..."
  }
}
```

#### Response Example (Example for `workflow_checkpoint` event)
```json
{
  "type": "workflow_checkpoint",
  "data": {
    "planId": "plan-uuid",
    "approvalMessage": "About to send email to 5 recipients",
    "approvalData": {
      "to": "user@example.com",
      "subject": "...",
      "body": "..."
    }
  }
}
```
```

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

### Manage AI Agent Workflows - TypeScript API

Source: https://context7.com/jonesphillip/weft/llms.txt

This snippet demonstrates how to interact with the AI agent workflow API using TypeScript. It covers generating workflow plans, fetching logs, approving checkpoints, requesting changes, and canceling workflows. No external libraries are strictly required beyond standard Fetch API.

```typescript
// Generate and start workflow plan for a task
const planResponse = await fetch(
  '/api/boards/board-uuid/tasks/task-uuid/generate-plan',
  { method: 'POST' }
);

const plan = await planResponse.json();
// { 
//   success: true,
//   data: {
//     id: "plan-uuid",
//     taskId: "task-uuid",
//     boardId: "board-uuid",
//     status: "running",
//     summary: null,
//     steps: [],
//     currentStepIndex: 0,
//     createdAt: "2024-01-08T00:00:00Z"
//   }
// }

// Get workflow logs in real-time
const logsResponse = await fetch(
  '/api/boards/board-uuid/plans/plan-uuid/logs?limit=50&offset=0'
);
const logs = await logsResponse.json();
// { 
//   success: true,
//   data: [
//     {
//       id: "log-uuid",
//       planId: "plan-uuid",
//       level: "info",
//       message: "Agent thinking: I need to search Gmail for Q4 reports",
//       timestamp: "2024-01-08T00:00:00Z"
//     }
//   ]
// }

// Approve pending workflow checkpoint (e.g., before sending email)
await fetch('/api/boards/board-uuid/plans/plan-uuid/checkpoint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'approve',
    feedback: 'Looks good, proceed with sending'
  })
});

// Request changes at checkpoint
await fetch('/api/boards/board-uuid/plans/plan-uuid/checkpoint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'request_changes',
    feedback: 'Change the email subject line',
    data: { subject: 'Updated subject line' }
  })
});

// Cancel running workflow
await fetch('/api/boards/board-uuid/plans/plan-uuid/cancel', {
  method: 'POST'
});

```

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

### Add Built-in GitHub MCP Server

Source: https://context7.com/jonesphillip/weft/llms.txt

Adds a built-in MCP server for GitHub. This operation uses a POST request to the API endpoint for MCP servers, specifying the account ID and MCP ID for GitHub.

```typescript
// Add built-in GitHub MCP server
await fetch('/api/boards/board-uuid/mcp-servers/account', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    accountId: 'github',
    mcpId: 'github'
  })
});
```

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

### Task Operations API

Source: https://context7.com/jonesphillip/weft/llms.txt

Endpoints for managing tasks within board columns, including creation, moving, and updating task details.

```APIDOC
## POST /api/boards/:boardId/tasks

### Description
Creates a new task within a specified column of a board.

### Method
POST

### Endpoint
/api/boards/:boardId/tasks

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board where the task will be created.
#### Request Body
- **columnId** (string) - Required - The ID of the column where the task should be placed.
- **title** (string) - Required - The title of the task.
- **description** (string) - Optional - A detailed description of the task.
- **priority** (string) - Optional - The priority level of the task (e.g., 'low', 'medium', 'high').

### Request Example
```json
{
  "columnId": "column-uuid",
  "title": "Send quarterly report emails",
  "description": "Draft and send Q4 reports to all stakeholders",
  "priority": "high"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the newly created task.
  - **id** (string) - The unique identifier for the task.
  - **columnId** (string) - The ID of the column the task belongs to.
  - **boardId** (string) - The ID of the board the task belongs to.
  - **title** (string) - The title of the task.
  - **description** (string) - The description of the task.
  - **priority** (string) - The priority of the task.
  - **position** (integer) - The position of the task within its column.
  - **createdAt** (string) - The timestamp when the task was created.
  - **updatedAt** (string) - The timestamp when the task was last updated.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "task-uuid",
    "columnId": "column-uuid",
    "boardId": "board-uuid",
    "title": "Send quarterly report emails",
    "description": "Draft and send Q4 reports to all stakeholders",
    "priority": "high",
    "position": 0,
    "createdAt": "2024-01-08T00:00:00Z",
    "updatedAt": "2024-01-08T00:00:00Z"
  }
}
```

## POST /api/boards/:boardId/tasks/:taskId/move

### Description
Moves a task from its current column to a different column, optionally specifying its position.

### Method
POST

### Endpoint
/api/boards/:boardId/tasks/:taskId/move

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board containing the task.
- **taskId** (string) - Required - The unique identifier of the task to move.
#### Request Body
- **columnId** (string) - Required - The ID of the target column.
- **position** (integer) - Required - The desired position of the task within the new column.

### Request Example
```json
{
  "columnId": "new-column-uuid",
  "position": 0
}
```

### Response
#### Success Response (200)
Indicates a successful move operation. The response body is typically empty or a confirmation message.

## PUT /api/boards/:boardId/tasks/:taskId

### Description
Updates the details of an existing task.

### Method
PUT

### Endpoint
/api/boards/:boardId/tasks/:taskId

### Parameters
#### Path Parameters
- **boardId** (string) - Required - The unique identifier of the board containing the task.
- **taskId** (string) - Required - The unique identifier of the task to update.
#### Request Body
- **title** (string) - Optional - The new title for the task.
- **description** (string) - Optional - The new description for the task.
- **priority** (string) - Optional - The new priority for the task.
- **columnId** (string) - Optional - The ID of the column to move the task to.
- **position** (integer) - Optional - The new position of the task within its column.

### Request Example
```json
{
  "title": "Updated task title",
  "priority": "medium"
}
```

### Response
#### Success Response (200)
Indicates a successful update operation. The response body is typically empty or a confirmation message.
```

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

### Manage Credentials: Store, List, Delete (TypeScript)

Source: https://context7.com/jonesphillip/weft/llms.txt

This snippet illustrates how to manage credentials required for various integrations, such as API keys and OAuth tokens. It covers storing new credentials, listing existing ones (without returning sensitive values), and deleting them. Secure credential storage is vital for AI agent operations.

```typescript
// Store Anthropic API key (required for agent execution)
const credResponse = await fetch('/api/boards/board-uuid/credentials', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'anthropic_api_key',
    name: 'Claude API Key',
    value: 'sk-ant-...',
    metadata: {}
  })
});

// Store Google OAuth tokens
await fetch('/api/boards/board-uuid/credentials', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'google_oauth',
    name: 'Google Account',
    value: JSON.stringify({
      access_token: 'ya29.xxx',
      refresh_token: 'xxx',
      expires_at: '2024-01-08T01:00:00Z'
    }),
    metadata: { email: 'user@example.com' }
  })
});

// List credentials (values are never returned)
const credsResponse = await fetch('/api/boards/board-uuid/credentials');
const creds = await credsResponse.json();
// {
//   success: true,
//   data: [
//     { id: "cred-uuid", type: "anthropic_api_key", name: "Claude API Key", createdAt: "..." }
//   ]
// }

// Delete credential
await fetch('/api/boards/board-uuid/credentials/cred-uuid', {
  method: 'DELETE'
});
```

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

### Durable Object RPC for Board Operations - TypeScript

Source: https://context7.com/jonesphillip/weft/llms.txt

This server-side code snippet demonstrates how to perform board operations using Durable Object RPC within a Cloudflare Worker. It includes initializing a board, creating/updating/moving/deleting tasks, and retrieving board data. Requires a Cloudflare Worker environment and a defined BoardDO interface.

```typescript
// Server-side usage in Cloudflare Worker
import type { BoardDO } from './BoardDO';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const boardId = 'board-uuid';

    // Get BoardDO stub with RPC support
    const boardDoId = env.BOARD_DO.idFromName(boardId);
    const boardStub = env.BOARD_DO.get(boardDoId) as DurableObjectStub<BoardDO>;

    // Initialize new board
    const board = await boardStub.initBoard({
      id: boardId,
      name: 'New Board',
      ownerId: 'user-id'
    });

    // Create column
    const column = await boardStub.createColumn(boardId, { name: 'To Do' });

    // Create task
    const task = await boardStub.createTask({
      boardId,
      columnId: column.id,
      title: 'Task title',
      description: 'Task description',
      priority: 'medium'
    });

    // Get board with all data
    const fullBoard = await boardStub.getBoard(boardId);
    // { id, name, ownerId, columns: [...], tasks: [...], createdAt, updatedAt }

    // Update task
    await boardStub.updateTask(task.id, {
      title: 'Updated title',
      priority: 'high'
    });

    // Move task to different column
    await boardStub.moveTask(task.id, {
      columnId: 'another-column-id',
      position: 0
    });

    // Delete task
    await boardStub.deleteTask(task.id);

    return new Response('OK');
  }
};

```