Typescript - Barndoor Documentation

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:

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

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.

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:

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:

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

  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