@leavepulse/control-sdk 0.3.31

package/runtime/oauth2.ts

@@ -0,0 +1,150 @@
+// LeavePulse SDK — OAuth2 authorization-code + PKCE facade for 3rd-party web
+// apps acting on behalf of a LeavePulse *user*.
+//
+// `buildAuthorizeUrl` is a pure helper: it mints a PKCE S256 pair and assembles
+// the authorize URL. The app sends the user to that URL; a **frontend** page
+// renders the visual consent (the SDK never drives a browser). After the
+// redirect-back with `?code=`, `exchangeCode` trades the code for tokens at
+// `/auth/oauth/token` (form-urlencoded) and returns an auto-refreshing
+// `OAuth2Credential`. The exchange is driven through the caller's transport,
+// so it works without the generated `auth.oauth2.*` methods existing yet.
+
+import { OAuth2Credential } from "./credentials";
+import type { Transport } from "./transport";
+
+/** Inputs for {@link buildAuthorizeUrl}. */
+export interface BuildAuthorizeUrlInit {
+	/** OAuth2 client id of the third-party app. */
+	clientId: string;
+	/** Redirect URI registered for the app (must match at exchange). */
+	redirectUri: string;
+	/** Requested scopes; joined with spaces per OAuth2. */
+	scope: string[];
+	/** Base URL of the authorize page (a frontend URL). */
+	authorizeBaseUrl: string;
+	/** CSRF/anti-forgery state; a random one is generated when omitted. */
+	state?: string;
+}
+
+/** Result of {@link buildAuthorizeUrl}: the URL to send the user to, plus the
+ * PKCE verifier and state the app must keep until {@link exchangeCode}. */
+export interface AuthorizeUrl {
+	/** The authorize URL to open in the frontend (visual consent). */
+	url: string;
+	/** PKCE `code_verifier` — keep secret, pass back to `exchangeCode`. */
+	codeVerifier: string;
+	/** The `state` echoed back on redirect — verify it matches. */
+	state: string;
+}
+
+/**
+ * Build an OAuth2 authorize URL with a fresh PKCE (S256) challenge. Pure (no
+ * network); runs anywhere Web Crypto is available. `response_type=code`,
+ * `code_challenge_method=S256`. Async because the S256 digest is async.
+ */
+export async function buildAuthorizeUrl(
+	init: BuildAuthorizeUrlInit,
+): Promise<AuthorizeUrl> {
+	const codeVerifier = randomUrlSafe(64);
+	const state = init.state ?? randomUrlSafe(32);
+	const codeChallenge = await s256Challenge(codeVerifier);
+
+	const params = new URLSearchParams({
+		response_type: "code",
+		client_id: init.clientId,
+		redirect_uri: init.redirectUri,
+		scope: init.scope.join(" "),
+		state,
+		code_challenge: codeChallenge,
+		code_challenge_method: "S256",
+	});
+	const base = init.authorizeBaseUrl.replace(/\/$/, "");
+	return { url: `${base}?${params.toString()}`, codeVerifier, state };
+}
+
+/** Inputs for {@link exchangeCode}. */
+export interface ExchangeCodeInit {
+	clientId: string;
+	/** Authorization code returned to the redirect URI. */
+	code: string;
+	/** Same redirect URI used to build the authorize URL. */
+	redirectUri: string;
+	/** The PKCE `code_verifier` from {@link buildAuthorizeUrl}. */
+	codeVerifier: string;
+}
+
+/** `/auth/oauth/token` response shape (wire snake_case). */
+interface TokenExchangeResponse {
+	access_token: string;
+	refresh_token?: string | null;
+	expires_in?: number | null;
+	token_type?: string | null;
+}
+
+/**
+ * Exchange an authorization code for tokens at `/auth/oauth/token`
+ * (form-urlencoded, `grant_type=authorization_code`) and return an
+ * auto-refreshing {@link OAuth2Credential}. Driven through the supplied
+ * `transport` (channel `auth`), so it does not depend on generated code.
+ */
+export async function exchangeCode(
+	init: ExchangeCodeInit,
+	transport: Transport,
+): Promise<OAuth2Credential> {
+	const tokens = await postToken(transport, {
+		grant_type: "authorization_code",
+		code: init.code,
+		client_id: init.clientId,
+		redirect_uri: init.redirectUri,
+		code_verifier: init.codeVerifier,
+	});
+	return new OAuth2Credential({
+		accessToken: tokens.access_token,
+		refreshToken: tokens.refresh_token ?? "",
+		expiresIn: tokens.expires_in,
+		// Auto-refresh via the same /token endpoint (refresh_token grant).
+		refreshFn: (refreshToken) =>
+			postToken(transport, {
+				grant_type: "refresh_token",
+				refresh_token: refreshToken,
+				client_id: init.clientId,
+			}),
+	});
+}
+
+/** POST a form-encoded grant request to `/auth/oauth/token` on the auth channel. */
+function postToken(
+	transport: Transport,
+	form: Record<string, string>,
+): Promise<TokenExchangeResponse> {
+	return transport.request<TokenExchangeResponse>({
+		method: "POST",
+		path: "/auth/oauth/token",
+		channel: "auth",
+		form,
+	});
+}
+
+/** Base64url-encode bytes (no padding), per RFC 7636. */
+function base64UrlEncode(bytes: Uint8Array): string {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary)
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+}
+
+/** A cryptographically-random URL-safe string of `byteLength` entropy. */
+function randomUrlSafe(byteLength: number): string {
+	const bytes = new Uint8Array(byteLength);
+	crypto.getRandomValues(bytes);
+	return base64UrlEncode(bytes);
+}
+
+/** Compute the PKCE S256 `code_challenge` from a verifier. */
+async function s256Challenge(verifier: string): Promise<string> {
+	const data = new TextEncoder().encode(verifier);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return base64UrlEncode(new Uint8Array(digest));
+}

package/runtime/page.ts

@@ -0,0 +1,81 @@
+// LeavePulse SDK — pagination.
+//
+// `list`-style operations (x-sdk-paginated) return a Page<T> that is both a
+// snapshot of one page and an async iterator over all pages. Callers can do
+// `for await (const item of client.project.list()) { ... }` without juggling
+// page/limit by hand.
+
+export interface PageData<T> {
+	items: T[];
+	page: number;
+	per_page: number;
+	total: number;
+}
+
+export type PageFetcher<T> = (
+	page: number,
+	perPage: number,
+) => Promise<PageData<T>>;
+
+/** Coerce an arbitrary list-envelope body into `PageData<T>`, hydrating items
+ * via the supplied callback and reading the canonical `{total,page,per_page}`
+ * fields (falling back sensibly when a field is absent). Generated list methods
+ * build the per-endpoint `hydrate` closure; the field plumbing lives here so it
+ * stays identical across every paginated method. */
+export function pageDataFrom<T>(
+	body: unknown,
+	hydrate: (items: unknown[]) => T[],
+	requestedPage: number,
+	requestedPerPage: number,
+): PageData<T> {
+	const obj = (body ?? {}) as Record<string, unknown>;
+	const rawItems = Array.isArray(obj.items) ? (obj.items as unknown[]) : [];
+	const items = hydrate(rawItems);
+	const num = (v: unknown, fallback: number): number => {
+		const n = Number(v);
+		return Number.isFinite(n) ? n : fallback;
+	};
+	return {
+		items,
+		total: num(obj.total, items.length),
+		page: num(obj.page, requestedPage),
+		per_page: num(obj.per_page, requestedPerPage),
+	};
+}
+
+export class Page<T> implements AsyncIterable<T> {
+	readonly items: T[];
+	readonly page: number;
+	readonly perPage: number;
+	readonly total: number;
+
+	constructor(
+		data: PageData<T>,
+		private readonly fetcher: PageFetcher<T>,
+	) {
+		this.items = data.items;
+		this.page = data.page;
+		this.perPage = data.per_page;
+		this.total = data.total;
+	}
+
+	get hasNext(): boolean {
+		return this.page * this.perPage < this.total;
+	}
+
+	async next(): Promise<Page<T> | null> {
+		if (!this.hasNext) return null;
+		const data = await this.fetcher(this.page + 1, this.perPage);
+		return new Page(data, this.fetcher);
+	}
+
+	/** Iterate every item across all pages, fetching lazily. */
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		// eslint-disable-next-line @typescript-eslint/no-this-alias
+		let current: Page<T> | null = this;
+		while (current) {
+			for (const item of current.items) yield item;
+			current = await current.next();
+		}
+	}
+}

package/runtime/realtime-client.ts

@@ -0,0 +1,339 @@
+// LeavePulse SDK — bidirectional realtime client.
+//
+// THE single WS contract between a client and the system. One multiplexed
+// socket carries every topic subscription AND bidirectional exchanges:
+//   - fan-out:        server → client `event` frames for subscribed topics
+//   - request/reply:  client → server `request`, server → client `reply`
+//   - session input:  client → server `input` (for future console/exec)
+// The wire-format is protobuf (ws.proto: ClientFrame / ServerFrame), so the
+// contract evolves by field tags without rewrites and is shared by every client
+// (browser, node) and the gateway. This client owns connect/auth/reconnect; Vue
+// or other UI layers wrap it, they never touch the socket.
+
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import {
+	ClientFrameSchema,
+	type ServerFrame,
+	ServerFrameSchema,
+} from "./realtime_pb/leavepulse/realtime/v1/ws_pb.js";
+
+/** Binary WebSocket shape both the browser and the `ws` package satisfy. */
+export interface BinaryWebSocketLike {
+	send(data: Uint8Array): void;
+	close(): void;
+	binaryType: string;
+	addEventListener(type: "open" | "close" | "error", cb: () => void): void;
+	addEventListener(type: "message", cb: (ev: { data: unknown }) => void): void;
+}
+
+export type RealtimeEventKind = "initial" | "update" | "error";
+
+export interface RealtimeEnvelope<T = unknown> {
+	topic: string;
+	data: T;
+}
+
+export type RealtimeHandler<T = unknown> = (env: RealtimeEnvelope<T>) => void;
+
+export interface RealtimeClientOptions {
+	/** Build a socket for the given URL (browser `WebSocket`, or `ws`). */
+	socketFactory: (url: string) => BinaryWebSocketLike;
+	/** Base WS URL, e.g. `wss://rt.leavepulse.com`. */
+	url: string;
+	/** Async provider for the realtime auth (ws-)token; re-invoked on reconnect. */
+	getToken?: () => Promise<string | null> | string | null;
+	/** Reconnect backoff bounds (ms). */
+	reconnectMinMs?: number;
+	reconnectMaxMs?: number;
+}
+
+interface Subscription {
+	topic: string;
+	handlers: { kind: RealtimeEventKind; fn: RealtimeHandler }[];
+	bootstrapped: boolean;
+}
+
+interface PendingRequest {
+	resolve: (payload: Uint8Array) => void;
+	reject: (err: Error) => void;
+}
+
+const DEFAULT_MIN_MS = 500;
+const DEFAULT_MAX_MS = 30_000;
+
+/** Decode a JSON payload carried in an Event/Reply `data` byte field. */
+function decodeJson(bytes: Uint8Array): unknown {
+	if (bytes.length === 0) return null;
+	try {
+		return JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return null;
+	}
+}
+
+function encodeJson(value: unknown): Uint8Array {
+	return new TextEncoder().encode(JSON.stringify(value ?? null));
+}
+
+/**
+ * Owns the single multiplexed protobuf WebSocket. Reconnects with backoff,
+ * re-authenticates and re-subscribes on reconnect, and routes events / replies.
+ */
+export class RealtimeClient {
+	private socket: BinaryWebSocketLike | null = null;
+	private connecting: Promise<void> | null = null;
+	private authenticated = false;
+	private closedByUser = false;
+	private reconnectAttempts = 0;
+	private requestSeq = 0;
+	private readonly subscriptions = new Map<string, Subscription>();
+	private readonly pending = new Map<string, PendingRequest>();
+	// Resolved when the server's `welcome` frame lands — i.e. auth has been
+	// processed. Subscribes wait on this so a private topic is never requested
+	// before the gateway has bound the socket's identity (otherwise it replies
+	// "Authentication required for private topic" and we needlessly reconnect).
+	private welcomed: Promise<void> | null = null;
+	private resolveWelcome: (() => void) | null = null;
+
+	constructor(private readonly opts: RealtimeClientOptions) {}
+
+	get isAuthenticated(): boolean {
+		return this.authenticated;
+	}
+
+	/** Subscribe to a topic; returns an unsubscribe function. */
+	async subscribe(
+		topic: string,
+		kind: RealtimeEventKind,
+		handler: RealtimeHandler,
+	): Promise<() => void> {
+		await this.ensureConnected();
+		let sub = this.subscriptions.get(topic);
+		if (!sub) {
+			sub = { topic, handlers: [], bootstrapped: false };
+			this.subscriptions.set(topic, sub);
+			this.sendSubscribe(topic);
+		}
+		sub.handlers.push({ kind, fn: handler });
+		return () => this.removeHandler(topic, handler);
+	}
+
+	/** Send a request and await its single reply (the JSON-decoded payload). */
+	async request<T = unknown>(method: string, payload?: unknown): Promise<T> {
+		await this.ensureConnected();
+		const id = `r${++this.requestSeq}`;
+		const frame = create(ClientFrameSchema, {
+			body: {
+				case: "request",
+				value: { id, method, payload: encodeJson(payload) },
+			},
+		});
+		const result = new Promise<Uint8Array>((resolve, reject) => {
+			this.pending.set(id, { resolve, reject });
+		});
+		this.sendFrame(frame);
+		const bytes = await result;
+		return decodeJson(bytes) as T;
+	}
+
+	/** Send a chunk of session input (e.g. console stdin) for a session. */
+	async sendInput(sessionId: string, data: Uint8Array): Promise<void> {
+		await this.ensureConnected();
+		this.sendFrame(
+			create(ClientFrameSchema, {
+				body: { case: "input", value: { sessionId, data } },
+			}),
+		);
+	}
+
+	close(): void {
+		this.closedByUser = true;
+		this.subscriptions.clear();
+		for (const p of this.pending.values())
+			p.reject(new Error("realtime client closed"));
+		this.pending.clear();
+		this.socket?.close();
+		this.socket = null;
+		this.connecting = null;
+		this.authenticated = false;
+		this.resolveWelcome?.();
+		this.resolveWelcome = null;
+		this.welcomed = null;
+	}
+
+	// ── internals ────────────────────────────────────────────────────────────
+
+	private removeHandler(topic: string, handler: RealtimeHandler): void {
+		const sub = this.subscriptions.get(topic);
+		if (!sub) return;
+		sub.handlers = sub.handlers.filter((h) => h.fn !== handler);
+		if (sub.handlers.length === 0) {
+			this.subscriptions.delete(topic);
+			this.sendFrame(
+				create(ClientFrameSchema, {
+					body: { case: "unsubscribe", value: { topic } },
+				}),
+			);
+		}
+	}
+
+	private sendSubscribe(topic: string): void {
+		this.sendFrame(
+			create(ClientFrameSchema, {
+				body: { case: "subscribe", value: { topic } },
+			}),
+		);
+	}
+
+	private async ensureConnected(): Promise<void> {
+		if (this.socket && this.authenticated) return;
+		if (this.connecting) return this.connecting;
+		this.connecting = this.connect();
+		return this.connecting;
+	}
+
+	private async connect(): Promise<void> {
+		this.closedByUser = false;
+		const token = this.opts.getToken ? await this.opts.getToken() : null;
+		const socket = this.opts.socketFactory(this.opts.url);
+		socket.binaryType = "arraybuffer";
+		this.socket = socket;
+
+		// Arm the welcome gate before sending auth, so the frame can't race us.
+		this.welcomed = new Promise<void>((resolve) => {
+			this.resolveWelcome = resolve;
+		});
+
+		await new Promise<void>((resolve, reject) => {
+			socket.addEventListener("open", () => resolve());
+			socket.addEventListener("error", () =>
+				reject(new Error("realtime socket error")),
+			);
+		});
+		socket.addEventListener("message", (ev) => this.onMessage(ev.data));
+		socket.addEventListener("close", () => this.onClose());
+
+		// Authenticate first so private subscriptions are accepted.
+		if (token) {
+			this.sendFrame(
+				create(ClientFrameSchema, {
+					body: { case: "auth", value: { token } },
+				}),
+			);
+		}
+		// Wait for the gateway's `welcome` (auth applied) before (re)subscribing,
+		// so private topics aren't requested on an un-bound socket. The gate is
+		// resolved in onMessage; if the socket drops first, onClose rejects the
+		// retry path, so a hung await can't wedge us.
+		await this.welcomed;
+		// Re-subscribe everything (covers reconnect).
+		for (const topic of this.subscriptions.keys()) this.sendSubscribe(topic);
+		this.reconnectAttempts = 0;
+	}
+
+	private onClose(): void {
+		this.socket = null;
+		this.connecting = null;
+		this.authenticated = false;
+		// Unblock a connect() still awaiting `welcome` so its promise can settle
+		// (it'll re-arm on the next attempt); reconnect drives the retry.
+		this.resolveWelcome?.();
+		this.resolveWelcome = null;
+		if (this.closedByUser) return;
+		this.scheduleReconnect();
+	}
+
+	private scheduleReconnect(): void {
+		const min = this.opts.reconnectMinMs ?? DEFAULT_MIN_MS;
+		const max = this.opts.reconnectMaxMs ?? DEFAULT_MAX_MS;
+		const delay = Math.min(max, min * 2 ** this.reconnectAttempts++);
+		setTimeout(() => {
+			if (this.closedByUser) return;
+			void this.ensureConnected().catch(() => this.scheduleReconnect());
+		}, delay);
+	}
+
+	private onMessage(raw: unknown): void {
+		const bytes = this.toBytes(raw);
+		if (!bytes) return;
+		let frame: ServerFrame;
+		try {
+			frame = fromBinary(ServerFrameSchema, bytes);
+		} catch {
+			return;
+		}
+		switch (frame.body.case) {
+			case "ping":
+				this.sendFrame(
+					create(ClientFrameSchema, { body: { case: "ping", value: {} } }),
+				);
+				return;
+			case "welcome":
+				this.authenticated = frame.body.value.authenticated;
+				// Release any subscribes waiting on the auth handshake.
+				this.resolveWelcome?.();
+				this.resolveWelcome = null;
+				return;
+			case "event": {
+				const ev = frame.body.value;
+				this.dispatchEvent(ev.topic, decodeJson(ev.data));
+				return;
+			}
+			case "reply": {
+				const reply = frame.body.value;
+				const pending = this.pending.get(reply.id);
+				if (!pending) return;
+				this.pending.delete(reply.id);
+				if (reply.error)
+					pending.reject(
+						new Error(
+							reply.error.message || reply.error.code || "request failed",
+						),
+					);
+				else pending.resolve(reply.payload);
+				return;
+			}
+			case "error": {
+				const err = frame.body.value;
+				if (err.id && this.pending.has(err.id)) {
+					const p = this.pending.get(err.id);
+					this.pending.delete(err.id);
+					p?.reject(new Error(err.message || err.code || "realtime error"));
+					return;
+				}
+				if (err.topic) this.dispatchError(err.topic, err);
+				return;
+			}
+			default:
+				return;
+		}
+	}
+
+	private toBytes(raw: unknown): Uint8Array | null {
+		if (raw instanceof Uint8Array) return raw;
+		if (raw instanceof ArrayBuffer) return new Uint8Array(raw);
+		return null;
+	}
+
+	private dispatchEvent(topic: string, data: unknown): void {
+		const sub = this.subscriptions.get(topic);
+		if (!sub) return;
+		const kind: RealtimeEventKind = sub.bootstrapped ? "update" : "initial";
+		sub.bootstrapped = true;
+		for (const h of sub.handlers) if (h.kind === kind) h.fn({ topic, data });
+	}
+
+	private dispatchError(topic: string, error: unknown): void {
+		const sub = this.subscriptions.get(topic);
+		if (!sub) return;
+		for (const h of sub.handlers)
+			if (h.kind === "error") h.fn({ topic, data: error });
+	}
+
+	private sendFrame(
+		frame: ReturnType<typeof create<typeof ClientFrameSchema>>,
+	): void {
+		if (!this.socket) return;
+		this.socket.send(toBinary(ClientFrameSchema, frame));
+	}
+}