@tuvl/client 0.0.1 → 2026.2.1-beta.2

package/dist/index.d.ts

@@ -0,0 +1,569 @@
+/**
+ * Low-level HTTP transport for @tuvl/client.
+ *
+ * Handles auth header injection, JSON serialisation, and returns raw
+ * Response objects so higher-level transports (SSE, gRPC) can consume them.
+ */
+interface TransportOptions {
+    baseUrl: string;
+    defaultToken?: string;
+}
+declare class Transport {
+    /** Public so TuvlClient can forward it to the gRPC subtransport. */
+    readonly baseUrl: string;
+    private defaultToken;
+    constructor(options: TransportOptions);
+    /** Update the default token (e.g. after refresh). */
+    setToken(token: string): void;
+    /** Build the Authorization header value, or undefined if no token. */
+    private authHeader;
+    /** Perform a plain JSON POST and return the parsed response body. */
+    post<TBody = unknown, TResponse = unknown>(path: string, body: TBody, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<TResponse>;
+    /**
+     * Open an SSE-capable stream and return the raw Response.
+     * Callers are responsible for reading `response.body`.
+     */
+    postStream(path: string, body: unknown, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** Simple GET returning parsed JSON. */
+    get<TResponse = unknown>(path: string, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<TResponse>;
+    /** Perform a JSON PATCH and return the parsed response body. */
+    patch<TBody = unknown, TResponse = unknown>(path: string, body: TBody, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<TResponse>;
+    /** Perform a DELETE request. Expects a 204 No Content response. */
+    delete(path: string, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+/**
+ * Shared types for @tuvl/client.
+ *
+ * Mirrors the Python-side StepEvent dataclass, the SSE envelope produced by
+ * tuvl.core.engine.streaming, and the system_router manifest shapes.
+ */
+/** Returned by all /auth/* login and refresh endpoints. */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+}
+/**
+ * Decoded identity and permissions for the currently authenticated user.
+ * Returned by GET /auth/me.
+ */
+interface MeResponse {
+    /** User UUID extracted from the `user()` Datalog fact in the token. */
+    user_id: string;
+    /** Role names from all `group()` facts — e.g. ["hr_manager", "member"]. */
+    groups: string[];
+    /** Permission scopes from all `scope()` facts — e.g. ["candidate:read"]. */
+    scopes: string[];
+}
+/** A single execution event streamed by the tuvl server (SSE or gRPC). */
+interface StepEvent {
+    event_type: "step";
+    step_id: string;
+    kind: string;
+    signal: string;
+    snapshot: Record<string, unknown>;
+    duration_ms: number;
+    error_detail?: string | null;
+}
+/**
+ * Terminal event emitted when the workflow finishes (success OR business failure).
+ * Wire shape from tuvl.core.api.manager._sse_generator:
+ *   {success: true,  data: <output>,  error: null}
+ *   {success: false, data: <partial>, error: {...workflow error...}}
+ */
+interface DoneEvent {
+    event_type: "done";
+    success: boolean;
+    data: unknown;
+    error: WorkflowErrorPayload | null;
+}
+/** Terminal event emitted when the workflow engine itself raised an exception. */
+interface ErrorEvent {
+    event_type: "error";
+    message: string;
+    details?: string | null;
+}
+/** Terminal event emitted when a workflow hits a Human-in-the-Loop step. */
+interface SuspendedEvent {
+    event_type: "suspended";
+    instance_id?: string;
+    paused_step_id?: string;
+    ui?: unknown;
+    schema?: unknown;
+    context_data?: Record<string, unknown>;
+    output_key?: string;
+    [key: string]: unknown;
+}
+/** Shape of the `error` field on a non-success DoneEvent / REST envelope. */
+interface WorkflowErrorPayload {
+    code?: string;
+    message?: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Shape of the plain REST response body returned by
+ * `POST <workflow_trigger_path>` (and the versioned variant).
+ *
+ * `execute()` unwraps this and returns just `data` on success, throwing
+ * `TuvlWorkflowError` on `success === false`.
+ */
+interface RestEnvelope<TData = unknown> {
+    success: boolean;
+    status_code: number;
+    data: TData | null;
+    error: WorkflowErrorPayload | null;
+}
+/** Manifest for a single workflow (from GET /api/_system/workflows/{name}). */
+interface WorkflowManifest {
+    name: string;
+    trigger_path: string;
+    trigger_method: string;
+    has_slow_steps: boolean;
+    slow_kinds_present: string[];
+    required_scope: string | null;
+    required_group: string | null;
+    steps: Array<{
+        id: string;
+        kind: string;
+    }>;
+}
+/** Map of workflow manifests (from GET /api/_system/workflows). */
+type WorkflowManifestMap = Record<string, Omit<WorkflowManifest, "name" | "steps">>;
+/** Options passed to TuvlClient.execute(). */
+interface ExecuteOptions<_TOutput = unknown> {
+    payload?: Record<string, unknown>;
+    onProgress?: (event: StepEvent) => void;
+    onSuspended?: (event: SuspendedEvent) => void;
+    mode?: "sse" | "grpc" | "rest";
+    token?: string;
+    signal?: AbortSignal;
+}
+/** Options passed to TuvlClient.executeVersioned(). */
+interface ExecuteVersionedOptions<_TOutput = unknown> extends ExecuteOptions<_TOutput> {
+    /** The workflow's schema_version, e.g. "v2". Calls /{version}/run/{name}. */
+    version: string;
+}
+/** Body sent to POST /api/workflows/resume. */
+interface ResumeRequest {
+    instance_id: string;
+    human_input?: Record<string, unknown>;
+}
+/** Options passed to TuvlClient.resumeWorkflow(). */
+interface ResumeOptions<_TOutput = unknown> {
+    instanceId: string;
+    humanInput?: Record<string, unknown>;
+    onProgress?: (event: StepEvent) => void;
+    onSuspended?: (event: SuspendedEvent) => void;
+    mode?: "sse" | "rest";
+    token?: string;
+    signal?: AbortSignal;
+}
+/** Options passed to TuvlClient constructor. */
+interface TuvlClientOptions {
+    baseUrl: string;
+    token?: string;
+    manifestCacheTtl?: number;
+}
+/**
+ * Options for listing records from a CRUD model endpoint.
+ *
+ * `filters` maps to bracket-notation query params: `filter[key]=value`.
+ * `include` maps to `?include=relation1,relation2` for eager-loading relations.
+ */
+interface CrudListOptions {
+    limit?: number;
+    offset?: number;
+    /** Server-side field filters: { stage: "screening" } → `?filter[stage]=screening` */
+    filters?: Record<string, string>;
+    /** Relation names to embed: ["posting"] → `?include=posting` */
+    include?: string[];
+    token?: string;
+    signal?: AbortSignal;
+}
+/** Options for retrieving a single CRUD record. */
+interface CrudGetOptions {
+    /** Relation names to embed: ["candidate"] → `?include=candidate` */
+    include?: string[];
+    token?: string;
+    signal?: AbortSignal;
+}
+/** Options for create / update / delete calls. */
+interface CrudMutateOptions {
+    token?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Thrown by `execute()` when a workflow finishes with `success: false`.
+ */
+declare class TuvlWorkflowError extends Error {
+    readonly data: unknown;
+    readonly error: WorkflowErrorPayload | null;
+    constructor(message: string, data: unknown, error: WorkflowErrorPayload | null);
+}
+/**
+ * Thrown by `execute()` when a workflow suspends at a Human-in-the-Loop step.
+ */
+declare class TuvlWorkflowSuspendedError extends Error {
+    readonly suspended: SuspendedEvent;
+    constructor(suspended: SuspendedEvent);
+}
+
+/**
+ * CrudClient — typed CRUD access for tuvl model endpoints.
+ *
+ * The tuvl server mounts auto-generated CRUD routers at:
+ *   /models/{modelname}/          (list, create)
+ *   /models/{modelname}/{id}      (get, update, delete)
+ *
+ * Usage via TuvlClient.crud():
+ *
+ * ```ts
+ * const client = new TuvlClient({ baseUrl: "http://localhost:8000", token });
+ *
+ * // List all candidates
+ * const all = await client.crud("candidate").list();
+ *
+ * // Filter + embed relations
+ * const results = await client.crud("candidate").list({
+ *   filters: { stage: "screening" },
+ *   include: ["posting"],
+ *   limit: 50,
+ * });
+ *
+ * // Get one
+ * const c = await client.crud("candidate").get("uuid-here");
+ *
+ * // Create
+ * const created = await client.crud<CandidateRead, CandidateCreate>("candidate")
+ *   .create({ name: "Alice", email: "alice@example.com" });
+ *
+ * // Update
+ * const updated = await client.crud("candidate").update("uuid", { stage: "interview" });
+ *
+ * // Delete
+ * await client.crud("candidate").delete("uuid");
+ * ```
+ *
+ * Type parameters:
+ *   TRead   — shape returned by GET / POST / PATCH (defaults to `unknown`)
+ *   TCreate — body for POST (defaults to `Partial<TRead>`)
+ *   TUpdate — body for PATCH (defaults to `Partial<TRead>`)
+ */
+
+declare class CrudClient<TRead = unknown, TCreate = Partial<TRead>, TUpdate = Partial<TRead>> {
+    private readonly transport;
+    private readonly basePath;
+    constructor(transport: Transport, modelName: string);
+    /** Build query string from list options. */
+    private _buildQuery;
+    /** Build ?include= query string for get-by-id calls. */
+    private _buildGetQuery;
+    /**
+     * GET /models/{model}/
+     * Returns all records matching the given filters (server default: up to 100).
+     */
+    list(options?: CrudListOptions): Promise<TRead[]>;
+    /**
+     * GET /models/{model}/{id}
+     * Returns a single record by UUID, optionally with embedded relations.
+     */
+    get(id: string, options?: CrudGetOptions): Promise<TRead>;
+    /**
+     * POST /models/{model}/
+     * Creates a new record and returns the created resource (HTTP 201).
+     */
+    create(body: TCreate, options?: CrudMutateOptions): Promise<TRead>;
+    /**
+     * PATCH /models/{model}/{id}
+     * Partially updates a record (only fields present in `body` are changed).
+     */
+    update(id: string, body: TUpdate, options?: CrudMutateOptions): Promise<TRead>;
+    /**
+     * DELETE /models/{model}/{id}
+     * Deletes a record (HTTP 204). Throws if the record is not found.
+     */
+    delete(id: string, options?: CrudMutateOptions): Promise<void>;
+}
+
+/**
+ * TuvlClient — the main entry point for @tuvl/client.
+ *
+ * Auto-detects the best transport for each workflow call:
+ *
+ *   mode="rest"  (default)    → plain POST, unwraps the REST envelope
+ *   mode="sse"  (auto)        → SSE streaming when onProgress is provided
+ *                               AND the workflow has_slow_steps === true
+ *   mode="grpc"               → gRPC-Web via sonora (requires peer deps)
+ *
+ * Return-value contract — IDENTICAL across all three transports:
+ *
+ *   • on success                  → resolves with the `data` value
+ *   • on workflow-business error  → rejects with `TuvlWorkflowError`
+ *   • on HITL suspension          → rejects with `TuvlWorkflowSuspendedError`
+ *   • on transport / engine error → rejects with a plain `Error`
+ *
+ * Manifest caching avoids extra round-trips on repeated calls to the same
+ * workflow.  TTL defaults to 60 s and is configurable.
+ */
+
+declare class TuvlClient {
+    private readonly transport;
+    private readonly manifestCache;
+    private readonly manifestCacheTtl;
+    constructor(options: TuvlClientOptions);
+    /** Update the default auth token (e.g. after token refresh). */
+    setToken(token: string): void;
+    /** Expose the base URL for callers that need raw access (e.g. gRPC). */
+    get baseUrl(): string;
+    /** Fetch (and cache) the manifest for a single workflow. */
+    getManifest(workflowName: string, options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkflowManifest>;
+    /** Fetch manifests for all registered workflows. */
+    listWorkflows(options?: {
+        token?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkflowManifestMap>;
+    /** Invalidate the cached manifest for a workflow (or all if no name given). */
+    invalidateManifest(workflowName?: string): void;
+    /**
+     * 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
+     */
+    execute<TOutput = unknown>(workflowName: string, options?: ExecuteOptions<TOutput>): Promise<TOutput>;
+    /**
+     * 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
+     */
+    executeVersioned<TOutput = unknown>(workflowName: string, version: string, options?: ExecuteVersionedOptions<TOutput> | ExecuteOptions<TOutput>): Promise<TOutput>;
+    /**
+     * 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
+     */
+    resumeWorkflow<TOutput = unknown>(options: ResumeOptions<TOutput>): Promise<TOutput>;
+    private _executeSse;
+    private _executeGrpc;
+    private _unwrapRest;
+    /**
+     * Return a typed CRUD client for a tuvl model endpoint.
+     *
+     * The returned client targets `/models/{modelName}/` and shares the
+     * same transport (base URL + auth token) as this TuvlClient instance.
+     *
+     * @example
+     * ```ts
+     * // List all candidates
+     * const all = await client.crud("candidate").list();
+     *
+     * // With filters + embedded relations
+     * const results = await client.crud("candidate").list({
+     *   filters: { stage: "screening" },
+     *   include: ["posting"],
+     *   limit: 50,
+     * });
+     *
+     * // Get one record
+     * const c = await client.crud("candidate").get("uuid-here");
+     *
+     * // Strongly-typed variant
+     * const c2 = await client
+     *   .crud<CandidateRead, CandidateCreate>("candidate")
+     *   .create({ name: "Alice", email: "alice@example.com" });
+     * ```
+     */
+    crud<TRead = unknown, TCreate = Partial<TRead>, TUpdate = Partial<TRead>>(modelName: string): CrudClient<TRead, TCreate, TUpdate>;
+}
+
+/**
+ * TuvlAuth — authentication helpers for @tuvl/client.
+ *
+ * Wraps the most common /auth/* endpoints (login, refresh, logout, who-am-I,
+ * OAuth start, bootstrap) so consumers never have to manually construct
+ * form-encoded bodies or manage Bearer headers for auth operations.
+ *
+ * Admin endpoints (user/role/scope CRUD, federation config) are NOT wrapped
+ * — call them directly via `Transport` or `fetch` with the token.
+ */
+
+interface TuvlAuthOptions {
+    /** Base URL of the tuvl server. Trailing slash is stripped automatically. */
+    baseUrl: string;
+}
+interface BootstrapRequest {
+    email: string;
+    password: string;
+    /** Optional extra scope to grant the superadmin role on creation. */
+    admin_scope?: string;
+}
+declare class TuvlAuth {
+    private readonly baseUrl;
+    constructor(options: TuvlAuthOptions);
+    /**
+     * 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.
+     */
+    getMe(token: string): Promise<MeResponse>;
+    /**
+     * 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.
+     */
+    loginWithPassword(email: string, password: string): Promise<TokenResponse>;
+    /**
+     * Create the first superadmin user (one-time IAM bootstrap).
+     *
+     * Calls `POST /auth/bootstrap`. Returns 409 on every subsequent call
+     * once any user exists.
+     */
+    bootstrap(req: BootstrapRequest): Promise<TokenResponse>;
+    /**
+     * 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: string): string;
+    /**
+     * Exchange a valid (non-expired, non-revoked) token for a fresh one.
+     * The old token is immediately blacklisted — discard it after this call.
+     */
+    refresh(token: string): Promise<TokenResponse>;
+    /**
+     * 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).
+     */
+    logout(token: string): Promise<void>;
+}
+
+/**
+ * SSE transport for @tuvl/client.
+ *
+ * Uses the Fetch API ReadableStream to parse SSE frames from a POST response
+ * opened by Transport.postStream().  This avoids the browser's native
+ * EventSource (which only supports GET) and works in Node 18+.
+ *
+ * Wire format produced by tuvl.core.engine.streaming:
+ *
+ *   event: step       data: {step_id, kind, signal, snapshot, duration_ms, error_detail}
+ *   event: suspended  data: {<hitl_request payload>}
+ *   event: done       data: {success, data, error}
+ *   event: error      data: {message, details}
+ *
+ * The JSON body has NO `event_type` field — it lives only on the `event:`
+ * line.  This parser injects the event name as `event_type` into the yielded
+ * object so downstream consumers can switch on a single discriminator.
+ */
+
+type SseFrame = StepEvent | DoneEvent | ErrorEvent | SuspendedEvent;
+/**
+ * Parse an SSE stream from a Fetch Response body.
+ *
+ * Yields typed frames as they arrive.  The generator terminates when it
+ * receives an event with event_type "done", "error", or "suspended", or
+ * when the stream closes.
+ */
+declare function parseSseStream(response: Response, signal?: AbortSignal): AsyncGenerator<SseFrame>;
+
+/**
+ * gRPC-Web transport for @tuvl/client.
+ *
+ * This module is an OPTIONAL transport that requires the peer dependencies:
+ *   @protobuf-ts/grpcweb-transport
+ *   @protobuf-ts/runtime-rpc
+ *
+ * It uses dynamic import() so the main bundle has zero overhead if you never
+ * use mode="grpc".  The protobuf definitions are created inline rather than
+ * from generated stubs, keeping the SDK self-contained (no make proto step
+ * required on the client side).
+ *
+ * The wire format matches execution.proto:
+ *   service ExecutionService { rpc RunWorkflow(RunRequest) → stream StepEvent }
+ */
+/**
+ * gRPC StepEvent on the wire. Unlike the typed SSE `StepEvent` (which is
+ * narrowed to `event_type: "step"`), this can carry "step" | "done" |
+ * "error" | "suspended" — the discriminator the servicer chose.
+ */
+interface GrpcStepEvent {
+    event_type: "step" | "done" | "error" | "suspended";
+    step_id: string;
+    kind: string;
+    signal: string;
+    /** Decoded from `snapshot_json` on the wire. */
+    snapshot: Record<string, unknown>;
+    duration_ms: number;
+    error_detail?: string;
+}
+interface GrpcRunOptions {
+    baseUrl: string;
+    workflowName: string;
+    payloadJson: string;
+    tokenFallback?: string;
+    token?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Open a gRPC-Web server-streaming call to ExecutionService.RunWorkflow.
+ *
+ * Yields `GrpcStepEvent` objects (with `snapshot_json` already parsed into
+ * `snapshot`).  The caller decides what each `event_type` means.
+ *
+ * Throws if the peer deps are not installed.
+ */
+declare function openGrpcStream(options: GrpcRunOptions): AsyncGenerator<GrpcStepEvent>;
+
+export { type BootstrapRequest, CrudClient, type CrudGetOptions, type CrudListOptions, type CrudMutateOptions, type DoneEvent, type ErrorEvent, type ExecuteOptions, type ExecuteVersionedOptions, type MeResponse, type RestEnvelope, type ResumeOptions, type ResumeRequest, type StepEvent, type SuspendedEvent, type TokenResponse, Transport, TuvlAuth, type TuvlAuthOptions, TuvlClient, type TuvlClientOptions, TuvlWorkflowError, TuvlWorkflowSuspendedError, type WorkflowErrorPayload, type WorkflowManifest, type WorkflowManifestMap, openGrpcStream, parseSseStream };