@barndoor-ai/sdk 0.2.0

package/RELEASE.md

@@ -0,0 +1,203 @@
+# Release Process
+
+This document is for maintainers and describes the process for releasing a new version of the Barndoor TypeScript SDK.
+
+## Overview
+
+The SDK uses automated publishing via GitHub Actions. When you create a GitHub release, the CI/CD pipeline automatically:
+1. Runs the full test suite
+2. Builds the package
+3. Publishes to npm
+
+## Prerequisites
+
+Before creating a release, ensure you have:
+
+- [ ] Write access to the GitHub repository
+- [ ] Permissions to create GitHub releases and merge pull requests
+- [ ] All changes merged to the `main` branch
+- [ ] All tests passing on `main`
+
+## Release Steps
+
+### 1. Prepare the Release Branch
+
+Create a release branch from `main`:
+
+```bash
+# Ensure you're on main and up to date
+git checkout main
+git pull origin main
+
+# Create a release branch
+git checkout -b release/v0.1.1
+```
+
+#### Update Version Number
+
+Update the version in `package.json`:
+
+```bash
+# For patch releases (0.1.0 -> 0.1.1)
+npm version patch --no-git-tag-version
+
+# For minor releases (0.1.0 -> 0.2.0)
+npm version minor --no-git-tag-version
+
+# For major releases (0.1.0 -> 1.0.0)
+npm version major --no-git-tag-version
+```
+
+**Note:** We use `--no-git-tag-version` to prevent automatic tagging. The tag will be created after the PR is merged.
+
+#### Verify the Build
+
+Run the full build and test suite locally:
+
+```bash
+# Clean build
+npm run clean
+npm install
+
+# Build
+npm run build
+
+# Run all checks
+npm test
+npm run lint
+npm run type-check
+```
+
+All checks should pass before proceeding.
+
+#### Update Documentation (if needed)
+
+- Update `README.md` if there are API changes
+- Update examples if API usage has changed
+
+#### Commit Version Changes
+
+Commit the version bump and any documentation updates:
+
+```bash
+git add package.json package-lock.json README.md
+git commit -m "chore: bump version to v0.1.1"
+```
+
+### 2. Create and Merge Pull Request
+
+#### Push Release Branch
+
+Push the release branch to GitHub:
+
+```bash
+git push origin release/v0.1.1
+```
+
+#### Open Pull Request
+
+1. Go to: https://github.com/barndoor-ai/barndoor-ts-sdk/pulls
+2. Click "New pull request"
+3. Set base to `main` and compare to `release/v0.1.1`
+4. Title: "Release v0.1.1"
+5. Description should include:
+   - Summary of changes
+   - Release notes
+   - Link to any relevant issues
+6. Request reviews from team members if required
+7. Wait for CI checks to pass
+8. Get approval and merge the PR
+
+### 3. Create and Push Release Tag
+
+After the PR is merged, create the release tag:
+
+```bash
+# Switch to main and pull the merged changes
+git checkout main
+git pull origin main
+
+# Create the version tag
+git tag v0.1.1
+
+# Push the tag
+git push origin v0.1.1
+```
+
+### 4. Create GitHub Release
+
+#### Via GitHub Web UI
+
+1. Go to: https://github.com/barndoor-ai/barndoor-ts-sdk/releases/new
+2. Click "Choose a tag" and select the version tag you just pushed (e.g., `v0.1.1`)
+3. Set the release title to the version number (e.g., `v0.1.1`)
+4. Add release notes describing:
+   - **New Features**: What's new in this release
+   - **Bug Fixes**: What issues were resolved
+   - **Breaking Changes**: Any backwards-incompatible changes
+   - **Deprecations**: Features being deprecated
+   - **Internal Changes**: Refactoring, dependency updates, etc.
+5. Check "Set as the latest release"
+6. Click "Publish release"
+
+### 5. Monitor the Release
+
+Once you publish the GitHub release:
+
+1. **Check GitHub Actions**: Go to https://github.com/barndoor-ai/barndoor-ts-sdk/actions
+   - The CI workflow should trigger automatically
+   - Verify the `build` job passes
+   - Verify the `publish` job completes successfully
+
+2. **Verify npm Publication**: Check https://www.npmjs.com/package/@barndoor-ai/sdk
+   - The new version should appear within a few minutes
+   - Verify the package contents look correct
+
+3. **Test Installation**: Install the published package:
+   ```bash
+   # In a test directory
+   npm install @barndoor-ai/sdk@latest
+   ```
+
+### 6. Post-Release
+
+#### Clean Up Release Branch
+
+Once the release is successfully published, clean up the release branch:
+
+```bash
+# Delete local branch
+git branch -d release/v0.1.1
+
+# Delete remote branch (if it wasn't auto-deleted by GitHub)
+git push origin --delete release/v0.1.1
+```
+
+## Release Checklist
+
+Use this checklist for each release:
+
+- [ ] All changes merged to `main` branch
+- [ ] Release branch created from latest `main`
+- [ ] Version bumped in `package.json` (using `--no-git-tag-version`)
+- [ ] Documentation updated for API changes
+- [ ] Local build and tests pass
+- [ ] Release PR opened and approved
+- [ ] Release PR merged to `main`
+- [ ] Release tag created and pushed
+- [ ] GitHub release created with release notes
+- [ ] CI/CD pipeline completed successfully
+- [ ] Package verified on npm
+- [ ] Test installation from npm works
+
+## Emergency Rollback
+
+If a critical issue is discovered after release:
+
+1. Publish a new patch version with the fix immediately
+2. Deprecate the broken version:
+   ```bash
+   npm deprecate @barndoor-ai/sdk@0.1.1 "Critical bug - use 0.1.2+"
+   ```
+3. Notify all users through appropriate channels
+4. Consider creating a security advisory if it's a security issue

package/examples/README.md

@@ -0,0 +1,92 @@
+# Barndoor SDK Examples
+
+This directory contains working examples that demonstrate how to use the Barndoor TypeScript SDK with MCP servers.
+
+## Working Examples
+
+### 1. `openai-integration.js` - OpenAI + MCP Integration
+Complete example showing how to integrate OpenAI's function calling with MCP tools.
+
+**What it does:**
+- Authenticates with Barndoor
+- Connects to an MCP server (Salesforce by default)
+- Lets OpenAI decide which MCP tools to call
+- Executes the tools and feeds results back to OpenAI
+
+**Requirements:**
+```bash
+npm install openai dotenv
+```
+
+**Environment:**
+```bash
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+**Run:**
+```bash
+node examples/openai-integration.js
+```
+
+### 2. `basic-mcp-client.js` - Direct MCP Client
+Basic example showing direct MCP server interaction without AI frameworks.
+
+**What it does:**
+- Authenticates with Barndoor
+- Connects to an MCP server
+- Lists available tools and resources
+- Executes basic operations
+
+**Requirements:**
+```bash
+npm install dotenv
+```
+
+**Run:**
+```bash
+node examples/basic-mcp-client.js
+```
+
+## Configuration
+
+Both examples use the same authentication pattern:
+
+1. **Environment Variables** (create a `.env` file):
+   ```
+   AUTH_DOMAIN=your-auth-domain
+   AGENT_CLIENT_ID=your-client-id
+   AGENT_CLIENT_SECRET=your-client-secret
+   MODE=development  # or production
+   ```
+
+2. **Server Configuration**: Change the `SERVER_SLUG` constant in each file to target different MCP servers:
+   - `'salesforce'` - Salesforce integration
+   - `'notion'` - Notion integration
+   - Or any other configured MCP server
+
+## Key Patterns
+
+Both examples follow the same proven pattern:
+
+```typescript
+// 1. Authenticate
+const sdk = await loginInteractive();
+
+// 2. Ensure server is connected
+await ensureServerConnected(sdk, SERVER_SLUG);
+
+// 3. Create MCP client
+const mcpClient = await makeMcpClient(sdk, SERVER_SLUG);
+
+// 4. Use MCP client
+const { tools } = await mcpClient.listTools();
+const result = await mcpClient.callTool({ name: 'tool_name', arguments: {} });
+
+// 5. Cleanup
+await mcpClient.close();
+await sdk.close();
+```
+
+This pattern uses the `@modelcontextprotocol/sdk` package internally and handles all the complex MCP protocol details for you.
+
+**Note:** While the SDK is written in TypeScript, the current examples are still in JavaScript (.js files) for broader compatibility. You can easily convert them to TypeScript by changing the file extensions to `.ts` and adding type annotations as needed.

package/examples/basic-mcp-client.js

@@ -0,0 +1,134 @@
+/**
+ * Basic MCP Client Example
+ *
+ * This script demonstrates how to use the Barndoor SDK to connect to MCP servers
+ * and perform basic operations without any AI framework dependencies.
+ */
+
+import 'dotenv/config';
+import { loginInteractive, ensureServerConnected, makeMcpClient } from '../dist/index.esm.js';
+
+const SERVER_SLUG = 'salesforce'; // or 'notion'
+
+async function main() {
+  try {
+    console.log('🚀 Starting Basic MCP Client Example...\n');
+
+    // ---------------------------------------------------------------------
+    // 1. Initialize Barndoor SDK and MCP client (with retry on 401)
+    // ---------------------------------------------------------------------
+    console.log('🔐 Authenticating with Barndoor...');
+    let sdk = await loginInteractive();
+
+    // Test authentication by trying to list servers
+    try {
+      await sdk.listServers();
+      console.log('✅ Authentication successful!');
+    } catch (error) {
+      if (error.statusCode === 401) {
+        console.log('⚠️  Cached token invalid, clearing and re-authenticating...');
+        // Clear cached token and try again
+        const { clearCachedToken } = await import('../dist/index.esm.js');
+        clearCachedToken();
+        sdk = await loginInteractive();
+        await sdk.listServers(); // Test again
+        console.log('✅ Re-authentication successful!');
+      } else {
+        throw error;
+      }
+    }
+
+    console.log(`\n🔗 Ensuring ${SERVER_SLUG} server is connected...`);
+    await ensureServerConnected(sdk, SERVER_SLUG);
+    console.log(`✅ ${SERVER_SLUG} server connected!`);
+
+    // Use the makeMcpClient helper
+    const mcpClient = await makeMcpClient(sdk, SERVER_SLUG);
+    console.log('📡 MCP client connected!');
+
+    // ---------------------------------------------------------------------
+    // 2. List available resources and tools using SDK
+    // ---------------------------------------------------------------------
+    console.log('\n📋 Listing available resources...');
+    try {
+      const { resources = [] } = await mcpClient.listResources();
+      console.log(`Found ${resources.length} resources`);
+    } catch (error) {
+      console.log('⚠️  List resources failed:', error.message);
+    }
+
+    console.log('\n🔧 Listing available tools...');
+    try {
+      const { tools = [] } = await mcpClient.listTools();
+      console.log(`Found ${tools.length} tools`);
+      tools.forEach((tool, i) => {
+        console.log(`  ${i + 1}. ${tool.name}: ${tool.description || 'No description'}`);
+      });
+    } catch (error) {
+      console.log('⚠️  List tools failed:', error.message);
+    }
+
+    // ---------------------------------------------------------------------
+    // 3. Test specific operations
+    // ---------------------------------------------------------------------
+    console.log('\n🧪 Testing specific operations...');
+
+    if (SERVER_SLUG === 'salesforce') {
+      console.log('\n📊 Testing Salesforce operations...');
+      try {
+        const queryResponse = await mcpClient.callTool({
+          name: 'query_records',
+          arguments: {
+            query: 'SELECT Id, Name, Industry FROM Account LIMIT 5',
+          },
+        });
+        const records =
+          queryResponse?.content?.[0]?.type === 'text'
+            ? JSON.parse(queryResponse.content[0].text)
+            : queryResponse.records || [];
+        console.log(`Found ${records.length} accounts`);
+        records.forEach((record, i) => {
+          console.log(`  ${i + 1}. ${record.Name} (${record.Industry || 'No industry'})`);
+        });
+      } catch (error) {
+        console.log('⚠️  Salesforce query failed:', error.message);
+      }
+    } else if (SERVER_SLUG === 'notion') {
+      console.log('\n📝 Testing Notion operations...');
+      try {
+        const pagesResponse = await mcpClient.callTool({
+          name: 'list_pages',
+          arguments: {},
+        });
+        const pages = pagesResponse?.pages || [];
+        console.log(`Found ${pages.length} pages`);
+        pages.slice(0, 5).forEach((page, i) => {
+          console.log(`  ${i + 1}. ${page.title || 'Untitled'}`);
+        });
+      } catch (error) {
+        console.log('⚠️  Notion operation failed:', error.message);
+      }
+    }
+
+    await mcpClient.close();
+    await sdk.close();
+    console.log('\n✅ Basic MCP client example completed successfully!');
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error('Stack trace:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  process.exit(1);
+});
+
+// Run the main function
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/examples/openai-integration.js

@@ -0,0 +1,137 @@
+/**
+ * OpenAI Function-Calling + MCP Integration
+ *
+ * Shows how to let an LLM decide which MCP tool to invoke, run it, and feed the
+ * result back to the model – all in ~60 lines.
+ *
+ * Requirements:
+ *   npm install openai dotenv
+ *
+ * Make sure OPENAI_API_KEY is set in .env.
+ */
+
+import 'dotenv/config';
+import { OpenAI } from 'openai';
+import { loginInteractive, ensureServerConnected, makeMcpClient } from '../dist/index.esm.js';
+
+const SERVER_SLUG = 'salesforce';
+
+// --- Step 0: Prepare OpenAI client -------------------------------------------------
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// --- Main --------------------------------------------------------------------------
+(async () => {
+  let sdk;
+  let mcpClient;
+
+  try {
+    // 1. Authenticate and get MCP params (with retry on 401)
+    console.log('🔐 Authenticating with Barndoor...');
+    sdk = await loginInteractive();
+
+    // Test authentication by trying to list servers
+    try {
+      await sdk.listServers();
+      console.log('✅ Authentication successful!');
+    } catch (error) {
+      if (error.statusCode === 401) {
+        console.log('⚠️  Cached token invalid, clearing and re-authenticating...');
+        // Clear cached token and try again
+        const { clearCachedToken } = await import('../src/index.js');
+        clearCachedToken();
+        sdk = await loginInteractive();
+        await sdk.listServers(); // Test again
+        console.log('✅ Re-authentication successful!');
+      } else {
+        throw error;
+      }
+    }
+
+    await ensureServerConnected(sdk, SERVER_SLUG);
+    mcpClient = await makeMcpClient(sdk, SERVER_SLUG);
+
+    // ---------------------------------------------------------------------
+    // List available servers
+    // ---------------------------------------------------------------------
+    const servers = await sdk.listServers();
+    console.log('\nAvailable MCP servers:');
+    servers.forEach(s => console.log(`  • ${s.slug.padEnd(12)} status=${s.connection_status}`));
+
+    // Fetch public URL as well for display
+    const [params, publicUrl] = (await sdk.makeMcpConnectionParams)
+      ? await sdk.makeMcpConnectionParams(sdk, SERVER_SLUG)
+      : [null, null];
+    if (publicUrl) {
+      console.log(`\n✓ Ready – MCP URL: ${params.url}  (public: ${publicUrl})`);
+    }
+
+    // 2. Fetch available MCP tools and convert to OpenAI function schemas
+    const { tools = [] } = await mcpClient.listTools();
+
+    const functions = tools.map(t => ({
+      type: 'function',
+      function: {
+        name: t.name.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 64), // ensure valid & short
+        description: t.description || 'MCP tool',
+        parameters: t.parameters ?? {
+          type: 'object',
+          properties: {},
+          additionalProperties: true,
+        },
+      },
+    }));
+
+    // 3. Conversation loop – ask the model, detect a function_call, run it, respond
+    // Example prompt (renamed to avoid semgrep false-positive on "user*")
+    const prompt = 'What are the first 5 Account names in Salesforce?';
+    const msgs = [{ role: 'user', content: prompt }];
+
+    // First round: model decides if it wants the function
+    let chat = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: msgs,
+      tools: functions,
+      tool_choice: 'auto',
+    });
+
+    let msg = chat.choices[0].message;
+    let toolCall = msg.tool_calls?.[0];
+
+    // Handle a single tool call for demo purposes
+    if (toolCall) {
+      const { name: toolName, arguments: raw } = toolCall.function;
+      const args = JSON.parse(raw || '{}');
+
+      const mcpResult = await mcpClient.callTool({
+        name: toolName,
+        arguments: args,
+      });
+
+      msgs.push(msg); // add function_call msg
+      msgs.push({
+        role: 'tool',
+        tool_call_id: toolCall.id,
+        name: toolName,
+        content: JSON.stringify(mcpResult),
+      });
+
+      // Second round: give result back to model for final answer
+      chat = await openai.chat.completions.create({
+        model: 'gpt-4o-mini',
+        messages: msgs,
+      });
+    }
+
+    console.log('\n💬 Final answer:\n', chat.choices[0].message.content);
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error('Stack trace:', error.stack);
+    }
+    process.exit(1);
+  } finally {
+    // Always cleanup
+    if (sdk) await sdk.close();
+    if (mcpClient) await mcpClient.close();
+  }
+})();

package/jest.config.js

@@ -0,0 +1,16 @@
+export default {
+  testEnvironment: 'node',
+  transform: {},
+  collectCoverageFrom: [
+    'src/**/*.{ts,js}',
+    '!src/**/*.test.{ts,js}'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70
+    }
+  }
+};