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 and our NPM package

Installation

npm install @barndoor-ai/sdk

Quick Start

Basic Usage

import { BarndoorSDK } from '@barndoor-ai/sdk';

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

// ② 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();

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.

import { loginInteractive } from '@barndoor-ai/sdk';

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

Complete Workflow

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:

# 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.

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.

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.

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

`listServers()`

List all MCP servers available to your organization.

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

`getServer(serverId)`

Get detailed information about a specific server.

const server = await sdk.getServer('server-uuid');
// Returns: ServerDetail

`initiateConnection(serverId, returnUrl?)`

Initiate OAuth connection flow for a server.

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

`getConnectionStatus(serverId)`

Get connection status for a server.

const status = await sdk.getConnectionStatus('server-uuid');
// Returns: 'available' | 'pending' | 'connected'

Quick-start Helpers

`loginInteractive(options?)`

Perform interactive OAuth login and return initialized SDK.

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.

await ensureServerConnected(sdk, 'notion', { timeout: 90 });

`makeMcpConnectionParams(sdk, serverSlug, options?)`

Generate MCP connection parameters for AI frameworks.

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

Error Handling

The SDK provides a comprehensive error hierarchy:

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:

// 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:

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

Clone the repository
Install dependencies: npm install
Build the project: npm run build
Run tests: npm test
Run type checking: npm run type-check
Run safety checks: npm run safety-check

SDK Documentation

SDK Examples

Typescript

Barndoor TypeScript SDK

Be sure to checkout our examples and our NPM package

Installation

Quick Start

Basic Usage

Complete Workflow

Environment Configuration

API Reference

BarndoorSDK

`authenticate(jwtToken)`

`ensureServerConnected(serverSlug, options?)`

`listServers()`

`getServer(serverId)`

`initiateConnection(serverId, returnUrl?)`

`getConnectionStatus(serverId)`

Quick-start Helpers

`loginInteractive(options?)`

`ensureServerConnected(sdk, serverSlug, options?)`

`makeMcpConnectionParams(sdk, serverSlug, options?)`

Error Handling

Browser Support

Examples

TypeScript Support

Contributing

​Barndoor TypeScript SDK

​Be sure to checkout our examples and our NPM package

​Installation

​Quick Start

​Basic Usage

​Interactive Login

​Complete Workflow

​Environment Configuration

​API Reference

​BarndoorSDK

​authenticate(jwtToken)

​ensureServerConnected(serverSlug, options?)

​listServers()

​getServer(serverId)

​initiateConnection(serverId, returnUrl?)

​getConnectionStatus(serverId)

​Quick-start Helpers

​loginInteractive(options?)

​ensureServerConnected(sdk, serverSlug, options?)

​makeMcpConnectionParams(sdk, serverSlug, options?)

​Error Handling

​Browser Support

​Examples

​TypeScript Support

​Contributing

Barndoor TypeScript SDK

Be sure to checkout our examples and our NPM package

Installation

Quick Start

Basic Usage

Interactive Login

Complete Workflow

Environment Configuration

API Reference

BarndoorSDK

`authenticate(jwtToken)`

`ensureServerConnected(serverSlug, options?)`

`listServers()`

`getServer(serverId)`

`initiateConnection(serverId, returnUrl?)`

`getConnectionStatus(serverId)`

Quick-start Helpers

`loginInteractive(options?)`

`ensureServerConnected(sdk, serverSlug, options?)`

`makeMcpConnectionParams(sdk, serverSlug, options?)`

Error Handling

Browser Support

Examples

TypeScript Support

Contributing