@leavepulse/control-sdk 0.3.31

package/runtime/cache-policy.ts

@@ -0,0 +1,371 @@
+// LeavePulse SDK — CachePolicy.
+//
+// An OPTIONAL layer that sits ABOVE the identity map (cache.ts) and answers a
+// different question than the ETag store does. The ETag store (etag-store.ts)
+// answers "did the bytes change?" (HTTP 304). CachePolicy answers "is my entity
+// fresh enough, at this completeness level, that I can skip the network
+// entirely?" (TTL + levels). The two stack:
+//
+//   TTL-hit  → no request at all (zero RTT)
+//   TTL-miss → the caller's fetcher runs; a generated SDK GET already routes
+//              through fetchCached, so a 304 reuses the body — and CachePolicy
+//              then stamps a fresh TTL. So an unchanged entity is "fresh" again
+//              after one cheap 304, with no re-download.
+//
+// CachePolicy holds NO module-level state: it is handed a `PolicyState` whose
+// Records are owned by the consumer (e.g. Pinia `ref()`s), which keeps it
+// SSR-safe. It NEVER touches the network itself except inside `ensure()`, and
+// even there only via the caller-supplied fetcher — so sync getters stay
+// network-free (RFC 0001 §5).
+
+/** Caller-defined completeness levels, ranked by number (higher = more complete). */
+export interface PolicyConfig<TData, TLevel extends string> {
+	/** Identity-map type key, e.g. "Server". Informational; the policy keys by id. */
+	type: string;
+	/** Level → rank. e.g. `{ list: 1, profile: 2, manage: 3 }`. */
+	levels: Record<TLevel, number>;
+	/** Level → TTL in ms. e.g. `{ list: 60_000, profile: 300_000, manage: 180_000 }`. */
+	ttlMs: Record<TLevel, number>;
+	/** Extract the alias refs an entity can be addressed by (id/slug/domain/...). */
+	refs?: (data: TData) => string[];
+	/** Normalize a ref before indexing/lookup. Default: trim + lowercase. */
+	normalizeRef?: (ref: string) => string;
+	/** Shallow-merge incoming onto base, skipping `undefined`. Default below. */
+	merge?: (base: TData, incoming: Partial<TData>) => TData;
+	/** Default TTL for query/page entries when `setQuery` gets no override. */
+	queryTtlMs?: number;
+	/**
+	 * Optional readiness gate BEYOND level+TTL: whether a cached entry's payload
+	 * is rich enough to satisfy `level`. Lets a consumer demand specific fields
+	 * (e.g. a "profile" entry without `display_server` is incomplete, so re-fetch
+	 * even though its level/TTL pass). Returns `true` when ready. Default: always
+	 * ready (level+TTL alone decide).
+	 */
+	ready?: (data: TData, level: TLevel) => boolean;
+	/**
+	 * Fields to PRESERVE when a lower-level upsert lands on a higher-level entry,
+	 * keyed by the level that owns them. When merging e.g. a "list" payload onto
+	 * an entry already at "manage", the manage-owned fields are not clobbered by
+	 * the thinner payload. Returns the protected field names for a given level.
+	 */
+	protectedFields?: (level: TLevel) => readonly string[];
+}
+
+export interface PolicyEntry<TData, TLevel extends string> {
+	data: TData;
+	level: TLevel;
+	/** Per-level last-updated timestamp (ms). 0 = never. */
+	freshness: Record<TLevel, number>;
+}
+
+export interface QueryEntry {
+	ids: string[];
+	total: number;
+	page: number;
+	limit: number;
+	fetchedAt: number;
+	staleAt: number;
+}
+
+/**
+ * The backing state. The consumer owns these Records (e.g. as Pinia refs) so
+ * the policy stays SSR-safe and reactive — CachePolicy only reads/writes them.
+ */
+export interface PolicyState<TData, TLevel extends string> {
+	entities: Record<string, PolicyEntry<TData, TLevel>>;
+	refToId: Record<string, string>;
+	queries: Record<string, QueryEntry>;
+}
+
+export interface EnsureOptions<TLevel extends string> {
+	/** Minimum level the cached entry must satisfy to count as a hit. */
+	minLevel?: TLevel;
+	/** Level to stamp on the fetched result. Defaults to `minLevel`. */
+	level?: TLevel;
+	/** Force a fetch even if the cache is fresh. */
+	force?: boolean;
+}
+
+const DEFAULT_QUERY_TTL_MS = 45_000;
+
+function defaultNormalizeRef(ref: string): string {
+	return String(ref ?? "")
+		.trim()
+		.toLowerCase();
+}
+
+function defaultMerge<T extends Record<string, unknown>>(
+	base: T,
+	incoming: Partial<T>,
+): T {
+	const merged: Record<string, unknown> = { ...base };
+	for (const [key, value] of Object.entries(incoming)) {
+		if (value !== undefined) merged[key] = value;
+	}
+	return merged as T;
+}
+
+export class CachePolicy<
+	TData extends Record<string, unknown> & { id: string | number },
+	TLevel extends string,
+> {
+	private readonly config: PolicyConfig<TData, TLevel>;
+	private readonly state: PolicyState<TData, TLevel>;
+	private readonly normalizeRef: (ref: string) => string;
+	private readonly merge: (base: TData, incoming: Partial<TData>) => TData;
+	private readonly levelKeys: TLevel[];
+
+	constructor(
+		config: PolicyConfig<TData, TLevel>,
+		state: PolicyState<TData, TLevel>,
+	) {
+		this.config = config;
+		this.state = state;
+		this.normalizeRef = config.normalizeRef ?? defaultNormalizeRef;
+		this.merge = config.merge ?? defaultMerge;
+		this.levelKeys = Object.keys(config.levels) as TLevel[];
+	}
+
+	// --- level helpers ---------------------------------------------------------
+
+	private rank(level: TLevel): number {
+		return this.config.levels[level] ?? 0;
+	}
+
+	/** Whether `current` rank is at least `expected`'s. */
+	private levelAtLeast(current: TLevel, expected: TLevel): boolean {
+		return this.rank(current) >= this.rank(expected);
+	}
+
+	/** Return the higher-ranked of two levels. */
+	private maxLevel(current: TLevel, incoming: TLevel): TLevel {
+		return this.rank(current) >= this.rank(incoming) ? current : incoming;
+	}
+
+	private emptyFreshness(): Record<TLevel, number> {
+		const record = {} as Record<TLevel, number>;
+		for (const level of this.levelKeys) record[level] = 0;
+		return record;
+	}
+
+	/** Stamp every level up to and including `level` with `timestamp`. */
+	private touchFreshness(
+		freshness: Record<TLevel, number>,
+		level: TLevel,
+		timestamp: number,
+	): Record<TLevel, number> {
+		const targetRank = this.rank(level);
+		const next = { ...freshness };
+		for (const key of this.levelKeys) {
+			if (this.rank(key) <= targetRank) {
+				next[key] = Math.max(next[key] ?? 0, timestamp);
+			}
+		}
+		return next;
+	}
+
+	// --- ref index -------------------------------------------------------------
+
+	private indexRefs(data: TData, id: string): void {
+		if (!this.config.refs) return;
+		for (const ref of this.config.refs(data)) {
+			const key = this.normalizeRef(ref);
+			if (key) this.state.refToId[key] = id;
+		}
+	}
+
+	private idForRef(ref: string): string | null {
+		const key = this.normalizeRef(ref);
+		if (!key) return null;
+		return this.state.refToId[key] ?? null;
+	}
+
+	// --- sync reads (NEVER hit the network; RFC §5) ----------------------------
+
+	getById(id: string | number): TData | null {
+		const key = String(id ?? "").trim();
+		if (!key) return null;
+		return this.state.entities[key]?.data ?? null;
+	}
+
+	getByRef(ref: string): TData | null {
+		const id = this.idForRef(ref);
+		if (!id) return null;
+		return this.getById(id);
+	}
+
+	getByIds(ids: Array<string | number>): TData[] {
+		const items: TData[] = [];
+		for (const id of ids) {
+			const entity = this.getById(id);
+			if (entity) items.push(entity);
+		}
+		return items;
+	}
+
+	hasLevel(ref: string, level: TLevel): boolean {
+		const entry = this.entryForRef(ref);
+		if (!entry) return false;
+		if (!this.levelAtLeast(entry.level, level)) return false;
+		// A higher-or-equal level still fails the readiness gate if the payload
+		// lacks the fields that level requires.
+		return this.config.ready?.(entry.data, level) ?? true;
+	}
+
+	isFresh(ref: string, level: TLevel): boolean {
+		const entry = this.entryForRef(ref);
+		if (!entry) return false;
+		const lastUpdated = Number(entry.freshness[level] ?? 0);
+		if (lastUpdated <= 0) return false;
+		return Date.now() - lastUpdated <= (this.config.ttlMs[level] ?? 0);
+	}
+
+	private entryForRef(ref: string): PolicyEntry<TData, TLevel> | null {
+		// Accept a raw id directly as well as an indexed ref.
+		const direct = this.state.entities[String(ref ?? "").trim()];
+		if (direct) return direct;
+		const id = this.idForRef(ref);
+		if (!id) return null;
+		return this.state.entities[id] ?? null;
+	}
+
+	// --- mutations -------------------------------------------------------------
+
+	/** Identity-map upsert + ref index + level/freshness bump. */
+	upsert(data: TData, level: TLevel): TData {
+		const id = String(data.id ?? "").trim();
+		if (!id) return data;
+
+		const existing = this.state.entities[id];
+		const nextLevel = existing ? this.maxLevel(existing.level, level) : level;
+		const baseData = existing?.data ?? ({} as TData);
+		const mergedData = this.merge(baseData, data);
+		// When a thinner (lower-level) payload lands on a richer entry, keep the
+		// higher level's owned fields from being clobbered by absent/blank values.
+		if (
+			existing &&
+			this.config.protectedFields &&
+			this.levelAtLeast(existing.level, level) &&
+			existing.level !== level
+		) {
+			for (const field of this.config.protectedFields(existing.level)) {
+				if (baseData[field] !== undefined) {
+					(mergedData as Record<string, unknown>)[field] = baseData[field];
+				}
+			}
+		}
+		const mergedFreshness = this.touchFreshness(
+			existing?.freshness ?? this.emptyFreshness(),
+			level,
+			Date.now(),
+		);
+
+		this.state.entities[id] = {
+			data: mergedData,
+			level: nextLevel,
+			freshness: mergedFreshness,
+		};
+		this.indexRefs(mergedData, id);
+		return mergedData;
+	}
+
+	upsertMany(items: TData[], level: TLevel): void {
+		for (const item of items) this.upsert(item, level);
+	}
+
+	/** Shallow patch an existing entry's data (e.g. a realtime live overlay). */
+	patch(id: string | number, patch: Partial<TData>): void {
+		const key = String(id ?? "").trim();
+		if (!key) return;
+		const existing = this.state.entities[key];
+		if (!existing) return;
+		const data = this.merge(existing.data, patch);
+		this.state.entities[key] = { ...existing, data };
+		this.indexRefs(data, key);
+	}
+
+	invalidate(id: string | number): void {
+		const key = String(id ?? "").trim();
+		if (key) delete this.state.entities[key];
+	}
+
+	// --- query / page cache ----------------------------------------------------
+
+	setQuery(
+		queryKey: string,
+		payload: {
+			ids: Array<string | number>;
+			total: number;
+			page: number;
+			limit: number;
+		},
+		opts: { ttlMs?: number } = {},
+	): void {
+		const key = String(queryKey ?? "").trim();
+		if (!key) return;
+		const now = Date.now();
+		const ttl =
+			Number(opts.ttlMs) > 0
+				? Number(opts.ttlMs)
+				: (this.config.queryTtlMs ?? DEFAULT_QUERY_TTL_MS);
+		this.state.queries[key] = {
+			ids: payload.ids.map((id) => String(id)).filter(Boolean),
+			total: Number(payload.total || 0),
+			page: Number(payload.page || 1),
+			limit: Number(payload.limit || 20),
+			fetchedAt: now,
+			staleAt: now + ttl,
+		};
+	}
+
+	getQuery(queryKey: string): QueryEntry | null {
+		const key = String(queryKey ?? "").trim();
+		if (!key) return null;
+		return this.state.queries[key] ?? null;
+	}
+
+	isQueryFresh(queryKey: string): boolean {
+		const entry = this.getQuery(queryKey);
+		if (!entry) return false;
+		return Date.now() <= entry.staleAt;
+	}
+
+	// --- the ONLY network-touching method --------------------------------------
+
+	/**
+	 * Return a fresh-enough cached entry, or fetch via `fetcher` and cache it.
+	 *
+	 * The `fetcher` is a thunk the caller builds from a generated SDK GET (which
+	 * already routes through the ETag layer). So on a TTL-miss the round-trip may
+	 * still resolve to a 304 inside the fetcher, reusing the body; `ensure` then
+	 * stamps a fresh TTL. ETag is never touched here — the two layers compose.
+	 */
+	async ensure(
+		ref: string,
+		fetcher: () => Promise<TData | null>,
+		opts: EnsureOptions<TLevel> = {},
+	): Promise<TData | null> {
+		// levelKeys is derived from the required `config.levels` map, so it is
+		// always non-empty — the `[0]` fallback exists.
+		const minLevel: TLevel = opts.minLevel ?? (this.levelKeys[0] as TLevel);
+		const stampLevel = opts.level ?? minLevel;
+		const force = Boolean(opts.force);
+
+		const cached = this.entryForRef(ref);
+		// A hit must clear all three gates: level reached, readiness payload
+		// present (config.ready), and TTL still fresh. `hasLevel` covers the
+		// first two; `isFresh` the third.
+		if (
+			cached &&
+			!force &&
+			this.hasLevel(ref, minLevel) &&
+			this.isFresh(ref, minLevel)
+		) {
+			return cached.data;
+		}
+
+		const fetched = await fetcher();
+		if (!fetched) return cached?.data ?? null;
+		return this.upsert(fetched, stampLevel);
+	}
+}

package/runtime/cache.ts

@@ -0,0 +1,129 @@
+// LeavePulse SDK — identity map.
+//
+// Guarantees one live object per (resource, id): `client.project(1)` always
+// returns the same instance, so `p1 === p2`. Resource instances hold their
+// data; the cache hands back the existing instance and refreshes its data in
+// place rather than minting a new object.
+//
+// Per RFC 0001 §5 the cache is NOT a TTL auto-refetcher. Getters never touch
+// the network; data only changes on an explicit `refresh()` / `invalidate()`.
+
+export interface Identified {
+	/** Stable identity within its resource type. */
+	readonly id: string | number;
+	/** Replace this instance's backing data in place (used on refresh). */
+	_hydrate(data: unknown): void;
+}
+
+export class IdentityMap {
+	private readonly byType = new Map<string, Map<string, Identified>>();
+
+	/**
+	 * Return the canonical instance for (type, id), creating it via `factory`
+	 * on first sight and hydrating the existing one with fresh data otherwise.
+	 */
+	upsert<T extends Identified>(
+		type: string,
+		id: string | number,
+		data: unknown,
+		factory: () => T,
+	): T {
+		const key = String(id);
+		let bucket = this.byType.get(type);
+		if (!bucket) {
+			bucket = new Map();
+			this.byType.set(type, bucket);
+		}
+		const existing = bucket.get(key);
+		if (existing) {
+			existing._hydrate(data);
+			return existing as T;
+		}
+		const created = factory();
+		bucket.set(key, created);
+		return created;
+	}
+
+	/**
+	 * Hydrate a resource that may have been addressed by an alias, e.g. a public
+	 * user profile loaded by slug whose canonical identity is `user_id`.
+	 */
+	upsertAlias<T extends Identified>(
+		type: string,
+		aliasId: string | number,
+		canonicalId: string | number,
+		data: unknown,
+		factory: () => T,
+	): T {
+		const aliasKey = String(aliasId);
+		const canonicalKey = String(canonicalId);
+		let bucket = this.byType.get(type);
+		if (!bucket) {
+			bucket = new Map();
+			this.byType.set(type, bucket);
+		}
+
+		const canonical = bucket.get(canonicalKey);
+		const alias = bucket.get(aliasKey);
+		if (canonical) {
+			canonical._hydrate(data);
+			if (aliasKey !== canonicalKey) bucket.set(aliasKey, canonical);
+			if (alias && alias !== canonical) alias._hydrate(data);
+			return canonical as T;
+		}
+		if (alias) {
+			alias._hydrate(data);
+			bucket.set(canonicalKey, alias);
+			return alias as T;
+		}
+
+		const created = factory();
+		created._hydrate(data);
+		bucket.set(canonicalKey, created);
+		if (aliasKey !== canonicalKey) bucket.set(aliasKey, created);
+		return created;
+	}
+
+	/**
+	 * Return the canonical instance for (type, id) WITHOUT touching its data:
+	 * the existing one as-is, or a freshly constructed one (typically seeded
+	 * with just `{ id }`) on first sight. Used by sync id-accessors
+	 * (`client.project(1)`) that hand back a resource without a GET; data is
+	 * loaded on demand via `refresh()`. Unlike `upsert`, never overwrites an
+	 * already-hydrated instance.
+	 */
+	ensure<T extends Identified>(
+		type: string,
+		id: string | number,
+		factory: () => T,
+	): T {
+		const key = String(id);
+		let bucket = this.byType.get(type);
+		if (!bucket) {
+			bucket = new Map();
+			this.byType.set(type, bucket);
+		}
+		const existing = bucket.get(key);
+		if (existing) return existing as T;
+		const created = factory();
+		bucket.set(key, created);
+		return created;
+	}
+
+	get<T extends Identified>(type: string, id: string | number): T | undefined {
+		return this.byType.get(type)?.get(String(id)) as T | undefined;
+	}
+
+	/** Drop one instance (or a whole type) from the cache. */
+	invalidate(type: string, id?: string | number): void {
+		if (id === undefined) {
+			this.byType.delete(type);
+			return;
+		}
+		this.byType.get(type)?.delete(String(id));
+	}
+
+	clear(): void {
+		this.byType.clear();
+	}
+}

package/runtime/credentials.ts

@@ -0,0 +1,139 @@
+// LeavePulse SDK — credential providers.
+//
+// A `CredentialProvider` is the seam between *acquiring* a token (PAT, device
+// flow, OAuth2, service token) and *sending* it: `AuthenticatedTransport` asks
+// the provider for a bearer before each request and, on a `401`, for a refresh.
+// Providers are transport-agnostic — anything that performs a network call
+// (e.g. a token refresh) is injected, never hardcoded — so the same provider
+// works from a browser, a CLI, Node, or the launcher.
+
+/**
+ * Supplies the bearer token a transport sends, and optionally rotates it.
+ *
+ * - `token()` returns the **current** access token to send.
+ * - `refresh()` (optional) exchanges a refresh token for a new pair; the
+ *   transport calls it once on a `401` and retries. Omit it for non-rotating
+ *   credentials (PAT, service token).
+ */
+export interface CredentialProvider {
+	/** The current bearer token to send on the next request. */
+	token(): Promise<string>;
+	/** Rotate the credential (e.g. exchange a refresh token). Optional. */
+	refresh?(): Promise<void>;
+}
+
+/**
+ * A fixed, non-rotating credential: `token()` always returns the same value
+ * and there is no `refresh`. Use for Personal Access Tokens and out-of-band
+ * service tokens — `BearerTransport` is exactly this.
+ */
+export function StaticCredential(token: string): CredentialProvider {
+	return {
+		token: () => Promise.resolve(token),
+	};
+}
+
+/** The token pair a refresh call yields (wire shape: snake_case). */
+export interface TokenPair {
+	access_token: string;
+	refresh_token?: string | null;
+	/** Access-token lifetime in seconds, used to compute the local expiry. */
+	expires_in?: number | null;
+}
+
+/** Performs the actual refresh exchange. Injected so the credential stays
+ * transport-agnostic (no hardcoded fetch/URL): the caller decides whether it
+ * hits the transport, a raw fetch, or a mock. */
+export type RefreshFn = (refreshToken: string) => Promise<TokenPair>;
+
+/** Seed tokens for a {@link RefreshingCredential}. */
+export interface RefreshingCredentialInit {
+	accessToken: string;
+	refreshToken: string;
+	/** Access-token lifetime in seconds, from the issuing response. */
+	expiresIn?: number | null;
+	/** Performs the refresh-token exchange. */
+	refreshFn: RefreshFn;
+	/** Refresh this many seconds before the computed expiry (default 30). */
+	leewaySeconds?: number;
+}
+
+/**
+ * Holds an access + refresh token locally and rotates them on demand.
+ * `token()` returns the access token, transparently refreshing first if it is
+ * known to be expired; `refresh()` forces an exchange (called by the transport
+ * on a `401`). The network exchange is delegated to the injected `refreshFn`,
+ * so this works for the launcher (refresh-in-body), device flow, and any other
+ * rotating credential without knowing the URL or transport.
+ */
+export class RefreshingCredential implements CredentialProvider {
+	private accessToken: string;
+	private refreshToken: string;
+	private readonly refreshFn: RefreshFn;
+	private readonly leewayMs: number;
+	/** Epoch ms when the access token expires, or `undefined` if unknown. */
+	private expiresAt?: number;
+	/** Coalesces concurrent refreshes into one in-flight exchange. */
+	private inflight?: Promise<void>;
+
+	constructor(init: RefreshingCredentialInit) {
+		this.accessToken = init.accessToken;
+		this.refreshToken = init.refreshToken;
+		this.refreshFn = init.refreshFn;
+		this.leewayMs = (init.leewaySeconds ?? 30) * 1000;
+		this.expiresAt = expiryFromSeconds(init.expiresIn);
+	}
+
+	/** The current refresh token (for persisting to a local store). */
+	get currentRefreshToken(): string {
+		return this.refreshToken;
+	}
+
+	async token(): Promise<string> {
+		// Refresh `leeway` ms early so the token is still valid for the request.
+		if (
+			this.expiresAt !== undefined &&
+			Date.now() >= this.expiresAt - this.leewayMs
+		) {
+			await this.refresh();
+		}
+		return this.accessToken;
+	}
+
+	async refresh(): Promise<void> {
+		// Coalesce concurrent callers (e.g. a 401 retry racing an expiry check).
+		if (this.inflight) return this.inflight;
+		this.inflight = (async () => {
+			try {
+				const pair = await this.refreshFn(this.refreshToken);
+				this.applyTokenPair(pair);
+			} finally {
+				this.inflight = undefined;
+			}
+		})();
+		return this.inflight;
+	}
+
+	/** Adopt a freshly-issued token pair (keeps the old refresh token if the
+	 * server rotated only the access token). */
+	protected applyTokenPair(pair: TokenPair): void {
+		this.accessToken = pair.access_token;
+		if (pair.refresh_token) this.refreshToken = pair.refresh_token;
+		this.expiresAt = expiryFromSeconds(pair.expires_in);
+	}
+}
+
+/**
+ * A credential seeded from an OAuth2 authorization-code token exchange that
+ * auto-refreshes via the same `/auth/oauth2/token` endpoint. Behaviour is
+ * identical to {@link RefreshingCredential}; it exists as a named type so
+ * `sdk.oauth2.exchangeCode` can return a self-describing credential. The
+ * refresh exchange is still injected (`refreshFn`) to stay transport-agnostic.
+ */
+export class OAuth2Credential extends RefreshingCredential {}
+
+/** Convert a seconds-from-now lifetime into an absolute epoch-ms expiry. */
+function expiryFromSeconds(expiresIn?: number | null): number | undefined {
+	if (expiresIn === undefined || expiresIn === null) return undefined;
+	return Date.now() + expiresIn * 1000;
+}