@ralioco/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import { webcrypto } from 'node:crypto';
+
+/**
+ * ES256 / DPoP crypto primitives for the Ralio machine-auth path.
+ *
+ * Everything here mirrors what the Ralio API expects byte-for-byte:
+ *
+ * - P-256 (ES256) is the only curve the token endpoint accepts.
+ * - The public JWK is the canonical RFC 7638 form (`crv`/`kty`/`x`/`y` only),
+ *   so the thumbprint computed here matches the `cnf.jkt` the server stamps on
+ *   the access token and the fingerprint the owner confirms.
+ * - Client assertions follow RFC 7521/7523; DPoP proofs follow RFC 9449.
+ */
+
+/**
+ * Web-Crypto `CryptoKey`, re-exported from `node:crypto` so consumers don't
+ * need DOM lib types. This is what `jose` v6 returns from `importPKCS8` and
+ * `generateKeyPair` and what we accept everywhere a private key is needed.
+ */
+type CryptoKey = webcrypto.CryptoKey;
+/** Canonical RFC 7638 public JWK — exactly these members, in this order. */
+interface PublicJwk {
+    crv: "P-256";
+    kty: "EC";
+    x: string;
+    y: string;
+}
+
+/**
+ * Access-token lifecycle for the machine path.
+ *
+ * A {@link TokenManager} mints tokens via the `private_key_jwt` client
+ * assertion, caches the access token until shortly before expiry, and rotates
+ * the refresh token. All token mutations are serialised behind a lock:
+ *
+ * > Presenting a previously-rotated refresh token is treated as a replay
+ * > attack and revokes the whole chain.
+ *
+ * so two concurrent callers must never race a refresh.
+ */
+
+interface TokenManagerOptions {
+    clientId: string;
+    privateKey: CryptoKey;
+    kid: string;
+    tokenUrl: string;
+    scopes?: string[];
+    /** Refresh this many seconds before the token actually expires. */
+    refreshLeewaySeconds?: number;
+}
+declare class TokenManager {
+    private readonly clientId;
+    private readonly privateKey;
+    private readonly kid;
+    private readonly tokenUrl;
+    private readonly scopes?;
+    private readonly leewayMs;
+    private accessTokenValue;
+    private refreshTokenValue;
+    private expiresAtMs;
+    private chain;
+    constructor(opts: TokenManagerOptions);
+    /** Return a valid access token, minting or refreshing as needed. */
+    accessToken(): Promise<string>;
+    /** Discard the cached token and obtain a fresh one. Used after a 401. */
+    forceRefresh(): Promise<string>;
+    private withLock;
+    private obtain;
+    private mint;
+    private refresh;
+    private exchange;
+}
+
+/**
+ * Response types returned by the SDK.
+ *
+ * Parsing is forgiving: unknown fields the API may add later are ignored, so a
+ * server-side addition never breaks a pinned client.
+ */
+type Json = Record<string, unknown>;
+/**
+ * The result of a completed registration. `clientId` is the `cb_…` handle used
+ * to mint tokens; the private key lives on disk.
+ */
+interface CredentialBinding {
+    clientId: string;
+    scopes: string[];
+}
+interface Message {
+    id: string;
+    role: string;
+    content: string;
+    createdAt: string | null;
+}
+/** A synchronous `chat.send` response. */
+interface ChatReply {
+    reply: string;
+    conversationId: string;
+    newMessages: Message[];
+}
+/**
+ * One server-sent event from `chat.stream`.
+ *
+ * `event` is the SSE event name (`conversation`, `tool_started`,
+ * `tool_completed`, `tool_failed`, `text_delta`, `reply`, `error`); `data` is
+ * the decoded JSON payload. `text` is a convenience for the common
+ * `text_delta` / `reply` case (empty string when absent).
+ */
+interface ChatStreamEvent {
+    event: string;
+    data: Json;
+    text: string;
+}
+interface Transaction {
+    id: string;
+    amount: string;
+    currency: string;
+    status: string;
+    date: string | null;
+    creditor: string | null;
+    debtor: string | null;
+    reference: string | null;
+    paymentIntentId: string | null;
+}
+
+/**
+ * DPoP-bound HTTP transport.
+ *
+ * Every request carries `Authorization: DPoP <token>` plus a freshly-signed
+ * `DPoP` proof for that exact method + URL + token. On a 401 the transport
+ * refreshes the token once and retries with a brand-new proof (the proof `jti`
+ * is single-use server-side, so the retry must re-sign).
+ */
+
+interface TransportOptions {
+    baseUrl: string;
+    tokens: TokenManager;
+    privateKey: CryptoKey;
+    publicJwk: PublicJwk;
+    /** Per-request timeout in ms. Applies to `request`, not to SSE streams. */
+    requestTimeoutMs?: number;
+}
+interface RequestOptions {
+    jsonBody?: Record<string, unknown>;
+    params?: Record<string, string | number | undefined>;
+}
+declare class Transport {
+    private readonly baseUrl;
+    private readonly tokens;
+    private readonly privateKey;
+    private readonly publicJwk;
+    private readonly requestTimeoutMs?;
+    constructor(opts: TransportOptions);
+    request(method: string, path: string, opts?: RequestOptions): Promise<Response>;
+    streamSse(method: string, path: string, opts?: {
+        jsonBody?: Record<string, unknown>;
+    }): AsyncGenerator<ChatStreamEvent>;
+    private buildUrl;
+    private authHeaders;
+}
+
+/** Chat resource — drive an agent with natural language (`agents:execute`). */
+
+interface ChatParams {
+    agentId: string;
+    message: string;
+    conversationId?: string;
+}
+declare class ChatResource {
+    private readonly transport;
+    constructor(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.
+     */
+    send(params: ChatParams): Promise<ChatReply>;
+    /**
+     * 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: ChatParams): AsyncGenerator<ChatStreamEvent>;
+}
+
+/** Transactions resource — read executed payments (`transactions:read`). */
+
+interface ListTransactionsParams {
+    agentId?: string;
+    limit?: number;
+}
+declare class TransactionsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** List transactions across the caller's agents, newest first. */
+    list(params?: ListTransactionsParams): Promise<Transaction[]>;
+}
+
+/** The top-level {@link RalioClient}. */
+
+interface RalioClientOptions {
+    clientId: string;
+    /** Path to the PKCS8 PEM private key written by {@link register}. */
+    privateKeyPath: string;
+    baseUrl?: string;
+    scopes?: string[];
+    /** Per-request timeout in ms (default 30000). Streams are not bounded. */
+    timeoutMs?: number;
+}
+/**
+ * Client for the Ralio API, authenticated via a credential binding (OAuth 2.1
+ * `client_credentials` + `private_key_jwt` + DPoP).
+ *
+ * Obtain `clientId` and the private key once via {@link register}, then:
+ *
+ * ```ts
+ * const client = await RalioClient.create({
+ *   clientId: "cb_...",
+ *   privateKeyPath: "ralio-key.pem",
+ * });
+ * const reply = await client.chat.send({ agentId: "...", message: "What's my balance?" });
+ * ```
+ */
+declare class RalioClient {
+    readonly chat: ChatResource;
+    readonly transactions: TransactionsResource;
+    private constructor();
+    /** Load the private key and build a ready-to-use client. */
+    static create(opts: RalioClientOptions): Promise<RalioClient>;
+    /**
+     * Release resources. Present for API symmetry and forward compatibility;
+     * the native `fetch` transport holds no long-lived connections of its own.
+     */
+    close(): void;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * One-time credential-binding registration (the operator side).
+ *
+ * The owner mints a `ralio-reg-…` ticket in the console. The operator calls
+ * {@link register} on the agent host: it generates a P-256 keypair locally,
+ * submits the public key with the ticket, and polls until the owner approves
+ * the binding in the console. The private key never leaves the host.
+ */
+
+declare const DEFAULT_BASE_URL = "https://api.ralio.co";
+interface RegisterOptions {
+    ticket: string;
+    privateKeyPath: string;
+    baseUrl?: string;
+    requestedScopes?: string[];
+    clientMetadata?: Record<string, unknown>;
+    /** Poll interval in milliseconds (default 3000). */
+    pollIntervalMs?: number;
+    /** Overall timeout in milliseconds (default 900000 = 15 min). */
+    timeoutMs?: number;
+    /** Replace an existing key file. Off by default to avoid clobbering. */
+    overwrite?: boolean;
+}
+/**
+ * Run the registration flow and return the approved binding.
+ *
+ * Generates a keypair, writes the private key to `privateKeyPath`, and blocks
+ * until the owner approves (up to `timeoutMs`). Rejects with a
+ * {@link RalioRegistrationError} if the binding is rejected, expires, or the
+ * timeout elapses.
+ */
+declare function register(opts: RegisterOptions): Promise<CredentialBinding>;
+
+/** Exception hierarchy for the Ralio SDK. */
+/** Base class for every error raised by the SDK. */
+declare class RalioError extends Error {
+    constructor(message: string);
+}
+/** Local configuration problem — missing key, bad arguments. */
+declare class RalioConfigError extends RalioError {
+}
+/** A credential-binding registration was rejected, expired, or timed out. */
+declare class RalioRegistrationError extends RalioError {
+}
+/**
+ * An error response from the Ralio API.
+ *
+ * Carries the HTTP `statusCode`, the server-supplied `detail` string, and the
+ * `WWW-Authenticate` challenge when present (DPoP/OAuth failures put the
+ * specific reason there).
+ */
+declare class RalioAPIError extends RalioError {
+    readonly statusCode: number;
+    readonly detail: string | null;
+    readonly wwwAuthenticate: string | null;
+    constructor(message: string, opts: {
+        statusCode: number;
+        detail?: string | null;
+        wwwAuthenticate?: string | null;
+    });
+}
+/** 401 — missing/invalid token, failed client assertion, or rejected proof. */
+declare class RalioAuthError extends RalioAPIError {
+}
+/** 403 — token lacks the required scope, or the resource isn't owned. */
+declare class RalioPermissionError extends RalioAPIError {
+}
+/** 404 — resource does not exist. */
+declare class RalioNotFoundError extends RalioAPIError {
+}
+/** 422 — invalid field values or a business-rule violation. */
+declare class RalioValidationError extends RalioAPIError {
+}
+/** 429 — rate limited. Back off and retry. */
+declare class RalioRateLimitError extends RalioAPIError {
+}
+
+export { type ChatParams, type ChatReply, type ChatStreamEvent, type CredentialBinding, DEFAULT_BASE_URL, type ListTransactionsParams, type Message, RalioAPIError, RalioAuthError, RalioClient, type RalioClientOptions, RalioConfigError, RalioError, RalioNotFoundError, RalioPermissionError, RalioRateLimitError, RalioRegistrationError, RalioValidationError, type RegisterOptions, type Transaction, register };