@blokjs/client 0.6.17 → 0.6.19

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@blokjs/client",
-	"version": "0.6.17",
+	"version": "0.6.19",
+	"files": ["dist"],
 	"description": "Fully-typed, tRPC-style client SDK for calling Blok workflows from a frontend.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -15,7 +16,7 @@
 	"author": "Deskree Inc",
 	"license": "MIT",
 	"peerDependencies": {
-		"@blokjs/helper": "^0.6.17"
+		"@blokjs/helper": "^0.6.19"
 	},
 	"peerDependenciesMeta": {
 		"@blokjs/helper": {
@@ -23,7 +24,7 @@
 		}
 	},
 	"devDependencies": {
-		"@blokjs/helper": "^0.6.17",
+		"@blokjs/helper": "^0.6.19",
 		"@types/node": "^22.15.21",
 		"typescript": "^5.8.3",
 		"vitest": "^4.0.18",

package/src/index.ts

@@ -1,236 +0,0 @@
-/**
- * `@blokjs/client` — a fully-typed, tRPC-style client for calling Blok
- * workflows from a frontend.
- *
- * The client is **inference-based**: it imports the server's generated
- * `BlokApp` type (`blokctl gen app-types`) and maps every workflow to a typed
- * call. There is no generated runtime code — a single `Proxy` turns the access
- * path (`blok.users.list`) into the workflow name (`"users.list"`) and POSTs it
- * to the name-keyed RPC mount (`/__blok/rpc/:name`).
- *
- * @example
- *   import { createBlokClient } from "@blokjs/client";
- *   import type { BlokApp } from "./blok-app";       // generated, types only
- *
- *   const blok = createBlokClient<BlokApp>({ baseUrl: "/", headers: () => ({ Authorization: `Bearer ${token()}` }) });
- *   const { users, total } = await blok.users.list({ q: "ada" });   // typed both ways
- *
- * Unary (typed CRUD) and **streaming** (`.stream(input)` → a typed event union
- * over SSE) are both supported. TanStack-Query hooks land in a later phase
- * (see SPEC-blok-client-sdk.md).
- */
-
-import type { TypedWorkflow } from "@blokjs/helper";
-
-/** Configuration for {@link createBlokClient}. */
-export interface BlokClientConfig {
-	/**
-	 * Base URL the RPC mount is served from. Defaults to "" (same-origin
-	 * relative — `"/__blok/rpc/:name"`). Set to e.g. `"https://api.example.com"`
-	 * for a cross-origin backend. A trailing slash is trimmed.
-	 */
-	baseUrl?: string;
-	/**
-	 * Per-request header factory — called before each call so you can return a
-	 * fresh auth token. May be sync or async.
-	 */
-	headers?: () => Record<string, string> | Promise<Record<string, string>>;
-	/**
-	 * `fetch` implementation. Defaults to the global `fetch`. Inject for
-	 * SSR / tests / a custom runtime, or to add interceptors.
-	 */
-	fetch?: typeof fetch;
-}
-
-/** A typed unary call: `(input) => Promise<output>`. */
-export type UnaryCall<I, O> = (input: I) => Promise<O>;
-
-/**
- * A typed streaming call: `.stream(input)` yields the workflow's declared event
- * union (`{ type: "progress"; data: {…} } | …`). Driven by the name-keyed RPC
- * mount with `Accept: text/event-stream`.
- */
-export interface StreamCall<I, E> {
-	stream(input: I): AsyncIterable<E>;
-}
-
-/**
- * Maps a generated `BlokApp` tree to the client's call surface: each
- * {@link TypedWorkflow} leaf becomes a typed {@link UnaryCall} (no declared
- * events) or a {@link StreamCall} (declared `events`); nested groups recurse.
- */
-export type BlokClient<T> = {
-	[K in keyof T]: T[K] extends TypedWorkflow<infer I, infer O, infer E>
-		? [E] extends [never]
-			? UnaryCall<I, O>
-			: StreamCall<I, E>
-		: T[K] extends object
-			? BlokClient<T[K]>
-			: never;
-};
-
-/** Thrown when an RPC call returns a non-2xx status. Carries the parsed body. */
-export class BlokClientError extends Error {
-	readonly status: number;
-	readonly body: unknown;
-	readonly workflow: string;
-	constructor(status: number, body: unknown, workflow: string) {
-		super(`Blok RPC "${workflow}" failed with status ${status}`);
-		this.name = "BlokClientError";
-		this.status = status;
-		this.body = body;
-		this.workflow = workflow;
-	}
-}
-
-// Property keys that must NOT be treated as workflow-path segments — otherwise
-// `await blok.users` (thenable probe) or a structured-clone symbol probe would
-// be misread as a `.then`/symbol workflow name and break promise semantics.
-const PASSTHROUGH_KEYS = new Set<string>(["then", "catch", "finally"]);
-
-// Reserved leaf method names. `blok.<path>.stream(input)` opens a streaming
-// call rather than descending into a workflow group literally named "stream".
-const STREAM_METHOD = "stream";
-
-function NOOP(): void {
-	/* Proxy target must be callable so the `apply` trap fires. */
-}
-
-function safeJsonParse(raw: string): unknown {
-	if (raw === "") return undefined;
-	try {
-		return JSON.parse(raw);
-	} catch {
-		// A non-JSON `data:` payload is a valid SSE frame — surface it verbatim
-		// rather than dropping it (the client's "loud, never swallow" contract).
-		return raw;
-	}
-}
-
-/**
- * Spec-correct SSE frame parser over a `fetch` response body. Handles `event:`,
- * multi-line `data:`, `id:`, `:` comments (keep-alives), CRLF/CR/LF line
- * endings, and a trailing event with no final blank line. Yields one
- * `{ event, data, id }` per dispatched frame.
- */
-async function* parseSSE(
-	stream: ReadableStream<Uint8Array>,
-): AsyncGenerator<{ event: string; data: string; id?: string }> {
-	const reader = stream.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	let event = "";
-	let data: string[] = [];
-	let id: string | undefined;
-
-	type Frame = { event: string; data: string; id?: string };
-	// Apply one line of the SSE stream. Returns a dispatched frame on a blank
-	// line (end-of-event), else null while accumulating fields.
-	const handleLine = (raw: string): Frame | null => {
-		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
-		if (line === "") {
-			if (data.length === 0 && event === "") return null;
-			const frame: Frame = { event: event || "message", data: data.join("\n"), id };
-			event = "";
-			data = [];
-			id = undefined;
-			return frame;
-		}
-		if (line.startsWith(":")) return null; // comment / keep-alive
-		const colon = line.indexOf(":");
-		const field = colon === -1 ? line : line.slice(0, colon);
-		let val = colon === -1 ? "" : line.slice(colon + 1);
-		if (val.startsWith(" ")) val = val.slice(1);
-		if (field === "event") event = val;
-		else if (field === "data") data.push(val);
-		else if (field === "id") id = val;
-		// `retry:` is ignored — the client doesn't auto-reconnect (P3).
-		return null;
-	};
-
-	try {
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n");
-			buffer = lines.pop() ?? ""; // last (possibly partial) line stays buffered
-			for (const raw of lines) {
-				const frame = handleLine(raw);
-				if (frame) yield frame;
-			}
-		}
-		// Drain a final complete-but-unterminated line, then flush a trailing
-		// frame that wasn't closed by a blank line.
-		if (buffer !== "") {
-			const frame = handleLine(buffer);
-			if (frame) yield frame;
-		}
-		if (data.length > 0 || event !== "") yield { event: event || "message", data: data.join("\n"), id };
-	} finally {
-		reader.releaseLock();
-	}
-}
-
-/**
- * Create a typed Blok client. Pass the generated `BlokApp` type as the type
- * argument; the returned object's shape is inferred entirely from it.
- */
-export function createBlokClient<TApp>(config: BlokClientConfig = {}): BlokClient<TApp> {
-	const baseUrl = (config.baseUrl ?? "").replace(/\/+$/, "");
-	const doFetch = config.fetch ?? globalThis.fetch;
-	if (typeof doFetch !== "function") {
-		throw new Error(
-			"createBlokClient: no `fetch` available. Pass `fetch` in the config (e.g. on Node < 18 or a custom runtime).",
-		);
-	}
-
-	async function unaryCall(name: string, input: unknown): Promise<unknown> {
-		const extra = config.headers ? await config.headers() : {};
-		const res = await doFetch(`${baseUrl}/__blok/rpc/${name}`, {
-			method: "POST",
-			headers: { "content-type": "application/json", ...extra },
-			body: JSON.stringify(input ?? {}),
-		});
-		const contentType = res.headers.get("content-type") ?? "";
-		const payload: unknown = contentType.includes("application/json") ? await res.json() : await res.text();
-		if (!res.ok) throw new BlokClientError(res.status, payload, name);
-		return payload;
-	}
-
-	async function* streamCall(name: string, input: unknown): AsyncGenerator<{ type: string; data: unknown }> {
-		const extra = config.headers ? await config.headers() : {};
-		const res = await doFetch(`${baseUrl}/__blok/rpc/${name}`, {
-			method: "POST",
-			headers: { "content-type": "application/json", accept: "text/event-stream", ...extra },
-			body: JSON.stringify(input ?? {}),
-		});
-		if (!res.ok) {
-			const ct = res.headers.get("content-type") ?? "";
-			const body: unknown = ct.includes("application/json") ? await res.json() : await res.text();
-			throw new BlokClientError(res.status, body, name);
-		}
-		if (!res.body) {
-			throw new Error(`Blok stream "${name}": the response has no readable body (no ReadableStream).`);
-		}
-		for await (const frame of parseSSE(res.body)) {
-			yield { type: frame.event, data: safeJsonParse(frame.data) };
-		}
-	}
-
-	const build = (path: readonly string[]): unknown =>
-		new Proxy(NOOP, {
-			get(_target, key) {
-				if (typeof key !== "string" || PASSTHROUGH_KEYS.has(key)) return undefined;
-				// `.stream(input)` is a streaming call on the workflow at `path`,
-				// not a descent into a group named "stream".
-				if (key === STREAM_METHOD) return (input: unknown) => streamCall(path.join("."), input);
-				return build([...path, key]);
-			},
-			apply(_target, _thisArg, args: unknown[]) {
-				return unaryCall(path.join("."), args[0]);
-			},
-		});
-
-	return build([]) as BlokClient<TApp>;
-}

package/tests/client.test.ts

@@ -1,126 +0,0 @@
-import type { TypedWorkflow } from "@blokjs/helper";
-import { describe, expect, it, vi } from "vitest";
-import { type BlokClient, BlokClientError, createBlokClient } from "../src/index";
-
-/** A representative generated `BlokApp` type (what `blokctl gen app-types` emits). */
-type App = {
-	users: {
-		list: TypedWorkflow<{ q?: string }, { users: string[]; total: number }>;
-		create: TypedWorkflow<{ name: string }, { id: string }>;
-	};
-	health: TypedWorkflow<Record<string, never>, { ok: boolean }>;
-};
-
-/** Build a fetch mock that returns `body` as JSON with `status`. */
-function jsonFetch(status: number, body: unknown, capture?: (url: string, init: RequestInit) => void) {
-	return vi.fn(async (url: string | URL, init?: RequestInit) => {
-		capture?.(String(url), init ?? {});
-		return new Response(JSON.stringify(body), {
-			status,
-			headers: { "content-type": "application/json" },
-		});
-	}) as unknown as typeof fetch;
-}
-
-describe("createBlokClient — unary (P1.4)", () => {
-	it("POSTs to /__blok/rpc/<dotted-name> with the input as the JSON body and returns parsed output", async () => {
-		let seenUrl = "";
-		let seenInit: RequestInit = {};
-		const fetchMock = jsonFetch(200, { users: ["ada"], total: 1 }, (u, i) => {
-			seenUrl = u;
-			seenInit = i;
-		});
-		const blok = createBlokClient<App>({ baseUrl: "https://api.test", fetch: fetchMock });
-
-		const out = await blok.users.list({ q: "ada" });
-
-		expect(seenUrl).toBe("https://api.test/__blok/rpc/users.list");
-		expect(seenInit.method).toBe("POST");
-		expect(JSON.parse(seenInit.body as string)).toEqual({ q: "ada" });
-		expect(out).toEqual({ users: ["ada"], total: 1 });
-	});
-
-	it("trims a trailing slash from baseUrl and supports same-origin ('' base)", async () => {
-		let seenUrl = "";
-		const fetchMock = jsonFetch(200, { ok: true }, (u) => {
-			seenUrl = u;
-		});
-		const blok = createBlokClient<App>({ baseUrl: "https://api.test/", fetch: fetchMock });
-		await blok.health({});
-		expect(seenUrl).toBe("https://api.test/__blok/rpc/health");
-
-		let relUrl = "";
-		const relClient = createBlokClient<App>({
-			fetch: jsonFetch(200, { ok: true }, (u) => {
-				relUrl = u;
-			}),
-		});
-		await relClient.health({});
-		expect(relUrl).toBe("/__blok/rpc/health");
-	});
-
-	it("sends headers from the (async) headers() factory on every call", async () => {
-		const headers: Record<string, string>[] = [];
-		const fetchMock = vi.fn(async (_u: string | URL, init?: RequestInit) => {
-			headers.push(init?.headers as Record<string, string>);
-			return new Response("{}", { status: 200, headers: { "content-type": "application/json" } });
-		}) as unknown as typeof fetch;
-		let token = "t1";
-		const blok = createBlokClient<App>({
-			fetch: fetchMock,
-			headers: async () => ({ Authorization: `Bearer ${token}` }),
-		});
-
-		await blok.users.create({ name: "ada" });
-		token = "t2";
-		await blok.users.create({ name: "bob" });
-
-		expect(headers[0].Authorization).toBe("Bearer t1");
-		expect(headers[1].Authorization).toBe("Bearer t2");
-		// content-type is always set; the factory merges over the defaults.
-		expect(headers[0]["content-type"]).toBe("application/json");
-	});
-
-	it("throws BlokClientError with status + parsed body on a non-2xx response", async () => {
-		const fetchMock = jsonFetch(422, { error: "invalid" });
-		const blok = createBlokClient<App>({ fetch: fetchMock });
-
-		await expect(blok.users.create({ name: "" })).rejects.toMatchObject({
-			name: "BlokClientError",
-			status: 422,
-			workflow: "users.create",
-			body: { error: "invalid" },
-		});
-		expect(new BlokClientError(404, null, "x")).toBeInstanceOf(Error);
-	});
-
-	it("resolves nested group paths into dotted names (a.b.c)", async () => {
-		type Deep = { a: { b: { c: TypedWorkflow<{ n: number }, { doubled: number }> } } };
-		let seenUrl = "";
-		const fetchMock = jsonFetch(200, { doubled: 4 }, (u) => {
-			seenUrl = u;
-		});
-		const blok = createBlokClient<Deep>({ baseUrl: "http://x", fetch: fetchMock });
-		const out = await blok.a.b.c({ n: 2 });
-		expect(seenUrl).toBe("http://x/__blok/rpc/a.b.c");
-		expect(out).toEqual({ doubled: 4 });
-	});
-
-	it("does not pretend to be a thenable (awaiting a group node does not hang)", async () => {
-		const blok = createBlokClient<App>({ fetch: jsonFetch(200, {}) });
-		// `then` resolves to undefined on the proxy → not a thenable → this awaits
-		// the proxy object itself, not an infinite chain.
-		const usersGroup = blok.users as unknown as { then?: unknown };
-		expect(usersGroup.then).toBeUndefined();
-	});
-
-	it("infers the typed return (compile-time intent)", async () => {
-		const blok: BlokClient<App> = createBlokClient<App>({ fetch: jsonFetch(200, { users: [], total: 0 }) });
-		const out = await blok.users.list({ q: "x" });
-		// `out` is typed { users: string[]; total: number }
-		const total: number = out.total;
-		const first: string | undefined = out.users[0];
-		expect(total).toBe(0);
-		expect(first).toBeUndefined();
-	});
-});

package/tests/streaming.test.ts

@@ -1,105 +0,0 @@
-import type { TypedWorkflow } from "@blokjs/helper";
-import { describe, expect, it, vi } from "vitest";
-import { createBlokClient } from "../src/index";
-
-/** A streaming workflow's declared event union (TypedWorkflow's 3rd param). */
-type JobEvent =
-	| { type: "progress"; data: { pct: number } }
-	| { type: "log"; data: { line: string } }
-	| { type: "done"; data: { ok: boolean } };
-
-type StreamApp = {
-	jobs: { watch: TypedWorkflow<{ jobId: string }, unknown, JobEvent> };
-};
-
-/** Build a 200 text/event-stream Response whose body emits `chunks` in order. */
-function sseResponse(chunks: string[], status = 200): Response {
-	const enc = new TextEncoder();
-	const body = new ReadableStream<Uint8Array>({
-		start(controller) {
-			for (const c of chunks) controller.enqueue(enc.encode(c));
-			controller.close();
-		},
-	});
-	return new Response(body, { status, headers: { "content-type": "text/event-stream" } });
-}
-
-describe("@blokjs/client — streaming via .stream() (P3.1)", () => {
-	it("POSTs with Accept: text/event-stream and yields the typed event union", async () => {
-		let seenUrl = "";
-		let seenAccept = "";
-		const fetchMock = vi.fn(async (url: string | URL, init?: RequestInit) => {
-			seenUrl = String(url);
-			seenAccept = (init?.headers as Record<string, string>).accept;
-			return sseResponse([
-				'event: progress\ndata: {"pct":10}\n\n',
-				'event: progress\ndata: {"pct":100}\n\n',
-				'event: done\ndata: {"ok":true}\n\n',
-			]);
-		}) as unknown as typeof fetch;
-		const blok = createBlokClient<StreamApp>({ baseUrl: "https://api.test", fetch: fetchMock });
-
-		const got: JobEvent[] = [];
-		for await (const ev of blok.jobs.watch.stream({ jobId: "j1" })) got.push(ev);
-
-		expect(seenUrl).toBe("https://api.test/__blok/rpc/jobs.watch");
-		expect(seenAccept).toBe("text/event-stream");
-		expect(got).toEqual([
-			{ type: "progress", data: { pct: 10 } },
-			{ type: "progress", data: { pct: 100 } },
-			{ type: "done", data: { ok: true } },
-		]);
-	});
-
-	it("reassembles frames split arbitrarily across network chunks", async () => {
-		// One frame's bytes arrive in 3 separate reads; another spans a boundary.
-		const fetchMock = vi.fn(async () =>
-			sseResponse(["event: prog", 'ress\ndata: {"pct":', "42}\n\nevent: done\nda", 'ta: {"ok":true}\n\n']),
-		) as unknown as typeof fetch;
-		const blok = createBlokClient<StreamApp>({ fetch: fetchMock });
-
-		const got: JobEvent[] = [];
-		for await (const ev of blok.jobs.watch.stream({ jobId: "j" })) got.push(ev);
-		expect(got).toEqual([
-			{ type: "progress", data: { pct: 42 } },
-			{ type: "done", data: { ok: true } },
-		]);
-	});
-
-	it("skips `:` keep-alive comments and joins multi-line data", async () => {
-		const fetchMock = vi.fn(async () =>
-			sseResponse([": keep-alive\n\n", "event: log\ndata: line one\ndata: line two\n\n"]),
-		) as unknown as typeof fetch;
-		const blok = createBlokClient<StreamApp>({ fetch: fetchMock });
-
-		const got: JobEvent[] = [];
-		for await (const ev of blok.jobs.watch.stream({ jobId: "j" })) got.push(ev);
-		// data is non-JSON here → surfaced verbatim (joined with \n), never dropped.
-		expect(got).toEqual([{ type: "log", data: "line one\nline two" }]);
-	});
-
-	it("flushes a trailing frame with no final blank line", async () => {
-		const fetchMock = vi.fn(async () => sseResponse(['event: done\ndata: {"ok":true}'])) as unknown as typeof fetch;
-		const blok = createBlokClient<StreamApp>({ fetch: fetchMock });
-		const got: JobEvent[] = [];
-		for await (const ev of blok.jobs.watch.stream({ jobId: "j" })) got.push(ev);
-		expect(got).toEqual([{ type: "done", data: { ok: true } }]);
-	});
-
-	it("throws BlokClientError on a non-2xx stream response", async () => {
-		const fetchMock = vi.fn(
-			async () =>
-				new Response(JSON.stringify({ error: "nope" }), {
-					status: 403,
-					headers: { "content-type": "application/json" },
-				}),
-		) as unknown as typeof fetch;
-		const blok = createBlokClient<StreamApp>({ fetch: fetchMock });
-
-		await expect(async () => {
-			for await (const _ of blok.jobs.watch.stream({ jobId: "j" })) {
-				/* should throw before yielding */
-			}
-		}).rejects.toMatchObject({ name: "BlokClientError", status: 403, body: { error: "nope" } });
-	});
-});

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "es2022",
-		"module": "es2022",
-		"moduleResolution": "bundler",
-		"lib": ["es2022", "dom"],
-		"rootDir": "./src",
-		"declaration": true,
-		"sourceMap": true,
-		"outDir": "./dist",
-		"esModuleInterop": true,
-		"forceConsistentCasingInFileNames": true,
-		"strict": true,
-		"noUnusedLocals": true,
-		"noImplicitReturns": true,
-		"skipLibCheck": true
-	},
-	"compileOnSave": true,
-	"include": ["./src"]
-}