@tuvl/client 2026.2.1-beta.1 → 2026.2.1-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript client SDK for the [tuvl](https://tuvl.io) workflow orchestration engine.
 
-Supports three transports — plain REST, Server-Sent Events, and gRPC-Web — with automatic transport selection based on the workflow's streaming hints. Also ships first-class support for Human-in-the-Loop (HITL) resumption and explicit version pinning.
+Supports three transports — plain REST, Server-Sent Events, and gRPC-Web — with automatic transport selection based on the workflow's streaming hints. Also ships first-class support for Human-in-the-Loop (HITL) resumption, explicit version pinning, and typed CRUD access to tuvl model endpoints.
 
 ---
 
@@ -272,6 +272,70 @@ Clears the manifest cache for one workflow, or all if no name is given.
 
 ---
 
+## CRUD — model data access
+
+`client.crud(modelName)` returns a `CrudClient` that targets the auto-generated REST endpoints at `/models/{modelname}/`. The token and base URL are shared with the parent `TuvlClient`.
+
+```ts
+import { TuvlClient } from "@tuvl/client";
+
+const client = new TuvlClient({ baseUrl: "http://localhost:8000", token });
+
+// List all candidates (default limit: 100)
+const all = await client.crud("candidate").list();
+
+// Filter + embed relations
+const screened = await client.crud("candidate").list({
+  filters: { stage: "screening" },
+  include: ["posting"],
+  limit: 50,
+  offset: 0,
+});
+
+// Get one record by UUID
+const c = await client.crud("candidate").get("uuid-here");
+
+// Get one with embedded relations
+const cFull = await client.crud("candidate").get("uuid-here", {
+  include: ["posting", "assessments"],
+});
+
+// Create
+const created = await client.crud<CandidateRead, CandidateCreate>("candidate")
+  .create({ name: "Alice", email: "alice@example.com", stage: "applied" });
+
+// Partial update (PATCH — only the fields you pass are changed)
+const updated = await client.crud("candidate").update("uuid", { stage: "interview" });
+
+// Delete (resolves void on HTTP 204)
+await client.crud("candidate").delete("uuid");
+```
+
+### `client.crud<TRead, TCreate, TUpdate>(modelName)`
+
+Returns a `CrudClient<TRead, TCreate, TUpdate>` instance. All type parameters default to `unknown` / `Partial<TRead>`. The model name is lowercased automatically.
+
+### `CrudListOptions`
+
+| Option | Type | Description |
+|---|---|---|
+| `limit` | `number` | Max records to return (server default: 100, max: 1000) |
+| `offset` | `number` | Pagination offset |
+| `filters` | `Record<string, string>` | Field filters: `{ stage: "screening" }` → `?filter[stage]=screening` |
+| `include` | `string[]` | Relation names to embed: `["posting"]` → `?include=posting` |
+| `token` | `string` | Per-call token override |
+| `signal` | `AbortSignal` | Cancellation signal |
+
+### Auth scopes required
+
+| Operation | Required scope |
+|---|---|
+| `list()` / `get()` | `{modelname}:read` |
+| `create()` / `update()` | `{modelname}:write` |
+| `delete()` | `{modelname}:delete` |
+
+---
+
 ## TypeScript types
 
 ```ts
@@ -292,10 +356,15 @@ import type {
   ResumeOptions,        // options for resumeWorkflow()
   ResumeRequest,        // raw body sent to POST /api/workflows/resume
   TuvlClientOptions,    // constructor options
+  CrudListOptions,      // options for crud().list()
+  CrudGetOptions,       // options for crud().get()
+  CrudMutateOptions,    // options for crud().create() / update() / delete()
 } from "@tuvl/client";
 
 // Error classes are real classes — usable with `instanceof`
 import { TuvlWorkflowError, TuvlWorkflowSuspendedError } from "@tuvl/client";
+// CRUD client — also exported for use without TuvlClient
+import { CrudClient } from "@tuvl/client";
 ```
 
 ---

package/dist/index.d.mts

@@ -1,3 +1,52 @@
+/**
+ * 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.
  *
@@ -131,6 +180,34 @@ interface TuvlClientOptions {
     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`.
  */
@@ -147,6 +224,83 @@ declare class TuvlWorkflowSuspendedError extends Error {
     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.
  *
@@ -229,6 +383,34 @@ declare class TuvlClient {
     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>;
 }
 
 /**
@@ -384,43 +566,4 @@ interface GrpcRunOptions {
  */
 declare function openGrpcStream(options: GrpcRunOptions): AsyncGenerator<GrpcStepEvent>;
 
-/**
- * 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>;
-}
-
-export { type BootstrapRequest, 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 };
+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 };

package/dist/index.d.ts

@@ -1,3 +1,52 @@
+/**
+ * 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.
  *
@@ -131,6 +180,34 @@ interface TuvlClientOptions {
     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`.
  */
@@ -147,6 +224,83 @@ declare class TuvlWorkflowSuspendedError extends Error {
     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.
  *
@@ -229,6 +383,34 @@ declare class TuvlClient {
     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>;
 }
 
 /**
@@ -384,43 +566,4 @@ interface GrpcRunOptions {
  */
 declare function openGrpcStream(options: GrpcRunOptions): AsyncGenerator<GrpcStepEvent>;
 
-/**
- * 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>;
-}
-
-export { type BootstrapRequest, 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 };
+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 };