feat(v1.1.6-client): @picloud/client TypeScript package

First frontend library (v1.0.0), co-shipped with realtime. Hybrid
model — no direct service access from the browser.

- endpoint<Req,Res>(path).get()/.post() — typed HTTP, auth-token
  injection, structured errors, optional zod/valibot validate adapter.
- subscribe(topic, cb, {token, onTokenExpired}) — streaming-fetch SSE
  with exponential-backoff reconnect, 401 token refresh, Last-Event-ID
  resume.
- auth.login/logout/token over dev-defined endpoints.
- React (useTopic/useEndpoint + PicloudProvider) and Svelte
  (topicStore/endpointStore) subpath exports.

Build: tsup (ESM+CJS+.d.ts); tests: vitest (15); lint: tsc --noEmit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/typescript/src/auth.ts

@@ -0,0 +1,71 @@
+import { Endpoint } from './endpoint.js';
+import type { AuthTokenProvider } from './types.js';
+
+export interface AuthClientConfig {
+  baseURL: string;
+  fetchImpl: typeof fetch;
+  /** Path of the dev-defined login endpoint (default `/api/auth/login`). */
+  loginPath?: string;
+  /** Path of the dev-defined logout endpoint (default `/api/auth/logout`). */
+  logoutPath?: string;
+  /** Called whenever the stored token changes (e.g. to persist it). */
+  onToken?: (token: string | null) => void;
+}
+
+interface LoginResponse {
+  token?: string;
+}
+
+/**
+ * Auth-flow helpers. These call **dev-defined** endpoints under the hood
+ * (the script layer owns the actual auth); the lib only standardizes the
+ * dance + in-memory token storage. There is no built-in identity model —
+ * `login` POSTs credentials and stores whatever `token` comes back.
+ */
+export class AuthClient {
+  private current: string | null = null;
+
+  constructor(private readonly cfg: AuthClientConfig) {}
+
+  /** The current bearer token, or null. */
+  get token(): string | null {
+    return this.current;
+  }
+
+  /** Suitable as `PicloudClientOptions.getAuthToken`. */
+  readonly provider: AuthTokenProvider = () => this.current;
+
+  /** POST credentials to the login endpoint; store the returned token. */
+  async login(email: string, password: string): Promise<string | null> {
+    const ep = new Endpoint<{ email: string; password: string }, LoginResponse>({
+      baseURL: this.cfg.baseURL,
+      path: this.cfg.loginPath ?? '/api/auth/login',
+      fetchImpl: this.cfg.fetchImpl
+    });
+    const res = await ep.post({ email, password });
+    this.setToken(typeof res?.token === 'string' ? res.token : null);
+    return this.current;
+  }
+
+  /** POST to the logout endpoint (best-effort) and clear the token. */
+  async logout(): Promise<void> {
+    const ep = new Endpoint<undefined, unknown>({
+      baseURL: this.cfg.baseURL,
+      path: this.cfg.logoutPath ?? '/api/auth/logout',
+      // Send the current token so the script can invalidate the session.
+      getAuthToken: () => this.current,
+      fetchImpl: this.cfg.fetchImpl
+    });
+    try {
+      await ep.post();
+    } finally {
+      this.setToken(null);
+    }
+  }
+
+  /** Manually set (or clear) the token — e.g. restoring from storage. */
+  setToken(token: string | null): void {
+    this.current = token;
+    this.cfg.onToken?.(token);
+  }
+}

clients/typescript/src/client.ts

@@ -0,0 +1,61 @@
+import { AuthClient } from './auth.js';
+import { Endpoint } from './endpoint.js';
+import { subscribeTopic } from './subscribe.js';
+import type {
+  PicloudClientOptions,
+  RealtimeEvent,
+  SubscribeOptions,
+  Unsubscribe
+} from './types.js';
+
+/**
+ * The PiCloud frontend client. Three capabilities, all script-mediated
+ * (the hybrid model — no direct KV/docs/users access from the browser):
+ *
+ *   - `endpoint<Req, Res>(path)` — typed HTTP to a dev-defined route.
+ *   - `subscribe(topic, cb, opts?)` — SSE realtime subscription.
+ *   - `auth` — login/logout/token helpers over dev-defined endpoints.
+ */
+export class PicloudClient {
+  readonly auth: AuthClient;
+  private readonly baseURL: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly getAuthToken: PicloudClientOptions['getAuthToken'];
+
+  constructor(opts: PicloudClientOptions) {
+    if (!opts.baseURL) throw new Error('PicloudClient: baseURL is required');
+    this.baseURL = opts.baseURL;
+    const f = opts.fetch ?? globalThis.fetch;
+    if (typeof f !== 'function') {
+      throw new Error('PicloudClient: no fetch available — pass options.fetch');
+    }
+    // Bind to avoid "Illegal invocation" when calling a detached global.
+    this.fetchImpl = f.bind(globalThis);
+    this.getAuthToken = opts.getAuthToken;
+    this.auth = new AuthClient({ baseURL: this.baseURL, fetchImpl: this.fetchImpl });
+  }
+
+  /** A typed handle to a dev-defined endpoint. */
+  endpoint<Req = unknown, Res = unknown>(path: string): Endpoint<Req, Res> {
+    return new Endpoint<Req, Res>({
+      baseURL: this.baseURL,
+      path,
+      getAuthToken: this.getAuthToken,
+      fetchImpl: this.fetchImpl
+    });
+  }
+
+  /** Subscribe to a realtime topic. Returns an unsubscribe function. */
+  subscribe<T = unknown>(
+    topic: string,
+    onMessage: (event: RealtimeEvent<T>) => void,
+    opts?: SubscribeOptions<T>
+  ): Unsubscribe {
+    return subscribeTopic<T>(
+      { baseURL: this.baseURL, fetchImpl: this.fetchImpl },
+      topic,
+      onMessage,
+      opts
+    );
+  }
+}

clients/typescript/src/endpoint.ts

@@ -0,0 +1,106 @@
+import { PicloudHttpError, type AuthTokenProvider, type Validator } from './types.js';
+
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export interface EndpointConfig {
+  baseURL: string;
+  path: string;
+  getAuthToken?: AuthTokenProvider;
+  fetchImpl: typeof fetch;
+}
+
+export interface RequestOptions<Res> {
+  /** Extra headers merged over the defaults. */
+  headers?: Record<string, string>;
+  /** Optional runtime validation of the parsed response. */
+  validate?: Validator<Res>;
+  /** AbortSignal to cancel the request. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Typed HTTP to a dev-defined script endpoint. Auth header injection +
+ * structured errors; the request/response types are caller-supplied
+ * generics (`endpoint<Req, Res>('/path')`). No service access — every
+ * call hits a route a script binds (the hybrid model).
+ */
+export class Endpoint<Req = unknown, Res = unknown> {
+  constructor(private readonly cfg: EndpointConfig) {}
+
+  get(opts?: RequestOptions<Res>): Promise<Res> {
+    return this.send('GET', undefined, opts);
+  }
+
+  post(body?: Req, opts?: RequestOptions<Res>): Promise<Res> {
+    return this.send('POST', body, opts);
+  }
+
+  put(body?: Req, opts?: RequestOptions<Res>): Promise<Res> {
+    return this.send('PUT', body, opts);
+  }
+
+  patch(body?: Req, opts?: RequestOptions<Res>): Promise<Res> {
+    return this.send('PATCH', body, opts);
+  }
+
+  delete(opts?: RequestOptions<Res>): Promise<Res> {
+    return this.send('DELETE', undefined, opts);
+  }
+
+  private async send(method: Method, body: Req | undefined, opts?: RequestOptions<Res>): Promise<Res> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...(opts?.headers ?? {})
+    };
+    if (body !== undefined) {
+      headers['Content-Type'] ??= 'application/json';
+    }
+    const token = this.cfg.getAuthToken ? await this.cfg.getAuthToken() : undefined;
+    if (token) {
+      headers['Authorization'] ??= `Bearer ${token}`;
+    }
+
+    const url = joinUrl(this.cfg.baseURL, this.cfg.path);
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      init.body = JSON.stringify(body);
+    }
+    if (opts?.signal) {
+      init.signal = opts.signal;
+    }
+
+    const res = await this.cfg.fetchImpl(url, init);
+    const parsed = await parseBody(res);
+    if (!res.ok) {
+      const message =
+        (isRecord(parsed) && typeof parsed['error'] === 'string' && parsed['error']) ||
+        `${method} ${this.cfg.path} failed with ${res.status}`;
+      throw new PicloudHttpError(res.status, message, parsed);
+    }
+    return opts?.validate ? opts.validate.parse(parsed) : (parsed as Res);
+  }
+}
+
+async function parseBody(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (text.length === 0) return null;
+  const ct = res.headers.get('content-type') ?? '';
+  if (ct.includes('application/json')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+export function joinUrl(base: string, path: string): string {
+  const b = base.endsWith('/') ? base.slice(0, -1) : base;
+  const p = path.startsWith('/') ? path : `/${path}`;
+  return `${b}${p}`;
+}

clients/typescript/src/index.ts

@@ -0,0 +1,14 @@
+export { PicloudClient } from './client.js';
+export { Endpoint } from './endpoint.js';
+export { AuthClient } from './auth.js';
+export { subscribeTopic } from './subscribe.js';
+export {
+  PicloudHttpError,
+  type PicloudClientOptions,
+  type AuthTokenProvider,
+  type RealtimeEvent,
+  type SubscribeOptions,
+  type Unsubscribe,
+  type Validator
+} from './types.js';
+export type { RequestOptions } from './endpoint.js';

clients/typescript/src/react/index.ts

@@ -0,0 +1,101 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode
+} from 'react';
+
+import type { PicloudClient } from '../client.js';
+import type { SubscribeOptions } from '../types.js';
+
+const PicloudContext = createContext<PicloudClient | null>(null);
+
+export interface PicloudProviderProps {
+  client: PicloudClient;
+  children?: ReactNode;
+}
+
+/** Provides a `PicloudClient` to `useTopic` / `useEndpoint`. */
+export function PicloudProvider(props: PicloudProviderProps) {
+  return createElement(PicloudContext.Provider, { value: props.client }, props.children);
+}
+
+/** The client from the nearest `PicloudProvider`. Throws if absent. */
+export function usePicloud(): PicloudClient {
+  const client = useContext(PicloudContext);
+  if (!client) {
+    throw new Error('usePicloud: wrap your tree in <PicloudProvider client={...}>');
+  }
+  return client;
+}
+
+/**
+ * Subscribe to a realtime topic; returns the accumulated messages in
+ * arrival order. Re-subscribes when `topic` changes; unsubscribes on
+ * unmount.
+ */
+export function useTopic<T = unknown>(topic: string, opts?: SubscribeOptions<T>): T[] {
+  const client = usePicloud();
+  const [messages, setMessages] = useState<T[]>([]);
+  useEffect(() => {
+    setMessages([]);
+    const unsubscribe = client.subscribe<T>(
+      topic,
+      (event) => setMessages((prev) => [...prev, event.message]),
+      opts
+    );
+    return () => unsubscribe();
+    // `opts` is intentionally excluded: a new object literal each render
+    // would otherwise resubscribe every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, topic]);
+  return messages;
+}
+
+export interface QueryState<T> {
+  data: T | null;
+  loading: boolean;
+  error: unknown;
+}
+
+export interface EndpointHook<Req, Res> {
+  get: () => QueryState<Res>;
+  post: (body?: Req) => QueryState<Res>;
+}
+
+/**
+ * Typed endpoint hook. `useEndpoint<Res>(path).get()` fires a GET and
+ * returns `{ data, loading, error }`, re-running when `path` changes.
+ * `.post(body)` is the mutation variant (auto-fires once per mount).
+ */
+export function useEndpoint<Res = unknown, Req = unknown>(path: string): EndpointHook<Req, Res> {
+  const client = usePicloud();
+  return {
+    get: () => useResource<Res>(() => client.endpoint<Req, Res>(path).get(), path, 'GET'),
+    post: (body?: Req) =>
+      useResource<Res>(() => client.endpoint<Req, Res>(path).post(body), path, 'POST')
+  };
+}
+
+function useResource<Res>(run: () => Promise<Res>, key: string, method: string): QueryState<Res> {
+  const [state, setState] = useState<QueryState<Res>>({
+    data: null,
+    loading: true,
+    error: null
+  });
+  useEffect(() => {
+    let active = true;
+    setState({ data: null, loading: true, error: null });
+    run()
+      .then((data) => active && setState({ data, loading: false, error: null }))
+      .catch((error) => active && setState({ data: null, loading: false, error }));
+    return () => {
+      active = false;
+    };
+    // `run` is recreated each render; key it on path + method instead.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, method]);
+  return state;
+}

clients/typescript/src/subscribe.ts

@@ -0,0 +1,194 @@
+import { joinUrl } from './endpoint.js';
+import type { RealtimeEvent, SubscribeOptions, Unsubscribe } from './types.js';
+
+interface SubscribeConfig {
+  baseURL: string;
+  fetchImpl: typeof fetch;
+}
+
+/**
+ * Subscribe to an app pub/sub topic over SSE.
+ *
+ * Implemented over streaming `fetch` (not native `EventSource`) so the
+ * lib can: detect a 401 on (re)connect and refresh the token, send a
+ * `Last-Event-ID` header on resume, and apply its own exponential
+ * backoff. See HANDBACK for the rationale. Returns an unsubscribe
+ * function that aborts the connection and stops reconnecting.
+ */
+export function subscribeTopic<T = unknown>(
+  cfg: SubscribeConfig,
+  topic: string,
+  onMessage: (event: RealtimeEvent<T>) => void,
+  opts: SubscribeOptions<T> = {}
+): Unsubscribe {
+  const baseBackoff = opts.baseBackoffMs ?? 1_000;
+  const maxBackoff = opts.maxBackoffMs ?? 30_000;
+  let token = opts.token;
+  let stopped = false;
+  let attempt = 0;
+  let lastEventId: string | undefined;
+  let controller: AbortController | null = null;
+  let backoffTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const stop = () => {
+    stopped = true;
+    if (backoffTimer) clearTimeout(backoffTimer);
+    controller?.abort();
+  };
+
+  const scheduleReconnect = () => {
+    if (stopped) return;
+    // Exponential backoff: base, 2x, 4x… capped at maxBackoff.
+    const delay = Math.min(maxBackoff, baseBackoff * 2 ** attempt);
+    attempt += 1;
+    backoffTimer = setTimeout(() => void connect(), delay);
+  };
+
+  const connect = async (): Promise<void> => {
+    if (stopped) return;
+    controller = new AbortController();
+    const url = buildUrl(cfg.baseURL, topic, token);
+    const headers: Record<string, string> = { Accept: 'text/event-stream' };
+    if (lastEventId) headers['Last-Event-ID'] = lastEventId;
+
+    let res: Response;
+    try {
+      res = await cfg.fetchImpl(url, { headers, signal: controller.signal });
+    } catch (err) {
+      if (stopped || isAbort(err)) return;
+      scheduleReconnect();
+      return;
+    }
+
+    if (res.status === 401) {
+      // Token expired / rejected — try to refresh, else give up.
+      const fresh = opts.onTokenExpired ? await opts.onTokenExpired() : null;
+      if (fresh) {
+        token = fresh;
+        attempt = 0; // fresh credential → reconnect immediately
+        void connect();
+      } else {
+        opts.onError?.(new Error('realtime subscribe unauthorized (401)'));
+        stop();
+      }
+      return;
+    }
+
+    if (!res.ok || !res.body) {
+      if (!stopped) scheduleReconnect();
+      return;
+    }
+
+    // Connected — reset backoff and stream frames until the body ends.
+    attempt = 0;
+    try {
+      await readStream(res.body, (frame) => {
+        if (frame.id !== undefined) lastEventId = frame.id;
+        if (frame.data === undefined) return; // comment / heartbeat
+        const parsed = parseEvent<T>(frame.data, opts);
+        if (parsed) onMessage(parsed);
+      });
+    } catch (err) {
+      if (stopped || isAbort(err)) return;
+    }
+    // Stream ended (server closed, e.g. topic deleted) → reconnect.
+    if (!stopped) scheduleReconnect();
+  };
+
+  void connect();
+  return stop;
+}
+
+function buildUrl(baseURL: string, topic: string, token?: string): string {
+  const url = joinUrl(baseURL, `/realtime/topics/${encodeURIComponent(topic)}`);
+  // EventSource can't set headers, so the token rides in the query
+  // string — the same path a raw EventSource would use.
+  return token ? `${url}?token=${encodeURIComponent(token)}` : url;
+}
+
+function parseEvent<T>(data: string, opts: SubscribeOptions<T>): RealtimeEvent<T> | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (!isRealtimeShape(json)) return null;
+  const message = opts.validate ? opts.validate.parse(json.message) : (json.message as T);
+  return { topic: json.topic, message, published_at: json.published_at };
+}
+
+function isRealtimeShape(v: unknown): v is RealtimeEvent<unknown> {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof (v as Record<string, unknown>)['topic'] === 'string' &&
+    typeof (v as Record<string, unknown>)['published_at'] === 'string' &&
+    'message' in (v as Record<string, unknown>)
+  );
+}
+
+interface SseFrame {
+  data?: string;
+  id?: string;
+}
+
+/**
+ * Read an SSE response body, invoking `onFrame` per event. Minimal
+ * parser: accumulates `data:` lines (joined by `\n`) and `id:` until a
+ * blank line dispatches the frame. Lines starting with `:` are comments
+ * (heartbeats) — surfaced as a frame with no `data` so the id can still
+ * advance.
+ */
+async function readStream(
+  body: ReadableStream<Uint8Array>,
+  onFrame: (frame: SseFrame) => void
+): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let dataLines: string[] = [];
+  let id: string | undefined;
+  let sawComment = false;
+
+  const dispatch = () => {
+    if (dataLines.length > 0) {
+      onFrame({ data: dataLines.join('\n'), id });
+    } else if (sawComment) {
+      onFrame({ id });
+    }
+    dataLines = [];
+    sawComment = false;
+  };
+
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let nl: number;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).replace(/\r$/, '');
+      buffer = buffer.slice(nl + 1);
+      if (line === '') {
+        dispatch();
+        continue;
+      }
+      if (line.startsWith(':')) {
+        sawComment = true;
+        continue;
+      }
+      const colon = line.indexOf(':');
+      const field = colon === -1 ? line : line.slice(0, colon);
+      const rawVal = colon === -1 ? '' : line.slice(colon + 1);
+      const val = rawVal.startsWith(' ') ? rawVal.slice(1) : rawVal;
+      if (field === 'data') dataLines.push(val);
+      else if (field === 'id') id = val;
+    }
+  }
+  // Flush a trailing frame if the stream ended without a blank line.
+  dispatch();
+}
+
+function isAbort(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { name?: string }).name === 'AbortError';
+}

clients/typescript/src/svelte/index.ts

@@ -0,0 +1,72 @@
+import { readable, type Readable } from 'svelte/store';
+
+import type { PicloudClient } from '../client.js';
+import type { SubscribeOptions } from '../types.js';
+
+/**
+ * A Svelte store of realtime messages for a topic. `$messages` is an
+ * array that grows as events arrive. The SSE connection opens on the
+ * first subscriber and closes when the last unsubscribes (standard
+ * `readable` lifecycle).
+ *
+ * The client is passed explicitly (Svelte stores aren't components, so
+ * there's no React-style context to read). See HANDBACK §7.
+ */
+export function topicStore<T = unknown>(
+  client: PicloudClient,
+  topic: string,
+  opts?: SubscribeOptions<T>
+): Readable<T[]> {
+  return readable<T[]>([], (set) => {
+    let items: T[] = [];
+    const unsubscribe = client.subscribe<T>(
+      topic,
+      (event) => {
+        items = [...items, event.message];
+        set(items);
+      },
+      opts
+    );
+    return () => unsubscribe();
+  });
+}
+
+export interface QueryState<T> {
+  data: T | null;
+  loading: boolean;
+  error: unknown;
+}
+
+export interface EndpointStore<Req, Res> {
+  get: () => Readable<QueryState<Res>>;
+  post: (body?: Req) => Readable<QueryState<Res>>;
+}
+
+/**
+ * A Svelte store wrapper over a typed endpoint. `$query` is
+ * `{ data, loading, error }`. The request fires when the store gains its
+ * first subscriber.
+ */
+export function endpointStore<Res = unknown, Req = unknown>(
+  client: PicloudClient,
+  path: string
+): EndpointStore<Req, Res> {
+  const run = (exec: () => Promise<Res>): Readable<QueryState<Res>> =>
+    readable<QueryState<Res>>({ data: null, loading: true, error: null }, (set) => {
+      let active = true;
+      exec()
+        .then((data) => {
+          if (active) set({ data, loading: false, error: null });
+        })
+        .catch((error) => {
+          if (active) set({ data: null, loading: false, error });
+        });
+      return () => {
+        active = false;
+      };
+    });
+  return {
+    get: () => run(() => client.endpoint<Req, Res>(path).get()),
+    post: (body?: Req) => run(() => client.endpoint<Req, Res>(path).post(body))
+  };
+}

clients/typescript/src/types.ts

@@ -0,0 +1,73 @@
+// Shared types for @picloud/client.
+
+/** Returns the current bearer token (or null) before each HTTP request. */
+export type AuthTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+
+export interface PicloudClientOptions {
+  /** Base URL of the PiCloud deployment, e.g. `https://api.example.com`. */
+  baseURL: string;
+  /**
+   * Optional: returns the current bearer token, called before each
+   * request. The client doesn't manage tokens — it just sends them.
+   */
+  getAuthToken?: AuthTokenProvider;
+  /**
+   * Optional fetch implementation (defaults to the global `fetch`).
+   * Injected mainly for tests / non-browser runtimes.
+   */
+  fetch?: typeof fetch;
+}
+
+/** A realtime event as delivered over SSE. */
+export interface RealtimeEvent<T = unknown> {
+  topic: string;
+  message: T;
+  published_at: string;
+}
+
+/**
+ * Minimal validator shape for the optional runtime-validation adapter.
+ * A Zod schema satisfies this directly (`schema.parse`); for Valibot,
+ * wrap it: `{ parse: (i) => v.parse(schema, i) }`. No hard dep on either.
+ */
+export interface Validator<T> {
+  parse: (input: unknown) => T;
+}
+
+/** Thrown when an endpoint call returns a non-2xx status. */
+export class PicloudHttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.name = 'PicloudHttpError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export interface SubscribeOptions<T = unknown> {
+  /**
+   * Subscriber token for `auth_mode = 'token'` topics. Obtained from one
+   * of your app's script endpoints (which calls
+   * `pubsub::subscriber_token`). Sent as `?token=` (EventSource-parity).
+   */
+  token?: string;
+  /**
+   * Called when a (re)connect is rejected with 401 — typically an
+   * expired token. Return a fresh token to retry immediately, or
+   * null/undefined to stop and surface the error.
+   */
+  onTokenExpired?: () => string | null | undefined | Promise<string | null | undefined>;
+  /** Called on a terminal error (after retries are exhausted or aborted). */
+  onError?: (err: unknown) => void;
+  /** Optional runtime validation of each event's `message`. */
+  validate?: Validator<T>;
+  /** Max reconnect backoff in ms (default 30_000). */
+  maxBackoffMs?: number;
+  /** Base reconnect backoff in ms (default 1_000). */
+  baseBackoffMs?: number;
+}
+
+/** Cancels a realtime subscription. */
+export type Unsubscribe = () => void;