@jigs.design/client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @jigs.design/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`createPickleClient` is the browser's connection to a Pickle server: the transport and the query cache, on TanStack Query Core. It has no React and no schema library.
+
+```ts
+import { createPickleClient } from "@jigs.design/client";
+
+export const client = createPickleClient({ endpoint: "/api/pickle" });
+```
+
+Create one client per app, in its own module. Every view and session that imports it shares one query cache, so two views reading the same query make one request, and a mutation's invalidations reach both. The client retries network failures, aborts a query's request when nothing reads it any more, and refreshes the queries a mutation invalidates.
+
+## Exports
+
+| Export               | What it is                                                       |
+| -------------------- | ---------------------------------------------------------------- |
+| `createPickleClient` | The client, with `observe`, `mutate`, `invalidate` and `session` |
+
+The view calls `observe` and `mutate`; app code calls `invalidate`. `mutate(name, input, procedure)` takes the procedure's `kind` and `invalidates` from the program, and every call goes out with its `kind`, which the server checks against the host.
+| `httpTransport`, `Transport` | The default HTTP transport, and the type to implement your own |
+| `TransportError` | What a transport rejects with: `{ code, message }` |
+
+It re-exports the shared types from `@jigs.design/runtime`.
+
+## Source
+
+- `src/client.ts`: the client and its query cache.
+- `src/transport.ts`: the transport contract and the HTTP transport.
+
+## Docs
+
+[Transport](../../apps/docs/docs/running/transport.mdx) and [Session](../../apps/docs/docs/running/session.mdx).

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+import { HeadersOption, Transport } from "./transport.js";
+import { Message, MutationResult, QueryResult, SessionEvent, SessionOptions } from "@jigs.design/runtime";
+//#region src/client.d.ts
+interface CacheOptions {
+  /**
+   * How long a query result stays fresh, in milliseconds. A fresh result is
+   * reused by a new view, so two blocks or two turns that read the same
+   * query share one call; a stale one refetches when a view reads it again.
+   * `invalidates` and `invalidate` refetch at any age. Default 60,000: a
+   * minute, so a long session does not show hour-old data.
+   */
+  staleTime?: number;
+}
+/**
+ * What the page asks the user before a mutation whose policy is "confirm"
+ * runs. `message` is the host's text, never the model's; `input` is what
+ * the program sent. Resolve true to run the mutation. `signal` aborts when
+ * the view that called the mutation stops or loads another document: close
+ * the question then, since the mutation has already failed as `DECLINED`.
+ */
+export type ConfirmFunction = (request: {
+  input: unknown;
+  message: string;
+  name: string;
+  signal: AbortSignal;
+}) => Promise<boolean>;
+interface ConfirmOptions {
+  /**
+   * Asks the user to approve a mutation whose policy is "confirm", in the
+   * page's own UI, outside the sandbox. Without it, or when it resolves
+   * false or throws, the mutation fails with `DECLINED`. A `PickleView`'s
+   * `onConfirm` takes its place for that view.
+   */
+  confirm?: ConfirmFunction;
+}
+export type ClientOptions = CacheOptions & ConfirmOptions & ({
+  credentials?: RequestCredentials;
+  endpoint: string;
+  fetch?: typeof fetch;
+  headers?: HeadersOption;
+  transport?: never;
+} | {
+  credentials?: never;
+  endpoint?: never;
+  fetch?: never;
+  headers?: never;
+  transport: Transport;
+});
+export interface PickleClient {
+  /** URL of the sandbox frame document. */
+  readonly frame: string;
+  /** Refetches every query with this name, for every input. */
+  invalidate: (name: string) => Promise<void>;
+  /**
+   * Runs one mutation or action and, when it succeeds, refetches the
+   * queries the server says it refreshed. A reply without that list
+   * refetches every input of each query in `invalidates`. `kind` goes to
+   * the server, which refuses a call whose kind is not the procedure's.
+   * When the server asks for confirmation, `procedure.confirm` (else the
+   * client's `confirm`) asks the user, and the call goes again with the
+   * server's token only if they approve before `procedure.signal` aborts.
+   * The signal only withdraws the question: a call already sent is not
+   * cancelled, since the server may have run it.
+   */
+  mutate: (name: string, input: unknown, procedure: {
+    confirm?: ConfirmFunction | undefined;
+    invalidates: ReadonlyArray<string>;
+    kind: "action" | "mutation";
+    signal?: AbortSignal | undefined;
+  }) => Promise<MutationResult>;
+  /**
+   * Keeps one query subscribed and reports every result. Unsubscribing
+   * aborts its request when nothing else reads it. The call goes out with
+   * `kind: "query"`.
+   */
+  observe: (name: string, input: unknown, listener: (result: QueryResult) => void) => () => void;
+  /** One turn, as session events. */
+  session: (body: {
+    messages: ReadonlyArray<Message>;
+    options?: SessionOptions;
+  }, options: {
+    signal: AbortSignal;
+  }) => AsyncIterable<SessionEvent>;
+}
+/**
+ * The browser's connection to a Pickle server. Create one per app, in its
+ * own module: each client has its own query cache, so two clients share no
+ * requests and no invalidations.
+ */
+export declare function createPickleClient(options: ClientOptions): PickleClient;
+//#endregion
+export {};

package/dist/client.js

@@ -0,0 +1,159 @@
+import { TransportError, errorDataOf, httpTransport } from "./transport.js";
+import { QueryClient, QueryObserver } from "@tanstack/query-core";
+//#region src/client.ts
+/** How long a query result stays fresh by default: a minute. */
+const DEFAULT_STALE_TIME = 6e4;
+const RETRYABLE = /* @__PURE__ */ new Set(["NETWORK", "UNAVAILABLE"]);
+const MAX_RETRIES = 2;
+function toQueryResult(result) {
+	if (result.status === "success") return {
+		data: result.data,
+		error: null,
+		status: "success"
+	};
+	if (result.status === "error") return {
+		data: null,
+		error: errorDataOf(result.error),
+		status: "error"
+	};
+	return {
+		data: null,
+		error: null,
+		status: "pending"
+	};
+}
+/**
+* The browser's connection to a Pickle server. Create one per app, in its
+* own module: each client has its own query cache, so two clients share no
+* requests and no invalidations.
+*/
+function createPickleClient(options) {
+	const transport = options.transport === void 0 ? httpTransport(httpOptions(options)) : options.transport;
+	const queries = new QueryClient({ defaultOptions: {
+		mutations: { retry: false },
+		queries: {
+			gcTime: 3e5,
+			refetchOnReconnect: false,
+			refetchOnWindowFocus: false,
+			retry: (failures, error) => failures < MAX_RETRIES && RETRYABLE.has(errorDataOf(error).code),
+			staleTime: options.staleTime ?? DEFAULT_STALE_TIME
+		}
+	} });
+	return {
+		frame: transport.frame,
+		invalidate: (name) => queries.invalidateQueries({ queryKey: [name] }),
+		mutate: async (name, input, procedure) => {
+			const send = async (confirmation) => {
+				try {
+					return await transport.call(confirmation === void 0 ? {
+						input,
+						kind: procedure.kind,
+						name
+					} : {
+						confirmation,
+						input,
+						kind: procedure.kind,
+						name
+					}, { signal: new AbortController().signal });
+				} catch (error) {
+					return { error: errorDataOf(error) };
+				}
+			};
+			let reply = await send();
+			if ("requiresAction" in reply) {
+				const declined = await askToConfirm(procedure.confirm ?? options.confirm, {
+					input,
+					message: reply.requiresAction.message,
+					name,
+					signal: procedure.signal ?? new AbortController().signal
+				});
+				if (declined !== null) return {
+					error: declined,
+					status: "error"
+				};
+				reply = await send(reply.requiresAction.token);
+			}
+			if ("error" in reply) return {
+				error: reply.error,
+				status: "error"
+			};
+			if ("requiresAction" in reply) return {
+				error: unconfirmed,
+				status: "error"
+			};
+			const targets = reply.invalidate ?? procedure.invalidates.map((target) => ({ name: target }));
+			for (const target of targets) queries.invalidateQueries({ queryKey: target.input === void 0 ? [target.name] : [target.name, target.input] });
+			return {
+				data: reply.data,
+				status: "success"
+			};
+		},
+		observe: (name, input, listener) => {
+			const observer = new QueryObserver(queries, {
+				queryFn: async (context) => {
+					const reply = await transport.call({
+						input,
+						kind: "query",
+						name
+					}, { signal: context.signal });
+					if ("requiresAction" in reply) throw new TransportError(unconfirmed);
+					return reply.data;
+				},
+				queryKey: [name, input]
+			});
+			const unsubscribe = observer.subscribe((result) => {
+				listener(toQueryResult(result));
+			});
+			listener(toQueryResult(observer.getCurrentResult()));
+			return unsubscribe;
+		},
+		session: (body, sessionOptions) => transport.session(body, sessionOptions)
+	};
+}
+const unconfirmed = {
+	code: "FORBIDDEN",
+	message: "The server asked for a confirmation the call cannot give."
+};
+/**
+* Asks the user through `confirm`. Null when they approved before
+* `request.signal` aborted; otherwise the `DECLINED` error the mutation fails
+* with, which says why. An abort settles it even if `confirm` never does.
+*/
+async function askToConfirm(confirm, request) {
+	if (confirm === void 0) return {
+		code: "DECLINED",
+		message: `"${request.name}" needs the user's confirmation, and this page cannot ask for it.`
+	};
+	const withdrawn = {
+		code: "DECLINED",
+		message: `The confirmation for "${request.name}" was withdrawn before the user answered.`
+	};
+	if (request.signal.aborted) return withdrawn;
+	const aborted = Promise.withResolvers();
+	const onAbort = () => aborted.resolve(false);
+	request.signal.addEventListener("abort", onAbort, { once: true });
+	let answer;
+	try {
+		answer = await Promise.race([confirm(request), aborted.promise]) === true ? null : {
+			code: "DECLINED",
+			message: "The user declined."
+		};
+	} catch (error) {
+		answer = {
+			code: "DECLINED",
+			message: `The confirmation for "${request.name}" failed: ${error instanceof Error ? error.message : String(error)}`
+		};
+	} finally {
+		request.signal.removeEventListener("abort", onAbort);
+	}
+	return request.signal.aborted ? withdrawn : answer;
+}
+function httpOptions(options) {
+	const http = { endpoint: options.endpoint };
+	if (options.credentials !== void 0) http.credentials = options.credentials;
+	if (options.fetch !== void 0) http.fetch = options.fetch;
+	if (options.headers !== void 0) http.headers = options.headers;
+	return http;
+}
+//#endregion
+export { createPickleClient };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { CallReply, HeadersOption, HttpTransportOptions, Transport, TransportError, httpTransport } from "./transport.js";
+import { ClientOptions, ConfirmFunction, PickleClient, createPickleClient } from "./client.js";
+import { Diagnostic, Invalidation, Message, PickleErrorCode, PickleErrorData, Program, SessionEvent, Span } from "@jigs.design/runtime";
+export { type CallReply, type ClientOptions, type ConfirmFunction, type Diagnostic, type HeadersOption, type HttpTransportOptions, type Invalidation, type Message, type PickleClient, type PickleErrorCode, type PickleErrorData, type Program, type SessionEvent, type Span, type Transport, TransportError, createPickleClient, httpTransport };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { TransportError, httpTransport } from "./transport.js";
+import { createPickleClient } from "./client.js";
+export { TransportError, createPickleClient, httpTransport };

package/dist/transport.d.ts

@@ -0,0 +1,60 @@
+import { Invalidation, Message, PickleErrorCode, PickleErrorData, ProcedureKind, SessionEvent, SessionOptions } from "@jigs.design/runtime";
+//#region src/transport.d.ts
+/**
+ * A call's reply: the procedure's data and, for a mutation, the queries the
+ * server says it refreshed. Without `invalidate`, the client refreshes every
+ * input of each query in the program's `invalidates` list. A mutation whose
+ * policy is "confirm" first replies with `requiresAction` instead, and has
+ * not run.
+ */
+export type CallReply = {
+  data: unknown;
+  invalidate?: ReadonlyArray<Invalidation>;
+} | {
+  requiresAction: {
+    message: string;
+    token: string;
+  };
+};
+/** How the browser reaches the server. Implement it to host Pickle behind another router. */
+export interface Transport {
+  /**
+   * Resolves with the reply, or rejects with a `TransportError`. `kind` is
+   * the procedure's kind in the program; send it on, since the server
+   * refuses a call without it or with the wrong one.
+   */
+  call: (request: {
+    /** The token from a `requiresAction` reply, once the user approved. */
+    confirmation?: string;
+    input: unknown;
+    kind: ProcedureKind;
+    name: string;
+  }, options: {
+    signal: AbortSignal;
+  }) => Promise<CallReply>;
+  /** URL of the sandbox frame document. */
+  frame: string;
+  /** Reports every failure as one `error` event and then ends; never throws. */
+  session: (body: {
+    messages: ReadonlyArray<Message>;
+    options?: SessionOptions;
+  }, options: {
+    signal: AbortSignal;
+  }) => AsyncIterable<SessionEvent>;
+}
+/** A failure with a code the spec can read. */
+export declare class TransportError extends Error implements PickleErrorData {
+  readonly code: PickleErrorCode;
+  constructor(data: PickleErrorData);
+}
+export type HeadersOption = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export interface HttpTransportOptions {
+  credentials?: RequestCredentials;
+  /** Path or URL where `pickle.handler` is mounted. */
+  endpoint: string;
+  fetch?: typeof fetch;
+  headers?: HeadersOption;
+}
+/** The default transport: `fetch` against `pickle.handler`. */
+export declare function httpTransport(options: HttpTransportOptions): Transport;
+//#endregion

package/dist/transport.js

@@ -0,0 +1,197 @@
+import { parseErrorData, parseInvalidations, parseSessionEvent } from "@jigs.design/runtime";
+//#region src/transport.ts
+/** A failure with a code the spec can read. */
+var TransportError = class extends Error {
+	code;
+	constructor(data) {
+		super(data.message);
+		this.code = data.code;
+		this.name = "TransportError";
+	}
+};
+const VERSION_HEADER = "pickle-version";
+const GATEWAY_STATUSES = /* @__PURE__ */ new Set([
+	502,
+	503,
+	504
+]);
+const unavailable = {
+	code: "UNAVAILABLE",
+	message: "The server is not available right now."
+};
+const network = {
+	code: "NETWORK",
+	message: "Could not reach the server."
+};
+/** The error a reply carries, or `UNAVAILABLE` when the reply is not one of Pickle's. */
+async function replyError(response) {
+	if (GATEWAY_STATUSES.has(response.status) || !response.headers.has(VERSION_HEADER)) return unavailable;
+	try {
+		const body = await response.json();
+		return (typeof body === "object" && body !== null && "error" in body ? parseErrorData(body.error) : null) ?? unavailable;
+	} catch {
+		return unavailable;
+	}
+}
+/** Why the `headers` function failed, as the call's error. */
+function headersError(cause) {
+	return thrownErrorData(cause) ?? {
+		code: "UNAUTHORIZED",
+		message: `The request headers could not be built: ${cause instanceof Error ? cause.message : String(cause)}`
+	};
+}
+/** The default transport: `fetch` against `pickle.handler`. */
+function httpTransport(options) {
+	const fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const credentials = options.credentials ?? "same-origin";
+	/**
+	* The request's headers. A `headers` function that throws, such as a
+	* token refresh that failed, is not a network failure: it keeps a thrown
+	* `{ code, message }` and is otherwise `UNAUTHORIZED`, never retried.
+	*/
+	const headers = async () => {
+		let extra;
+		try {
+			extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+		} catch (error) {
+			throw new TransportError(headersError(error));
+		}
+		const merged = new Headers(extra);
+		merged.set("content-type", "application/json");
+		return merged;
+	};
+	const post = (body, init, signal) => fetcher(options.endpoint, {
+		body,
+		credentials,
+		headers: init,
+		method: "POST",
+		signal
+	});
+	return {
+		async call(request, callOptions) {
+			const init = await headers();
+			let response;
+			try {
+				response = await post(JSON.stringify({
+					confirmation: request.confirmation,
+					input: request.input,
+					kind: request.kind,
+					name: request.name,
+					type: "call"
+				}), init, callOptions.signal);
+			} catch (error) {
+				if (callOptions.signal.aborted) throw error;
+				throw new TransportError(network);
+			}
+			if (!response.ok || !response.headers.has(VERSION_HEADER)) throw new TransportError(await replyError(response));
+			let body;
+			try {
+				body = await response.json();
+			} catch {
+				throw new TransportError(unavailable);
+			}
+			if (typeof body !== "object" || body === null) throw new TransportError(unavailable);
+			if ("requiresAction" in body) {
+				const requiresAction = parseRequiresAction(body.requiresAction);
+				if (requiresAction === null) throw new TransportError(unavailable);
+				return { requiresAction };
+			}
+			if (!("data" in body)) throw new TransportError(unavailable);
+			if (!("invalidate" in body)) return { data: body.data };
+			const invalidate = parseInvalidations(body.invalidate);
+			if (invalidate === null) throw new TransportError(unavailable);
+			return {
+				data: body.data,
+				invalidate
+			};
+		},
+		frame: options.endpoint,
+		async *session(body, { signal }) {
+			let init;
+			try {
+				init = await headers();
+			} catch (error) {
+				yield {
+					error: errorDataOf(error),
+					type: "error"
+				};
+				return;
+			}
+			let response;
+			try {
+				response = await post(JSON.stringify({
+					messages: body.messages,
+					options: body.options,
+					type: "session"
+				}), init, signal);
+			} catch {
+				if (!signal.aborted) yield {
+					error: network,
+					type: "error"
+				};
+				return;
+			}
+			if (!response.ok || !response.headers.has(VERSION_HEADER) || response.body === null) {
+				yield {
+					error: await replyError(response),
+					type: "error"
+				};
+				return;
+			}
+			const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+			let buffer = "";
+			let ended = false;
+			try {
+				for (;;) {
+					const chunk = await reader.read();
+					if (chunk.done) {
+						if (!ended && !signal.aborted) yield {
+							error: network,
+							type: "error"
+						};
+						return;
+					}
+					buffer += chunk.value;
+					let end = buffer.indexOf("\n\n");
+					while (end !== -1) {
+						const frame = buffer.slice(0, end);
+						buffer = buffer.slice(end + 2);
+						const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+						const event = data === "" ? null : parseSessionEvent(data);
+						if (event !== null) {
+							ended ||= event.type !== "program";
+							yield event;
+						}
+						end = buffer.indexOf("\n\n");
+					}
+				}
+			} catch {
+				if (!signal.aborted) yield {
+					error: network,
+					type: "error"
+				};
+			} finally {
+				reader.releaseLock();
+			}
+		}
+	};
+}
+function parseRequiresAction(value) {
+	return typeof value === "object" && value !== null && "message" in value && "token" in value && typeof value.message === "string" && typeof value.token === "string" ? {
+		message: value.message,
+		token: value.token
+	} : null;
+}
+/** The `{ code, message }` of anything a transport rejected with. */
+function errorDataOf(cause) {
+	return thrownErrorData(cause) ?? unavailable;
+}
+/** The `{ code, message }` that `cause` carries, or null. */
+function thrownErrorData(cause) {
+	return typeof cause === "object" && cause !== null ? parseErrorData({
+		code: "code" in cause ? cause.code : void 0,
+		message: "message" in cause ? cause.message : void 0
+	}) : null;
+}
+//#endregion
+export { TransportError, errorDataOf, httpTransport };

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@jigs.design/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "createPickleClient: the browser's transport and query cache. No React.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tanstack/query-core": "5.104.4",
+    "@jigs.design/runtime": "0.1.0"
+  }
 }