@olbrain/js-sdk 1.1.0 → 1.2.0

package/README.md

@@ -91,6 +91,22 @@ const client = new AgentClient({ agentId: '...', apiKey: '...' });
 const response: ChatResponse = await client.sendAndWait(sessionId, 'Hi!');
 ```
 
+## Workflow runs and approvals
+
+```ts
+import { Olbrain } from '@olbrain/js-sdk';
+
+const olbrain = new Olbrain({ apiKey: 'ak_…' });                       // servers and scripts
+// const olbrain = new Olbrain({ getIdToken: () => user.getIdToken() }); // a signed-in Olbrain user
+
+const { runId } = await olbrain.workflows.run(agentId, { payload: { deck: fileId } });
+const run = await olbrain.runs.get(agentId, runId);
+const pending = await olbrain.approvals.list(agentId, runId);
+await olbrain.approvals.resolve(agentId, runId, { exceptionId: pending[0].exception_id, resolution: 'approved' });
+```
+
+Errors carry the API's code: `BillingError` (the organization can't pay), `NotFoundError`, `AuthenticationError`, `RateLimitError`, and `ApiError` for everything else.
+
 ## 🎯 Core Concepts
 
 ### AgentClient

package/dist/index.d.mts

@@ -191,6 +191,87 @@ declare class AgentClient {
     private _parseSessionInfo;
 }
 
+interface OlbrainConfig {
+    /** An Olbrain access key, ak_… Give this or getIdToken. */
+    apiKey?: string;
+    /** Returns the signed-in user's Firebase ID token; called before every request. */
+    getIdToken?: () => Promise<string>;
+    /** Defaults to https://webhook.olbrain.com */
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+interface RunSummary {
+    total_processed: number;
+    successful: number;
+    failed: number;
+    exceptions: number;
+    skipped: number;
+}
+interface Run {
+    run_id: string;
+    status: string;
+    progress_percent?: number;
+    started_at?: string | null;
+    completed_at?: string | null;
+    duration_seconds?: number | null;
+    error?: string | null;
+    summary?: RunSummary | null;
+    [key: string]: unknown;
+}
+interface Approval {
+    exception_id: string;
+    step_id: string;
+    item_id?: string | null;
+    data?: Record<string, unknown> | null;
+    error: string;
+    requires_human_review: boolean;
+    blocking: boolean;
+}
+interface ResolveInput {
+    exceptionId: string;
+    resolution: 'approved' | 'rejected' | 'modified';
+    /** Only with resolution "modified". */
+    modifiedData?: Record<string, unknown>;
+}
+interface ResolveResult {
+    exception_id: string;
+    resolution: string;
+    all_resolved: boolean;
+    resumed: boolean;
+}
+declare class Olbrain {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: OlbrainConfig);
+    readonly workflows: {
+        run: (agentId: string, input?: {
+            payload?: unknown;
+            variables?: Record<string, unknown>;
+        }) => Promise<{
+            runId: string;
+            status: string;
+        }>;
+    };
+    readonly runs: {
+        list: (agentId: string, opts?: {
+            status?: string;
+            limit?: number;
+        }) => Promise<Run[]>;
+        get: (agentId: string, runId: string) => Promise<Run>;
+        cancel: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        pause: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        retry: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        resume: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+    };
+    readonly approvals: {
+        list: (agentId: string, runId: string) => Promise<Approval[]>;
+        resolve: (agentId: string, runId: string, input: ResolveInput) => Promise<ResolveResult>;
+    };
+    private control;
+    private request;
+}
+
 /**
  * Error classes for Olbrain SDK
  */
@@ -239,12 +320,25 @@ declare class ValidationError extends OlbrainError {
 declare class StreamingError extends OlbrainError {
     constructor(message?: string);
 }
+/** An error the API answered with: its HTTP status and machine-readable code. */
+declare class ApiError extends OlbrainError {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class NotFoundError extends ApiError {
+    constructor(code?: string, message?: string);
+}
+/** The organization can't pay for this run (balance, credit limit or subscription). */
+declare class BillingError extends ApiError {
+    constructor(status: number, code: string, message: string);
+}
 
 /**
  * Olbrain JavaScript SDK
  * Main entry point for core API exports
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
-export { AgentClient, type AgentConfig, AuthenticationError, type ChatResponse, type CreateSessionOptions, type ErrorCallback, type Message, type MessageCallback, NetworkError, OlbrainError, RateLimitError, type SendOptions, type SessionInfo, SessionNotFoundError, type SessionStats, type SessionUpdates, type StreamConfig, StreamingError, type TokenUsage, VERSION, ValidationError, type WidgetConfig };
+export { AgentClient, type AgentConfig, ApiError, type Approval, AuthenticationError, BillingError, type ChatResponse, type CreateSessionOptions, type ErrorCallback, type Message, type MessageCallback, NetworkError, NotFoundError, Olbrain, type OlbrainConfig, OlbrainError, RateLimitError, type ResolveInput, type ResolveResult, type Run, type RunSummary, type SendOptions, type SessionInfo, SessionNotFoundError, type SessionStats, type SessionUpdates, type StreamConfig, StreamingError, type TokenUsage, VERSION, ValidationError, type WidgetConfig };

package/dist/index.d.ts

@@ -191,6 +191,87 @@ declare class AgentClient {
     private _parseSessionInfo;
 }
 
+interface OlbrainConfig {
+    /** An Olbrain access key, ak_… Give this or getIdToken. */
+    apiKey?: string;
+    /** Returns the signed-in user's Firebase ID token; called before every request. */
+    getIdToken?: () => Promise<string>;
+    /** Defaults to https://webhook.olbrain.com */
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+interface RunSummary {
+    total_processed: number;
+    successful: number;
+    failed: number;
+    exceptions: number;
+    skipped: number;
+}
+interface Run {
+    run_id: string;
+    status: string;
+    progress_percent?: number;
+    started_at?: string | null;
+    completed_at?: string | null;
+    duration_seconds?: number | null;
+    error?: string | null;
+    summary?: RunSummary | null;
+    [key: string]: unknown;
+}
+interface Approval {
+    exception_id: string;
+    step_id: string;
+    item_id?: string | null;
+    data?: Record<string, unknown> | null;
+    error: string;
+    requires_human_review: boolean;
+    blocking: boolean;
+}
+interface ResolveInput {
+    exceptionId: string;
+    resolution: 'approved' | 'rejected' | 'modified';
+    /** Only with resolution "modified". */
+    modifiedData?: Record<string, unknown>;
+}
+interface ResolveResult {
+    exception_id: string;
+    resolution: string;
+    all_resolved: boolean;
+    resumed: boolean;
+}
+declare class Olbrain {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: OlbrainConfig);
+    readonly workflows: {
+        run: (agentId: string, input?: {
+            payload?: unknown;
+            variables?: Record<string, unknown>;
+        }) => Promise<{
+            runId: string;
+            status: string;
+        }>;
+    };
+    readonly runs: {
+        list: (agentId: string, opts?: {
+            status?: string;
+            limit?: number;
+        }) => Promise<Run[]>;
+        get: (agentId: string, runId: string) => Promise<Run>;
+        cancel: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        pause: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        retry: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+        resume: (agentId: string, runId: string) => Promise<Record<string, unknown>>;
+    };
+    readonly approvals: {
+        list: (agentId: string, runId: string) => Promise<Approval[]>;
+        resolve: (agentId: string, runId: string, input: ResolveInput) => Promise<ResolveResult>;
+    };
+    private control;
+    private request;
+}
+
 /**
  * Error classes for Olbrain SDK
  */
@@ -239,12 +320,25 @@ declare class ValidationError extends OlbrainError {
 declare class StreamingError extends OlbrainError {
     constructor(message?: string);
 }
+/** An error the API answered with: its HTTP status and machine-readable code. */
+declare class ApiError extends OlbrainError {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class NotFoundError extends ApiError {
+    constructor(code?: string, message?: string);
+}
+/** The organization can't pay for this run (balance, credit limit or subscription). */
+declare class BillingError extends ApiError {
+    constructor(status: number, code: string, message: string);
+}
 
 /**
  * Olbrain JavaScript SDK
  * Main entry point for core API exports
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
-export { AgentClient, type AgentConfig, AuthenticationError, type ChatResponse, type CreateSessionOptions, type ErrorCallback, type Message, type MessageCallback, NetworkError, OlbrainError, RateLimitError, type SendOptions, type SessionInfo, SessionNotFoundError, type SessionStats, type SessionUpdates, type StreamConfig, StreamingError, type TokenUsage, VERSION, ValidationError, type WidgetConfig };
+export { AgentClient, type AgentConfig, ApiError, type Approval, AuthenticationError, BillingError, type ChatResponse, type CreateSessionOptions, type ErrorCallback, type Message, type MessageCallback, NetworkError, NotFoundError, Olbrain, type OlbrainConfig, OlbrainError, RateLimitError, type ResolveInput, type ResolveResult, type Run, type RunSummary, type SendOptions, type SessionInfo, SessionNotFoundError, type SessionStats, type SessionUpdates, type StreamConfig, StreamingError, type TokenUsage, VERSION, ValidationError, type WidgetConfig };

package/dist/index.global.js

@@ -416,8 +416,12 @@ var Olbrain = (() => {
   var index_exports = {};
   __export(index_exports, {
     AgentClient: () => AgentClient,
+    ApiError: () => ApiError,
     AuthenticationError: () => AuthenticationError,
+    BillingError: () => BillingError,
     NetworkError: () => NetworkError,
+    NotFoundError: () => NotFoundError,
+    Olbrain: () => Olbrain,
     OlbrainError: () => OlbrainError,
     RateLimitError: () => RateLimitError,
     SessionNotFoundError: () => SessionNotFoundError,
@@ -479,16 +483,39 @@ var Olbrain = (() => {
       Object.setPrototypeOf(this, _StreamingError.prototype);
     }
   };
+  var ApiError = class _ApiError extends OlbrainError {
+    constructor(status, code, message) {
+      super(message);
+      this.name = "ApiError";
+      this.status = status;
+      this.code = code;
+      Object.setPrototypeOf(this, _ApiError.prototype);
+    }
+  };
+  var NotFoundError = class _NotFoundError extends ApiError {
+    constructor(code = "not_found", message = "Not found") {
+      super(404, code, message);
+      this.name = "NotFoundError";
+      Object.setPrototypeOf(this, _NotFoundError.prototype);
+    }
+  };
+  var BillingError = class _BillingError extends ApiError {
+    constructor(status, code, message) {
+      super(status, code, message);
+      this.name = "BillingError";
+      Object.setPrototypeOf(this, _BillingError.prototype);
+    }
+  };
 
   // src/core/utils.ts
   function validateApiKey(apiKey) {
     if (!apiKey) {
       throw new ValidationError("API key is required");
     }
-    const validPrefixes = ["sk_live_", "org_live_", "sk_", "org_"];
+    const validPrefixes = ["ak_", "sk_live_", "org_live_", "sk_", "org_"];
     if (!validPrefixes.some((prefix) => apiKey.startsWith(prefix))) {
       throw new ValidationError(
-        "Invalid API key format. Must start with sk_, org_, sk_live_, or org_live_"
+        "Invalid API key format. Must start with ak_, sk_, org_, sk_live_, or org_live_"
       );
     }
   }
@@ -508,7 +535,7 @@ var Olbrain = (() => {
     return typeof window !== "undefined" && typeof document !== "undefined";
   }
   function isNode() {
-    return typeof process !== "undefined" && process.versions && process.versions.node;
+    return typeof process !== "undefined" && !!process.versions?.node;
   }
   async function getEventSourceImpl() {
     if (isBrowser()) {
@@ -972,8 +999,98 @@ var Olbrain = (() => {
     }
   };
 
+  // src/core/olbrain.ts
+  var DEFAULT_BASE_URL2 = "https://webhook.olbrain.com";
+  var BILLING_CODES = /* @__PURE__ */ new Set([
+    "insufficient_funds",
+    "credit_limit_exceeded",
+    "subscription_suspended",
+    "subscription_inactive",
+    "billing_unavailable"
+  ]);
+  var enc = encodeURIComponent;
+  var Olbrain = class {
+    constructor(config) {
+      this.config = config;
+      this.workflows = {
+        run: async (agentId, input = {}) => {
+          const out = await this.request("POST", `/api/workflows/${enc(agentId)}/trigger`, input);
+          return { runId: out.run_id, status: out.status };
+        }
+      };
+      this.runs = {
+        list: (agentId, opts = {}) => {
+          const q = new URLSearchParams();
+          if (opts.limit !== void 0) q.set("limit", String(opts.limit));
+          if (opts.status) q.set("status", opts.status);
+          const qs = q.toString();
+          return this.request("GET", `/api/agents/${enc(agentId)}/runs${qs ? `?${qs}` : ""}`);
+        },
+        get: (agentId, runId) => this.request("GET", `/api/agents/${enc(agentId)}/runs/${enc(runId)}`),
+        cancel: (agentId, runId) => this.control(agentId, runId, "cancel"),
+        pause: (agentId, runId) => this.control(agentId, runId, "pause"),
+        retry: (agentId, runId) => this.control(agentId, runId, "retry"),
+        resume: (agentId, runId) => this.control(agentId, runId, "resume")
+      };
+      this.approvals = {
+        list: (agentId, runId) => this.request("GET", `/api/agents/${enc(agentId)}/runs/${enc(runId)}/approvals`),
+        resolve: (agentId, runId, input) => this.request("POST", `/api/agents/${enc(agentId)}/runs/${enc(runId)}/approvals/resolve`, {
+          exception_id: input.exceptionId,
+          resolution: input.resolution,
+          ...input.modifiedData ? { modified_data: input.modifiedData } : {}
+        })
+      };
+      if (!config || Boolean(config.apiKey) === Boolean(config.getIdToken)) {
+        throw new ValidationError("Give exactly one of apiKey or getIdToken");
+      }
+      if (config.apiKey && !config.apiKey.startsWith("ak_")) {
+        throw new ValidationError("apiKey must be an Olbrain access key (ak_\u2026)");
+      }
+      this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL2).replace(/\/$/, "");
+      this.timeoutMs = config.timeoutMs ?? 3e4;
+    }
+    control(agentId, runId, verb) {
+      return this.request("POST", `/api/agents/${enc(agentId)}/runs/${enc(runId)}/${verb}`);
+    }
+    async request(method, path, body) {
+      const token = this.config.apiKey ?? await this.config.getIdToken();
+      const headers = { Authorization: `Bearer ${token}` };
+      if (body !== void 0) headers["Content-Type"] = "application/json";
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      let res;
+      try {
+        res = await fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body === void 0 ? void 0 : JSON.stringify(body),
+          signal: controller.signal
+        });
+      } catch (err) {
+        const e = err;
+        throw new NetworkError(e?.name === "AbortError" ? `Request timed out after ${this.timeoutMs}ms` : e?.message || "Network error");
+      } finally {
+        clearTimeout(timer);
+      }
+      const data = await res.json().catch(() => void 0);
+      if (res.ok) return data;
+      const detail = data?.detail;
+      const pick = (k) => [data?.error?.[k], typeof detail === "object" && !Array.isArray(detail) ? detail?.[k] : void 0, data?.[k]].find((v) => typeof v === "string" && v);
+      const code = pick("code") ?? "error";
+      const message = data?.error?.message ?? (typeof detail === "string" && detail ? detail : void 0) ?? pick("message") ?? (res.statusText || "Request failed");
+      if (BILLING_CODES.has(code)) throw new BillingError(res.status, code, message);
+      if (res.status === 401) throw new AuthenticationError(message);
+      if (res.status === 404) throw new NotFoundError(code, message);
+      if (res.status === 429) {
+        const retryAfter = Number(res.headers.get("Retry-After"));
+        throw new RateLimitError(message, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0);
+      }
+      throw new ApiError(res.status, code, message);
+    }
+  };
+
   // src/index.ts
-  var VERSION = "1.0.0";
+  var VERSION = "1.2.0";
   return __toCommonJS(index_exports);
 })();
 //# sourceMappingURL=index.global.js.map