@barndoor-ai/sdk 1.2.0 → 2.0.0-dev.g37b8897

package/README.md

@@ -1,315 +1,159 @@
-# Barndoor TypeScript SDK
+# @barndoor-ai/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
+TypeScript client for the [Barndoor AI](https://barndoor.ai) platform API.
 
 ```bash
 npm install @barndoor-ai/sdk
 ```
 
-## Quick Start
-
-### Basic Usage
-
-```typescript
-import { BarndoorSDK } from '@barndoor-ai/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
+Node 22 or later. Ships ESM and CommonJS builds with type declarations.
 
-For development and prototyping, use the interactive login helper:
+## Quick start
 
-`loginInteractive()` builds an SDK *without* requiring `token` in the ctor—it internally calls `sdk.authenticate()` for you.
+```ts
+import { createClient } from '@barndoor-ai/sdk';
 
-```typescript
-import { loginInteractive } from '@barndoor-ai/sdk';
+const client = createClient({ auth: process.env.BARNDOOR_API_KEY! });
 
-// 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-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);
-
-  // 5. Disconnect when done (optional)
-  await sdk.disconnectServer('notion');
-
-  await sdk.close();
+const { data } = await client.registry.listMcpServers({});
+for (const server of data) {
+  console.log(server.name, server.slug);
 }
 ```
 
-### Disconnecting from Servers
-
-To disconnect from a server and clean up OAuth credentials:
+`createClient` is synchronous — nothing it does touches the network, so building
+a client cannot fail because an identity provider is briefly unreachable. The
+first request performs discovery and obtains a token.
 
-```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
-```
+## Authentication
 
-## Environment Configuration
+`auth` takes one of three things.
 
-The SDK automatically configures endpoints. Just set your credentials:
+**An API key**, or any token you already hold:
 
-```bash
-export AGENT_CLIENT_ID=your_client_id
-export AGENT_CLIENT_SECRET=your_client_secret
+```ts
+createClient({ auth: 'bdai_…' });
 ```
 
-**OAuth Redirect Host:** The SDK defaults to `127.0.0.1` for OAuth callbacks. If you need to use a different host (e.g., `localhost`), set:
+**Machine-to-machine credentials**, exchanged and refreshed for you:
 
-```bash
-export BARNDOOR_REDIRECT_HOST=localhost
-```
-
-## 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>
+```ts
+createClient({
+  auth: {
+    clientId: process.env.BARNDOOR_CLIENT_ID!,
+    clientSecret: process.env.BARNDOOR_CLIENT_SECRET!,
+  },
+});
 ```
 
-#### `ensureServerConnected(serverSlug, options?)`
-Ensure a server is connected, launching OAuth if needed – same behaviour as quick-start helper.
+**Your own token provider**, called on every request — for a token you source
+from somewhere else, such as a secrets manager or an inbound request:
 
-```typescript
-await sdk.ensureServerConnected('notion', { pollSeconds: 2 });
-// Returns: Promise<void>
+```ts
+createClient({ auth: async () => fetchTokenFromVault() });
 ```
 
-#### `listServers()`
-List all MCP servers available to your organization. Automatically fetches all pages if results are paginated.
+For a user-facing login there is also an authorization-code flow:
+`startAuthorizationCode` and `completeAuthorizationCode`.
 
-```typescript
-const servers = await sdk.listServers();
-// Returns: ServerSummary[]
-```
+## API surface
 
-#### `getServer(serverId)`
-Get detailed information about a specific server.
+The client exposes one namespace per service:
 
-```typescript
-const server = await sdk.getServer('server-uuid');
-// Returns: ServerDetail
-```
+| Namespace | Covers |
+|---|---|
+| `client.registry` | MCP servers, agents, connections, the directory |
+| `client.policy` | Policies, rules, impact analysis |
+| `client.identity` | Organizations, users, groups, identity providers |
+| `client.notification` | Channels, alerts, subscriptions |
+| `client.dlp` | Detection rules, findings, redaction |
+| `client.llmGateway` | Models, budgets, API keys, usage |
+| `client.systemManagement` | Operational endpoints |
 
-#### `initiateConnection(serverId, returnUrl?)`
-Initiate OAuth connection flow for a server.
+The full surface — every operation, parameter and model — is the OpenAPI
+specification the client is generated from, published in this repository as
+[openapi.yaml](./openapi.yaml). Types for all of it ship with the package, so
+your editor is usually the fastest reference.
 
-```typescript
-const connection = await sdk.initiateConnection('server-uuid');
-// Returns: { connection_id, auth_url, state }
-```
+## Connecting to MCP
 
-#### `getConnectionStatus(serverId)`
-Get connection status for a server.
+The platform serves MCP as well as REST. `createMcpClient` returns a connected
+[Model Context Protocol](https://modelcontextprotocol.io) client, authenticated
+with the same credentials:
 
-```typescript
-const status = await sdk.getConnectionStatus('server-uuid');
-// Returns: 'available' | 'pending' | 'connected'
-```
+```ts
+import { createClient, createMcpClient } from '@barndoor-ai/sdk';
 
-#### `disconnectServer(serverId)`
-Disconnect from a specific MCP server.
+const client = createClient({ auth: process.env.BARNDOOR_API_KEY! });
+const mcp = await createMcpClient(client, 'acme');
 
-```typescript
-await sdk.disconnectServer('server-uuid');
-// Returns: Promise<void>
+const { tools } = await mcp.listTools();
 ```
 
-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
+If you would rather pass connection details to another framework than use the
+client directly, `mcpConnectionParams` returns the `url` and `headers` without
+opening a connection.
 
-#### `loginInteractive(options?)`
-Perform interactive OAuth login and return initialized SDK.
+## Reliability
 
-```typescript
-// Uses env vars by default (AGENT_CLIENT_ID, AGENT_CLIENT_SECRET)
-const sdk = await loginInteractive();
+Requests are retried by default, with backoff. Pass `retry` to tune it, or
+`retry: false` to turn it off:
 
-// Or pass credentials explicitly
-const sdk = await loginInteractive({
-  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 });
+```ts
+createClient({ auth, retry: { retries: 5, timeoutMs: 30_000 } });
 ```
 
-#### `makeMcpConnectionParams(sdk, serverSlugOrId, options?)`
-Generate MCP connection parameters for AI frameworks. Accepts server slug or UUID.
+The SDK logs nothing. To see requests, add middleware — this is the extension
+point for logging, tracing and metrics:
 
-```typescript
-// Using slug
-const [params, publicUrl] = await makeMcpConnectionParams(sdk, 'notion');
-
-// Using UUID
-const [params, publicUrl] = await makeMcpConnectionParams(sdk, '123e4567-...');
-
-// Or via options
-const [params, publicUrl] = await makeMcpConnectionParams(sdk, 'notion', {
-  serverId: '123e4567-...',  // alternative: pass UUID in options
-  serverSlug: 'notion'        // alternative: pass slug in options
+```ts
+createClient({
+  auth,
+  middleware: [{ pre: async (ctx) => { console.log(ctx.init.method, ctx.url); } }],
 });
-
-// params: { url, transport, headers }
 ```
 
-## Error Handling
-
-The SDK provides a comprehensive error hierarchy:
-
-```typescript
-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
-  }
-}
-```
+## Non-production environments
 
-## Browser Support
+Production is the default and needs no configuration. For other environments:
 
-The SDK works in both Node.js and browser environments:
+```ts
+import { createClient, DEV } from '@barndoor-ai/sdk';
 
-```typescript
-// 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'
-});
+const client = createClient({ auth, env: DEV });
 ```
 
-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.
+`environmentFromEnv()` reads the same from `BARNDOOR_ENV`. Credentials inherit
+the environment's issuer, so pointing at dev cannot leave you calling dev with a
+production token.
 
 ## Examples
 
-See the `examples/` directory for complete working examples:
+Runnable examples are in [examples/](./examples).
 
-- `openai-integration.js` - OpenAI + MCP function calling integration
-- `basic-mcp-client.js` - Direct MCP client without AI framework
+## Versioning
 
-## TypeScript Support
+The version is the version of the **API contract**, so which SDK speaks to which
+API needs no lookup table. It is independent of the Barndoor platform's own
+release version.
 
-The SDK is written in TypeScript and includes full type definitions:
+| Part | Changes when |
+|---|---|
+| MAJOR | the API breaks — an operation removed, a field made required |
+| MINOR | the API gains something — a new operation or optional field |
+| PATCH | the SDK changes on its own — a fix, a dependency bump |
 
-```typescript
-import { BarndoorSDK, ServerSummary } from '@barndoor-ai/sdk';
+Versions on the `dev` dist-tag are prereleases built from unreleased platform
+work and carry a `-dev.<commit>` suffix. `npm install @barndoor-ai/sdk` gives
+you the latest formal release.
 
-const sdk = new BarndoorSDK('https://api.barndoor.ai', {
-  token: 'your-token'
-});
+## This repository is generated
 
-const servers: ServerSummary[] = await sdk.listServers();
-```
+The client, this README and the examples are generated or maintained in
+Barndoor's platform monorepo and pushed here, which is where the package is
+published from. **Pull requests against generated files here will be
+overwritten.** Open an issue instead, or contact your Barndoor representative.
 
-## Contributing
+## License
 
-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`
+MIT — see [LICENSE](./LICENSE).