@datagrout/conduit 0.3.0 → 0.5.0

package/dist/index.js

@@ -343,6 +343,81 @@ var init_identity = __esm({
   }
 });
 
+// src/onramp.ts
+var onramp_exports = {};
+__export(onramp_exports, {
+  _doRegister: () => _doRegister,
+  _exchangeToken: () => _exchangeToken,
+  registerAndExchange: () => registerAndExchange,
+  registerOnly: () => registerOnly
+});
+async function _doRegister(opts) {
+  const base = opts.gateway.replace(/\/$/, "");
+  const body = { agent_name: opts.agentName };
+  if (opts.agentType) body["agent_type"] = opts.agentType;
+  if (opts.intendedUse) body["intended_use"] = opts.intendedUse;
+  if (opts.accessCode) body["access_code"] = opts.accessCode;
+  const initResp = await fetch(`${base}/onramp`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!initResp.ok) {
+    const text = await initResp.text();
+    throw new Error(`onramp init rejected (HTTP ${initResp.status}): ${text}`);
+  }
+  const initData = await initResp.json();
+  const sessionToken = initData.session_token;
+  const completeResp = await fetch(`${base}/onramp/complete`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${sessionToken}` }
+  });
+  if (!completeResp.ok) {
+    const text = await completeResp.text();
+    throw new Error(`onramp complete rejected (HTTP ${completeResp.status}): ${text}`);
+  }
+  const data = await completeResp.json();
+  return {
+    clientId: data["client_id"],
+    clientSecret: data["client_secret"],
+    tokenUrl: data["token_url"],
+    scopes: data["scopes"] ?? [],
+    expiresIn: data["expires_in"] ?? 0,
+    rpcUrl: data["rpc_url"],
+    mcpUrl: data["mcp_url"]
+  };
+}
+async function _exchangeToken(creds) {
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: creds.clientId,
+    client_secret: creds.clientSecret
+  });
+  const resp = await fetch(creds.tokenUrl, {
+    method: "POST",
+    body
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`token exchange failed (HTTP ${resp.status}): ${text}`);
+  }
+  const data = await resp.json();
+  return data.access_token;
+}
+async function registerOnly(opts) {
+  return _doRegister(opts);
+}
+async function registerAndExchange(opts) {
+  const creds = await _doRegister(opts);
+  const token = await _exchangeToken(creds);
+  return [creds, token];
+}
+var init_onramp = __esm({
+  "src/onramp.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -360,6 +435,8 @@ __export(index_exports, {
   OAuthTokenProvider: () => OAuthTokenProvider,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
+  WS_SUBPROTOCOL: () => SUBPROTOCOL,
+  WsTransport: () => WsTransport,
   deriveTokenEndpoint: () => deriveTokenEndpoint,
   extractMeta: () => extractMeta,
   fetchDgCaCert: () => fetchDgCaCert,
@@ -367,7 +444,9 @@ __export(index_exports, {
   generateKeypair: () => generateKeypair,
   isDgUrl: () => isDgUrl,
   refreshCaCert: () => refreshCaCert,
+  registerAndExchange: () => registerAndExchange,
   registerIdentity: () => registerIdentity,
+  registerOnly: () => registerOnly,
   rotateIdentity: () => rotateIdentity,
   saveIdentity: () => saveIdentity,
   version: () => version
@@ -727,6 +806,295 @@ var JSONRPCTransport = class extends Transport {
   }
 };
 
+// src/transports/ws.ts
+var SUBPROTOCOL = "datagrout-jsonrpc.v1";
+var SUBSCRIPTION_BUFFER = 256;
+var Subscription = class {
+  id;
+  topic;
+  _queue = [];
+  _waiters = [];
+  _rejecters = [];
+  _closed = false;
+  constructor(id, topic) {
+    this.id = id;
+    this.topic = topic;
+  }
+  /**
+   * Wait for the next event from this subscription.
+   *
+   * @throws When the subscription has been closed.
+   */
+  recv() {
+    if (this._queue.length > 0) {
+      return Promise.resolve(this._queue.shift());
+    }
+    if (this._closed) {
+      return Promise.reject(new Error("Subscription closed"));
+    }
+    return new Promise((resolve, reject) => {
+      this._waiters.push(resolve);
+      this._rejecters.push(reject);
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    while (this._queue.length > 0 || !this._closed) {
+      try {
+        yield await this.recv();
+      } catch {
+        return;
+      }
+    }
+  }
+  // ── Internal ───────────────────────────────────────────────────────────────
+  _enqueue(event) {
+    if (this._waiters.length > 0) {
+      const resolve = this._waiters.shift();
+      this._rejecters.shift();
+      resolve(event);
+    } else if (this._queue.length < SUBSCRIPTION_BUFFER) {
+      this._queue.push(event);
+    }
+  }
+  _close() {
+    this._closed = true;
+    const err = new Error("Subscription closed");
+    for (const reject of this._rejecters) {
+      reject(err);
+    }
+    this._waiters.length = 0;
+    this._rejecters.length = 0;
+  }
+};
+var WsTransport = class extends Transport {
+  _url;
+  _auth;
+  _ws = null;
+  _nextId = 0;
+  _pending = /* @__PURE__ */ new Map();
+  _pendingSubscribe = /* @__PURE__ */ new Map();
+  _subscriptions = /* @__PURE__ */ new Map();
+  constructor(url, auth, _timeout, _identity) {
+    super();
+    const scheme = new URL(url).protocol.replace(":", "");
+    if (scheme !== "ws" && scheme !== "wss") {
+      throw new Error(`WS transport requires a ws:// or wss:// URL, got ${scheme}://`);
+    }
+    this._url = url;
+    this._auth = auth;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+  async connect() {
+    if (this._ws !== null) return;
+    const WsImpl = await resolveWebSocketImpl();
+    const headers = buildUpgradeHeaders(this._auth);
+    const ws = new WsImpl(this._url, [SUBPROTOCOL], {
+      headers
+    });
+    await new Promise((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (ev) => reject(new Error(`WS connect failed: ${ev.message ?? "unknown"}`));
+    });
+    ws.onmessage = (ev) => this._handleMessage(ev.data);
+    ws.onerror = (_ev) => this._failAll("WS connection error");
+    ws.onclose = () => {
+      this._failAll("WS connection closed");
+      this._ws = null;
+    };
+    this._ws = ws;
+  }
+  async disconnect() {
+    const ws = this._ws;
+    this._ws = null;
+    this._failAll("WS connection closed");
+    if (ws !== null) {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  }
+  // ── Subscriptions ─────────────────────────────────────────────────────────
+  /**
+   * Open a server-side push subscription for `topic`.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle whose async-for loop delivers events.
+   */
+  async subscribe(topic) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pendingSubscribe.set(id, { topic, resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method: "subscribe", params: { topic } });
+    });
+  }
+  /**
+   * Cancel a server-side subscription.
+   *
+   * The local {@link Subscription} queue is closed immediately.
+   *
+   * @param subscriptionId - The `id` field from the {@link Subscription}
+   *   returned by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this._requireConnected();
+    const sub = this._subscriptions.get(subscriptionId);
+    if (sub !== void 0) {
+      this._subscriptions.delete(subscriptionId);
+      sub._close();
+    }
+    const id = this._mintId();
+    const ackPromise = new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+    });
+    this._send({
+      jsonrpc: "2.0",
+      id,
+      method: "unsubscribe",
+      params: { subscription: subscriptionId }
+    });
+    await Promise.race([
+      ackPromise,
+      new Promise((resolve) => setTimeout(resolve, 5e3))
+    ]);
+    this._pending.delete(id);
+  }
+  // ── Transport base implementation ─────────────────────────────────────────
+  async listTools(options) {
+    return await this._request("tools/list", options);
+  }
+  async callTool(name, args, _options) {
+    return this._request("tools/call", { name, arguments: args });
+  }
+  async listResources(_options) {
+    return await this._request("resources/list");
+  }
+  async readResource(uri, _options) {
+    return this._request("resources/read", { uri });
+  }
+  async listPrompts(_options) {
+    return await this._request("prompts/list");
+  }
+  async getPrompt(name, args, _options) {
+    return this._request("prompts/get", { name, arguments: args });
+  }
+  // ── Internal ──────────────────────────────────────────────────────────────
+  _mintId() {
+    return `ws-${++this._nextId}`;
+  }
+  _requireConnected() {
+    if (this._ws === null) {
+      throw new Error("WS transport not connected. Call connect() first.");
+    }
+  }
+  _send(payload) {
+    this._ws.send(JSON.stringify(payload));
+  }
+  async _request(method, params) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method, ...params !== void 0 ? { params } : {} });
+    });
+  }
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (!("id" in msg)) {
+      if (msg["method"] === "notification") {
+        this._routeNotification(msg["params"]);
+      }
+      return;
+    }
+    const msgId = String(msg["id"]);
+    const pendingSub = this._pendingSubscribe.get(msgId);
+    if (pendingSub !== void 0) {
+      this._pendingSubscribe.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pendingSub.reject(new Error(String(err["message"] ?? "Subscribe failed")));
+        return;
+      }
+      const result = msg["result"] ?? {};
+      const subId = String(result["subscription"] ?? msgId);
+      const sub = new Subscription(subId, pendingSub.topic);
+      this._subscriptions.set(subId, sub);
+      pendingSub.resolve(sub);
+      return;
+    }
+    const pending = this._pending.get(msgId);
+    if (pending !== void 0) {
+      this._pending.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pending.reject(new Error(String(err["message"] ?? "RPC error")));
+      } else {
+        pending.resolve(msg["result"]);
+      }
+    }
+  }
+  _routeNotification(params) {
+    if (params === void 0) return;
+    const subId = params["subscription"];
+    if (typeof subId !== "string") return;
+    const sub = this._subscriptions.get(subId);
+    if (sub === void 0) return;
+    sub._enqueue({
+      subscription: subId,
+      event: String(params["event"] ?? ""),
+      data: params["data"]
+    });
+  }
+  _failAll(reason) {
+    const err = new Error(reason);
+    for (const { reject } of this._pending.values()) {
+      reject(err);
+    }
+    this._pending.clear();
+    for (const { reject } of this._pendingSubscribe.values()) {
+      reject(err);
+    }
+    this._pendingSubscribe.clear();
+    for (const sub of this._subscriptions.values()) {
+      sub._close();
+    }
+    this._subscriptions.clear();
+  }
+};
+function buildUpgradeHeaders(auth) {
+  const headers = {};
+  if (auth === void 0) return headers;
+  if ("bearer" in auth && auth.bearer !== void 0) {
+    headers["Authorization"] = `Bearer ${auth.bearer}`;
+  } else if ("apiKey" in auth && auth.apiKey !== void 0) {
+    headers["X-API-Key"] = auth.apiKey;
+  } else if ("basic" in auth && auth.basic !== void 0) {
+    const encoded = Buffer.from(`${auth.basic.username}:${auth.basic.password}`).toString("base64");
+    headers["Authorization"] = `Basic ${encoded}`;
+  }
+  return headers;
+}
+async function resolveWebSocketImpl() {
+  if (typeof globalThis.WebSocket !== "undefined") {
+    return globalThis.WebSocket;
+  }
+  try {
+    const { default: WS } = await import("ws");
+    return WS;
+  } catch {
+    throw new Error(
+      "No WebSocket implementation found. Install the 'ws' package: npm install ws"
+    );
+  }
+}
+
 // src/client.ts
 init_identity();
 
@@ -1247,13 +1615,15 @@ var Client2 = class _Client {
     this.isDg = isDgUrl(this.url);
     this.useIntelligentInterface = options.useIntelligentInterface ?? this.isDg;
     this.maxRetries = options.maxRetries ?? 3;
-    let identity = options.identity ?? (options.identityAuto ? ConduitIdentity.tryDiscover(options.identityDir) ?? void 0 : void 0);
-    if (identity === void 0 && this.isDg && !options.disableMtls) {
-      identity = ConduitIdentity.tryDiscover(options.identityDir) ?? void 0;
-    }
+    const identity = options.identity ?? (options.identityAuto ? ConduitIdentity.tryDiscover(options.identityDir) ?? void 0 : void 0);
     const transportType = options.transport || "mcp";
     if (transportType === "mcp") {
       this.transport = new MCPTransport(this.url, this.auth, identity);
+    } else if (transportType === "websocket") {
+      let wsUrl = this.url;
+      if (wsUrl.startsWith("https://")) wsUrl = "wss://" + wsUrl.slice(8);
+      else if (wsUrl.startsWith("http://")) wsUrl = "ws://" + wsUrl.slice(7);
+      this.transport = new WsTransport(wsUrl, this.auth, options.timeout, identity);
     } else {
       const rpcUrl = this.url.endsWith("/mcp") ? this.url.slice(0, -4) + "/rpc" : this.url;
       this.transport = new JSONRPCTransport(rpcUrl, this.auth, options.timeout, identity);
@@ -1330,6 +1700,60 @@ var Client2 = class _Client {
       substrateEndpoint: options.substrateEndpoint
     });
   }
+  /**
+   * Register autonomously with DG and bootstrap an mTLS identity.
+   *
+   * The all-in-one flow: onramp (no prior credentials required) →
+   * OAuth token exchange → mTLS identity registration and persistence.
+   *
+   * On subsequent runs the saved mTLS identity is auto-discovered and
+   * no credentials are needed.
+   *
+   * @param options.opts         - Onramp registration options.
+   * @param options.url          - MCP server URL. Required if the onramp
+   *                               response does not include `mcpUrl`.
+   * @param options.identityDir  - Custom identity storage directory.
+   *
+   * @example
+   * ```ts
+   * import { Client } from './client';
+   * import type { OnrampOptions } from './onramp';
+   *
+   * const client = await Client.bootstrapOnramp({
+   *   opts: {
+   *     gateway: 'https://app.datagrout.ai',
+   *     agentName: 'my-research-agent',
+   *     agentType: 'claude-sonnet-4-6',
+   *   },
+   * });
+   * await client.connect();
+   * ```
+   */
+  static async bootstrapOnramp(options) {
+    const { _doRegister: _doRegister2, _exchangeToken: _exchangeToken2 } = await Promise.resolve().then(() => (init_onramp(), onramp_exports));
+    const dir = options.identityDir || DEFAULT_IDENTITY_DIR;
+    const existing = ConduitIdentity.tryDiscover(dir);
+    if (existing && !existing.needsRotation(7)) {
+      if (!options.url) {
+        throw new Error("'url' must be provided when an existing identity is reused");
+      }
+      return new _Client({ url: options.url, identity: existing, identityDir: dir });
+    }
+    const creds = await _doRegister2(options.opts);
+    const token = await _exchangeToken2(creds);
+    const url = creds.mcpUrl ?? options.url;
+    if (!url) {
+      throw new Error(
+        "'url' must be provided when mcpUrl is absent from the onramp response"
+      );
+    }
+    return _Client.bootstrapIdentity({
+      url,
+      authToken: token,
+      name: options.opts.agentName,
+      identityDir: options.identityDir
+    });
+  }
   // ===== Lifecycle =====
   /**
    * Establish the underlying transport connection.
@@ -1488,6 +1912,50 @@ var Client2 = class _Client {
     this.ensureInitialized();
     return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
   }
+  // ===== WebSocket push subscriptions =====
+  /**
+   * Subscribe to a server-push topic (WebSocket transport only).
+   *
+   * Requires `transport: 'websocket'` when constructing the client.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle. Consume events with
+   *   {@link Subscription.recv} or an `for await` loop.
+   *
+   * @example
+   * ```ts
+   * const sub = await client.subscribe('agents.my-agent-id.events');
+   * for await (const event of sub) {
+   *   console.log(event.event, event.data);
+   * }
+   * await client.unsubscribe(sub.id);
+   * ```
+   */
+  async subscribe(topic) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "subscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.subscribe(topic);
+  }
+  /**
+   * Cancel a server-side push subscription.
+   *
+   * @param subscriptionId - The `id` from the {@link Subscription} returned
+   *   by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "unsubscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.unsubscribe(subscriptionId);
+  }
   // ===== DG-awareness helpers =====
   warnIfNotDg(method) {
     if (!this.isDg && !this.dgWarned) {
@@ -1778,7 +2246,8 @@ function buildToolMeta(raw) {
 }
 
 // src/index.ts
-var version = "0.1.0";
+init_onramp();
+var version = "0.5.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
@@ -1795,6 +2264,8 @@ var version = "0.1.0";
   OAuthTokenProvider,
   RateLimitError,
   ServerError,
+  WS_SUBPROTOCOL,
+  WsTransport,
   deriveTokenEndpoint,
   extractMeta,
   fetchDgCaCert,
@@ -1802,7 +2273,9 @@ var version = "0.1.0";
   generateKeypair,
   isDgUrl,
   refreshCaCert,
+  registerAndExchange,
   registerIdentity,
+  registerOnly,
   rotateIdentity,
   saveIdentity,
   version