@barndoor-ai/sdk 0.2.0

package/.eslintignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+coverage/
+
+# Skip JS test and example files from TypeScript-typed linting for now
+test/**
+examples/**
+

package/.eslintrc.cjs

@@ -0,0 +1,102 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: [
+    '@typescript-eslint',
+    'prettier'
+  ],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    'prettier'
+  ],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+  env: {
+    node: true,
+    es2020: true,
+    jest: true
+  },
+  rules: {
+    // Prettier integration
+    'prettier/prettier': 'error',
+
+    // TypeScript specific rules (relaxed to reduce CI friction)
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    '@typescript-eslint/prefer-nullish-coalescing': 'off',
+    '@typescript-eslint/prefer-optional-chain': 'off',
+    '@typescript-eslint/strict-boolean-expressions': 'off',
+    '@typescript-eslint/no-floating-promises': 'warn',
+    '@typescript-eslint/await-thenable': 'warn',
+    '@typescript-eslint/no-misused-promises': 'warn',
+    '@typescript-eslint/require-await': 'off',
+    '@typescript-eslint/no-unsafe-assignment': 'off',
+    '@typescript-eslint/no-unsafe-member-access': 'off',
+    '@typescript-eslint/no-unsafe-return': 'off',
+    '@typescript-eslint/no-unsafe-argument': 'off',
+    '@typescript-eslint/no-unsafe-call': 'off',
+    '@typescript-eslint/no-unnecessary-type-assertion': 'off',
+    '@typescript-eslint/restrict-template-expressions': 'off',
+
+    // General rules
+    'no-console': 'warn',
+    'prefer-const': 'error',
+    'no-var': 'error',
+    'object-shorthand': 'error',
+    'prefer-template': 'warn'
+  },
+  overrides: [
+    {
+      files: ['**/*.test.ts', '**/*.spec.ts'],
+      rules: {
+        '@typescript-eslint/no-explicit-any': 'off',
+        'no-console': 'off'
+      }
+    },
+    {
+      files: ['test/**/*.js', 'examples/**/*.js'],
+      parser: 'espree',
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module'
+      },
+      env: {
+        node: true,
+        jest: true,
+        es2020: true
+      },
+      rules: {
+        // JS files should not use TS type-aware rules
+        '@typescript-eslint/await-thenable': 'off',
+        '@typescript-eslint/no-floating-promises': 'off',
+        '@typescript-eslint/no-misused-promises': 'off',
+        '@typescript-eslint/require-await': 'off',
+        '@typescript-eslint/strict-boolean-expressions': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/restrict-template-expressions': 'off',
+        '@typescript-eslint/explicit-function-return-type': 'off',
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/no-explicit-any': 'off'
+      }
+    },
+    {
+      files: ['examples/**/*.ts'],
+      rules: {
+        'no-console': 'off'
+      }
+    }
+  ]
+};
+

package/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Barndoor Typescript SDK owners
+
+# Default owners
+*       @barndoor-ai/barndoor-engineering

package/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run lint
+      - run: npm run type-check
+
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: release
+    needs: build
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          

package/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+coverage
+*.md
+package-lock.json
+.eslintrc.js

package/.prettierrc

@@ -0,0 +1,13 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "avoid",
+  "endOfLine": "lf",
+  "quoteProps": "as-needed"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Barndoor AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# 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.
+
+## Installation
+
+```bash
+npm install @barndoor/sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { BarndoorSDK } from '@barndoor/sdk';
+
+// ① token known at construction time (unchanged)
+const sdk = new BarndoorSDK('https://your-org.mcp.barndoor.ai', {
+  token: 'your-jwt'
+});
+```
+
+```typescript
+// ② deferred login (new)
+const sdk = new BarndoorSDK('https://your-org.mcp.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
+import { loginInteractive } from '@barndoor/sdk';
+
+// Automatically handles OAuth flow and token caching
+const sdk = await loginInteractive();
+const servers = await sdk.listServers();
+```
+
+### Complete Workflow
+
+```typescript
+import {
+  loginInteractive,
+  ensureServerConnected,
+  makeMcpConnectionParams
+} from '@barndoor/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);
+
+  // 5. Disconnect when done (optional)
+  await sdk.disconnectServer('notion');
+
+  await sdk.close();
+}
+```
+
+### Disconnecting from Servers
+
+To disconnect from a server and clean up OAuth credentials:
+
+```typescript
+// Disconnect using server ID or slug
+await sdk.disconnectServer('notion');
+// or
+await sdk.disconnectServer('123e4567-e89b-12d3-a456-426614174000');
+
+// The server will need to be reconnected before use
+```
+
+## Environment Configuration
+
+The SDK automatically detects your environment and configures appropriate endpoints:
+
+```bash
+# 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
+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
+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
+await sdk.ensureServerConnected('notion', { pollSeconds: 2 });
+// Returns: Promise<void>
+```
+
+#### `listServers()`
+List all MCP servers available to your organization.
+
+```typescript
+const servers = await sdk.listServers();
+// Returns: ServerSummary[]
+```
+
+#### `getServer(serverId)`
+Get detailed information about a specific server.
+
+```typescript
+const server = await sdk.getServer('server-uuid');
+// Returns: ServerDetail
+```
+
+#### `initiateConnection(serverId, returnUrl?)`
+Initiate OAuth connection flow for a server.
+
+```typescript
+const connection = await sdk.initiateConnection('server-uuid');
+// Returns: { connection_id, auth_url, state }
+```
+
+#### `getConnectionStatus(serverId)`
+Get connection status for a server.
+
+```typescript
+const status = await sdk.getConnectionStatus('server-uuid');
+// Returns: 'available' | 'pending' | 'connected'
+```
+
+#### `disconnectServer(serverId)`
+Disconnect from a specific MCP server.
+
+```typescript
+await sdk.disconnectServer('server-uuid');
+// Returns: Promise<void>
+```
+
+This will remove the connection record and clean up any stored OAuth credentials. The user will need to reconnect to use this server again.
+
+### Quick-start Helpers
+
+#### `loginInteractive(options?)`
+Perform interactive OAuth login and return initialized SDK.
+
+```typescript
+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
+await ensureServerConnected(sdk, 'notion', { timeout: 90 });
+```
+
+#### `makeMcpConnectionParams(sdk, serverSlug, options?)`
+Generate MCP connection parameters for AI frameworks.
+
+```typescript
+const [params, publicUrl] = await makeMcpConnectionParams(sdk, 'notion');
+// params: { url, transport, headers }
+```
+
+## Error Handling
+
+The SDK provides a comprehensive error hierarchy:
+
+```typescript
+import {
+  BarndoorError,
+  HTTPError,
+  ConnectionError,
+  TokenError,
+  ConfigurationError
+} from '@barndoor/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
+// Browser usage
+import { BarndoorSDK } from '@barndoor/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
+import { BarndoorSDK, ServerSummary } from '@barndoor/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 node `nvm install 22 && nvm use 22`
+3. Install dependencies: `npm install`
+4. Build the project: `npm run build`
+5. Run tests: `npm test`
+6. Run linting: `npm run lint`
+7. Run type checking: `npm run type-check`