> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Typescript

# Barndoor TypeScript SDK

A lightweight, **framework-agnostic** TypeScript/JavaScript client for the Barndoor Platform REST APIs and Model Context Protocol (MCP) servers.

The SDK supports *lazy authentication*—you can build an SDK instance first, then inject a JWT later with `authenticate()`.

The SDK removes boiler-plate around:

* Secure, offline-friendly **authentication to Barndoor** (interactive PKCE flow + token caching).
* **Server registry** – list, inspect and connect third-party providers (Salesforce, Notion, Slack …).
* **Managed Connector Proxy** – build ready-to-use connection parameters for any LLM/agent framework (CrewAI, LangChain, custom code …) without importing Barndoor-specific adapters.

#### Be sure to checkout our [examples](https://github.com/barndoor-ai/barndoor-ts-sdk/tree/main/examples) and our NPM [package](https://www.npmjs.com/package/@barndoor-ai/sdk)

## Installation

```bash theme={null}
npm install @barndoor-ai/sdk
```

## Quick Start

### Basic Usage

```typescript theme={null}
import { BarndoorSDK } from '@barndoor-ai/sdk';

// ① token known at construction time (unchanged)
const sdk = new BarndoorSDK('https://your-orgplatform.barndoor.ai', {
  token: 'your-jwt'
});
```

```typescript theme={null}
// ② deferred login (new)
const sdk = new BarndoorSDK('https://your-org.platform.barndoor.ai');
await sdk.authenticate('your-jwt');

// List available MCP servers
const servers = await sdk.listServers();
console.log('Available servers:', servers);

// Get details for a specific server
const server = await sdk.getServer('server-uuid');
console.log('Server details:', server);

// Clean up
await sdk.close();
```

### Interactive Login

For development and prototyping, use the interactive login helper:

`loginInteractive()` builds an SDK *without* requiring `token` in the ctor—it internally calls `sdk.authenticate()` for you.

```typescript theme={null}
import { loginInteractive } from '@barndoor-ai/sdk';

// Automatically handles OAuth flow and token caching
const sdk = await loginInteractive();
const servers = await sdk.listServers();
```

### Complete Workflow

```typescript theme={null}
import {
  loginInteractive,
  ensureServerConnected,
  makeMcpConnectionParams
} from '@barndoor-ai/sdk';

async function main() {
  // 1. Login (handles OAuth + caching)
  const sdk = await loginInteractive();

  // 2. Ensure server is connected (launches OAuth if needed)
  await ensureServerConnected(sdk, 'notion'); // sdk.ensureServerConnected(...) is also available directly

  // 3. Get connection parameters for your AI framework
  const [params, publicUrl] = await makeMcpConnectionParams(sdk, 'notion');

  // 4. Use with any MCP-compatible framework
  console.log('MCP URL:', params.url);
  console.log('Headers:', params.headers);

  await sdk.close();
}
```

## Environment Configuration

The SDK automatically detects your environment and configures appropriate endpoints:

```bash theme={null}
# Development
export MODE=development
export AGENT_CLIENT_ID=your_client_id
export AGENT_CLIENT_SECRET=your_client_secret

# Production  
export MODE=production
export AGENT_CLIENT_ID=your_client_id
export AGENT_CLIENT_SECRET=your_client_secret

# Local development
export MODE=localdev
export BARNDOOR_API=http://localhost:8000
export BARNDOOR_URL=http://localhost:8000
```

If you run without a token at construction time the SDK will still read `AGENT_CLIENT_ID/SECRET` when `loginInteractive()` is invoked.

## API Reference

### BarndoorSDK

Main SDK class for API interactions.

```javascript theme={null}
const sdk = new BarndoorSDK(apiBaseUrl, options);
```

**Parameters:**

* `apiBaseUrl` (string): Base URL of the Barndoor API
* `options.token?` (string): Initial JWT (pass later via authenticate() if omitted)
* `options.timeout` (number): Request timeout in seconds (default: 30)
* `options.maxRetries` (number): Maximum retry attempts (default: 3)

**Methods:**

#### `authenticate(jwtToken)`

Sets/validates token for the SDK instance.

```typescript theme={null}
await sdk.authenticate(jwtToken);
// Returns: Promise<void>
```

#### `ensureServerConnected(serverSlug, options?)`

Ensure a server is connected, launching OAuth if needed – same behaviour as quick-start helper.

```typescript theme={null}
await sdk.ensureServerConnected('notion', { pollSeconds: 2 });
// Returns: Promise<void>
```

#### `listServers()`

List all MCP servers available to your organization.

```typescript theme={null}
const servers = await sdk.listServers();
// Returns: ServerSummary[]
```

#### `getServer(serverId)`

Get detailed information about a specific server.

```typescript theme={null}
const server = await sdk.getServer('server-uuid');
// Returns: ServerDetail
```

#### `initiateConnection(serverId, returnUrl?)`

Initiate OAuth connection flow for a server.

```typescript theme={null}
const connection = await sdk.initiateConnection('server-uuid');
// Returns: { connection_id, auth_url, state }
```

#### `getConnectionStatus(serverId)`

Get connection status for a server.

```typescript theme={null}
const status = await sdk.getConnectionStatus('server-uuid');
// Returns: 'available' | 'pending' | 'connected'
```

### Quick-start Helpers

#### `loginInteractive(options?)`

Perform interactive OAuth login and return initialized SDK.

```typescript theme={null}
const sdk = await loginInteractive({
  authDomain: 'auth.barndoor.ai',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  port: 52765
});
```

#### `ensureServerConnected(sdk, serverSlug, options?)`

Ensure a server is connected, launching OAuth if needed.

```typescript theme={null}
await ensureServerConnected(sdk, 'notion', { timeout: 90 });
```

#### `makeMcpConnectionParams(sdk, serverSlug, options?)`

Generate MCP connection parameters for AI frameworks.

```typescript theme={null}
const [params, publicUrl] = await makeMcpConnectionParams(sdk, 'notion');
// params: { url, transport, headers }
```

## Error Handling

The SDK provides a comprehensive error hierarchy:

```typescript theme={null}
import {
  BarndoorError,
  HTTPError,
  ConnectionError,
  TokenError,
  ConfigurationError
} from '@barndoor-ai/sdk';

try {
  await sdk.listServers();
} catch (error) {
  if (error instanceof HTTPError) {
    console.error('HTTP Error:', error.statusCode, error.message);
  } else if (error instanceof TokenError) {
    console.error('Token Error:', error.message);
    // Re-authenticate
  } else if (error instanceof ConnectionError) {
    console.error('Connection Error:', error.message);
    // Check network
  }
}
```

## Browser Support

The SDK works in both Node.js and browser environments:

```typescript theme={null}
// Browser usage
import { BarndoorSDK } from '@barndoor-ai/sdk';

// Token storage uses localStorage in browsers
const sdk = new BarndoorSDK('https://api.barndoor.ai', {
  token: 'your-token'
});
```

When running in the browser you can also create the SDK first and later call `await sdk.authenticate(token)` once your SPA receives a JWT.

**Note:** Interactive login (`loginInteractive`) requires Node.js for the local callback server.

## Examples

See the `examples/` directory for complete working examples:

* `openai-integration.js` - OpenAI + MCP function calling integration
* `basic-mcp-client.js` - Direct MCP client without AI framework

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

```typescript theme={null}
import { BarndoorSDK, ServerSummary } from '@barndoor-ai/sdk';

const sdk = new BarndoorSDK('https://api.barndoor.ai', {
  token: 'your-token'
});

const servers: ServerSummary[] = await sdk.listServers();
```

## Contributing

1. Clone the repository
2. Install dependencies: `npm install`
3. Build the project: `npm run build`
4. Run tests: `npm test`
5. Run type checking: `npm run type-check`
6. Run safety checks: `npm run safety-check`