### Installation and Setup

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Instructions on how to install the Arcade SDK and initialize the client with API keys and optional configurations.

```APIDOC
## Installation and Setup

Installing the Arcade SDK and configuring the client with your API key.

```typescript
// Installation: npm install @arcadeai/arcadejs

import Arcade from '@arcadeai/arcadejs';

// Initialize with environment variable (default)
const client = new Arcade({
  apiKey: process.env['ARCADE_API_KEY'], // This is the default and can be omitted
});

// Or initialize with explicit configuration
const clientWithOptions = new Arcade({
  apiKey: 'your-api-key',
  baseURL: 'https://api.arcade.dev', // default
  timeout: 60000, // 1 minute (default)
  maxRetries: 2, // default retry count
  logLevel: 'warn', // 'debug' | 'info' | 'warn' | 'error' | 'off'
});
```
```

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

### Install and Build Project Dependencies

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Installs all project dependencies and builds output files to dist/. Use this command after cloning the repository.

```sh
pnpm install
pnpm build
```

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

### Install @arcadeai/arcadejs

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Install the Arcade TypeScript API library using npm.

```sh
npm install @arcadeai/arcadejs
```

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

### Add and Run Example Scripts

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Add custom example scripts to the examples/ directory. Ensure the script is executable before running it against your API.

```ts
// add an example to examples/<your-example>.ts

#!/usr/bin/env -S npm run tsn -T
…
```

```sh
chmod +x examples/<your-example>.ts
# run the example against your api
pnpm tsn -T examples/<your-example>.ts
```

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

### Install and Configure Arcade SDK Client

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Install the SDK using npm and initialize the client with your API key. You can use environment variables or provide explicit configuration options like baseURL, timeout, maxRetries, and logLevel.

```typescript
// Installation: npm install @arcadeai/arcadejs

import Arcade from '@arcadeai/arcadejs';

// Initialize with environment variable (default)
const client = new Arcade({
  apiKey: process.env['ARCADE_API_KEY'], // This is the default and can be omitted
});

// Or initialize with explicit configuration
const clientWithOptions = new Arcade({
  apiKey: 'your-api-key',
  baseURL: 'https://api.arcade.dev', // default
  timeout: 60000, // 1 minute (default)
  maxRetries: 2, // default retry count
  logLevel: 'warn', // 'debug' | 'info' | 'warn' | 'error' | 'off'
});
```

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

### Install Arcade.js via Git

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Installs the Arcade.js library directly from its Git repository. This is useful for using the latest development version.

```sh
npm install git+ssh://git@github.com:ArcadeAI/arcade-js.git
```

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

### List and Get Formatted Tools

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Fetch tools with schemas pre-formatted for specific AI platforms like OpenAI or Anthropic. Useful for direct integration with these platforms.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// List formatted tools for OpenAI integration
const formattedPage = await client.tools.formatted.list({
  limit: 20,
  toolkit: 'Google',
  format: 'openai', // 'openai' | 'anthropic'
  user_id: 'user@example.com',
});

for (const tool of formattedPage.items) {
  console.log('Tool:', tool.name);
  console.log('OpenAI format:', JSON.stringify(tool.definition, null, 2));
}

// Get a specific formatted tool
const formattedTool = await client.tools.formatted.get('Google.ListEmails', {
  format: 'anthropic',
  user_id: 'user@example.com',
});

console.log('Formatted definition:', formattedTool.definition);
```

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

### Install Bun Types for Package.json

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

Add the @types/bun package to devDependencies for Bun projects, ensuring version compatibility.

```json
{
  "devDependencies": {
    "@types/bun": ">= 1.2.0"
  }
}
```

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

### Auth - Start Authorization

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Initiates the OAuth2 authorization process for a user with a specified provider. This can be done via a simplified helper or with direct control over parameters.

```APIDOC
## Auth - Start Authorization

### Description
Initiates the authorization process for a user with a specific OAuth2 provider.

### Method
POST (implied by SDK function call)

### Endpoint
/auth/start (implied by SDK function call)

### Parameters
#### Request Body (for direct authorization)
- **user_id** (string) - Required - The unique identifier for the user.
- **auth_requirement** (object) - Required - Defines the authentication requirements.
  - **provider_id** (string) - Required - The ID of the authentication provider (e.g., 'github', 'google').
  - **provider_type** (string) - Required - The type of provider, typically 'oauth2'.
  - **oauth2** (object) - Optional - OAuth2 specific configurations.
    - **scopes** (array of strings) - Optional - List of requested scopes for the OAuth2 token.
- **next_uri** (string) - Optional - The URI to redirect to after authorization is complete.

### Request Example (Simplified Helper)
```typescript
const authResponse = await client.auth.start('user@example.com', 'github', {
  providerType: 'oauth2', // default
  scopes: ['repo', 'user:email'],
});
```

### Request Example (Direct Authorization)
```typescript
const directAuth = await client.auth.authorize({
  user_id: 'user@example.com',
  auth_requirement: {
    provider_id: 'google',
    provider_type: 'oauth2',
    oauth2: {
      scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
    },
  },
  next_uri: 'https://myapp.com/oauth/callback',
});
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the authorization process.
- **status** (string) - The current status of the authorization (e.g., 'pending', 'completed').
- **url** (string) - The URL the user needs to visit to authorize the application.

#### Response Example
```json
{
  "id": "auth-id-123",
  "status": "pending",
  "url": "https://auth.example.com/authorize?id=auth-id-123"
}
```
```

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

### Install Node.js Types for Package.json

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

Add the appropriate @types/node package to devDependencies for Node.js projects, ensuring version compatibility.

```json
{
  "devDependencies": {
    "@types/node": ">= 20"
  }
}
```

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

### List and Get Workers with Pagination

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Demonstrates listing all workers with pagination controls (limit and offset) and retrieving details for a specific worker. Also shows how to check a worker's health status and list its tools.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// List all workers with pagination
const workersPage = await client.workers.list({
  limit: 50,
  offset: 0,
});

for (const worker of workersPage.items) {
  console.log('Worker ID:', worker.id);
  console.log('Type:', worker.type);
  console.log('Enabled:', worker.enabled);
  console.log('Managed:', worker.managed);
  console.log('Requirements met:', worker.requirements?.met);
}

// Get a specific worker
const worker = await client.workers.get('my-worker-id');
console.log('Worker:', worker);

// Check worker health
const health = await client.workers.health('my-worker-id');
console.log('Healthy:', health.healthy);
console.log('Message:', health.message);

// List tools provided by a worker
const workerToolsPage = await client.workers.tools('my-worker-id', {
  limit: 20,
});

for (const tool of workerToolsPage.items) {
  console.log('Tool:', tool.fully_qualified_name);
}
```

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

### Configure Default HTTP Agent for Client

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

Configure the default HTTP agent for all requests using the `httpAgent` option. This example uses `HttpsProxyAgent` for proxy support.

```typescript
import Arcade from '@arcadeai/arcadejs';
import http from 'http';
import { HttpsProxyAgent } from 'https-proxy-agent';

// Configure the default for all requests:
const client = new Arcade({
  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
});
```

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

### Tools - Get Tool

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieves the specification for a specific tool by its fully qualified name.

```APIDOC
## Tools - Get Tool

### Description
Retrieves the specification for a specific tool by its fully qualified name.

### Method
GET

### Endpoint
/tools/{fully_qualified_name}

### Parameters
#### Path Parameters
- **fully_qualified_name** (string) - Required - The fully qualified name of the tool to retrieve.

#### Query Parameters
- **user_id** (string) - Optional - The user ID for context.
- **include_format** (array of strings) - Optional - Includes formatted schemas for the specified AI platforms (e.g., 'openai', 'anthropic').

### Request Example
```json
{
  "user_id": "user@example.com",
  "include_format": ["openai", "anthropic"]
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the tool.
- **qualified_name** (string) - The qualified name of the tool.
- **fully_qualified_name** (string) - The fully qualified name of the tool.
- **description** (string) - A description of the tool.
- **input** (object) - Schema for the tool's input.
  - **parameters** (array) - List of input parameters.
    - **name** (string) - The name of the parameter.
    - **value_schema** (object) - The schema defining the parameter's value.
      - **val_type** (string) - The data type of the parameter value.
    - **required** (boolean) - Whether the parameter is required.
    - **description** (string) - A description of the parameter.
- **requirements** (object) - Requirements for using the tool.
  - **authorization** (object) - Authorization requirements.
    - **provider_id** (string) - The ID of the authorization provider.
    - **status** (string) - The authorization status.
    - **oauth2** (object) - OAuth2 specific details.
      - **scopes** (array of strings) - Required OAuth2 scopes.
  - **secrets** (array) - List of secret requirements.
    - **key** (string) - The key of the secret.
    - **met** (boolean) - Indicates if the secret requirement is met.

#### Response Example
```json
{
  "name": "ListEmails",
  "qualified_name": "Google.ListEmails",
  "fully_qualified_name": "Google.ListEmails",
  "description": "Lists emails from a Gmail account.",
  "input": {
    "parameters": [
      {
        "name": "query",
        "value_schema": {"val_type": "string"},
        "required": false,
        "description": "The query to search for."
      }
    ]
  },
  "requirements": {
    "authorization": {"provider_id": "google", "status": "authorized", "oauth2": {"scopes": ["https://www.googleapis.com/auth/gmail.readonly"]}},
    "secrets": [{"key": "api_key", "met": true}]
  }
}
```
```

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

### Start Authorization with OAuth2 Provider

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Initiates the OAuth2 authorization process for a user with a specified provider. Use this helper for simplified flows or the `authorize` method for full control over parameters.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// Start authorization with a provider (simplified helper)
const authResponse = await client.auth.start('user@example.com', 'github', {
  providerType: 'oauth2', // default
  scopes: ['repo', 'user:email'],
});

console.log('Authorization ID:', authResponse.id);
console.log('Status:', authResponse.status);
console.log('Auth URL:', authResponse.url);
```

```typescript
// Direct authorization with full control
const directAuth = await client.auth.authorize({
  user_id: 'user@example.com',
  auth_requirement: {
    provider_id: 'google',
    provider_type: 'oauth2',
    oauth2: {
      scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
    },
  },
  next_uri: 'https://myapp.com/oauth/callback',
});
```

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

### List Scheduled Tool Executions

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieve a paginated list of scheduled tool executions, including their status and run times. Also shows how to get details for a specific execution and its attempts.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// List scheduled tool executions
const scheduledPage = await client.tools.scheduled.list({
  limit: 50,
  offset: 0,
});

for (const execution of scheduledPage.items) {
  console.log('Execution ID:', execution.id);
  console.log('Tool:', execution.tool_name);
  console.log('Status:', execution.execution_status);
  console.log('Run at:', execution.run_at);
  console.log('Finished at:', execution.finished_at);
  console.log('User ID:', execution.user_id);
}

// Get details of a specific scheduled execution
const scheduledExecution = await client.tools.scheduled.get('execution-id-123');
console.log('Execution:', scheduledExecution.tool_execution);

// Access execution attempts
if (scheduledExecution.tool_execution_attempts) {
  for (const attempt of scheduledExecution.tool_execution_attempts) {
    console.log('Attempt ID:', attempt.id);
    console.log('Success:', attempt.success);
    console.log('Started at:', attempt.started_at);
    console.log('Output:', attempt.output?.value);
  }
}
```

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

### Handle API Errors with Catch Block

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Handle potential API errors by using a .catch() block. This example demonstrates how to check if an error is an instance of Arcade.APIError and log its status, name, and headers.

```ts
const chatResponse = await client.chat.completions
  .create({ messages: [{ role: 'user', content: 'Hello, how can I use Arcade?' }] })
  .catch(async (err) => {
    if (err instanceof Arcade.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
```

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

### Set up Mock Server for Tests

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Sets up a mock server required for running most tests against the OpenAPI spec. Execute this script before running tests.

```sh
./scripts/mock
```

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

### Initialize Arcade Client and Execute Tool

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Initialize the Arcade client with an API key and execute a tool. The API key can be omitted if it's set as the default environment variable ARCADE_API_KEY.

```js
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade({
  apiKey: process.env['ARCADE_API_KEY'], // This is the default and can be omitted
});

const executeToolResponse = await client.tools.execute({
  tool_name: 'Google.ListEmails',
  input: { n_emails: 10 },
  user_id: 'user@example.com',
});

console.log(executeToolResponse.id);
```

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

### Get Specific Auth Provider

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Fetches the details for a single authentication provider by its ID.

```typescript
// Get a specific provider
const providerDetails = await client.admin.authProviders.get('google');
console.log('Provider details:', providerDetails);
```

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

### Configure Deno Proxy with HttpClient

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

In Deno, create a custom `HttpClient` using `Deno.createHttpClient` with proxy settings and pass it via the `client` property in `fetchOptions`.

```typescript
import Arcade from 'npm:@arcadeai/arcadejs';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Arcade({
  fetchOptions: {
    client: httpClient,
  },
});
```

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

### Workers - List and Get

Source: https://context7.com/arcadeai/arcade-js/llms.txt

List all workers and retrieve individual worker details including health status.

```APIDOC
## Workers - List and Get

List all workers and retrieve individual worker details including health status.

### GET /workers

#### Description
Lists all workers with optional pagination.

#### Method
GET

#### Endpoint
/workers

#### Query Parameters
- **limit** (number) - Optional - The maximum number of workers to return.
- **offset** (number) - Optional - The number of workers to skip.

#### Response
##### Success Response (200)
- **items** (array) - A list of worker objects.
  - **id** (string) - The worker's unique identifier.
  - **type** (string) - The type of worker ('http' or 'mcp').
  - **enabled** (boolean) - Whether the worker is enabled.
  - **managed** (boolean) - Whether the worker is managed by the system.
  - **requirements** (object) - Information about worker requirements.
    - **met** (boolean) - Whether the requirements are met.
- **total_count** (number) - The total number of workers available.

### GET /workers/{id}

#### Description
Retrieves details for a specific worker.

#### Method
GET

#### Endpoint
/workers/{id}

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the worker to retrieve.

#### Response
##### Success Response (200)
- **id** (string) - The worker's unique identifier.
- **type** (string) - The type of worker ('http' or 'mcp').
- **enabled** (boolean) - Whether the worker is enabled.
- **managed** (boolean) - Whether the worker is managed by the system.
- **requirements** (object) - Information about worker requirements.
  - **met** (boolean) - Whether the requirements are met.

### GET /workers/{id}/health

#### Description
Checks the health status of a specific worker.

#### Method
GET

#### Endpoint
/workers/{id}/health

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the worker to check.

#### Response
##### Success Response (200)
- **healthy** (boolean) - Whether the worker is healthy.
- **message** (string) - A status message.

### GET /workers/{id}/tools

#### Description
Lists the tools provided by a specific worker.

#### Method
GET

#### Endpoint
/workers/{id}/tools

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the worker.

#### Query Parameters
- **limit** (number) - Optional - The maximum number of tools to return.
- **offset** (number) - Optional - The number of tools to skip.

#### Response
##### Success Response (200)
- **items** (array) - A list of tool objects.
  - **fully_qualified_name** (string) - The fully qualified name of the tool.
- **total_count** (number) - The total number of tools available.

### Request Example (List Workers)
```json
{
  "limit": 50,
  "offset": 0
}
```

### Response Example (List Workers)
```json
{
  "items": [
    {
      "id": "my-http-worker",
      "type": "http",
      "enabled": true,
      "managed": false,
      "requirements": { "met": true }
    }
  ],
  "total_count": 1
}
```

### Response Example (Get Worker)
```json
{
  "id": "my-http-worker",
  "type": "http",
  "enabled": true,
  "managed": false,
  "requirements": { "met": true }
}
```

### Response Example (Worker Health)
```json
{
  "healthy": true,
  "message": "Worker is running normally."
}
```

### Response Example (List Worker Tools)
```json
{
  "items": [
    { "fully_qualified_name": "example.tool.calculator" }
  ],
  "total_count": 1
}
```
```

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

### Create Client with Modified Options

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Create a new client instance with updated default options by using the `withOptions` method. This allows for creating specialized clients without re-initializing.

```typescript
// Create a new client with modified options
const customClient = client.withOptions({
  timeout: 120000,
  maxRetries: 5,
});
```

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

### Install Cloudflare Workers Types for Package.json

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

Add the @cloudflare/workers-types package to devDependencies for Cloudflare Workers projects, specifying a compatible version.

```json
{
  "devDependencies": {
    "@cloudflare/workers-types": ">= 0.20221111.0"
  }
}
```

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

### Instantiate Arcade Client with Fetch Options

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Provide a `fetchOptions` object when instantiating the client to set custom fetch options. Request-specific options override client options.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade({
  fetchOptions: {
    // `RequestInit` options
  },
});
```

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

### Get Specific Tool Definition

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieve the detailed specification for a single tool using its fully qualified name. Useful for inspecting parameters and requirements.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// Get a specific tool definition
const tool = await client.tools.get('Google.ListEmails', {
  user_id: 'user@example.com',
  include_format: ['openai', 'anthropic'],
});

console.log('Tool name:', tool.name);
console.log('Qualified name:', tool.qualified_name);
console.log('Fully qualified name:', tool.fully_qualified_name);
console.log('Description:', tool.description);

// Inspect input parameters
if (tool.input.parameters) {
  for (const param of tool.input.parameters) {
    console.log(`Parameter: ${param.name}`);
    console.log(`  Type: ${param.value_schema.val_type}`);
    console.log(`  Required: ${param.required}`);
    console.log(`  Description: ${param.description}`);
  }
}

// Check authorization requirements
if (tool.requirements?.authorization) {
  console.log('Auth provider:', tool.requirements.authorization.provider_id);
  console.log('Auth status:', tool.requirements.authorization.status);
  console.log('OAuth2 scopes:', tool.requirements.authorization.oauth2?.scopes);
}

// Check secret requirements
if (tool.requirements?.secrets) {
  for (const secret of tool.requirements.secrets) {
    console.log(`Secret: ${secret.key}, Met: ${secret.met}`);
  }
}
```

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

### Initialize Arcade Client with Options

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Initialize the Arcade client with default request options such as timeout and maximum retries. These options can be overridden on a per-request basis.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade({
  timeout: 60000,
  maxRetries: 2,
});
```

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

### List Tools with Pagination and Filtering

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Use this to list available tools, with options to filter by toolkit, user ID, and include formatted schemas. Supports auto-pagination for iterating through all tools.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// List all tools with pagination
const toolsPage = await client.tools.list({
  limit: 20,
  offset: 0,
  toolkit: 'Google', // filter by toolkit name
  user_id: 'user@example.com',
  include_format: ['arcade', 'openai', 'anthropic'], // include formatted schemas
  include_all_versions: true,
});

for (const tool of toolsPage.items) {
  console.log('Tool:', tool.fully_qualified_name);
  console.log('Description:', tool.description);
  console.log('Toolkit:', tool.toolkit.name, tool.toolkit.version);
  console.log('Parameters:', tool.input.parameters?.map(p => p.name));
  console.log('Requirements met:', tool.requirements?.met);
}

// Auto-pagination to iterate through all tools
for await (const tool of client.tools.list()) {
  console.log('Tool:', tool.fully_qualified_name);
}

// Filter tools by metadata
const filteredTools = await client.tools.list({
  filter: JSON.stringify({
    read_only: true,
    service_domains: ['email', 'calendar'],
  }),
});
```

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

### Configure Bun Proxy

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Set the `proxy` option within `fetchOptions` to a string URL for configuring proxy behavior in Bun environments.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});
```

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

### Add Undocumented Request Parameters

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Use `// @ts-expect-error` to add undocumented parameters to requests. For GET requests, these are added to the query; for others, they are sent in the body.

```typescript
client.tools.execute({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});
```

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

### Configure Fetch Options with Proxy Agent

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

Replace `httpAgent` with `fetchOptions` for proxy support. Use `undici.ProxyAgent` and configure it within `fetchOptions.dispatcher`.

```typescript
import Arcade from '@arcadeai/arcadejs';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent(process.env.PROXY_URL);
const client = new Arcade({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

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

### Get Response as Raw Object

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieve the raw HTTP response object as soon as headers are received. This is beneficial for streaming responses or custom response parsing logic.

```typescript
// Get response as soon as headers are received (for streaming/custom parsing)
const rawResp = await client.chat.completions
  .create({ messages: [{ role: 'user', content: 'Hello' }] })
  .asResponse();

console.log('Status:', rawResp.status);
```

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

### Use TypeScript Definitions for Chat Completion

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Initialize the Arcade client and use TypeScript definitions for chat completion parameters. Ensure you have the necessary types imported.

```ts
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade({
  apiKey: process.env['ARCADE_API_KEY'], // This is the default and can be omitted
});

const params: Arcade.Chat.CompletionCreateParams = {
  messages: [{ role: 'user', content: 'Hello, how can I use Arcade?' }],
};
const chatResponse: Arcade.ChatResponse = await client.chat.completions.create(params);
```

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

### Access Raw Response Data with asResponse()

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Use `.asResponse()` to get the raw `Response` object. This method returns headers early and does not consume the body, allowing for custom parsing or streaming.

```typescript
const client = new Arcade();

const response = await client.chat.completions
  .create({ messages: [{ role: 'user', content: 'Hello, how can I use Arcade?' }] })
  .asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object
```

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

### Run Project Tests

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Executes the test suite for the Arcade.js project. Ensure the mock server is running if required by the tests.

```sh
pnpm run test
```

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

### Tools - Execute Tool

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Executes a tool by name with specified input arguments and user context. Tools can be run immediately or scheduled for future execution.

```APIDOC
## Tools - Execute Tool

Executes a tool by name with specified input arguments and user context. Tools can be run immediately or scheduled for future execution.

### Method
POST

### Endpoint
`/tools/execute`

### Parameters
#### Request Body
- **tool_name** (string) - Required - The name of the tool to execute.
- **input** (object) - Required - The input arguments for the tool.
- **user_id** (string) - Required - The identifier for the user on whose behalf the tool is being executed.
- **run_at** (string) - Optional - ISO 8601 formatted timestamp for scheduling future execution.
- **tool_version** (string) - Optional - The specific version of the tool to use.
- **include_error_stacktrace** (boolean) - Optional - Whether to include error stacktraces in the response for debugging.

### Request Example
```json
{
  "tool_name": "Google.ListEmails",
  "input": { "n_emails": 10 },
  "user_id": "user@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the execution request.
- **success** (boolean) - Indicates if the tool execution was successful.
- **output** (object | null) - The output of the tool execution, or null if an error occurred.
  - **value** (any) - The actual output data from the tool.
  - **authorization** (object | null) - Information about required authorization for the tool.
    - **url** (string) - The URL to redirect the user to for authorization.
    - **status** (string) - The current status of the authorization.
  - **error** (object | null) - Information about an error that occurred during execution.
    - **kind** (string) - The type of error.
    - **message** (string) - A human-readable error message.
    - **can_retry** (boolean) - Whether the operation can be retried.

#### Response Example
```json
{
  "id": "exec_12345",
  "success": true,
  "output": {
    "value": [
      { "subject": "Meeting Reminder", "from": "calendar@example.com" }
    ],
    "authorization": null,
    "error": null
  }
}
```

```json
{
  "id": "exec_67890",
  "success": false,
  "output": {
    "value": null,
    "authorization": {
      "url": "https://auth.arcade.dev/authorize?tool=Google.ListEmails&user=user@example.com",
      "status": "pending"
    },
    "error": null
  }
}
```
```

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

### Configure Web Shims for Fetch API

Source: https://github.com/arcadeai/arcade-js/blob/main/MIGRATION.md

The '@arcadeai/arcadejs/shims' imports have been removed. Configure your global types to use the Web Fetch API instead of node-fetch.

```typescript
// Tell TypeScript and the package to use the global Web fetch instead of node-fetch.
import '@arcadeai/arcadejs/shims/web';
import Arcade from '@arcadeai/arcadejs';
```

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

### Execute a Tool with Arcade SDK

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Execute a tool by its name with specified input arguments and user context. Tools can be run immediately or scheduled for future execution. Handles potential authorization requirements and errors returned by the tool.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// Execute a tool immediately
const executeResponse = await client.tools.execute({
  tool_name: 'Google.ListEmails',
  input: { n_emails: 10 },
  user_id: 'user@example.com',
});

console.log('Execution ID:', executeResponse.id);
console.log('Success:', executeResponse.success);
console.log('Output:', executeResponse.output?.value);

// Schedule a tool for future execution
const scheduledResponse = await client.tools.execute({
  tool_name: 'Slack.SendMessage',
  input: { channel: '#general', message: 'Hello World' },
  user_id: 'user@example.com',
  run_at: '2024-12-01T10:00:00', // ISO 8601 format
  tool_version: '1.0.0', // optional specific version
  include_error_stacktrace: true, // optional for debugging
});

// Handle authorization requirements
if (executeResponse.output?.authorization) {
  console.log('Authorization required:', executeResponse.output.authorization.url);
  console.log('Status:', executeResponse.output.authorization.status);
}

// Handle errors
if (executeResponse.output?.error) {
  console.log('Error kind:', executeResponse.output.error.kind);
  console.log('Error message:', executeResponse.output.error.message);
  console.log('Can retry:', executeResponse.output.error.can_retry);
}
```

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

### Link Local Arcade.js Repository with pnpm

Source: https://github.com/arcadeai/arcade-js/blob/main/CONTRIBUTING.md

Links a local clone of the Arcade.js repository to your project using pnpm. This is useful for testing local modifications.

```sh
# With pnpm
$ pnpm link --global
$ cd ../my-package
$ pnpm link --global @arcadeai/arcadejs
```

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

### Create HTTP and MCP Workers

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Demonstrates creating both HTTP and MCP type workers. Ensure correct configuration for URIs, secrets, timeouts, and retries based on the worker type.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// Create an HTTP worker
const httpWorker = await client.workers.create({
  id: 'my-http-worker',
  type: 'http',
  enabled: true,
  http: {
    uri: 'https://my-toolkit.example.com/api',
    secret: 'worker-secret-key',
    timeout: 30000,
    retry: 3,
  },
});

console.log('Worker created:', httpWorker.id);
console.log('Type:', httpWorker.type);

// Create an MCP (Model Context Protocol) worker
const mcpWorker = await client.workers.create({
  id: 'my-mcp-worker',
  type: 'mcp',
  enabled: true,
  mcp: {
    uri: 'https://mcp-server.example.com',
    timeout: 60000,
    retry: 2,
    headers: { 'X-Custom-Header': 'value' },
    secrets: { 'API_KEY': 'secret-value' },
    oauth2: {
      client_id: 'oauth-client-id',
      client_secret: 'oauth-client-secret',
      authorization_url: 'https://auth.example.com/oauth/authorize',
    },
  },
});
```

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

### Pass Custom Fetch Client to Arcade Constructor

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Provide a custom `fetch` implementation directly to the `Arcade` client constructor via the `fetch` option.

```typescript
import Arcade from '@arcadeai/arcadejs';
import fetch from 'my-fetch';

const client = new Arcade({ fetch });
```

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

### Tools - List Tools

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Returns a paginated list of available tools, optionally filtered by toolkit and metadata. Supports auto-pagination.

```APIDOC
## Tools - List Tools

### Description
Returns a paginated list of available tools, optionally filtered by toolkit and metadata. Supports auto-pagination.

### Method
GET

### Endpoint
/tools

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of tools to return per page.
- **offset** (integer) - Optional - The number of tools to skip before starting to collect the result set.
- **toolkit** (string) - Optional - Filters tools by the specified toolkit name.
- **user_id** (string) - Optional - Filters tools associated with a specific user ID.
- **include_format** (array of strings) - Optional - Includes formatted schemas for the specified AI platforms (e.g., 'arcade', 'openai', 'anthropic').
- **include_all_versions** (boolean) - Optional - If true, includes all versions of the tools.
- **filter** (string) - Optional - A JSON string representing filter criteria for tools (e.g., `{"read_only": true, "service_domains": ["email", "calendar"]}`).

### Request Example
```json
{
  "limit": 20,
  "offset": 0,
  "toolkit": "Google",
  "user_id": "user@example.com",
  "include_format": ["arcade", "openai", "anthropic"],
  "include_all_versions": true,
  "filter": "{\"read_only\": true, \"service_domains\": [\"email\", \"calendar\"]}"
}
```

### Response
#### Success Response (200)
- **items** (array) - A list of tool objects.
  - **fully_qualified_name** (string) - The unique identifier for the tool.
  - **description** (string) - A description of the tool.
  - **toolkit** (object) - Information about the toolkit the tool belongs to.
    - **name** (string) - The name of the toolkit.
    - **version** (string) - The version of the toolkit.
  - **input** (object) - Schema for the tool's input parameters.
    - **parameters** (array) - List of input parameters.
      - **name** (string) - The name of the parameter.
  - **requirements** (object) - Requirements for using the tool.
    - **met** (boolean) - Indicates if the requirements are met.

#### Response Example
```json
{
  "items": [
    {
      "fully_qualified_name": "Google.ListEmails",
      "description": "Lists emails from a Gmail account.",
      "toolkit": {"name": "Google", "version": "1.0"},
      "input": {"parameters": [{"name": "query"}]},
      "requirements": {"met": true}
    }
  ],
  "has_more": false
}
```
```

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

### Tools - Formatted Tools

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieve tools with pre-formatted schemas for specific AI platforms like OpenAI or Anthropic.

```APIDOC
## Tools - Formatted Tools - List

### Description
Retrieve tools with pre-formatted schemas for specific AI platforms like OpenAI or Anthropic.

### Method
GET

### Endpoint
/tools/formatted

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of formatted tools to return per page.
- **offset** (integer) - Optional - The number of formatted tools to skip before starting to collect the result set.
- **toolkit** (string) - Optional - Filters tools by the specified toolkit name.
- **format** (string) - Required - The desired format for the tool schema ('openai' or 'anthropic').
- **user_id** (string) - Optional - The user ID for context.

### Request Example
```json
{
  "limit": 20,
  "toolkit": "Google",
  "format": "openai",
  "user_id": "user@example.com"
}
```

### Response
#### Success Response (200)
- **items** (array) - A list of formatted tool objects.
  - **name** (string) - The name of the tool.
  - **definition** (object) - The tool definition formatted for the specified AI platform.

#### Response Example
```json
{
  "items": [
    {
      "name": "ListEmails",
      "definition": {
        "name": "list_emails",
        "description": "Lists emails from a Gmail account.",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {"type": "string", "description": "The query to search for."}
          }
        }
      }
    }
  ],
  "has_more": false
}
```

## Tools - Formatted Tools - Get Specific Tool

### Description
Get a specific tool with its schema pre-formatted for a given AI platform.

### Method
GET

### Endpoint
/tools/formatted/{fully_qualified_name}

### Parameters
#### Path Parameters
- **fully_qualified_name** (string) - Required - The fully qualified name of the tool.

#### Query Parameters
- **format** (string) - Required - The desired format for the tool schema ('openai' or 'anthropic').
- **user_id** (string) - Optional - The user ID for context.

### Request Example
```json
{
  "format": "anthropic",
  "user_id": "user@example.com"
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the tool.
- **definition** (object) - The tool definition formatted for the specified AI platform.

#### Response Example
```json
{
  "name": "ListEmails",
  "definition": {
    "name": "list_emails",
    "description": "Lists emails from a Gmail account.",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": {"type": "string", "description": "The query to search for."}
      }
    }
  }
}
```
```

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

### List All Secrets

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Demonstrates how to retrieve a list of all secrets managed by the system, including their IDs, keys, descriptions, and last accessed times. Supports pagination for large numbers of secrets.

```typescript
// List all secrets
const secretsList = await client.admin.secrets.list();
console.log('Total secrets:', secretsList.total_count);

for (const s of secretsList.items || []) {
  console.log('Secret:', s.key);
  console.log('  ID:', s.id);
  console.log('  Description:', s.description);
  console.log('  Last accessed:', s.last_accessed_at);
}
```

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

### Configure Node.js Proxy with Undici

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Use `fetchOptions` with a `dispatcher` property set to an `undici.ProxyAgent` to configure proxy behavior in Node.js environments.

```typescript
import Arcade from '@arcadeai/arcadejs';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new Arcade({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

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

### Authorize a Tool with Arcade SDK

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Authorize a user for a specific tool, initiating the OAuth flow if necessary. Handles the authorization status and provides a redirect URL if pending. Access granted context is available upon completion.

```typescript
import Arcade from '@arcadeai/arcadejs';

const client = new Arcade();

// Authorize a user for a specific tool
const authResponse = await client.tools.authorize({
  tool_name: 'Google.ListEmails',
  user_id: 'user@example.com',
  next_uri: 'https://myapp.com/callback', // redirect after auth
  tool_version: '1.0.0', // optional
});

console.log('Authorization ID:', authResponse.id);
console.log('Status:', authResponse.status); // 'not_started' | 'pending' | 'completed' | 'failed'
console.log('Provider:', authResponse.provider_id);

// If authorization is pending, redirect user to the auth URL
if (authResponse.status === 'pending' && authResponse.url) {
  console.log('Redirect user to:', authResponse.url);
}

// Access granted context when completed
if (authResponse.status === 'completed' && authResponse.context) {
  console.log('Token:', authResponse.context.token);
  console.log('User info:', authResponse.context.user_info);
}
```

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

### Provide Custom Logger to Arcade Client

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Integrate a custom logger, such as pino, by passing it to the `logger` option during client initialization. The `logLevel` option still filters messages sent to the custom logger.

```typescript
import Arcade from '@arcadeai/arcadejs';
import pino from 'pino';

const logger = pino();

const client = new Arcade({
  logger: logger.child({ name: 'Arcade' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});
```

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

### Iterate Through All Pages of List Results

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Use the 'for await...of' syntax to automatically fetch and iterate through all items across paginated list results from the Arcade API.

```ts
async function fetchAllUserConnectionResponses(params) {
  const allUserConnectionResponses = [];
  // Automatically fetches more pages as needed.
  for await (const userConnectionResponse of client.admin.userConnections.list()) {
    allUserConnectionResponses.push(userConnectionResponse);
  }
  return allUserConnectionResponses;
}
```

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

### Polyfill Global Fetch Client

Source: https://github.com/arcadeai/arcade-js/blob/main/README.md

Replace the global `fetch` function with a custom implementation by assigning it to `globalThis.fetch`.

```typescript
import fetch from 'my-fetch';

globalThis.fetch = fetch;
```

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

### List All Auth Providers

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Retrieve a list of all configured authentication providers. Iterates through the items and logs their IDs and statuses.

```typescript
// List all auth providers
const providersList = await client.admin.authProviders.list();
for (const p of providersList.items || []) {
  console.log('Provider:', p.id, 'Status:', p.status);
}
```

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

### Tools - Authorize Tool

Source: https://context7.com/arcadeai/arcade-js/llms.txt

Authorizes a user for a specific tool, initiating the OAuth flow if required by the tool's provider.

```APIDOC
## Tools - Authorize Tool

Authorizes a user for a specific tool, initiating the OAuth flow if required by the tool's provider.

### Method
POST

### Endpoint
`/tools/authorize`

### Parameters
#### Request Body
- **tool_name** (string) - Required - The name of the tool to authorize.
- **user_id** (string) - Required - The identifier for the user.
- **next_uri** (string) - Required - The URI to redirect to after the authorization process is complete.
- **tool_version** (string) - Optional - The specific version of the tool to authorize.

### Request Example
```json
{
  "tool_name": "Google.ListEmails",
  "user_id": "user@example.com",
  "next_uri": "https://myapp.com/callback"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the authorization request.
- **status** (string) - The status of the authorization ('not_started', 'pending', 'completed', 'failed').
- **provider_id** (string) - The identifier of the authorization provider.
- **url** (string | null) - The URL to redirect the user to for authorization, if status is 'pending'.
- **context** (object | null) - The authorization context, available when status is 'completed'.
  - **token** (string) - The access token obtained.
  - **user_info** (object) - Information about the authorized user.

#### Response Example
```json
{
  "id": "auth_abcde",
  "status": "pending",
  "provider_id": "google",
  "url": "https://auth.arcade.dev/authorize?auth_id=auth_abcde",
  "context": null
}
```

```json
{
  "id": "auth_fghij",
  "status": "completed",
  "provider_id": "google",
  "url": null,
  "context": {
    "token": "ya29.a0...",
    "user_info": { "email": "user@example.com", "name": "Example User" }
  }
}
```
```