@ralioco/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,635 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  RalioAPIError: () => RalioAPIError,
+  RalioAuthError: () => RalioAuthError,
+  RalioClient: () => RalioClient,
+  RalioConfigError: () => RalioConfigError,
+  RalioError: () => RalioError,
+  RalioNotFoundError: () => RalioNotFoundError,
+  RalioPermissionError: () => RalioPermissionError,
+  RalioRateLimitError: () => RalioRateLimitError,
+  RalioRegistrationError: () => RalioRegistrationError,
+  RalioValidationError: () => RalioValidationError,
+  register: () => register
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_promises2 = require("fs/promises");
+
+// src/crypto.ts
+var import_node_crypto = require("crypto");
+var import_jose = require("jose");
+var CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+var CLIENT_ASSERTION_TTL_SECONDS = 60;
+function b64url(raw) {
+  return Buffer.from(raw).toString("base64url");
+}
+function canonicalize(jwk) {
+  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.x || !jwk.y) {
+    throw new Error("Ralio credentials require a P-256 (EC) key");
+  }
+  return { crv: "P-256", kty: "EC", x: jwk.x, y: jwk.y };
+}
+async function jwkThumbprint(jwk) {
+  return (0, import_jose.calculateJwkThumbprint)(jwk, "sha256");
+}
+async function generateKeypair() {
+  const { privateKey } = await (0, import_jose.generateKeyPair)("ES256", { extractable: true });
+  return fromPrivateKey(privateKey);
+}
+async function fromPrivateKey(privateKey) {
+  const publicJwk = canonicalize(await (0, import_jose.exportJWK)(privateKey));
+  const kid = await jwkThumbprint(publicJwk);
+  return { privateKey, publicJwk, kid };
+}
+async function privateKeyToPem(privateKey) {
+  return (0, import_jose.exportPKCS8)(privateKey);
+}
+async function loadPrivateKey(pem) {
+  let key;
+  try {
+    key = await (0, import_jose.importPKCS8)(pem, "ES256", { extractable: true });
+  } catch (err) {
+    throw new Error(
+      `Ralio credentials require a P-256 (EC) private key: ${err.message}`,
+      { cause: err }
+    );
+  }
+  return fromPrivateKey(key);
+}
+async function signClientAssertion(privateKey, opts) {
+  const ttl = opts.ttlSeconds ?? CLIENT_ASSERTION_TTL_SECONDS;
+  const iat = Math.floor(Date.now() / 1e3);
+  return new import_jose.SignJWT({}).setProtectedHeader({ alg: "ES256", kid: opts.kid }).setIssuer(opts.clientId).setSubject(opts.clientId).setAudience(opts.audience).setIssuedAt(iat).setExpirationTime(iat + ttl).setJti(b64url((0, import_node_crypto.randomBytes)(16))).sign(privateKey);
+}
+async function signDpopProof(privateKey, opts) {
+  const iat = Math.floor(Date.now() / 1e3);
+  const ath = (0, import_node_crypto.createHash)("sha256").update(opts.accessToken, "ascii").digest("base64url");
+  return new import_jose.SignJWT({
+    htm: opts.method.toUpperCase(),
+    htu: opts.url,
+    ath
+  }).setProtectedHeader({ typ: "dpop+jwt", alg: "ES256", jwk: { ...opts.jwk } }).setIssuedAt(iat).setJti(b64url((0, import_node_crypto.randomBytes)(16))).sign(privateKey);
+}
+
+// src/errors.ts
+var RalioError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RalioConfigError = class extends RalioError {
+};
+var RalioRegistrationError = class extends RalioError {
+};
+var RalioAPIError = class extends RalioError {
+  statusCode;
+  detail;
+  wwwAuthenticate;
+  constructor(message, opts) {
+    super(message);
+    this.statusCode = opts.statusCode;
+    this.detail = opts.detail ?? null;
+    this.wwwAuthenticate = opts.wwwAuthenticate ?? null;
+  }
+};
+var RalioAuthError = class extends RalioAPIError {
+};
+var RalioPermissionError = class extends RalioAPIError {
+};
+var RalioNotFoundError = class extends RalioAPIError {
+};
+var RalioValidationError = class extends RalioAPIError {
+};
+var RalioRateLimitError = class extends RalioAPIError {
+};
+var STATUS_MAP = {
+  401: RalioAuthError,
+  403: RalioPermissionError,
+  404: RalioNotFoundError,
+  422: RalioValidationError,
+  429: RalioRateLimitError
+};
+async function raiseForResponse(response) {
+  if (response.ok) return;
+  const detail = await extractDetail(response);
+  const Cls = STATUS_MAP[response.status] ?? RalioAPIError;
+  const message = detail ?? `HTTP ${response.status}`;
+  throw new Cls(message, {
+    statusCode: response.status,
+    detail,
+    wwwAuthenticate: response.headers.get("www-authenticate")
+  });
+}
+async function extractDetail(response) {
+  const text = await response.text().catch(() => "");
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text || null;
+  }
+  if (payload && typeof payload === "object") {
+    const obj = payload;
+    if (typeof obj.detail === "string") return obj.detail;
+    if (obj.detail != null) return JSON.stringify(obj.detail);
+    const oauth = obj.error_description ?? obj.error;
+    if (typeof oauth === "string") return oauth;
+  }
+  return text || null;
+}
+
+// src/auth.ts
+var TokenManager = class {
+  clientId;
+  privateKey;
+  kid;
+  tokenUrl;
+  scopes;
+  leewayMs;
+  accessTokenValue = null;
+  refreshTokenValue = null;
+  expiresAtMs = 0;
+  // Serialises all token mutations: each exclusive section runs after the
+  // previous one settles, so two callers never mint/refresh concurrently.
+  chain = Promise.resolve();
+  constructor(opts) {
+    this.clientId = opts.clientId;
+    this.privateKey = opts.privateKey;
+    this.kid = opts.kid;
+    this.tokenUrl = opts.tokenUrl;
+    this.scopes = opts.scopes;
+    this.leewayMs = (opts.refreshLeewaySeconds ?? 300) * 1e3;
+  }
+  /** Return a valid access token, minting or refreshing as needed. */
+  async accessToken() {
+    if (this.accessTokenValue && Date.now() < this.expiresAtMs - this.leewayMs) {
+      return this.accessTokenValue;
+    }
+    return this.withLock(async () => {
+      if (this.accessTokenValue && Date.now() < this.expiresAtMs - this.leewayMs) {
+        return this.accessTokenValue;
+      }
+      return this.obtain();
+    });
+  }
+  /** Discard the cached token and obtain a fresh one. Used after a 401. */
+  async forceRefresh() {
+    return this.withLock(async () => {
+      this.accessTokenValue = null;
+      return this.obtain();
+    });
+  }
+  withLock(fn) {
+    const run = this.chain.then(fn, fn);
+    this.chain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  async obtain() {
+    if (this.refreshTokenValue) {
+      try {
+        return await this.refresh();
+      } catch {
+        this.refreshTokenValue = null;
+      }
+    }
+    return this.mint();
+  }
+  async mint() {
+    const assertion = await signClientAssertion(this.privateKey, {
+      clientId: this.clientId,
+      audience: this.tokenUrl,
+      kid: this.kid
+    });
+    const data = {
+      grant_type: "client_credentials",
+      client_assertion_type: CLIENT_ASSERTION_TYPE,
+      client_assertion: assertion
+    };
+    if (this.scopes && this.scopes.length > 0) {
+      data.scope = this.scopes.join(" ");
+    }
+    return this.exchange(data);
+  }
+  async refresh() {
+    if (!this.refreshTokenValue) throw new Error("no refresh token");
+    return this.exchange({
+      grant_type: "refresh_token",
+      refresh_token: this.refreshTokenValue,
+      client_id: this.clientId
+    });
+  }
+  async exchange(data) {
+    const response = await fetch(this.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(data).toString()
+    });
+    await raiseForResponse(response);
+    const body2 = await response.json();
+    this.accessTokenValue = body2.access_token;
+    this.refreshTokenValue = body2.refresh_token ?? this.refreshTokenValue;
+    this.expiresAtMs = Date.now() + (body2.expires_in ?? 1800) * 1e3;
+    return this.accessTokenValue;
+  }
+};
+
+// src/registration.ts
+var import_node_crypto2 = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var DEFAULT_BASE_URL = "https://api.ralio.co";
+var TERMINAL = /* @__PURE__ */ new Set(["active", "rejected", "expired"]);
+async function register(opts) {
+  const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const pollIntervalMs = opts.pollIntervalMs ?? 3e3;
+  const timeoutMs = opts.timeoutMs ?? 9e5;
+  if (!opts.overwrite && await exists(opts.privateKeyPath)) {
+    throw new RalioRegistrationError(
+      `${opts.privateKeyPath} already exists; pass overwrite: true to replace it`
+    );
+  }
+  const { privateKey, publicJwk, kid } = await generateKeypair();
+  await savePrivateKey(opts.privateKeyPath, await privateKeyToPem(privateKey));
+  const pollToken = await submit(base, opts, publicJwk, kid);
+  const clientId = await poll(base, pollToken, pollIntervalMs, timeoutMs);
+  return { clientId, scopes: opts.requestedScopes ?? [] };
+}
+async function submit(base, opts, publicJwk, fingerprint) {
+  const body2 = { ticket: opts.ticket, public_key_jwk: publicJwk };
+  if (opts.requestedScopes) body2.requested_scopes = opts.requestedScopes;
+  if (opts.clientMetadata) body2.client_metadata = opts.clientMetadata;
+  const response = await fetch(`${base}/api/credential-bindings/registrations`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body2)
+  });
+  await raiseForResponse(response);
+  const payload = await response.json();
+  if (payload.fingerprint && payload.fingerprint !== fingerprint) {
+    throw new RalioRegistrationError(
+      "fingerprint mismatch between local key and server response; aborting"
+    );
+  }
+  if (typeof payload.poll_token !== "string" || !payload.poll_token) {
+    throw new RalioRegistrationError("registration response did not include a poll_token");
+  }
+  return payload.poll_token;
+}
+async function poll(base, pollToken, intervalMs, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const url = `${base}/api/credential-bindings/registrations/${pollToken}`;
+  for (; ; ) {
+    const response = await fetch(url);
+    if (response.status === 404) {
+      throw new RalioRegistrationError("registration expired before approval");
+    }
+    await raiseForResponse(response);
+    const body2 = await response.json();
+    const status = body2.status ?? "";
+    if (status === "active") {
+      if (typeof body2.client_id !== "string" || !body2.client_id) {
+        throw new RalioRegistrationError("binding active but no client_id returned");
+      }
+      return body2.client_id;
+    }
+    if (TERMINAL.has(status)) {
+      throw new RalioRegistrationError(`registration ${status}`);
+    }
+    if (Date.now() >= deadline) {
+      throw new RalioRegistrationError("timed out waiting for owner approval");
+    }
+    await sleep(intervalMs);
+  }
+}
+async function exists(path) {
+  try {
+    await (0, import_promises.access)(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function savePrivateKey(path, pem) {
+  const dir = (0, import_node_path.dirname)(path);
+  const tmp = (0, import_node_path.join)(dir, `.tmp-${(0, import_node_crypto2.randomBytes)(8).toString("hex")}`);
+  const handle = await (0, import_promises.open)(tmp, "wx", 384);
+  try {
+    await handle.writeFile(pem);
+    await handle.close();
+    await (0, import_promises.rename)(tmp, path);
+  } catch (err) {
+    await handle.close().catch(() => void 0);
+    await (0, import_promises.rm)(tmp, { force: true });
+    throw err;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/types.ts
+function str(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+function optStr(value) {
+  return typeof value === "string" ? value : null;
+}
+function parseMessage(data) {
+  return {
+    id: str(data.id),
+    role: str(data.role),
+    content: str(data.content),
+    createdAt: optStr(data.created_at)
+  };
+}
+function parseChatReply(data) {
+  const raw = Array.isArray(data.new_messages) ? data.new_messages : [];
+  return {
+    reply: str(data.reply),
+    conversationId: str(data.conversation_id),
+    newMessages: raw.map((m) => parseMessage(m ?? {}))
+  };
+}
+function buildStreamEvent(event, data) {
+  return { event, data, text: typeof data.text === "string" ? data.text : "" };
+}
+function parseTransaction(data) {
+  return {
+    id: str(data.id),
+    amount: str(data.amount),
+    currency: str(data.currency),
+    status: str(data.status),
+    date: optStr(data.date),
+    creditor: optStr(data.creditor),
+    debtor: optStr(data.debtor),
+    reference: optStr(data.reference),
+    paymentIntentId: optStr(data.payment_intent_id)
+  };
+}
+
+// src/resources/chat.ts
+var ChatResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Send a message and wait for the agent's complete reply.
+   *
+   * Times out server-side after 120s. For interactive approval flows where a
+   * human may take longer, use {@link stream} instead.
+   */
+  async send(params) {
+    const response = await this.transport.request("POST", "/api/chat", {
+      jsonBody: body(params)
+    });
+    return parseChatReply(await response.json());
+  }
+  /**
+   * Stream the agent's reply as server-sent events.
+   *
+   * Yields `conversation`, `tool_started`/`tool_completed`/`tool_failed`,
+   * `text_delta`, and a final `reply` event.
+   */
+  stream(params) {
+    return this.transport.streamSse("POST", "/api/chat/stream", {
+      jsonBody: body(params)
+    });
+  }
+};
+function body(params) {
+  const out = {
+    agent_id: params.agentId,
+    message: params.message
+  };
+  if (params.conversationId !== void 0) out.conversation_id = params.conversationId;
+  return out;
+}
+
+// src/resources/transactions.ts
+var TransactionsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** List transactions across the caller's agents, newest first. */
+  async list(params = {}) {
+    const response = await this.transport.request("GET", "/api/transactions", {
+      params: { limit: params.limit ?? 50, agent_id: params.agentId }
+    });
+    const items = await response.json();
+    return items.map(parseTransaction);
+  }
+};
+
+// src/transport.ts
+var Transport = class {
+  baseUrl;
+  tokens;
+  privateKey;
+  publicJwk;
+  requestTimeoutMs;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.tokens = opts.tokens;
+    this.privateKey = opts.privateKey;
+    this.publicJwk = opts.publicJwk;
+    this.requestTimeoutMs = opts.requestTimeoutMs;
+  }
+  async request(method, path, opts = {}) {
+    const url = this.buildUrl(path, opts.params);
+    const init = (headers) => ({
+      method,
+      headers: opts.jsonBody ? { ...headers, "Content-Type": "application/json" } : headers,
+      body: opts.jsonBody ? JSON.stringify(opts.jsonBody) : void 0,
+      signal: this.requestTimeoutMs ? AbortSignal.timeout(this.requestTimeoutMs) : void 0
+    });
+    let response = await fetch(url, init(await this.authHeaders(method, url)));
+    if (response.status === 401) {
+      await this.tokens.forceRefresh();
+      response = await fetch(url, init(await this.authHeaders(method, url)));
+    }
+    await raiseForResponse(response);
+    return response;
+  }
+  async *streamSse(method, path, opts = {}) {
+    const url = this.buildUrl(path);
+    const init = async () => ({
+      method,
+      headers: {
+        ...await this.authHeaders(method, url),
+        Accept: "text/event-stream",
+        ...opts.jsonBody ? { "Content-Type": "application/json" } : {}
+      },
+      body: opts.jsonBody ? JSON.stringify(opts.jsonBody) : void 0
+    });
+    let response = await fetch(url, await init());
+    if (response.status === 401) {
+      await response.body?.cancel();
+      await this.tokens.forceRefresh();
+      response = await fetch(url, await init());
+    }
+    await raiseForResponse(response);
+    yield* parseSse(response);
+  }
+  buildUrl(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+  async authHeaders(method, url) {
+    const token = await this.tokens.accessToken();
+    const proof = await signDpopProof(this.privateKey, {
+      method,
+      url: htu(url),
+      accessToken: token,
+      jwk: this.publicJwk
+    });
+    return { Authorization: `DPoP ${token}`, DPoP: proof };
+  }
+};
+function htu(url) {
+  const parsed = new URL(url);
+  return `${parsed.origin}${parsed.pathname}`;
+}
+async function* parseSse(response) {
+  if (!response.body) return;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventName = "message";
+  let dataLines = [];
+  const flush = () => {
+    if (dataLines.length === 0) return null;
+    const event = buildEvent(eventName, dataLines);
+    eventName = "message";
+    dataLines = [];
+    return event;
+  };
+  const handleLine = (line) => {
+    if (line === "") return flush();
+    if (line.startsWith(":")) return null;
+    const idx = line.indexOf(":");
+    const field = idx === -1 ? line : line.slice(0, idx);
+    let value = idx === -1 ? "" : line.slice(idx + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") eventName = value;
+    else if (field === "data") dataLines.push(value);
+    return null;
+  };
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const raw = buffer.slice(0, newlineIdx);
+      buffer = buffer.slice(newlineIdx + 1);
+      const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+      const event = handleLine(line);
+      if (event) yield event;
+    }
+  }
+  const tail = flush();
+  if (tail) yield tail;
+}
+function buildEvent(eventName, dataLines) {
+  const raw = dataLines.join("\n");
+  let payload;
+  try {
+    const parsed = JSON.parse(raw);
+    payload = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { value: parsed };
+  } catch {
+    payload = { raw };
+  }
+  if (eventName === "error") {
+    const message = typeof payload.message === "string" ? payload.message : "stream error";
+    throw new RalioAPIError(message, { statusCode: 200, detail: message });
+  }
+  return buildStreamEvent(eventName, payload);
+}
+
+// src/client.ts
+var RalioClient = class _RalioClient {
+  chat;
+  transactions;
+  constructor(transport) {
+    this.chat = new ChatResource(transport);
+    this.transactions = new TransactionsResource(transport);
+  }
+  /** Load the private key and build a ready-to-use client. */
+  static async create(opts) {
+    const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const pem = await (0, import_promises2.readFile)(opts.privateKeyPath, "utf8");
+    const { privateKey, publicJwk, kid } = await loadPrivateKey(pem);
+    const tokens = new TokenManager({
+      clientId: opts.clientId,
+      privateKey,
+      kid,
+      tokenUrl: `${baseUrl}/oauth/token`,
+      scopes: opts.scopes
+    });
+    const transport = new Transport({
+      baseUrl,
+      tokens,
+      privateKey,
+      publicJwk,
+      requestTimeoutMs: opts.timeoutMs ?? 3e4
+    });
+    return new _RalioClient(transport);
+  }
+  /**
+   * Release resources. Present for API symmetry and forward compatibility;
+   * the native `fetch` transport holds no long-lived connections of its own.
+   */
+  close() {
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_URL,
+  RalioAPIError,
+  RalioAuthError,
+  RalioClient,
+  RalioConfigError,
+  RalioError,
+  RalioNotFoundError,
+  RalioPermissionError,
+  RalioRateLimitError,
+  RalioRegistrationError,
+  RalioValidationError,
+  register
+});
+//# sourceMappingURL=index.cjs.map