@datagrout/conduit 0.1.0

package/README.md

@@ -0,0 +1,213 @@
+# DataGrout Conduit — TypeScript SDK
+
+Production-ready MCP client with mTLS identity, OAuth 2.1, semantic discovery, and cost tracking.
+
+## Installation
+
+```bash
+npm install @datagrout/conduit
+```
+
+## Quick Start
+
+```typescript
+import { Client } from '@datagrout/conduit';
+
+const client = new Client('https://gateway.datagrout.ai/servers/{uuid}/mcp');
+await client.connect();
+
+const tools = await client.listTools();
+const result = await client.callTool('salesforce@1/get_lead@1', { id: '123' });
+
+await client.disconnect();
+```
+
+## Authentication
+
+### Bearer Token
+
+```typescript
+const client = new Client({
+  url: 'https://gateway.datagrout.ai/servers/{uuid}/mcp',
+  auth: { bearer: 'your-access-token' },
+});
+```
+
+### OAuth 2.1 (client_credentials)
+
+```typescript
+const client = new Client({
+  url: 'https://gateway.datagrout.ai/servers/{uuid}/mcp',
+  auth: {
+    clientCredentials: {
+      clientId: 'your-client-id',
+      clientSecret: 'your-client-secret',
+    },
+  },
+});
+```
+
+The SDK automatically fetches, caches, and refreshes JWTs before they expire.
+
+### mTLS (Mutual TLS)
+
+After bootstrapping, the client certificate handles authentication at the TLS layer — no tokens needed.
+
+```typescript
+import { Client, ConduitIdentity } from '@datagrout/conduit';
+
+// Auto-discover from env vars, CONDUIT_IDENTITY_DIR, or ~/.conduit/
+const client = new Client({
+  url: 'https://gateway.datagrout.ai/servers/{uuid}/mcp',
+  identityAuto: true,
+});
+
+// Explicit identity from files
+const identity = ConduitIdentity.fromPaths('certs/client.pem', 'certs/client_key.pem');
+const client = new Client({ url: '...', identity });
+
+// Multiple agents on one machine
+const client = new Client({
+  url: '...',
+  identityDir: '/opt/agents/agent-a/.conduit',
+  identityAuto: true,
+});
+```
+
+#### Identity Auto-Discovery Order
+
+1. `identityDir` option (if provided)
+2. `CONDUIT_MTLS_CERT` + `CONDUIT_MTLS_KEY` environment variables (inline PEM)
+3. `CONDUIT_IDENTITY_DIR` environment variable (directory path)
+4. `~/.conduit/identity.pem` + `~/.conduit/identity_key.pem`
+5. `.conduit/` relative to the current working directory
+
+For DataGrout URLs (`*.datagrout.ai`), auto-discovery runs silently even without `identityAuto: true`.
+
+#### Bootstrapping an mTLS Identity
+
+One-call provisioning — generates a keypair, registers with the DataGrout CA, saves certs locally, and returns a connected client. After this, the token is never needed again.
+
+```typescript
+import { Client } from '@datagrout/conduit';
+
+// One-call bootstrap with a one-time access token
+const client = await Client.bootstrapIdentity({
+  url: 'https://gateway.datagrout.ai/servers/{uuid}/mcp',
+  authToken: 'your-one-time-token',
+  name: 'my-agent',
+});
+
+// All subsequent runs: mTLS auto-discovered from ~/.conduit/
+const client = new Client('https://gateway.datagrout.ai/servers/{uuid}/mcp');
+await client.connect();
+```
+
+You can also use the registration functions directly:
+
+```typescript
+import { generateKeypair, registerIdentity, saveIdentityToDir } from '@datagrout/conduit';
+
+const { publicKeyPem, privateKeyPem } = generateKeypair();
+const reg = await registerIdentity(publicKeyPem, {
+  authToken: 'your-access-token',
+  name: 'my-agent',
+});
+await saveIdentityToDir(reg.certPem, privateKeyPem, '~/.conduit', reg.caCertPem);
+```
+
+## Semantic Discovery & Intelligent Interface
+
+For DataGrout URLs, the Intelligent Interface is enabled by default — `listTools()` returns only `data-grout@1/discovery.discover@1` and `data-grout@1/discovery.perform@1`. Agents use semantic search instead of enumerating raw integrations:
+
+```typescript
+// Intelligent Interface auto-enabled for DG URLs
+const client = new Client('https://gateway.datagrout.ai/servers/{uuid}/mcp');
+await client.connect();
+
+// Semantic search across all connected integrations
+const results = await client.discover({ query: 'find unpaid invoices', limit: 5 });
+
+// Direct execution with cost tracking
+const result = await client.perform('salesforce@1/get_lead@1', { id: '123' });
+```
+
+Pass `useIntelligentInterface: false` to opt out and see all raw tools.
+
+## Cost Tracking
+
+Every tool call returns a receipt with credit usage:
+
+```typescript
+import { extractMeta } from '@datagrout/conduit';
+
+const result = await client.callTool('salesforce@1/get_lead@1', { id: '123' });
+const meta = extractMeta(result);
+
+if (meta) {
+  console.log(`Credits: ${meta.receipt.netCredits}`);
+  console.log(`Savings: ${meta.receipt.savings}`);
+}
+```
+
+## Transports
+
+```typescript
+// MCP (default) — full MCP protocol over Streamable HTTP
+const client = new Client({ url });
+
+// JSONRPC — lightweight, stateless, same tools and auth
+const client = new Client({ url, transport: 'jsonrpc' });
+```
+
+## API Reference
+
+### Client Options
+
+```typescript
+new Client(options: {
+  url: string;
+  auth?: { bearer?: string; apiKey?: string; clientCredentials?: {...} };
+  transport?: 'mcp' | 'jsonrpc';
+  useIntelligentInterface?: boolean;
+  identity?: ConduitIdentity;
+  identityAuto?: boolean;
+  identityDir?: string;
+  disableMtls?: boolean;
+  timeout?: number;
+});
+```
+
+### Standard MCP Methods
+
+| Method | Description |
+|---|---|
+| `connect()` | Initialize connection |
+| `disconnect()` | Close connection |
+| `listTools()` | List available tools |
+| `callTool(name, args)` | Execute a tool |
+| `listResources()` | List resources |
+| `readResource(uri)` | Read a resource |
+| `listPrompts()` | List prompts |
+| `getPrompt(name, args)` | Get a prompt |
+
+### DataGrout Extensions
+
+| Method | Description |
+|---|---|
+| `discover(options)` | Semantic tool search |
+| `perform(options)` | Direct tool execution with tracking |
+| `performBatch(calls)` | Parallel tool execution |
+| `guide(options)` | Guided multi-step workflow |
+| `flowInto(options)` | Workflow orchestration |
+| `prismFocus(options)` | Type transformation |
+| `estimateCost(tool, args)` | Pre-execution credit estimate |
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+ (for TypeScript users)
+
+## License
+
+MIT

package/dist/chunk-RED5DKGI.mjs

@@ -0,0 +1,122 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/oauth.ts
+var oauth_exports = {};
+__export(oauth_exports, {
+  OAuthTokenProvider: () => OAuthTokenProvider,
+  deriveTokenEndpoint: () => deriveTokenEndpoint
+});
+function deriveTokenEndpoint(mcpUrl) {
+  const mcpIdx = mcpUrl.indexOf("/mcp");
+  const base = mcpIdx !== -1 ? mcpUrl.slice(0, mcpIdx) : mcpUrl.replace(/\/$/, "");
+  return `${base}/oauth/token`;
+}
+var OAuthTokenProvider;
+var init_oauth = __esm({
+  "src/oauth.ts"() {
+    OAuthTokenProvider = class {
+      clientId;
+      clientSecret;
+      tokenEndpoint;
+      scope;
+      cached = null;
+      fetchPromise = null;
+      constructor(opts) {
+        this.clientId = opts.clientId;
+        this.clientSecret = opts.clientSecret;
+        this.tokenEndpoint = opts.tokenEndpoint;
+        this.scope = opts.scope;
+      }
+      /**
+       * Return the current bearer token, fetching a fresh one if necessary.
+       * Concurrent callers share a single in-flight fetch.
+       */
+      async getToken() {
+        const now = Date.now();
+        if (this.cached && this.cached.expiresAt - now > 6e4) {
+          return this.cached.accessToken;
+        }
+        if (!this.fetchPromise) {
+          this.fetchPromise = this.fetchToken().finally(() => {
+            this.fetchPromise = null;
+          });
+        }
+        const cached = await this.fetchPromise;
+        return cached.accessToken;
+      }
+      /** Invalidate the cached token (e.g. after receiving a 401). */
+      invalidate() {
+        this.cached = null;
+      }
+      // ─── Private ───────────────────────────────────────────────────────────────
+      async fetchToken() {
+        const body = new URLSearchParams({
+          grant_type: "client_credentials",
+          client_id: this.clientId,
+          client_secret: this.clientSecret
+        });
+        if (this.scope) {
+          body.set("scope", this.scope);
+        }
+        let response;
+        try {
+          response = await fetch(this.tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString()
+          });
+        } catch (err) {
+          throw new Error(`OAuth token request failed: ${err}`);
+        }
+        if (!response.ok) {
+          const text = await response.text().catch(() => "");
+          throw new Error(`OAuth token endpoint returned ${response.status}: ${text}`);
+        }
+        const data = await response.json();
+        const expiresIn = data.expires_in ?? 3600;
+        const cached = {
+          accessToken: data.access_token,
+          expiresAt: Date.now() + expiresIn * 1e3
+        };
+        this.cached = cached;
+        return cached;
+      }
+    };
+  }
+});
+
+export {
+  __require,
+  __esm,
+  __export,
+  __toCommonJS,
+  deriveTokenEndpoint,
+  OAuthTokenProvider,
+  oauth_exports,
+  init_oauth
+};