extends true
+ ? unknown
+ : A extends object
+ ? A
+ : unknown
+ : unknown;
+
+export type InferPluginContribution =
+ P extends ClientPlugin
+ ? InferRoutes> & ActionsOf
+ : unknown;
+
+export type CombinedClientContributions = UnionToIntersection<
+ { [K in keyof Plugins]: InferPluginContribution }[number]
+>;
diff --git a/clients/typescript/packages/client/src/envelope.ts b/clients/typescript/packages/client/src/envelope.ts
new file mode 100644
index 0000000..613d42d
--- /dev/null
+++ b/clients/typescript/packages/client/src/envelope.ts
@@ -0,0 +1,48 @@
+import { DEFAULT_ENVELOPE_FIELDS } from "./constants";
+import { type EnvelopeConfig } from "./types";
+
+/**
+ * Unwrap a parsed JSON success body according to envelope config.
+ *
+ * - `mode: "off"`: return as-is.
+ * - `mode: "wrap-success" | "always"`: extract `body[fields.data]` if present;
+ * if the key is missing (server didn't wrap this particular response), fall
+ * back to the raw body so we don't lose data.
+ *
+ * Returning `unknown` is intentional: the caller knows the expected shape and
+ * narrows / validates it. Trying to be clever here would invite false typing.
+ */
+export function unwrapPayload(body: unknown, envelope: EnvelopeConfig): unknown {
+ if (envelope.mode === "off") {
+ return body;
+ }
+ if (body === null || typeof body !== "object") {
+ return body;
+ }
+ const fields = envelope.fields ?? DEFAULT_ENVELOPE_FIELDS;
+ const record = body as Record;
+ if (fields.data in record) {
+ return record[fields.data];
+ }
+ return body;
+}
+
+/**
+ * Pull the human-readable error message out of a non-2xx body.
+ *
+ * - `mode: "off" | "wrap-success"`: error bodies look like `{ message }`
+ * - `mode: "always"`: error bodies use the configured `fields.message` key.
+ *
+ * Returns `undefined` when no message can be located; the caller substitutes
+ * a status-based fallback (e.g. HTTP status text).
+ */
+export function unwrapErrorMessage(body: unknown, envelope: EnvelopeConfig): string | undefined {
+ if (body === null || typeof body !== "object") {
+ return undefined;
+ }
+ const record = body as Record;
+ const fields = envelope.fields ?? DEFAULT_ENVELOPE_FIELDS;
+ const key = envelope.mode === "always" ? fields.message : "message";
+ const value = record[key];
+ return typeof value === "string" ? value : undefined;
+}
diff --git a/clients/typescript/packages/client/src/errors.ts b/clients/typescript/packages/client/src/errors.ts
new file mode 100644
index 0000000..cf8e21a
--- /dev/null
+++ b/clients/typescript/packages/client/src/errors.ts
@@ -0,0 +1,46 @@
+export type LimenErrorCode =
+ | "unauthorized"
+ | "forbidden"
+ | "not_found"
+ | "rate_limited"
+ | "validation_error"
+ | "conflict"
+ | "server_error"
+ | "unknown";
+
+/** Map HTTP status → typed code. Anything unmapped becomes `"unknown"`. */
+// prettier-ignore
+export function deriveErrorCode(status: number): LimenErrorCode {
+ if (status === 401) {return "unauthorized";}
+ if (status === 403) {return "forbidden";}
+ if (status === 404) {return "not_found";}
+ if (status === 409) {return "conflict";}
+ if (status === 422 || status === 400) {return "validation_error";}
+ if (status === 429) {return "rate_limited";}
+ if (status >= 500 && status < 600) {return "server_error";}
+ return "unknown";
+}
+
+/**
+ * The single error type every SDK call throws on non-2xx. Carries the raw
+ * server message, the HTTP status, and a derived typed code.
+ */
+export class LimenError extends Error {
+ override readonly name = "LimenError";
+ readonly status: number;
+ readonly code: LimenErrorCode;
+
+ constructor(message: string, status: number, code?: LimenErrorCode) {
+ super(message);
+ this.status = status;
+ this.code = code ?? deriveErrorCode(status);
+ }
+
+ get isUnauthorized(): boolean {
+ return this.code === "unauthorized";
+ }
+
+ get isRateLimited(): boolean {
+ return this.code === "rate_limited";
+ }
+}
diff --git a/clients/typescript/packages/client/src/fetcher.ts b/clients/typescript/packages/client/src/fetcher.ts
new file mode 100644
index 0000000..9add952
--- /dev/null
+++ b/clients/typescript/packages/client/src/fetcher.ts
@@ -0,0 +1,179 @@
+import { unwrapErrorMessage, unwrapPayload } from "./envelope";
+import { LimenError, deriveErrorCode } from "./errors";
+import { ensureLeadingSlash, joinURL, stripTrailingSlash } from "./helpers";
+import type { HookRunner } from "./hooks";
+import type { FetchInit, RequestContext, ResponseContext } from "./plugin";
+import type { EnvelopeConfig, HTTPMethod } from "./types";
+
+type ClientFetchCallbackContext = ResponseContext & {};
+
+export type FetcherFetchOptions = {
+ /** Whether to send credentials (cookies). Defaults to `"include"`. */
+ credentials?: RequestCredentials;
+ /** Custom fetch impl. Defaults to `globalThis.fetch`. */
+ impl?: typeof fetch;
+ /** Default headers merged into every request. Per-request headers override these. */
+ headers?: HeadersInit;
+ /** Callback function to be called when the request is successful. */
+ onSuccess?: (context: ClientFetchCallbackContext & { response: Response }) => void;
+ /** Callback function to be called when the request fails. */
+ onError?: (context: ClientFetchCallbackContext & { error: Error }) => void;
+};
+
+type FetcherOptions = {
+ baseURL: string;
+ basePath: string;
+ fetchOptions: FetcherFetchOptions;
+ hooks: HookRunner;
+ envelope: EnvelopeConfig;
+};
+
+export class Fetcher {
+ private readonly fetchImpl: typeof fetch;
+ private readonly credentials: RequestCredentials;
+
+ constructor(private readonly opts: FetcherOptions) {
+ this.fetchImpl = opts.fetchOptions.impl ?? globalThis.fetch.bind(globalThis);
+ this.credentials = opts.fetchOptions.credentials ?? "include";
+ }
+
+ async fetch(path: string, init?: FetchInit, routePath: string = path): Promise {
+ const method: HTTPMethod = init?.method ?? (init?.body !== undefined ? "POST" : "GET");
+ return this.run({
+ method,
+ path,
+ routePath,
+ body: init?.body,
+ headers: init?.headers,
+ query: init?.query,
+ });
+ }
+
+ /**
+ * Builds the request context, runs hooks, does
+ * the fetch, parses the response, runs hooks again, throws on non-2xx.
+ */
+ private async run(args: {
+ method: HTTPMethod;
+ path: string;
+ routePath: string;
+ body: unknown;
+ headers: HeadersInit | undefined;
+ query: Record | undefined;
+ }): Promise {
+ const fullPath = this.normalizeRelativePath(this.opts.basePath, args.path, args.query);
+ const url = joinURL(this.opts.baseURL, fullPath);
+
+ const headers = new Headers({ ...args.headers, ...(this.opts.fetchOptions.headers ?? {}) });
+ if (!headers.has("Content-Type")) {
+ headers.set("Content-Type", "application/json");
+ }
+ if (!headers.has("Accept")) {
+ headers.set("Accept", "application/json");
+ }
+
+ let reqCtx: RequestContext = {
+ method: args.method,
+ fullPath: fullPath,
+ path: args.path,
+ routePath: args.routePath,
+ url,
+ headers,
+ body: args.body,
+ };
+
+ reqCtx = await this.opts.hooks.runBeforeRequest(reqCtx);
+
+ const payload = reqCtx.body !== undefined && reqCtx.body !== null ? JSON.stringify(reqCtx.body) : undefined;
+
+ const requestInit: RequestInit = {
+ method: reqCtx.method,
+ headers: reqCtx.headers,
+ credentials: this.credentials,
+ };
+
+ if (payload !== undefined) {
+ requestInit.body = payload;
+ }
+
+ let response: Response;
+ try {
+ response = await this.fetchImpl(reqCtx.url, requestInit);
+ } catch (err) {
+ this.opts.fetchOptions.onError?.({
+ ...reqCtx,
+ status: 0,
+ ok: false,
+ error: err as Error,
+ });
+ throw new LimenError(err instanceof Error ? err.message : "Network request failed", 0, "unknown");
+ }
+
+ const parsedBody = await this.parseResponseBody(response);
+ const unwrapped =
+ response.ok && parsedBody !== undefined ? unwrapPayload(parsedBody, this.opts.envelope) : parsedBody;
+
+ let resCtx: ResponseContext = {
+ method: args.method,
+ fullPath: fullPath,
+ path: args.path,
+ routePath: args.routePath,
+ status: response.status,
+ ok: response.ok,
+ headers: response.headers,
+ body: unwrapped,
+ };
+
+ resCtx = await this.opts.hooks.runAfterResponse(resCtx);
+
+ if (resCtx.ok) {
+ this.opts.fetchOptions.onSuccess?.({
+ ...resCtx,
+ response,
+ });
+ return resCtx.body as T;
+ }
+
+ const message =
+ unwrapErrorMessage(resCtx.body, this.opts.envelope) ??
+ response.statusText ??
+ `Request failed with status ${response.status}`;
+
+ const error = new LimenError(message, response.status, deriveErrorCode(response.status));
+ this.opts.fetchOptions.onError?.({
+ ...reqCtx,
+ status: response.status,
+ ok: false,
+ error,
+ });
+ throw error;
+ }
+
+ private async parseResponseBody(response: Response): Promise {
+ if (response.status === 204) {
+ return undefined;
+ }
+ const text = await response.text();
+ if (text.length === 0) {
+ return undefined;
+ }
+ return JSON.parse(text) as unknown;
+ }
+
+ private normalizeRelativePath(
+ basePath: string,
+ relativePath: string,
+ query: Record | undefined,
+ ): string {
+ const base = basePath === "" || basePath === "/" ? "" : ensureLeadingSlash(stripTrailingSlash(basePath));
+ let path = base + ensureLeadingSlash(relativePath);
+ if (query !== undefined) {
+ const params = new URLSearchParams(query);
+ const qs = params.toString();
+ if (qs.length > 0) {
+ path = `${path}?${qs}`;
+ }
+ }
+ return path;
+ }
+}
diff --git a/clients/typescript/packages/client/src/helpers.ts b/clients/typescript/packages/client/src/helpers.ts
new file mode 100644
index 0000000..99fbd42
--- /dev/null
+++ b/clients/typescript/packages/client/src/helpers.ts
@@ -0,0 +1,69 @@
+export function stripTrailingSlash(s: string): string {
+ return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+/**
+ * Ensure a leading slash while preserving `""` as "no path".
+ */
+export function ensureLeadingSlash(s: string): string {
+ if (s === "" || s === "/") {
+ return s;
+ }
+ return s.startsWith("/") ? s : `/${s}`;
+}
+
+/**
+ * Normalize a base path to `""` or a leading-slash path without a trailing
+ * slash.
+ */
+export function normalizeBasePath(p: string): string {
+ if (p === "" || p === "/") {
+ return "";
+ }
+ const withLeading = p.startsWith("/") ? p : `/${p}`;
+ return withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+}
+
+export function joinURL(baseURL: string, path: string): string {
+ return stripTrailingSlash(baseURL) + ensureLeadingSlash(path);
+}
+
+export function toCamelCaseKey(key: string): string {
+ return key.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+export function kebabToCamel(key: string): string {
+ return key.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Shallow-convert an object's keys from snake_case to camelCase. Non-object
+ * inputs and arrays pass through untouched.
+ */
+export function camelizeKeys>(raw: unknown): T {
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+ return raw as T;
+ }
+ const out: Record = {};
+ for (const [key, value] of Object.entries(raw)) {
+ out[toCamelCaseKey(key)] = value;
+ }
+ return out as T;
+}
+
+export function camelizeEach>(raw: unknown): T[] {
+ if (!Array.isArray(raw)) {
+ return [];
+ }
+ return raw.map((item) => camelizeKeys(item));
+}
+
+/**
+ * Convert camelCase to snake_case, leaving already-snake-cased keys unchanged.
+ */
+export function camelToSnake(key: string): string {
+ if (key.includes("_")) {
+ return key;
+ }
+ return key.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+}
diff --git a/clients/typescript/packages/client/src/hooks.ts b/clients/typescript/packages/client/src/hooks.ts
new file mode 100644
index 0000000..c64876e
--- /dev/null
+++ b/clients/typescript/packages/client/src/hooks.ts
@@ -0,0 +1,60 @@
+import type {
+ AfterResponseHook,
+ BeforeRequestHook,
+ PluginHooks,
+ RequestContext,
+ ResponseContext,
+ RouteMatcher,
+} from "./plugin";
+
+type HookProvider = {
+ hooks?: PluginHooks;
+};
+
+function matchesRoute(matcher: RouteMatcher | undefined, routePath: string): boolean {
+ if (matcher === undefined) {
+ return true;
+ }
+ if (typeof matcher === "string") {
+ return routePath === matcher;
+ }
+ if (typeof matcher === "function") {
+ return matcher({ path: routePath });
+ }
+ return routePath !== undefined && matcher.includes(routePath);
+}
+
+export class HookRunner {
+ private readonly before: BeforeRequestHook[];
+ private readonly after: AfterResponseHook[];
+
+ constructor(plugins: readonly HookProvider[]) {
+ this.before = plugins.flatMap((p) => p.hooks?.beforeRequest ?? []);
+ this.after = plugins.flatMap((p) => p.hooks?.afterResponse ?? []);
+ }
+
+ async runBeforeRequest(initial: RequestContext): Promise {
+ let ctx = initial;
+ for (const hook of this.before) {
+ if (!matchesRoute(hook.match, ctx.routePath)) {
+ continue;
+ }
+ ctx = await hook.run(ctx);
+ }
+ return ctx;
+ }
+
+ async runAfterResponse(initial: ResponseContext): Promise {
+ let ctx = initial;
+ for (const hook of this.after) {
+ if (!matchesRoute(hook.match, ctx.routePath)) {
+ continue;
+ }
+ if (!hook.allowOnFailure && ctx.status >= 400) {
+ continue;
+ }
+ ctx = await hook.run(ctx);
+ }
+ return ctx;
+ }
+}
diff --git a/clients/typescript/packages/client/src/index.ts b/clients/typescript/packages/client/src/index.ts
new file mode 100644
index 0000000..4e60f4d
--- /dev/null
+++ b/clients/typescript/packages/client/src/index.ts
@@ -0,0 +1,48 @@
+export { VERSION } from "./version";
+
+export { createAuthClient } from "./client";
+
+export { deriveErrorCode, LimenError } from "./errors";
+export type { LimenErrorCode } from "./errors";
+
+export { camelizeEach, camelizeKeys } from "./helpers";
+export { defaultSessionParse, normalizeUser } from "./normalize";
+
+export type { SessionState, SessionStore } from "./session-store";
+
+export type {
+ AfterResponseHook,
+ BeforeRequestHook,
+ FetchInit,
+ PluginClientOverride,
+ PluginIdOf,
+ PluginOverrides,
+ RequestContext,
+ ResponseContext,
+ RouteMatcher,
+} from "./plugin";
+
+export { defineClientPlugin, defineRoutes } from "./define-plugin";
+export { route } from "./route";
+export { defaultSerialize } from "./serialize";
+
+export type { AnyRouteContext, RouteContext } from "./context";
+export type { RunRoute } from "./define-plugin";
+export type { RouteCallOptions, RouteHandler } from "./route";
+
+export { coreClientPlugin } from "./routes";
+export type { ActiveSession, CoreContribution, VerifyEmailInput } from "./routes";
+
+export type {
+ AuthClient,
+ ClientFetchOptions,
+ CreateAuthClientOptions,
+ EnvelopeConfig,
+ EnvelopeFields,
+ EnvelopeMode,
+ HTTPMethod,
+ ParseSession,
+ RedirectFn,
+ Session,
+ User,
+} from "./types";
diff --git a/clients/typescript/packages/client/src/infer.ts b/clients/typescript/packages/client/src/infer.ts
new file mode 100644
index 0000000..bc7d70b
--- /dev/null
+++ b/clients/typescript/packages/client/src/infer.ts
@@ -0,0 +1,69 @@
+import type { InputOf, OutputOf, RouteCallOptions } from "./route";
+import type { KebabToCamel, Split, UnionToIntersection } from "./type-utils";
+
+type IsParam = S extends `:${string}` ? true : false;
+
+/**
+ * Turn a route path literal into its camelCased client-chain segments, dropping
+ * leading slashes and `:param` segments. `"/otp/send"` -> `["otp", "send"]`.
+ */
+export type PathSegments = P extends `/${infer Rest}`
+ ? PathSegments
+ : P extends `${infer Head}/${infer Tail}`
+ ? Head extends ""
+ ? PathSegments
+ : IsParam extends true
+ ? PathSegments
+ : [KebabToCamel, ...PathSegments]
+ : P extends ""
+ ? []
+ : IsParam extends true
+ ? []
+ : [KebabToCamel
];
+
+type PathOf = R extends { path: infer P extends string } ? P : never;
+
+/**
+ * The resolved chain for one route: an absolute `as` wins, otherwise it is the
+ * plugin's base-path segments followed by the route-path segments.
+ */
+type ChainSegments = R extends { as: infer A extends string }
+ ? Split
+ : [...BasePrefix, ...PathSegments>];
+
+type Nest = Segs extends readonly [
+ infer Head extends string,
+ ...infer Rest extends readonly string[],
+]
+ ? // Avoid emitting an index signature when route paths widen to `string`.
+ string extends Head
+ ? unknown
+ : { [K in Head]: Nest }
+ : Fn;
+
+/**
+ * A no-input route (`I` is `void`) takes no input — only the optional, trailing
+ * call options; everything else takes `input` followed by the call options.
+ * Options are always the trailing argument so the runtime can place them
+ * unambiguously (a lone argument is always the route input).
+ */
+type InferRouteFn = [I] extends [void]
+ ? (input?: void, opts?: RouteCallOptions) => Promise
+ : (input: I, opts?: RouteCallOptions) => Promise;
+
+type IsExposed = R extends { expose: false } ? false : true;
+
+type RouteFn = InferRouteFn, OutputOf>;
+
+type InferOneRoute =
+ IsExposed extends false ? unknown : Nest, RouteFn>;
+
+/**
+ * Infer the public API tree for a list of route descriptors, given the owning
+ * plugin's base-path segments. Each route mounts a callable at its resolved
+ * chain; sibling keys merge via intersection, so `signin.credential` and
+ * `signup.credential` coexist and both autocomplete.
+ */
+export type InferRoutes = UnionToIntersection<
+ { [K in keyof Routes]: InferOneRoute }[number]
+>;
diff --git a/clients/typescript/packages/client/src/json-deep-equal.ts b/clients/typescript/packages/client/src/json-deep-equal.ts
new file mode 100644
index 0000000..e47be93
--- /dev/null
+++ b/clients/typescript/packages/client/src/json-deep-equal.ts
@@ -0,0 +1,53 @@
+function isPlainObject(value: unknown): value is Record {
+ if (typeof value !== "object" || value === null) {
+ return false;
+ }
+ const proto = Object.getPrototypeOf(value);
+ return proto === Object.prototype || proto === null;
+}
+
+function equalArrays(a: unknown[], b: unknown[]): boolean {
+ if (a.length !== b.length) {
+ return false;
+ }
+
+ for (let i = 0; i < a.length; i += 1) {
+ if (!deepJsonEqual(a[i], b[i])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+function equalObjects(a: Record, b: Record): boolean {
+ const aKeys = Object.keys(a);
+ const bKeys = Object.keys(b);
+ if (aKeys.length !== bKeys.length) {
+ return false;
+ }
+
+ for (const key of aKeys) {
+ if (!Object.hasOwn(b, key) || !deepJsonEqual(a[key], b[key])) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/** Structural equality for JSON-shaped values. */
+export function deepJsonEqual(a: unknown, b: unknown): boolean {
+ if (Object.is(a, b)) {
+ return true;
+ }
+
+ const aIsArray = Array.isArray(a);
+ const bIsArray = Array.isArray(b);
+ if (aIsArray && bIsArray) {
+ return equalArrays(a, b);
+ }
+
+ if (!isPlainObject(a) || !isPlainObject(b)) {
+ return false;
+ }
+ return equalObjects(a, b);
+}
diff --git a/clients/typescript/packages/client/src/normalize.ts b/clients/typescript/packages/client/src/normalize.ts
new file mode 100644
index 0000000..18cc578
--- /dev/null
+++ b/clients/typescript/packages/client/src/normalize.ts
@@ -0,0 +1,24 @@
+import { toCamelCaseKey } from "./helpers";
+import type { Session, User } from "./types";
+
+/**
+ * Convert snake_case User keys from server payloads to camelCase. Unknown
+ * extension fields are converted with the same rule so consumers consistently
+ * read camelCase in SDK responses.
+ */
+export function normalizeUser(raw: Record): User {
+ const out: Record = {};
+ for (const [key, value] of Object.entries(raw)) {
+ out[toCamelCaseKey(key)] = value;
+ }
+ return out as User;
+}
+
+export function defaultSessionParse(raw: unknown): Session {
+ if (!raw || typeof raw !== "object") {
+ throw new TypeError(`Expected session response to be an object, got ${raw === null ? "null" : typeof raw}`);
+ }
+ const obj = raw as Record;
+ const userRaw = (obj["user"] ?? obj) as Record;
+ return { user: normalizeUser(userRaw) };
+}
diff --git a/clients/typescript/packages/client/src/path.ts b/clients/typescript/packages/client/src/path.ts
new file mode 100644
index 0000000..e009758
--- /dev/null
+++ b/clients/typescript/packages/client/src/path.ts
@@ -0,0 +1,50 @@
+import { kebabToCamel } from "./helpers";
+
+/**
+ * Derive the public client chain from a route path. Mirrors the type-level
+ * `PathSegments` in `infer.ts` exactly, so runtime materialization and compile
+ * time inference can never drift.
+ *
+ * "/otp/send" -> ["otp", "send"]
+ * "/revoke-sessions" -> ["revokeSessions"]
+ * "/:provider/authorize" -> ["authorize"] (param segments are dropped)
+ */
+export function pathToChain(path: string): string[] {
+ return path
+ .split("/")
+ .filter((seg) => seg.length > 0 && !seg.startsWith(":"))
+ .map(kebabToCamel);
+}
+
+export function chainFromDotted(chain: string): string[] {
+ return chain.split(".").filter((seg) => seg.length > 0);
+}
+
+type ResolvedPath = {
+ /** Path with `:param` segments substituted. */
+ path: string;
+ /** Input with declared param keys removed. */
+ rest: unknown;
+};
+
+/**
+ * Substitute declared path params from `input` into `path` and strip them from
+ * the payload.
+ */
+export function resolvePath(path: string, params: readonly string[] | undefined, input: unknown): ResolvedPath {
+ if (!params || params.length === 0) {
+ return { path, rest: input };
+ }
+ const source = (input ?? {}) as Record;
+ const rest: Record = { ...source };
+ let resolved = path;
+ for (const param of params) {
+ const value = rest[param];
+ if (value === undefined) {
+ throw new Error(`Missing required path param "${param}" for route "${path}"`);
+ }
+ resolved = resolved.replace(`:${param}`, encodeURIComponent(value as string));
+ delete rest[param];
+ }
+ return { path: resolved, rest };
+}
diff --git a/clients/typescript/packages/client/src/pipeline.ts b/clients/typescript/packages/client/src/pipeline.ts
new file mode 100644
index 0000000..de6c8fd
--- /dev/null
+++ b/clients/typescript/packages/client/src/pipeline.ts
@@ -0,0 +1,96 @@
+import type { AnyRouteContext } from "./context";
+import type { LimenError } from "./errors";
+import { camelizeEach } from "./helpers";
+import { resolvePath } from "./path";
+import type { FetchInit } from "./plugin";
+import type { AnyRoute, HttpRunner, RouteCallOptions } from "./route";
+import { defaultSerialize } from "./serialize";
+import type { Session } from "./types";
+
+/**
+ * Run the default HTTP steps for a route — merge defaults, resolve path params,
+ * serialize, dispatch, parse — without applying session effects.
+ */
+async function runHttp(ctx: AnyRouteContext, def: AnyRoute, input: unknown): Promise {
+ let merged = input;
+ if (def.defaults !== undefined) {
+ merged = { ...(def.defaults as Record), ...((input ?? {}) as Record) };
+ }
+
+ const { path, rest } = resolvePath(def.path, def.params, merged);
+ const payload = def.serialize !== undefined ? def.serialize(rest) : defaultSerialize(rest);
+
+ const init: FetchInit = { method: def.method, absolute: def.absolute ?? false };
+ if (def.method === "GET" && payload !== undefined) {
+ init.query = payload as Record;
+ } else {
+ init.body = payload;
+ }
+
+ const raw = await ctx.fetch(path, init);
+
+ if (def.parseSession === true) {
+ return ctx.parseSession(raw);
+ }
+
+ if (def.parse !== undefined) {
+ return def.parse(raw);
+ }
+ return Array.isArray(raw) ? camelizeEach(raw) : raw;
+}
+
+async function applyEffects(ctx: AnyRouteContext, def: AnyRoute, result: unknown): Promise {
+ if (def.clearSession === true) {
+ ctx.store.setData(null);
+ }
+
+ if (def.parseSession === true && def.skipStore !== true) {
+ if (result !== null && typeof result === "object" && "user" in result) {
+ ctx.store.setData(result as Session);
+ }
+ }
+
+ if (def.refetchSession === true) {
+ await ctx.store.refetch();
+ }
+}
+
+function makeHttpRunner(ctx: AnyRouteContext, def: AnyRoute, boundInput: unknown): HttpRunner {
+ const run = (override?: unknown): Promise =>
+ runHttp(ctx, def, override === undefined ? boundInput : override);
+ return run as HttpRunner;
+}
+
+/**
+ * Execute a route's behaviour: delegate to its `handler` when present (handler
+ * owns all behaviour, including any effects), otherwise run the default
+ * pipeline and apply declarative effects once at the top level.
+ */
+async function dispatchRoute(ctx: AnyRouteContext, def: AnyRoute, input: unknown): Promise {
+ if (def.handler !== undefined) {
+ return def.handler(ctx, input, makeHttpRunner(ctx, def, input));
+ }
+ const result = await runHttp(ctx, def, input);
+ await applyEffects(ctx, def, result);
+ return result;
+}
+
+/**
+ * Run a route as a public client call, firing the per-call `onSuccess` /
+ * `onError` hooks around the resolved value or thrown error.
+ */
+export async function runRoute(
+ ctx: AnyRouteContext,
+ def: AnyRoute,
+ input: unknown,
+ opts?: RouteCallOptions,
+): Promise {
+ try {
+ const result = await dispatchRoute(ctx, def, input);
+ opts?.onSuccess?.(result);
+ return result;
+ } catch (error) {
+ opts?.onError?.(error as LimenError);
+ throw error;
+ }
+}
diff --git a/clients/typescript/packages/client/src/plugin.ts b/clients/typescript/packages/client/src/plugin.ts
new file mode 100644
index 0000000..364c901
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugin.ts
@@ -0,0 +1,87 @@
+import type { KebabToCamel } from "./type-utils";
+import type { HTTPMethod } from "./types";
+
+/**
+ * Route filter for hooks. Matches the stable route path, so client overrides do
+ * not change which hooks run.
+ */
+export type RouteMatcher = string | readonly string[] | ((ctx: { path: string }) => boolean);
+
+/**
+ * Mutable request context passed to `beforeRequest` hooks. Return the updated
+ * context, or throw to abort the request.
+ */
+export type RequestContext = {
+ method: HTTPMethod;
+ /** Path relative to `baseURL` (already includes the configured `basePath`). */
+ fullPath: string;
+ /** Path relative to the client `basePath`. */
+ path: string;
+ /** Stable route identifier, unaffected by client overrides. */
+ routePath: string;
+ /** Full request URL. */
+ url: string;
+ headers: Headers;
+ body: unknown;
+};
+
+/**
+ * Mutable response context passed to `afterResponse` hooks. The body has
+ * already been envelope-unwrapped.
+ */
+export type ResponseContext = Omit & {
+ /** Status code. */
+ status: number;
+ /** Whether the response is successful. */
+ ok: boolean;
+};
+
+export type BeforeRequestHook = {
+ /** Optional route filter. Omit to run for every request. */
+ match?: RouteMatcher;
+ run: (req: RequestContext) => RequestContext | Promise;
+};
+
+export type AfterResponseHook = {
+ match?: RouteMatcher;
+ /** Run even for failed responses. */
+ allowOnFailure?: boolean;
+ run: (res: ResponseContext) => ResponseContext | Promise;
+};
+
+/**
+ * Request and response hooks contributed by a plugin.
+ */
+export type PluginHooks = {
+ beforeRequest?: BeforeRequestHook[];
+ afterResponse?: AfterResponseHook[];
+};
+
+/** Options accepted by `ctx.fetch(path, init)`. */
+export type FetchInit = {
+ method?: HTTPMethod;
+ /** JSON body. The fetcher stringifies. */
+ body?: unknown;
+ /** Appended as `?k=v` query string. */
+ query?: Record;
+ /** Extra headers to merge with the defaults (`Content-Type`, `Accept`). */
+ headers?: HeadersInit;
+ /**
+ * Resolve `path` from the client base path instead of the plugin base path.
+ */
+ absolute?: boolean;
+};
+
+export type PluginIdOf = P extends { readonly id: infer Id extends string } ? Id : never;
+
+export type PluginClientOverride = {
+ /** Replace the plugin's default base path (relative to the client `basePath`). */
+ basePath?: string;
+};
+
+/**
+ * Per-plugin client overrides, keyed by camelCased plugin id.
+ */
+export type PluginOverrides = Partial<
+ Record>, PluginClientOverride>
+>;
diff --git a/clients/typescript/packages/client/src/plugins/bearer/index.ts b/clients/typescript/packages/client/src/plugins/bearer/index.ts
new file mode 100644
index 0000000..5f91ed9
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/bearer/index.ts
@@ -0,0 +1,60 @@
+import { DEFAULT_TOKEN_STORAGE_KEY, SET_AUTH_TOKEN_HEADER, SET_REFRESH_TOKEN_HEADER } from "../../constants";
+import { defineClientPlugin, defineRoutes } from "../../define-plugin";
+import { resolveDefaultStorage } from "./storage";
+import type { BearerPluginConfig, BearerTokens } from "./types";
+
+export function bearerPlugin(config: BearerPluginConfig = {}) {
+ const store = config.storage ?? resolveDefaultStorage(config.storageKey ?? DEFAULT_TOKEN_STORAGE_KEY);
+
+ return defineClientPlugin({
+ id: "bearer",
+ routes: defineRoutes(),
+ actions: () => ({
+ bearer: {
+ getTokens: () => store.get(),
+ setTokens: (tokens: BearerTokens) => store.set(tokens),
+ clear: () => store.clear(),
+ },
+ }),
+ hooks: {
+ beforeRequest: [
+ {
+ run: (req) => {
+ const tokens = store.get();
+ if (tokens?.accessToken && !req.headers.has("Authorization")) {
+ req.headers.set("Authorization", `Bearer ${tokens.accessToken}`);
+ }
+ return req;
+ },
+ },
+ ],
+ afterResponse: [
+ {
+ allowOnFailure: true,
+ run: (res) => {
+ const accessToken = res.headers.get(SET_AUTH_TOKEN_HEADER);
+ if (accessToken) {
+ const tokens: BearerTokens = { accessToken };
+ const refreshToken = res.headers.get(SET_REFRESH_TOKEN_HEADER);
+ if (refreshToken) {
+ tokens.refreshToken = refreshToken;
+ }
+ store.set(tokens);
+ }
+ return res;
+ },
+ },
+ {
+ match: ["/signout", "/revoke-sessions"],
+ run: (res) => {
+ store.clear();
+ return res;
+ },
+ },
+ ],
+ },
+ });
+}
+
+export { localStorageBearerStorage, memoryBearerStorage, resolveDefaultStorage } from "./storage";
+export type { BearerPluginConfig, BearerPlugin as BearerPublic, BearerStorage, BearerTokens } from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/bearer/storage.ts b/clients/typescript/packages/client/src/plugins/bearer/storage.ts
new file mode 100644
index 0000000..706cec7
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/bearer/storage.ts
@@ -0,0 +1,48 @@
+import { DEFAULT_TOKEN_STORAGE_KEY } from "../../constants";
+import type { BearerStorage, BearerTokens } from "./types";
+
+export function memoryBearerStorage(): BearerStorage {
+ let tokens: BearerTokens | null = null;
+ return {
+ get: () => tokens,
+ set: (next) => {
+ tokens = next;
+ },
+ clear: () => {
+ tokens = null;
+ },
+ };
+}
+
+export function localStorageBearerStorage(key: string = DEFAULT_TOKEN_STORAGE_KEY): BearerStorage {
+ return {
+ get: () => {
+ try {
+ const raw = globalThis.localStorage.getItem(key);
+ if (!raw) {
+ return null;
+ }
+ const parsed = JSON.parse(raw) as Partial;
+ if (typeof parsed?.accessToken !== "string") {
+ return null;
+ }
+ return parsed as BearerTokens;
+ } catch {
+ return null;
+ }
+ },
+ set: (tokens) => {
+ globalThis.localStorage.setItem(key, JSON.stringify(tokens));
+ },
+ clear: () => {
+ globalThis.localStorage.removeItem(key);
+ },
+ };
+}
+
+export function resolveDefaultStorage(key: string): BearerStorage {
+ if (typeof globalThis.localStorage !== "undefined") {
+ return localStorageBearerStorage(key);
+ }
+ return memoryBearerStorage();
+}
diff --git a/clients/typescript/packages/client/src/plugins/bearer/types.ts b/clients/typescript/packages/client/src/plugins/bearer/types.ts
new file mode 100644
index 0000000..56efd1f
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/bearer/types.ts
@@ -0,0 +1,34 @@
+export type BearerPlugin = {
+ bearer: {
+ /** Currently stored tokens, or `null` if signed out / never set. */
+ getTokens: () => BearerTokens | null;
+ /** Manually persist tokens. */
+ setTokens: (tokens: BearerTokens) => void;
+ /** Discard stored tokens. Also runs automatically on `signOut`. */
+ clear: () => void;
+ };
+};
+
+export type BearerTokens = {
+ accessToken: string;
+ refreshToken?: string;
+};
+
+export interface BearerStorage {
+ get(): BearerTokens | null;
+ set(tokens: BearerTokens): void;
+ clear(): void;
+}
+
+export type BearerPluginConfig = {
+ /**
+ * Where to persist tokens. Defaults to `localStorage` when available,
+ * otherwise an in-memory store (SSR / non-browser).
+ */
+ storage?: BearerStorage;
+ /**
+ * Key used by the default `localStorage` adapter. Ignored when a custom
+ * `storage` is supplied. Defaults to `"limen.tokens"`.
+ */
+ storageKey?: string;
+};
diff --git a/clients/typescript/packages/client/src/plugins/credential/index.ts b/clients/typescript/packages/client/src/plugins/credential/index.ts
new file mode 100644
index 0000000..5968f5c
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/credential/index.ts
@@ -0,0 +1,76 @@
+import { defineClientPlugin, defineRoutes } from "../../define-plugin";
+import { route } from "../../route";
+import type { Session } from "../../types";
+import type {
+ ChangePasswordInput,
+ CheckUsernameInput,
+ RequestPasswordResetInput,
+ ResetPasswordInput,
+ SetPasswordInput,
+ SignInCredentialInput,
+ SignUpCredentialInput,
+} from "./types";
+
+export function credentialPasswordPlugin() {
+ const routes = defineRoutes(
+ route>()({
+ method: "POST",
+ path: "/signin/credential",
+ parseSession: true,
+ as: "signIn.credential",
+ defaults: { rememberMe: true },
+ }),
+ route>()({
+ method: "POST",
+ path: "/signup/credential",
+ parseSession: true,
+ as: "signUp.credential",
+ }),
+ route()({
+ method: "POST",
+ path: "/passwords/request-reset",
+ as: "password.requestReset",
+ }),
+ route()({
+ method: "POST",
+ path: "/passwords/reset",
+ as: "password.reset",
+ }),
+ route>()({
+ method: "POST",
+ path: "/passwords/change",
+ parseSession: true,
+ defaults: { revokeOtherSessions: true },
+ as: "password.change",
+ }),
+ route>()({
+ method: "PUT",
+ path: "/passwords",
+ as: "password.set",
+ parseSession: true,
+ defaults: { revokeOtherSessions: true },
+ }),
+ route()({
+ method: "POST",
+ path: "/usernames/check",
+ parse: (raw) => (raw as { available: boolean }).available,
+ as: "username.checkAvailability",
+ }),
+ );
+
+ return defineClientPlugin({
+ id: "credential-password",
+ basePath: "/",
+ routes,
+ });
+}
+
+export type {
+ ChangePasswordInput,
+ CheckUsernameInput,
+ RequestPasswordResetInput,
+ ResetPasswordInput,
+ SetPasswordInput,
+ SignInCredentialInput,
+ SignUpCredentialInput,
+} from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/credential/types.ts b/clients/typescript/packages/client/src/plugins/credential/types.ts
new file mode 100644
index 0000000..d3e288d
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/credential/types.ts
@@ -0,0 +1,44 @@
+export type SignInCredentialInput = {
+ /** Email or username, depending on what the server enables. */
+ credential: string;
+ password: string;
+ /** When true (default), issues a long-lived session. */
+ rememberMe?: boolean;
+};
+
+export type SignUpCredentialInput = {
+ email: string;
+ password: string;
+ /** Required when username-on-signup is enabled. */
+ username?: string;
+ /** Optional profile fields the server records on the user. */
+ firstname?: string;
+ lastname?: string;
+ /** Extra fields recorded on the user at registration. */
+ additionalFields?: Record;
+};
+
+export type ChangePasswordInput = {
+ currentPassword: string;
+ newPassword: string;
+ /** Invalidate other sessions on success. Defaults to true. */
+ revokeOtherSessions?: boolean;
+};
+
+export type SetPasswordInput = {
+ newPassword: string;
+ revokeOtherSessions?: boolean;
+};
+
+export type RequestPasswordResetInput = {
+ email: string;
+};
+
+export type ResetPasswordInput = {
+ token: string;
+ newPassword: string;
+};
+
+export type CheckUsernameInput = {
+ username: string;
+};
diff --git a/clients/typescript/packages/client/src/plugins/index.ts b/clients/typescript/packages/client/src/plugins/index.ts
new file mode 100644
index 0000000..7e93685
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/index.ts
@@ -0,0 +1,6 @@
+export * from "./bearer";
+export * from "./credential";
+export * from "./magic-link";
+export * from "./oauth";
+export * from "./session-jwt";
+export * from "./two-factor";
diff --git a/clients/typescript/packages/client/src/plugins/magic-link/index.ts b/clients/typescript/packages/client/src/plugins/magic-link/index.ts
new file mode 100644
index 0000000..bb0d31f
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/magic-link/index.ts
@@ -0,0 +1,26 @@
+import { defineClientPlugin, defineRoutes } from "../../define-plugin";
+import { route } from "../../route";
+import type { Session } from "../../types";
+import type { RequestMagicLinkInput, VerifyMagicLinkInput } from "./types";
+
+export function magicLinkPlugin() {
+ const routes = defineRoutes(
+ route()({
+ method: "POST",
+ path: "/signin",
+ }),
+ route>()({
+ method: "GET",
+ path: "/verify",
+ parseSession: true,
+ }),
+ );
+
+ return defineClientPlugin({
+ id: "magic-link",
+ basePath: "/magic-link",
+ routes,
+ });
+}
+
+export type { RequestMagicLinkInput, VerifyMagicLinkInput } from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/magic-link/types.ts b/clients/typescript/packages/client/src/plugins/magic-link/types.ts
new file mode 100644
index 0000000..e5758b2
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/magic-link/types.ts
@@ -0,0 +1,11 @@
+export type RequestMagicLinkInput = {
+ email: string;
+ redirectUri?: string;
+ newUserRedirectUri?: string;
+ errorRedirectUri?: string;
+ meta?: Record;
+};
+
+export type VerifyMagicLinkInput = {
+ token: string;
+};
diff --git a/clients/typescript/packages/client/src/plugins/oauth/index.ts b/clients/typescript/packages/client/src/plugins/oauth/index.ts
new file mode 100644
index 0000000..e87bacc
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/oauth/index.ts
@@ -0,0 +1,69 @@
+import { defineClientPlugin, defineRoutes } from "../../define-plugin";
+import { camelizeKeys } from "../../helpers";
+import { route, type RouteHandler } from "../../route";
+import type { LinkOAuthInput, OAuthAccount, OAuthAuthorizeResult, OAuthTokens, SignInOAuthInput } from "./types";
+
+const fetchThenRedirect: RouteHandler = async (ctx, input, http) => {
+ const { disableRedirect, ...rest } = input;
+ const { url } = await http<{ url: string }>(rest);
+ return { url, redirect: disableRedirect === true ? false : ctx.redirect(url) };
+};
+
+export function oauthClientPlugin() {
+ const routes = defineRoutes(
+ route()({
+ method: "GET",
+ path: "/:provider/authorize",
+ as: "signIn.social",
+ params: ["provider"],
+ handler: fetchThenRedirect,
+ }),
+ route()({
+ method: "GET",
+ path: "/:provider/link",
+ as: "social.link",
+ params: ["provider"],
+ handler: fetchThenRedirect,
+ }),
+ route<{ provider: string }, void>()({
+ method: "DELETE",
+ path: "/:provider/unlink",
+ as: "social.unlink",
+ params: ["provider"],
+ }),
+ route()({
+ method: "GET",
+ path: "/accounts",
+ as: "social.accounts",
+ }),
+ route<{ provider: string }, OAuthTokens>()({
+ method: "GET",
+ path: "/:provider/tokens",
+ as: "social.tokens",
+ params: ["provider"],
+ parse: camelizeKeys,
+ }),
+ route<{ provider: string }, OAuthTokens>()({
+ method: "POST",
+ path: "/:provider/tokens/refresh",
+ as: "social.refreshTokens",
+ params: ["provider"],
+ parse: camelizeKeys,
+ }),
+ );
+
+ return defineClientPlugin({
+ id: "oauth",
+ basePath: "/oauth",
+ routes,
+ });
+}
+
+export type {
+ LinkOAuthInput,
+ OAuthAccount,
+ OAuthAuthorizeQuery,
+ OAuthAuthorizeResult,
+ OAuthTokens,
+ SignInOAuthInput,
+} from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/oauth/types.ts b/clients/typescript/packages/client/src/plugins/oauth/types.ts
new file mode 100644
index 0000000..89f82bf
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/oauth/types.ts
@@ -0,0 +1,42 @@
+export type OAuthAuthorizeQuery = {
+ /** Where the server redirects the browser after a successful callback. */
+ redirectUri?: string;
+ /** Where the server redirects on a failed callback. Falls back to `redirectUri`. */
+ errorRedirectUri?: string;
+};
+
+export type SignInOAuthInput = OAuthAuthorizeQuery & {
+ /** Provider id, e.g. `"google"` or `"github"`. */
+ provider: string;
+ /**
+ * When true, skip auto-navigation and only resolve with the authorization
+ * URL — the caller is responsible for navigating the browser.
+ */
+ disableRedirect?: boolean;
+};
+
+export type LinkOAuthInput = SignInOAuthInput;
+
+export type OAuthAuthorizeResult = {
+ /** Provider authorization URL. */
+ url: string;
+ /** Whether the SDK navigated to `url`. */
+ redirect: boolean;
+};
+
+export type OAuthAccount = {
+ provider: string;
+ providerAccountId: string;
+ scopes: string[];
+ accessTokenExpiresAt?: string;
+ createdAt: string;
+ updatedAt: string;
+};
+
+export type OAuthTokens = {
+ accessToken: string;
+ refreshToken?: string;
+ idToken?: string;
+ accessTokenExpiresAt?: string;
+ scope?: string;
+};
diff --git a/clients/typescript/packages/client/src/plugins/session-jwt/constants.ts b/clients/typescript/packages/client/src/plugins/session-jwt/constants.ts
new file mode 100644
index 0000000..b012e1a
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/session-jwt/constants.ts
@@ -0,0 +1,2 @@
+/** Refresh once the access token is within this many seconds of its `exp`. */
+export const DEFAULT_EXPIRY_SKEW_SECONDS = 30;
diff --git a/clients/typescript/packages/client/src/plugins/session-jwt/index.ts b/clients/typescript/packages/client/src/plugins/session-jwt/index.ts
new file mode 100644
index 0000000..55b9df1
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/session-jwt/index.ts
@@ -0,0 +1,134 @@
+import { DEFAULT_TOKEN_STORAGE_KEY } from "../../constants";
+import type { AnyRouteContext } from "../../context";
+import { defineClientPlugin, defineRoutes, type RunRoute } from "../../define-plugin";
+import { LimenError } from "../../errors";
+import { route } from "../../route";
+import type { Session } from "../../types";
+import { resolveDefaultStorage } from "../bearer";
+import { DEFAULT_EXPIRY_SKEW_SECONDS } from "./constants";
+import { isExpiring, tokensFromHeaders } from "./jwt";
+import type { RefreshInput, SessionJwtPluginConfig, SessionJwtTokens } from "./types";
+
+export function sessionJwtPlugin(config: SessionJwtPluginConfig = {}) {
+ const store = config.storage ?? resolveDefaultStorage(config.storageKey ?? DEFAULT_TOKEN_STORAGE_KEY);
+ const skewMs = (config.expirySkewSeconds ?? DEFAULT_EXPIRY_SKEW_SECONDS) * 1000;
+
+ const refreshRoute = route>()({
+ method: "POST",
+ path: "/refresh",
+ parseSession: true,
+ expose: false,
+ });
+
+ let ctx!: AnyRouteContext;
+ let run!: RunRoute;
+ let inFlight: Promise | null = null;
+
+ const runRefresh = async (): Promise => {
+ const current = store.get();
+ if (!current?.refreshToken) {
+ throw new LimenError("No refresh token found", 401, "unauthorized");
+ }
+ try {
+ await run(refreshRoute, { refreshToken: current.refreshToken });
+ const tokens = store.get();
+ if (!tokens?.accessToken) {
+ throw new LimenError("Refresh did not return a valid access token", 500, "unknown");
+ }
+ return tokens;
+ } catch (err) {
+ store.clear();
+ ctx.setSession(null);
+ throw err;
+ }
+ };
+
+ const refresh = (): Promise => {
+ if (!inFlight) {
+ inFlight = runRefresh().finally(() => {
+ inFlight = null;
+ });
+ }
+ return inFlight;
+ };
+
+ const getAccessToken = async (): Promise => {
+ const current = store.get();
+ if (!current?.accessToken) {
+ return null;
+ }
+
+ if (!isExpiring(current.accessToken, skewMs)) {
+ return current.accessToken;
+ }
+
+ if (!current.refreshToken) {
+ return null;
+ }
+ return (await refresh()).accessToken;
+ };
+
+ const applyAuthHeader = async (req: { headers: Headers }): Promise => {
+ if (req.headers.has("Authorization")) {
+ return;
+ }
+ const token = await getAccessToken().catch(() => null);
+ if (token) {
+ req.headers.set("Authorization", `Bearer ${token}`);
+ }
+ };
+
+ return defineClientPlugin({
+ id: "session-jwt",
+ routes: defineRoutes(refreshRoute),
+ actions: (pluginCtx, pluginRun) => {
+ ctx = pluginCtx;
+ run = pluginRun;
+ return {
+ sessionJwt: {
+ /**
+ * Get the current access token. If the token is expiring, refresh it.
+ * @returns The current access token or null if no token is found.
+ */
+ getAccessToken,
+ refresh,
+ getTokens: () => store.get(),
+ clear: () => store.clear(),
+ },
+ };
+ },
+ hooks: {
+ beforeRequest: [
+ {
+ match: (route) => route.path !== "/refresh",
+ run: async (req) => {
+ await applyAuthHeader(req);
+ return req;
+ },
+ },
+ ],
+ afterResponse: [
+ {
+ allowOnFailure: true,
+ run: (res) => {
+ const tokens = tokensFromHeaders(res.headers);
+ if (tokens) {
+ store.set(tokens);
+ }
+ return res;
+ },
+ },
+ {
+ match: ["/signout", "/revoke-sessions"],
+ allowOnFailure: true,
+ run: (res) => {
+ store.clear();
+ return res;
+ },
+ },
+ ],
+ },
+ });
+}
+
+export type { SessionJwtPluginConfig, SessionJwtTokens } from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/session-jwt/jwt.ts b/clients/typescript/packages/client/src/plugins/session-jwt/jwt.ts
new file mode 100644
index 0000000..befbbfc
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/session-jwt/jwt.ts
@@ -0,0 +1,44 @@
+import { SET_AUTH_TOKEN_HEADER, SET_REFRESH_TOKEN_HEADER } from "../../constants";
+import type { SessionJwtTokens } from "./types";
+
+/**
+ * Read the `exp` (seconds since epoch) from a JWT without verifying its
+ * signature — the server is the source of truth; the client only needs expiry
+ * to decide when to refresh. Returns `null` for anything malformed.
+ */
+export function decodeJwtExp(token: string): number | null {
+ const payload = token.split(".")[1];
+ if (!payload) {
+ return null;
+ }
+ try {
+ const b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+ const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+ const claims = JSON.parse(atob(padded)) as { exp?: unknown };
+ return typeof claims.exp === "number" ? claims.exp : null;
+ } catch {
+ return null;
+ }
+}
+
+export function isExpiring(token: string, skewMs: number): boolean {
+ const exp = decodeJwtExp(token);
+ if (exp === null) {
+ return true;
+ }
+ return exp * 1000 - skewMs <= Date.now();
+}
+
+export function tokensFromHeaders(headers: Headers): SessionJwtTokens | null {
+ const accessToken = headers.get(SET_AUTH_TOKEN_HEADER);
+ if (!accessToken) {
+ return null;
+ }
+
+ const tokens: SessionJwtTokens = { accessToken };
+ const refreshToken = headers.get(SET_REFRESH_TOKEN_HEADER);
+ if (refreshToken) {
+ tokens.refreshToken = refreshToken;
+ }
+ return tokens;
+}
diff --git a/clients/typescript/packages/client/src/plugins/session-jwt/types.ts b/clients/typescript/packages/client/src/plugins/session-jwt/types.ts
new file mode 100644
index 0000000..2da76e3
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/session-jwt/types.ts
@@ -0,0 +1,10 @@
+import type { BearerPluginConfig, BearerTokens } from "../bearer";
+
+export type SessionJwtTokens = BearerTokens;
+
+export type SessionJwtPluginConfig = BearerPluginConfig & {
+ /** Refresh once the access token is within this many seconds of expiry. Default 30. */
+ expirySkewSeconds?: number;
+};
+
+export type RefreshInput = { refreshToken: string };
diff --git a/clients/typescript/packages/client/src/plugins/two-factor/index.ts b/clients/typescript/packages/client/src/plugins/two-factor/index.ts
new file mode 100644
index 0000000..5d7711a
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/two-factor/index.ts
@@ -0,0 +1,87 @@
+import { defineClientPlugin, defineRoutes } from "../../define-plugin";
+import { route } from "../../route";
+import type { Session } from "../../types";
+import type {
+ DisableTwoFactorInput,
+ FinalizeSetupInput,
+ InitiateSetupInput,
+ SendOTPInput,
+ TwoFactorConfig,
+ TwoFactorSetupURI,
+ VerifyInput,
+} from "./types";
+
+export function twoFactorPlugin(config: TwoFactorConfig) {
+ const routes = defineRoutes(
+ route()({
+ method: "POST",
+ path: "/initiate-setup",
+ }),
+ route>()({
+ method: "POST",
+ path: "/finalize-setup",
+ parseSession: true,
+ }),
+ route>()({
+ method: "POST",
+ path: "/disable",
+ parseSession: true,
+ }),
+ route>()({
+ method: "POST",
+ path: "/verify",
+ parseSession: true,
+ }),
+ route()({
+ method: "GET",
+ path: "/totp/uri",
+ as: "twoFactor.getTotpUri",
+ }),
+ route()({
+ method: "GET",
+ path: "/backup-codes",
+ as: "twoFactor.getBackupCodes",
+ }),
+ route()({
+ method: "PUT",
+ path: "/backup-codes",
+ as: "twoFactor.regenerateBackupCodes",
+ }),
+ route()({
+ method: "POST",
+ path: "/otp/send",
+ as: "twoFactor.sendOTP",
+ }),
+ );
+
+ return defineClientPlugin({
+ id: "two-factor",
+ basePath: "/two-factor",
+ routes,
+ hooks: {
+ afterResponse: [
+ {
+ match: "/signin/credential",
+ run: (ctx) => {
+ const body = ctx.body as Record;
+ if (body["two_factor_required"] === true) {
+ config.onTwoFactorRedirect();
+ }
+ return ctx;
+ },
+ },
+ ],
+ },
+ });
+}
+
+export type {
+ DisableTwoFactorInput,
+ FinalizeSetupInput,
+ InitiateSetupInput,
+ SendOTPInput,
+ TwoFactorConfig,
+ TwoFactorMethod,
+ TwoFactorSetupURI,
+ VerifyInput,
+} from "./types";
diff --git a/clients/typescript/packages/client/src/plugins/two-factor/types.ts b/clients/typescript/packages/client/src/plugins/two-factor/types.ts
new file mode 100644
index 0000000..b29eaed
--- /dev/null
+++ b/clients/typescript/packages/client/src/plugins/two-factor/types.ts
@@ -0,0 +1,31 @@
+export type TwoFactorConfig = {
+ /** Called when sign-in requires a two-factor challenge. */
+ onTwoFactorRedirect: () => void;
+};
+
+export type VerifyInput = {
+ code: string;
+ method?: TwoFactorMethod;
+};
+
+export type InitiateSetupInput = {
+ password: string;
+};
+
+export type FinalizeSetupInput = {
+ code: string;
+};
+
+export type DisableTwoFactorInput = {
+ password: string;
+};
+
+export type SendOTPInput = {
+ email: string;
+};
+
+export type TwoFactorSetupURI = {
+ uri: string;
+};
+
+export type TwoFactorMethod = "totp" | "otp";
diff --git a/clients/typescript/packages/client/src/react/index.ts b/clients/typescript/packages/client/src/react/index.ts
new file mode 100644
index 0000000..abbeff3
--- /dev/null
+++ b/clients/typescript/packages/client/src/react/index.ts
@@ -0,0 +1,35 @@
+import { createAuthClient as createCoreClient } from "../client";
+import type { AnyClientPlugin } from "../define-plugin";
+import type { SessionState } from "../session-store";
+import type { Prettify } from "../type-utils";
+import type { AuthClient, CreateAuthClientOptions } from "../types";
+import { useStore } from "./react-store";
+
+/**
+ * An {@link AuthClient} augmented with React hooks.
+ */
+export type ReactAuthClient = Prettify<
+ AuthClient & {
+ /**
+ * Reactively read the session store. Re-renders the component whenever
+ * `{ data, isPending, error }` changes.
+ */
+ useSession: () => SessionState;
+ }
+>;
+
+/**
+ * Create a Limen auth client with React hooks attached.
+ */
+export function createAuthClient(
+ opts: CreateAuthClientOptions,
+): ReactAuthClient {
+ const client = createCoreClient(opts);
+ const useSession = (): SessionState => useStore(client.$session);
+
+ return Object.assign(client, { useSession }) as ReactAuthClient;
+}
+
+export type { SessionState, SessionStore } from "../session-store";
+export type { AuthClient, CreateAuthClientOptions, Session, User } from "../types";
+export { useStore } from "./react-store";
diff --git a/clients/typescript/packages/client/src/react/react-store.ts b/clients/typescript/packages/client/src/react/react-store.ts
new file mode 100644
index 0000000..832abe2
--- /dev/null
+++ b/clients/typescript/packages/client/src/react/react-store.ts
@@ -0,0 +1,29 @@
+import type { Store, StoreValue } from "nanostores";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+export function useStore(store: SomeStore): StoreValue {
+ type Value = StoreValue;
+
+ const snapshotRef = useRef(store.get());
+
+ const subscribe = useCallback(
+ (onChange: () => void) => {
+ const emitValue = (value: Value): void => {
+ if (snapshotRef.current === value) {
+ return;
+ }
+ snapshotRef.current = value;
+ onChange();
+ };
+ // Resync before listening: the value may have changed between render and
+ // this effect, and `listen` does not fire for the current value.
+ emitValue(store.value);
+ return store.listen(emitValue);
+ },
+ [store],
+ );
+
+ const get = (): Value => snapshotRef.current as Value;
+
+ return useSyncExternalStore(subscribe, get, get);
+}
diff --git a/clients/typescript/packages/client/src/route.ts b/clients/typescript/packages/client/src/route.ts
new file mode 100644
index 0000000..e2543fd
--- /dev/null
+++ b/clients/typescript/packages/client/src/route.ts
@@ -0,0 +1,113 @@
+import type { RouteContext } from "./context";
+import type { LimenError } from "./errors";
+import type { HTTPMethod } from "./types";
+
+declare const INPUT: unique symbol;
+declare const OUTPUT: unique symbol;
+
+/**
+ * Runs the route's default HTTP request and parser without session effects.
+ * Pass an input override when a handler needs to omit client-only fields.
+ */
+export type HttpRunner = (input?: I) => Promise;
+
+/**
+ * Custom route behavior for flows that need more than the default request
+ * pipeline.
+ */
+export type RouteHandler = (
+ ctx: RouteContext,
+ input: I,
+ http: HttpRunner,
+) => Promise;
+
+/**
+ * Per-call options accepted as the final argument of every generated route
+ * method.
+ */
+export type RouteCallOptions = {
+ /** Invoked with the resolved value after the call succeeds. */
+ onSuccess?: (data: O) => void;
+ /** Invoked with the error just before it is re-thrown. */
+ onError?: (error: LimenError) => void;
+};
+
+/**
+ * Declarative client route definition. The public client chain is derived from
+ * `path` unless `as` is provided.
+ */
+export type RouteDef = {
+ method: HTTPMethod;
+ path: `/${string}`;
+
+ /** Dotted client chain override, e.g. `"twoFactor.getTotpUri"`. */
+ as?: string;
+
+ /** Merged under the caller's input before serialization. */
+ defaults?: Partial;
+ /** SDK input → wire body/query. Defaults to shallow camelCase → snake_case. */
+ serialize?: (input: I) => unknown;
+ /** Raw response → typed output. Ignored when `parseSession` is set. */
+ parse?: (raw: unknown) => O;
+ /**
+ * Parse the response as a session and store it when it contains a `user`.
+ * Set `skipStore` to return the parsed session without writing it.
+ */
+ parseSession?: boolean;
+ /** Resolve `path` from the client base path instead of the plugin base path. */
+ absolute?: boolean;
+
+ /** Input keys used as `:param` path values. */
+ params?: readonly (keyof I & string)[];
+
+ /** For `parseSession` routes, skip the session-store write. */
+ skipStore?: boolean;
+ /** Clear the session store on success. */
+ clearSession?: boolean;
+ /** Revalidate the session after success. */
+ refetchSession?: boolean;
+
+ /** Set `false` to keep the route out of the public client API. */
+ expose?: boolean;
+
+ /** Override the default route call behavior. */
+ handler?: RouteHandler;
+};
+
+/**
+ * A route definition carrying its input and output types for inference.
+ */
+export type RouteDescriptor = RouteDef> = D & {
+ readonly [INPUT]: I;
+ readonly [OUTPUT]: O;
+};
+
+/**
+ * Loose route-descriptor constraint for route tuples and plugin definitions.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- accepts any route descriptor
+export type AnyRouteDescriptor = RouteDescriptor;
+
+/**
+ * Route definition with erased input/output types but typed fields.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- erases route I/O only
+export type AnyRoute = RouteDef;
+
+export type InputOf = R extends { readonly [INPUT]: infer I } ? I : never;
+export type OutputOf = R extends { readonly [OUTPUT]: infer O } ? O : never;
+
+/**
+ * Define an HTTP-backed client method for a plugin. The input/output types
+ * become the generated method's argument and resolved value.
+ *
+ * @example
+ * route>()({
+ * method: "POST",
+ * path: "/verify",
+ * parseSession: true,
+ * })
+ */
+export function route() {
+ return >(def: D): RouteDescriptor => def as RouteDescriptor;
+}
diff --git a/clients/typescript/packages/client/src/routes.ts b/clients/typescript/packages/client/src/routes.ts
new file mode 100644
index 0000000..e90a6b8
--- /dev/null
+++ b/clients/typescript/packages/client/src/routes.ts
@@ -0,0 +1,89 @@
+import type { RouteContext } from "./context";
+import type { InferPluginContribution } from "./define-plugin";
+import { defineClientPlugin, defineRoutes } from "./define-plugin";
+import { route } from "./route";
+import type { Session } from "./types";
+
+export type VerifyEmailInput = {
+ token: string;
+};
+
+export type ActiveSession = {
+ id: string | number;
+ token: string;
+ userId: unknown;
+ createdAt: string;
+ expiresAt: string;
+ lastAccess: string;
+ metadata?: Record;
+};
+
+/**
+ * Core routes available on every client.
+ */
+export function coreClientPlugin() {
+ const routes = defineRoutes(
+ route()({
+ method: "GET",
+ path: "/sessions",
+ }),
+ route()({
+ method: "POST",
+ path: "/signout",
+ clearSession: true,
+ }),
+ route()({
+ method: "POST",
+ path: "/revoke-sessions",
+ clearSession: true,
+ }),
+ route()({
+ method: "POST",
+ path: "/verify-email",
+ refetchSession: true,
+ }),
+ route()({
+ method: "POST",
+ path: "/email-verifications",
+ as: "requestEmailVerification",
+ }),
+ );
+
+ return defineClientPlugin({
+ id: "core",
+ basePath: "/",
+ routes,
+ actions: (ctx) => ({
+ /**
+ * Revalidate session state with `GET /me`, update `$session`, and return the
+ * resolved value (`null` when signed out).
+ *
+ * Prefer subscribing to `$session` for reactive UI state (`data`, `isPending`,
+ * `error`). Use `getSession()` when you need an awaited server re-check, such
+ * as route guards or SSR revalidation after `initialSession`.
+ */
+ getSession: async (): Promise | null> => {
+ await ctx.refetchSession();
+ const state = ctx.store.$session.get();
+ if (state.error) {
+ throw state.error;
+ }
+ return state.data as Session | null;
+ },
+ }),
+ });
+}
+
+export type CoreContribution = InferPluginContribution>>;
+
+/**
+ * Fetch and parse the current session for the reactive store.
+ */
+export function createSessionHydrator(
+ ctx: Pick, "fetch" | "parseSession">,
+): () => Promise> {
+ return async () => {
+ const raw = await ctx.fetch("/me", { method: "GET" });
+ return ctx.parseSession(raw);
+ };
+}
diff --git a/clients/typescript/packages/client/src/serialize.ts b/clients/typescript/packages/client/src/serialize.ts
new file mode 100644
index 0000000..422cdaf
--- /dev/null
+++ b/clients/typescript/packages/client/src/serialize.ts
@@ -0,0 +1,31 @@
+import { camelToSnake } from "./helpers";
+
+/**
+ * Default request serializer: shallow camelCase → snake_case, drops `undefined`,
+ * leaves non-objects unchanged.
+ *
+ * `additionalFields` entries are merged into the top-level body verbatim.
+ * Known route fields win on key collisions.
+ */
+export function defaultSerialize(input: unknown): unknown {
+ if (input === null || input === undefined) {
+ return input;
+ }
+ if (typeof input !== "object" || Array.isArray(input)) {
+ return input;
+ }
+ const { additionalFields, ...rest } = input as Record;
+ const out: Record = {};
+
+ if (additionalFields && typeof additionalFields === "object" && !Array.isArray(additionalFields)) {
+ Object.assign(out, additionalFields);
+ }
+
+ for (const [key, value] of Object.entries(rest)) {
+ if (value === undefined) {
+ continue;
+ }
+ out[camelToSnake(key)] = value;
+ }
+ return out;
+}
diff --git a/clients/typescript/packages/client/src/session-store.ts b/clients/typescript/packages/client/src/session-store.ts
new file mode 100644
index 0000000..11524f2
--- /dev/null
+++ b/clients/typescript/packages/client/src/session-store.ts
@@ -0,0 +1,124 @@
+import { atom, onMount, type ReadableAtom } from "nanostores";
+import { LimenError } from "./errors";
+import { createSessionSync } from "./session-sync";
+import type { Session } from "./types";
+
+export type SessionState = {
+ /** The current session, or `null` when signed out. */
+ data: Session | null;
+ /** True while a `/me` fetch is in flight. */
+ isPending: boolean;
+ /**
+ * The last non-401 failure (network error, 5xx, etc.). A 401 is not an error
+ * — it resolves to `data: null`. `error` is cleared on the next successful or
+ * 401 outcome.
+ */
+ error: LimenError | null;
+};
+
+type RefetchOptions = {
+ /** Skip the fetch when the last hydration ran within this many milliseconds. */
+ maxAgeMs?: number;
+ /** Skip the fetch when the session is signed out. */
+ skipSignedOut?: boolean;
+};
+
+export type SessionStore = {
+ readonly $session: ReadableAtom>;
+ setData(session: Session | null): void;
+ /**
+ * Re-validate the session from the server.
+ */
+ refetch(options?: RefetchOptions): Promise;
+};
+
+type CreateSessionStoreArgs = {
+ hydrator: () => Promise>;
+ initialSession?: Session | null;
+ /** Mirror session changes to other same-origin tabs. */
+ crossTabSync?: boolean;
+ /** Re-validate against `/me` when the tab returns to the foreground. */
+ refetchOnWindowFocus?: boolean;
+};
+
+export function createSessionStore(options: CreateSessionStoreArgs): SessionStore {
+ const $session = atom>({
+ data: options.initialSession ?? null,
+ isPending: false,
+ error: null,
+ });
+
+ let inFlightHydration: Promise | null = null;
+ // Bumped on every write so older async refresh results cannot overwrite newer state.
+ let writeVersion = 0;
+ // Timestamp the most recent session refetched.
+ let lastRefreshedAt = 0;
+ const isStale = (requestVersion: number): boolean => requestVersion !== writeVersion;
+
+ const fetchSessionFromServer = async (): Promise => {
+ const requestVersion = ++writeVersion;
+ $session.set({ data: $session.get().data, isPending: true, error: null });
+ try {
+ const session = await options.hydrator();
+
+ if (isStale(requestVersion)) {
+ return;
+ }
+
+ $session.set({ data: session, isPending: false, error: null });
+ } catch (err) {
+ if (isStale(requestVersion)) {
+ return;
+ }
+
+ if (err instanceof LimenError && err.isUnauthorized) {
+ // Not an error — the user is simply signed out.
+ $session.set({ data: null, isPending: false, error: null });
+ return;
+ }
+
+ const error =
+ err instanceof LimenError
+ ? err
+ : new LimenError(err instanceof Error ? err.message : "Failed to load session", 0, "unknown");
+ // Preserve the last known session; surface the failure via `error`.
+ $session.set({ data: $session.get().data, isPending: false, error });
+ }
+ };
+
+ const refetch = (options?: RefetchOptions): Promise => {
+ const { skipSignedOut, maxAgeMs } = options ?? {};
+ if (skipSignedOut && $session.get().data === null) {
+ return Promise.resolve();
+ }
+
+ if (maxAgeMs !== undefined && Date.now() - lastRefreshedAt < maxAgeMs) {
+ return Promise.resolve();
+ }
+
+ if (!inFlightHydration) {
+ inFlightHydration = fetchSessionFromServer().finally(() => {
+ inFlightHydration = null;
+ lastRefreshedAt = Date.now();
+ });
+ }
+ return inFlightHydration;
+ };
+
+ const setData = (session: Session | null): void => {
+ writeVersion++; // supersede any in-flight hydrate so it can't overwrite this
+ $session.set({ data: session, isPending: false, error: null });
+ };
+
+ const store: SessionStore = { $session, setData, refetch };
+
+ onMount($session, () =>
+ createSessionSync(store, {
+ fetchOnMount: options.initialSession === undefined,
+ crossTabSync: options.crossTabSync ?? false,
+ refetchOnWindowFocus: options.refetchOnWindowFocus ?? false,
+ }),
+ );
+
+ return store;
+}
diff --git a/clients/typescript/packages/client/src/session-sync.ts b/clients/typescript/packages/client/src/session-sync.ts
new file mode 100644
index 0000000..19701e9
--- /dev/null
+++ b/clients/typescript/packages/client/src/session-sync.ts
@@ -0,0 +1,82 @@
+import { onNotify } from "nanostores";
+import { createBroadcastChannel } from "./broadcast-channel";
+import { deepJsonEqual } from "./json-deep-equal";
+import type { SessionStore } from "./session-store";
+import type { Session } from "./types";
+
+const CHANNEL_NAME = "limen.session";
+const FOCUS_REFETCH_THROTTLE_MS = 5_000;
+
+type SyncMessage = { data: Session | null };
+
+type SessionSyncOptions = {
+ /** Fetch the session on mount. */
+ fetchOnMount: boolean;
+ /** Mirror session changes to other same-origin tabs. */
+ crossTabSync: boolean;
+ /** Re-validate against `/me` when the tab returns to the foreground. */
+ refetchOnWindowFocus: boolean;
+};
+
+export function createSessionSync(
+ store: SessionStore,
+ options: SessionSyncOptions,
+): () => void {
+ if (options.fetchOnMount) {
+ void store.refetch();
+ }
+
+ const teardowns: Array<() => void> = [];
+ if (options.crossTabSync) {
+ teardowns.push(syncAcrossTabs(store));
+ }
+
+ if (options.refetchOnWindowFocus) {
+ teardowns.push(refetchOnFocus(store));
+ }
+
+ return () => {
+ for (const teardown of teardowns) {
+ teardown();
+ }
+ };
+}
+
+function syncAcrossTabs(store: SessionStore): () => void {
+ const port = createBroadcastChannel>(CHANNEL_NAME);
+ let lastData = store.$session.get().data;
+
+ const unsubscribe = port.subscribe((message) => {
+ // Mark remote updates as seen before applying them to avoid echoing them.
+ lastData = message.data;
+ store.setData(message.data);
+ });
+
+ const unbindNotify = onNotify(store.$session, () => {
+ const data = store.$session.get().data;
+ if (deepJsonEqual(data, lastData)) {
+ return;
+ }
+ lastData = data;
+ port.post({ data: data });
+ });
+
+ return () => {
+ unbindNotify();
+ unsubscribe();
+ port.close();
+ };
+}
+
+function refetchOnFocus(store: SessionStore): () => void {
+ if (typeof document === "undefined") {
+ return () => {};
+ }
+ const onVisibilityChange = (): void => {
+ if (document.visibilityState === "visible") {
+ void store.refetch({ maxAgeMs: FOCUS_REFETCH_THROTTLE_MS, skipSignedOut: true });
+ }
+ };
+ document.addEventListener("visibilitychange", onVisibilityChange);
+ return () => document.removeEventListener("visibilitychange", onVisibilityChange);
+}
diff --git a/clients/typescript/packages/client/src/solid/index.ts b/clients/typescript/packages/client/src/solid/index.ts
new file mode 100644
index 0000000..ad41c1d
--- /dev/null
+++ b/clients/typescript/packages/client/src/solid/index.ts
@@ -0,0 +1,36 @@
+import type { Accessor } from "solid-js";
+import { createAuthClient as createCoreClient } from "../client";
+import type { AnyClientPlugin } from "../define-plugin";
+import type { SessionState } from "../session-store";
+import type { Prettify } from "../type-utils";
+import type { AuthClient, CreateAuthClientOptions } from "../types";
+import { useStore } from "./solid-store";
+
+/**
+ * An {@link AuthClient} augmented with Solid primitives.
+ */
+export type SolidAuthClient = Prettify<
+ AuthClient & {
+ /**
+ * Reactively read the session store as a Solid accessor. Updates whenever
+ * `{ data, isPending, error }` changes.
+ */
+ useSession: () => Accessor>;
+ }
+>;
+
+/**
+ * Create a Limen auth client with Solid primitives attached.
+ */
+export function createAuthClient(
+ opts: CreateAuthClientOptions,
+): SolidAuthClient {
+ const client = createCoreClient(opts);
+ const useSession = (): Accessor
+
+
