@tuvl/client 0.0.1 → 2026.2.1-beta.1

package/dist/index.js

@@ -0,0 +1,697 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 });
+};
+
+// src/grpc.ts
+var grpc_exports = {};
+__export(grpc_exports, {
+  openGrpcStream: () => openGrpcStream
+});
+async function* openGrpcStream(options) {
+  let GrpcWebFetchTransport;
+  try {
+    const mod = await import('@protobuf-ts/grpcweb-transport');
+    GrpcWebFetchTransport = mod.GrpcWebFetchTransport;
+  } catch {
+    throw new Error(
+      "@tuvl/client: gRPC mode requires @protobuf-ts/grpcweb-transport. Install it with: npm i @protobuf-ts/grpcweb-transport @protobuf-ts/runtime-rpc"
+    );
+  }
+  const { BinaryWriter, BinaryReader, WireType } = await import('@protobuf-ts/runtime');
+  function encodeRunRequest(workflowName, payloadJson, tokenFallback) {
+    const writer = new BinaryWriter();
+    writer.tag(1, WireType.LengthDelimited).string(workflowName);
+    writer.tag(2, WireType.LengthDelimited).string(payloadJson);
+    if (tokenFallback) {
+      writer.tag(3, WireType.LengthDelimited).string(tokenFallback);
+    }
+    return writer.finish();
+  }
+  function decodeStepEvent(bytes) {
+    const reader = new BinaryReader(bytes);
+    let eventType = "";
+    let stepId = "";
+    let kind = "";
+    let signal = "";
+    let snapshotJson = "";
+    let durationMs = 0;
+    let errorDetail = "";
+    while (reader.pos < reader.len) {
+      const [fieldNo, wireType] = reader.tag();
+      switch (fieldNo) {
+        case 1:
+          eventType = reader.string();
+          break;
+        case 2:
+          stepId = reader.string();
+          break;
+        case 3:
+          kind = reader.string();
+          break;
+        case 4:
+          signal = reader.string();
+          break;
+        case 5:
+          snapshotJson = reader.string();
+          break;
+        case 6:
+          durationMs = reader.float();
+          break;
+        case 7:
+          errorDetail = reader.string();
+          break;
+        default:
+          reader.skip(wireType);
+      }
+    }
+    let snapshot = {};
+    if (snapshotJson) {
+      try {
+        snapshot = JSON.parse(snapshotJson);
+      } catch {
+      }
+    }
+    const et = eventType || "step";
+    return {
+      event_type: et,
+      step_id: stepId,
+      kind,
+      signal,
+      snapshot,
+      duration_ms: durationMs,
+      error_detail: errorDetail || void 0
+    };
+  }
+  const transport = new GrpcWebFetchTransport({
+    baseUrl: options.baseUrl,
+    fetchInit: options.token ? { headers: { Authorization: `Bearer ${options.token}` } } : void 0
+  });
+  const methodDescriptor = {
+    name: "/tuvl.v1.ExecutionService/RunWorkflow",
+    clientStreaming: false,
+    serverStreaming: true,
+    I: { create: () => ({}) },
+    O: { create: () => ({}) },
+    options: {}
+  };
+  const requestBytes = encodeRunRequest(
+    options.workflowName,
+    options.payloadJson,
+    options.tokenFallback ?? ""
+  );
+  const call = transport.serverStreaming(methodDescriptor, requestBytes, {
+    abort: options.signal
+  });
+  for await (const responseBytes of call.responses) {
+    const event = decodeStepEvent(responseBytes);
+    yield event;
+    if (event.event_type === "done" || event.event_type === "error" || event.event_type === "suspended") {
+      break;
+    }
+  }
+}
+var init_grpc = __esm({
+  "src/grpc.ts"() {
+  }
+});
+
+// src/sse.ts
+async function* parseSseStream(response, signal) {
+  if (!response.body) {
+    throw new Error("SSE response has no body");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let currentEventType = "message";
+  let currentDataLines = [];
+  const flush = function* () {
+    const dataStr = currentDataLines.join("\n");
+    const eventType = currentEventType;
+    currentDataLines = [];
+    currentEventType = "message";
+    if (!dataStr) return;
+    let parsed;
+    try {
+      parsed = JSON.parse(dataStr);
+    } catch {
+      return;
+    }
+    if (typeof parsed !== "object" || parsed === null) return;
+    const frame = { ...parsed, event_type: eventType };
+    yield frame;
+  };
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const rawLine of lines) {
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        if (line.startsWith("event:")) {
+          currentEventType = line.slice(6).trim();
+        } else if (line.startsWith("data:")) {
+          currentDataLines.push(line.slice(5).trim());
+        } else if (line === "") {
+          for (const frame of flush()) {
+            yield frame;
+            if (frame.event_type === "done" || frame.event_type === "error" || frame.event_type === "suspended") {
+              return;
+            }
+          }
+        }
+      }
+    }
+    for (const frame of flush()) {
+      yield frame;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/transport.ts
+var Transport = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.defaultToken = options.defaultToken;
+  }
+  /** Update the default token (e.g. after refresh). */
+  setToken(token) {
+    this.defaultToken = token;
+  }
+  /** Build the Authorization header value, or undefined if no token. */
+  authHeader(overrideToken) {
+    const tok = overrideToken ?? this.defaultToken;
+    return tok ? `Bearer ${tok}` : void 0;
+  }
+  /** Perform a plain JSON POST and return the parsed response body. */
+  async post(path, body, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    const auth = this.authHeader(options?.token);
+    if (auth) headers["Authorization"] = auth;
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: options?.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl POST ${path} \u2192 HTTP ${response.status}: ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Open an SSE-capable stream and return the raw Response.
+   * Callers are responsible for reading `response.body`.
+   */
+  async postStream(path, body, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache"
+    };
+    const auth = this.authHeader(options?.token);
+    if (auth) headers["Authorization"] = auth;
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: options?.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl SSE ${path} \u2192 HTTP ${response.status}: ${text}`);
+    }
+    return response;
+  }
+  /** Simple GET returning parsed JSON. */
+  async get(path, options) {
+    const headers = { Accept: "application/json" };
+    const auth = this.authHeader(options?.token);
+    if (auth) headers["Authorization"] = auth;
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers,
+      signal: options?.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl GET ${path} \u2192 HTTP ${response.status}: ${text}`);
+    }
+    return response.json();
+  }
+};
+
+// src/types.ts
+var TuvlWorkflowError = class extends Error {
+  constructor(message, data, error) {
+    super(message);
+    this.name = "TuvlWorkflowError";
+    this.data = data;
+    this.error = error;
+  }
+};
+var TuvlWorkflowSuspendedError = class extends Error {
+  constructor(suspended) {
+    super(`tuvl workflow suspended at step '${suspended.paused_step_id ?? "?"}'`);
+    this.name = "TuvlWorkflowSuspendedError";
+    this.suspended = suspended;
+  }
+};
+
+// src/client.ts
+var TuvlClient = class {
+  constructor(options) {
+    this.manifestCache = /* @__PURE__ */ new Map();
+    this.transport = new Transport({
+      baseUrl: options.baseUrl,
+      defaultToken: options.token
+    });
+    this.manifestCacheTtl = options.manifestCacheTtl ?? 6e4;
+  }
+  /** Update the default auth token (e.g. after token refresh). */
+  setToken(token) {
+    this.transport.setToken(token);
+  }
+  /** Expose the base URL for callers that need raw access (e.g. gRPC). */
+  get baseUrl() {
+    return this.transport.baseUrl;
+  }
+  // ── Manifest ──────────────────────────────────────────────────────────────
+  /** Fetch (and cache) the manifest for a single workflow. */
+  async getManifest(workflowName, options) {
+    const cached = this.manifestCache.get(workflowName);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.manifest;
+    }
+    const manifest = await this.transport.get(
+      `/api/_system/workflows/${encodeURIComponent(workflowName)}`,
+      options
+    );
+    if (this.manifestCacheTtl > 0) {
+      this.manifestCache.set(workflowName, {
+        manifest,
+        expiresAt: Date.now() + this.manifestCacheTtl
+      });
+    }
+    return manifest;
+  }
+  /** Fetch manifests for all registered workflows. */
+  async listWorkflows(options) {
+    return this.transport.get("/api/_system/workflows", options);
+  }
+  /** Invalidate the cached manifest for a workflow (or all if no name given). */
+  invalidateManifest(workflowName) {
+    if (workflowName) {
+      this.manifestCache.delete(workflowName);
+    } else {
+      this.manifestCache.clear();
+    }
+  }
+  // ── Execute ───────────────────────────────────────────────────────────────
+  /**
+   * Execute a workflow and return its `data` payload.
+   *
+   * Transport selection:
+   * 1. mode="grpc"            → gRPC-Web (always, regardless of onProgress)
+   * 2. mode="sse"             → SSE stream
+   * 3. onProgress provided    → SSE if workflow has_slow_steps, else REST
+   * 4. default                → REST
+   *
+   * @throws {TuvlWorkflowError}          when the workflow returns success=false
+   * @throws {TuvlWorkflowSuspendedError} when the workflow suspends at HITL
+   * @throws {Error}                      on transport / engine failures
+   */
+  async execute(workflowName, options = {}) {
+    const { payload = {}, onProgress, onSuspended, mode, token, signal } = options;
+    const manifest = await this.getManifest(workflowName, { token, signal });
+    const useSse = mode === "sse" || mode !== "rest" && mode !== "grpc" && !!onProgress && manifest.has_slow_steps;
+    if (mode === "grpc") {
+      return this._executeGrpc(manifest, payload, onProgress, onSuspended, token, signal);
+    }
+    if (useSse) {
+      return this._executeSse(manifest, payload, onProgress, onSuspended, token, signal);
+    }
+    const envelope = await this.transport.post(
+      manifest.trigger_path,
+      payload,
+      { token, signal }
+    );
+    return this._unwrapRest(envelope, manifest.name);
+  }
+  /**
+   * Execute a specific version of a workflow via `/{version}/run/{name}`.
+   *
+   * Useful when you want to pin to a particular schema_version without
+   * relying on the currently-active default trigger path.
+   *
+   * @throws {TuvlWorkflowError}          when the workflow returns success=false
+   * @throws {TuvlWorkflowSuspendedError} when the workflow suspends at HITL
+   * @throws {Error}                      on transport / engine failures
+   */
+  async executeVersioned(workflowName, version, options = {}) {
+    const { payload = {}, onProgress, onSuspended, mode, token, signal } = options;
+    const triggerPath = `/${version}/run/${workflowName}`;
+    let cachedManifest;
+    try {
+      cachedManifest = await this.getManifest(workflowName, { token, signal });
+    } catch {
+    }
+    const syntheticManifest = {
+      name: workflowName,
+      trigger_path: triggerPath,
+      trigger_method: "POST",
+      has_slow_steps: cachedManifest?.has_slow_steps ?? false,
+      slow_kinds_present: cachedManifest?.slow_kinds_present ?? [],
+      required_scope: cachedManifest?.required_scope ?? null,
+      required_group: cachedManifest?.required_group ?? null,
+      steps: cachedManifest?.steps ?? []
+    };
+    const useSse = mode === "sse" || mode !== "rest" && mode !== "grpc" && !!onProgress && syntheticManifest.has_slow_steps;
+    if (mode === "grpc") {
+      return this._executeGrpc(
+        syntheticManifest,
+        payload,
+        onProgress,
+        onSuspended,
+        token,
+        signal
+      );
+    }
+    if (useSse) {
+      return this._executeSse(
+        syntheticManifest,
+        payload,
+        onProgress,
+        onSuspended,
+        token,
+        signal
+      );
+    }
+    const envelope = await this.transport.post(
+      triggerPath,
+      payload,
+      { token, signal }
+    );
+    return this._unwrapRest(envelope, workflowName);
+  }
+  /**
+   * Resume a HITL-suspended workflow instance.
+   *
+   * After the workflow throws `TuvlWorkflowSuspendedError`, capture the
+   * `event.instance_id` from the suspended event and pass it here along with
+   * the human-provided data to continue execution.
+   *
+   * @throws {TuvlWorkflowError}          when the resumed workflow returns success=false
+   * @throws {TuvlWorkflowSuspendedError} when the workflow suspends again at another HITL step
+   * @throws {Error}                      on transport / engine failures
+   */
+  async resumeWorkflow(options) {
+    const { instanceId, humanInput = {}, onProgress, onSuspended, mode, token, signal } = options;
+    const body = {
+      instance_id: instanceId,
+      human_input: humanInput
+    };
+    if (mode === "sse" || mode !== "rest" && !!onProgress) {
+      const syntheticManifest = {
+        name: `(resumed:${instanceId})`,
+        trigger_path: "/api/workflows/resume",
+        trigger_method: "POST",
+        has_slow_steps: true,
+        slow_kinds_present: [],
+        required_scope: null,
+        required_group: null,
+        steps: []
+      };
+      return this._executeSse(
+        syntheticManifest,
+        body,
+        onProgress,
+        onSuspended,
+        token,
+        signal
+      );
+    }
+    const envelope = await this.transport.post(
+      "/api/workflows/resume",
+      body,
+      { token, signal }
+    );
+    return this._unwrapRest(envelope, `(resumed:${instanceId})`);
+  }
+  // ── SSE transport ─────────────────────────────────────────────────────────
+  async _executeSse(manifest, payload, onProgress, onSuspended, token, signal) {
+    const response = await this.transport.postStream(manifest.trigger_path, payload, {
+      token,
+      signal
+    });
+    let done;
+    for await (const frame of parseSseStream(response, signal)) {
+      switch (frame.event_type) {
+        case "step":
+          onProgress?.(frame);
+          break;
+        case "done":
+          done = frame;
+          break;
+        case "suspended":
+          onSuspended?.(frame);
+          throw new TuvlWorkflowSuspendedError(frame);
+        case "error": {
+          const err = frame;
+          throw new Error(
+            `tuvl workflow '${manifest.name}' engine error: ${err.message}` + (err.details ? ` \u2014 ${err.details}` : "")
+          );
+        }
+      }
+    }
+    if (!done) {
+      throw new Error(`tuvl SSE stream for '${manifest.name}' ended without a done event`);
+    }
+    if (!done.success) {
+      throw new TuvlWorkflowError(
+        `tuvl workflow '${manifest.name}' failed`,
+        done.data,
+        done.error
+      );
+    }
+    return done.data;
+  }
+  // ── gRPC-Web transport ────────────────────────────────────────────────────
+  async _executeGrpc(manifest, payload, onProgress, onSuspended, token, signal) {
+    const { openGrpcStream: openGrpcStream2 } = await Promise.resolve().then(() => (init_grpc(), grpc_exports));
+    let finalSnapshot;
+    for await (const event of openGrpcStream2({
+      baseUrl: this.baseUrl,
+      workflowName: manifest.name,
+      payloadJson: JSON.stringify(payload),
+      token,
+      signal
+    })) {
+      switch (event.event_type) {
+        case "step":
+          onProgress?.(event);
+          break;
+        case "done":
+          finalSnapshot = event.snapshot;
+          break;
+        case "suspended": {
+          const snap = event.snapshot;
+          const suspended = {
+            event_type: "suspended",
+            paused_step_id: event.step_id,
+            ...snap
+          };
+          onSuspended?.(suspended);
+          throw new TuvlWorkflowSuspendedError(suspended);
+        }
+        case "error":
+          throw new Error(
+            `tuvl workflow '${manifest.name}' gRPC error: ${event.error_detail ?? "unknown"}`
+          );
+      }
+    }
+    if (finalSnapshot === void 0) {
+      throw new Error(`tuvl gRPC stream for '${manifest.name}' ended without a done event`);
+    }
+    if ("_last_error" in finalSnapshot) {
+      throw new TuvlWorkflowError(
+        `tuvl workflow '${manifest.name}' failed`,
+        finalSnapshot,
+        finalSnapshot._last_error ?? null
+      );
+    }
+    if ("_response" in finalSnapshot) {
+      return finalSnapshot._response;
+    }
+    return finalSnapshot;
+  }
+  // ── REST envelope ─────────────────────────────────────────────────────────
+  _unwrapRest(envelope, workflowName) {
+    if (!envelope || typeof envelope !== "object") {
+      return envelope;
+    }
+    if (envelope.success === false) {
+      throw new TuvlWorkflowError(
+        `tuvl workflow '${workflowName}' failed`,
+        envelope.data,
+        envelope.error
+      );
+    }
+    return envelope.data ?? envelope;
+  }
+};
+
+// src/auth.ts
+var TuvlAuth = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+  }
+  /**
+   * Decode the current token server-side and return the user's identity,
+   * role memberships (`groups`), and permission scopes.
+   *
+   * Biscuit tokens are protobuf-encoded and cannot be decoded in pure JS,
+   * so this is the correct way to read "who is logged in" and "what can
+   * they do" from the TypeScript SDK.
+   *
+   * @throws if the token is invalid, expired, or revoked.
+   */
+  async getMe(token) {
+    const response = await fetch(`${this.baseUrl}/auth/me`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl getMe failed (HTTP ${response.status}): ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Exchange an email + password for a Biscuit bearer token.
+   *
+   * Calls `POST /auth/token` with an `application/x-www-form-urlencoded`
+   * body (OAuth2 password-grant). The `username` field must be the user's
+   * email address.
+   */
+  async loginWithPassword(email, password) {
+    const body = new URLSearchParams({ username: email, password });
+    const response = await fetch(`${this.baseUrl}/auth/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl login failed (HTTP ${response.status}): ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Create the first superadmin user (one-time IAM bootstrap).
+   *
+   * Calls `POST /auth/bootstrap`. Returns 409 on every subsequent call
+   * once any user exists.
+   */
+  async bootstrap(req) {
+    const response = await fetch(`${this.baseUrl}/auth/bootstrap`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      },
+      body: JSON.stringify(req)
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl bootstrap failed (HTTP ${response.status}): ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Return the URL the browser should navigate to in order to start an
+   * OAuth2 login flow for the given provider.
+   *
+   * Supported built-ins: `"google"`, `"github"`, `"microsoft"`. Any
+   * provider configured in the project's `federation/` directory also
+   * works.
+   *
+   * After the OAuth dance the server either:
+   * - redirects to `TUVL_OAUTH_UI_REDIRECT_URL?token=<biscuit_b64>`, OR
+   * - returns a JSON `{access_token, token_type}` body (CLI / server flows).
+   */
+  getOAuthLoginUrl(provider) {
+    return `${this.baseUrl}/auth/oauth/${encodeURIComponent(provider)}/start`;
+  }
+  /**
+   * Exchange a valid (non-expired, non-revoked) token for a fresh one.
+   * The old token is immediately blacklisted — discard it after this call.
+   */
+  async refresh(token) {
+    const response = await fetch(`${this.baseUrl}/auth/refresh`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`tuvl token refresh failed (HTTP ${response.status}): ${text}`);
+    }
+    return response.json();
+  }
+  /**
+   * Revoke the given token (logout). After this the token is blacklisted
+   * across all workers that share a Redis instance. Resolves silently on
+   * success (HTTP 204).
+   */
+  async logout(token) {
+    const response = await fetch(`${this.baseUrl}/auth/logout`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!response.ok && response.status !== 204) {
+      const text = await response.text();
+      throw new Error(`tuvl logout failed (HTTP ${response.status}): ${text}`);
+    }
+  }
+};
+
+// src/index.ts
+init_grpc();
+
+exports.Transport = Transport;
+exports.TuvlAuth = TuvlAuth;
+exports.TuvlClient = TuvlClient;
+exports.TuvlWorkflowError = TuvlWorkflowError;
+exports.TuvlWorkflowSuspendedError = TuvlWorkflowSuspendedError;
+exports.openGrpcStream = openGrpcStream;
+exports.parseSseStream = parseSseStream;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map