@kbve/droid 0.1.1 → 0.1.2

package/src/lib/state/bento.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	$bentoShipment,
+	$bentoLedger,
+	shipBentoWord,
+	advanceBentoShipment,
+	resetBentoFlow,
+} from './bento';
+
+beforeEach(() => {
+	resetBentoFlow();
+});
+
+describe('Bento flow state', () => {
+	it('shipBentoWord creates a shipped shipment', () => {
+		const shipment = shipBentoWord('games');
+		expect(shipment.word).toBe('games');
+		expect(shipment.stage).toBe('shipped');
+		expect($bentoShipment.get()).toEqual(shipment);
+		expect($bentoLedger.get()).toEqual([shipment]);
+	});
+
+	it('shipBentoWord assigns unique incrementing ids', () => {
+		const a = shipBentoWord('games');
+		const b = shipBentoWord('apps');
+		expect(b.id).toBeGreaterThan(a.id);
+	});
+
+	it('advanceBentoShipment updates stage and preserves word', () => {
+		const shipment = shipBentoWord('games');
+		const arrived = advanceBentoShipment(shipment.id, 'arrived');
+		expect(arrived?.word).toBe('games');
+		expect(arrived?.stage).toBe('arrived');
+		expect($bentoShipment.get()?.stage).toBe('arrived');
+		expect($bentoLedger.get()).toHaveLength(1);
+	});
+
+	it('advanceBentoShipment returns null for unknown id', () => {
+		expect(advanceBentoShipment(999, 'arrived')).toBeNull();
+	});
+
+	it('advanceBentoShipment returns null when stage unchanged', () => {
+		const shipment = shipBentoWord('games');
+		expect(advanceBentoShipment(shipment.id, 'shipped')).toBeNull();
+	});
+
+	it('listeners see each lifecycle transition', () => {
+		const handler = vi.fn();
+		const unsub = $bentoShipment.listen(handler);
+
+		const shipment = shipBentoWord('games');
+		advanceBentoShipment(shipment.id, 'arrived');
+		advanceBentoShipment(shipment.id, 'delivered');
+
+		expect(handler).toHaveBeenCalledTimes(3);
+		expect(handler.mock.calls.map(([s]) => s.stage)).toEqual([
+			'shipped',
+			'arrived',
+			'delivered',
+		]);
+		unsub();
+	});
+
+	it('ledger caps at 24 shipments', () => {
+		for (let i = 0; i < 30; i++) shipBentoWord(`word-${i}`);
+		expect($bentoLedger.get()).toHaveLength(24);
+		expect($bentoLedger.get()[23].word).toBe('word-29');
+	});
+
+	it('resetBentoFlow clears state', () => {
+		shipBentoWord('games');
+		resetBentoFlow();
+		expect($bentoShipment.get()).toBeNull();
+		expect($bentoLedger.get()).toEqual([]);
+	});
+});

package/src/lib/state/bento.ts

@@ -0,0 +1,51 @@
+import { atom } from 'nanostores';
+
+export type BentoStage = 'shipped' | 'arrived' | 'delivered' | 'dropped';
+
+export interface BentoShipment {
+	id: number;
+	word: string;
+	stage: BentoStage;
+	at: number;
+}
+
+const LEDGER_MAX = 24;
+
+let nextShipmentId = 1;
+
+export const $bentoShipment = atom<BentoShipment | null>(null);
+export const $bentoLedger = atom<readonly BentoShipment[]>([]);
+
+function record(shipment: BentoShipment) {
+	const rest = $bentoLedger.get().filter((s) => s.id !== shipment.id);
+	$bentoLedger.set([...rest, shipment].slice(-LEDGER_MAX));
+	$bentoShipment.set(shipment);
+}
+
+export function shipBentoWord(word: string): BentoShipment {
+	const shipment: BentoShipment = {
+		id: nextShipmentId++,
+		word,
+		stage: 'shipped',
+		at: Date.now(),
+	};
+	record(shipment);
+	return shipment;
+}
+
+export function advanceBentoShipment(
+	id: number,
+	stage: BentoStage,
+): BentoShipment | null {
+	const current = $bentoLedger.get().find((s) => s.id === id);
+	if (!current || current.stage === stage) return null;
+	const updated: BentoShipment = { ...current, stage, at: Date.now() };
+	record(updated);
+	return updated;
+}
+
+export function resetBentoFlow() {
+	nextShipmentId = 1;
+	$bentoShipment.set(null);
+	$bentoLedger.set([]);
+}

package/src/lib/state/index.ts

@@ -1,8 +1,13 @@
 export {
 	$auth,
+	$isStaff,
 	setAuth,
 	resetAuth,
+	AuthFlags,
+	AuthPresets,
+	hasAuthFlag,
 	type AuthTone,
+	type AuthFlag,
 	type AuthState,
 } from './auth';
 
@@ -20,6 +25,16 @@ export {
 	closeModal,
 } from './ui';
 
+export {
+	$bentoShipment,
+	$bentoLedger,
+	shipBentoWord,
+	advanceBentoShipment,
+	resetBentoFlow,
+	type BentoStage,
+	type BentoShipment,
+} from './bento';
+
 export { $toasts, addToast, removeToast } from './toasts';
 
 export { showWelcomeToast } from './welcome-toast';
@@ -32,3 +47,52 @@ export {
 
 export { OverlayManager } from './overlay-manager';
 export type { RenderPath } from './overlay-manager';
+
+export {
+	$profileCache,
+	clearProfileCache,
+	fetchAndCacheProfile,
+	fetchProfileFromApi,
+	getProfileFromCache,
+	PROFILE_CACHE_TTL_MS,
+	PROFILE_DEFAULT_API_BASE,
+	readProfileForFastPaint,
+	readSupabaseSessionFromStorage,
+	setProfileCache,
+	type CachedSupabaseSession,
+	type DroidProfile,
+	type FetchProfileOptions,
+	type ProfileCacheEnvelope,
+	type ProfileFastPaintResult,
+} from './profile';
+
+export {
+	$staffPermissions,
+	applyStaffFlagFromCache,
+	bootStaffPermissions,
+	clearStaffPermsCache,
+	fetchAndCacheStaffPermissions,
+	fetchStaffPermissionsFromApi,
+	getStaffPermsFromCache,
+	setStaffPermsCache,
+	STAFF_CACHE_TTL_MS,
+	type FetchStaffPermsOptions,
+	type StaffPermsEnvelope,
+} from './staff';
+
+export {
+	broadcastProfileClear,
+	broadcastProfileRefresh,
+	broadcastStaffClear,
+	broadcastStaffRefresh,
+	installSyncBusListener,
+	type SyncBusMessage,
+} from './sync-bus';
+
+export {
+	disposeProfileSync,
+	installProfileSync,
+	refreshProfileSyncNow,
+	type AuthEventLike,
+	type ProfileSyncOptions,
+} from './profile-sync';

package/src/lib/state/profile-sync.ts

@@ -0,0 +1,214 @@
+import { broadcastProfileRefresh, broadcastStaffRefresh } from './sync-bus';
+import {
+	$profileCache,
+	PROFILE_CACHE_TTL_MS,
+	fetchProfileFromApi,
+	setProfileCache,
+	type DroidProfile,
+} from './profile';
+import {
+	$staffPermissions,
+	STAFF_CACHE_TTL_MS,
+	fetchStaffPermissionsFromApi,
+	setStaffPermsCache,
+} from './staff';
+
+const FALLBACK_REFRESH_MS = 15 * 60 * 1000;
+const DEBOUNCE_MS = 250;
+
+export interface AuthEventLike {
+	session?: {
+		access_token?: string;
+		user?: { id?: string } | null;
+	} | null;
+}
+
+export interface ProfileSyncOptions {
+	apiBase: string;
+	supabaseUrl: string;
+	supabaseAnonKey: string;
+	/** Provide a way to subscribe to auth events from the SharedWorker / gateway. */
+	subscribeAuth: (handler: (event: AuthEventLike) => void) => () => void;
+	/**
+	 * Optional override for the recurring fallback cadence. Defaults to
+	 * 15 minutes. Pass `0` to disable.
+	 */
+	fallbackIntervalMs?: number;
+}
+
+interface SyncState {
+	apiBase: string;
+	supabaseUrl: string;
+	supabaseAnonKey: string;
+	timer: ReturnType<typeof setInterval> | null;
+	debounce: ReturnType<typeof setTimeout> | null;
+	inflight: Promise<void> | null;
+	disposers: Array<() => void>;
+}
+
+let active: SyncState | null = null;
+
+async function refreshProfileAndStaff(state: SyncState): Promise<void> {
+	if (state.inflight) return state.inflight;
+	state.inflight = (async () => {
+		try {
+			const sessionRaw = readSession();
+			const userId = sessionRaw?.user?.id;
+			const token = sessionRaw?.access_token;
+			if (!userId || !token) return;
+
+			const profilePromise = fetchProfileFromApi({
+				token,
+				apiBase: state.apiBase,
+			});
+			const staffPromise = fetchStaffPermissionsFromApi({
+				token,
+				apikey: state.supabaseAnonKey,
+				supabaseUrl: state.supabaseUrl,
+			});
+
+			const [profile, staff] = await Promise.all([
+				profilePromise.catch(() => null),
+				staffPromise.catch(() => null),
+			]);
+
+			if (profile && profile.user_id) {
+				setProfileCache(profile);
+				broadcastProfileRefresh(profile);
+			}
+			if (typeof staff === 'number') {
+				setStaffPermsCache(userId, staff);
+				broadcastStaffRefresh(userId, staff);
+			}
+		} finally {
+			if (active === state) state.inflight = null;
+		}
+	})();
+	return state.inflight;
+}
+
+function readSession(): AuthEventLike['session'] {
+	if (typeof localStorage === 'undefined') return null;
+	const raw = localStorage.getItem('sb-auth-token');
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed?.currentSession?.access_token) return parsed.currentSession;
+		if (parsed?.access_token) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+function scheduleRefresh(state: SyncState): void {
+	if (state.debounce) clearTimeout(state.debounce);
+	state.debounce = setTimeout(() => {
+		state.debounce = null;
+		void refreshProfileAndStaff(state);
+	}, DEBOUNCE_MS);
+}
+
+function isProfileStale(): boolean {
+	const entry = $profileCache.get();
+	if (!entry) return true;
+	return Date.now() - entry.cached_at > PROFILE_CACHE_TTL_MS;
+}
+
+function isStaffStale(): boolean {
+	const entry = $staffPermissions.get();
+	if (!entry) return true;
+	return Date.now() - entry.cached_at > STAFF_CACHE_TTL_MS;
+}
+
+/**
+ * Install a profile + staff_permissions sync coordinator. Returns a
+ * dispose function that tears down listeners and the fallback timer.
+ *
+ * Refresh triggers:
+ *   - auth events from the SharedWorker (token refresh, sign-in)
+ *   - `document.visibilitychange` (only if at least one cache is stale)
+ *   - `window.focus`            (only if at least one cache is stale)
+ *   - fallback `setInterval` every `fallbackIntervalMs` (default 15m)
+ *
+ * Each refresh is debounced (250ms) and reentrancy-guarded; a refresh
+ * in flight is reused rather than queued.
+ *
+ * Idempotent — calling twice tears down the previous coordinator first
+ * so callers can re-run safely.
+ */
+export function installProfileSync(opts: ProfileSyncOptions): () => void {
+	disposeProfileSync();
+
+	const state: SyncState = {
+		apiBase: opts.apiBase,
+		supabaseUrl: opts.supabaseUrl,
+		supabaseAnonKey: opts.supabaseAnonKey,
+		timer: null,
+		debounce: null,
+		inflight: null,
+		disposers: [],
+	};
+	active = state;
+
+	const unsubscribeAuth = opts.subscribeAuth((evt) => {
+		if (!evt?.session?.user?.id) return;
+		scheduleRefresh(state);
+	});
+	state.disposers.push(unsubscribeAuth);
+
+	if (typeof document !== 'undefined') {
+		const onVisibility = () => {
+			if (document.visibilityState !== 'visible') return;
+			if (!isProfileStale() && !isStaffStale()) return;
+			scheduleRefresh(state);
+		};
+		document.addEventListener('visibilitychange', onVisibility);
+		state.disposers.push(() =>
+			document.removeEventListener('visibilitychange', onVisibility),
+		);
+	}
+	if (typeof window !== 'undefined') {
+		const onFocus = () => {
+			if (!isProfileStale() && !isStaffStale()) return;
+			scheduleRefresh(state);
+		};
+		window.addEventListener('focus', onFocus);
+		state.disposers.push(() =>
+			window.removeEventListener('focus', onFocus),
+		);
+	}
+
+	const interval = opts.fallbackIntervalMs ?? FALLBACK_REFRESH_MS;
+	if (interval > 0) {
+		state.timer = setInterval(() => {
+			void refreshProfileAndStaff(state);
+		}, interval);
+	}
+
+	return disposeProfileSync;
+}
+
+export function disposeProfileSync(): void {
+	if (!active) return;
+	const state = active;
+	active = null;
+	if (state.timer) clearInterval(state.timer);
+	if (state.debounce) clearTimeout(state.debounce);
+	for (const dispose of state.disposers) {
+		try {
+			dispose();
+		} catch {
+			/* best effort */
+		}
+	}
+	state.disposers.length = 0;
+}
+
+/** Trigger an immediate refresh if a sync coordinator is installed. */
+export async function refreshProfileSyncNow(): Promise<void> {
+	if (!active) return;
+	await refreshProfileAndStaff(active);
+}
+
+export type { DroidProfile };

package/src/lib/state/profile.ts

@@ -0,0 +1,155 @@
+import { persistentAtom } from '@nanostores/persistent';
+
+export interface DroidProfile {
+	user_id: string;
+	username?: string;
+	email?: string;
+	profile_exists?: boolean;
+	discord?: {
+		username?: string;
+		avatar_url?: string;
+		is_guild_member?: boolean;
+	};
+	github?: { username?: string; avatar_url?: string };
+	twitch?: { username?: string; avatar_url?: string; is_live?: boolean };
+	connected_providers?: string[];
+	[k: string]: unknown;
+}
+
+export interface ProfileCacheEnvelope {
+	profile: DroidProfile;
+	cached_at: number;
+	user_id: string;
+}
+
+const PROFILE_CACHE_KEY = 'cache:profile:me';
+const SUPABASE_SESSION_STORAGE_KEY = 'sb-auth-token';
+export const PROFILE_CACHE_TTL_MS = 5 * 60 * 1000;
+export const PROFILE_DEFAULT_API_BASE = 'https://kbve.com';
+
+export const $profileCache = persistentAtom<ProfileCacheEnvelope | null>(
+	PROFILE_CACHE_KEY,
+	null,
+	{
+		encode: (value) => JSON.stringify(value),
+		decode: (raw) => {
+			if (!raw || raw === 'null') return null;
+			try {
+				return JSON.parse(raw) as ProfileCacheEnvelope;
+			} catch {
+				return null;
+			}
+		},
+	},
+);
+
+export function getProfileFromCache(userId: string): DroidProfile | null {
+	const entry = $profileCache.get();
+	if (!entry) return null;
+	if (entry.user_id !== userId) return null;
+	if (Date.now() - entry.cached_at > PROFILE_CACHE_TTL_MS) return null;
+	return entry.profile;
+}
+
+export function setProfileCache(profile: DroidProfile): void {
+	if (!profile.user_id) return;
+	$profileCache.set({
+		profile,
+		cached_at: Date.now(),
+		user_id: profile.user_id,
+	});
+}
+
+export function clearProfileCache(): void {
+	$profileCache.set(null);
+}
+
+export interface CachedSupabaseSession {
+	access_token: string;
+	refresh_token?: string;
+	expires_at?: number;
+	user?: {
+		id: string;
+		email?: string;
+		user_metadata?: Record<string, unknown>;
+		[k: string]: unknown;
+	};
+	[k: string]: unknown;
+}
+
+export function readSupabaseSessionFromStorage(): CachedSupabaseSession | null {
+	if (typeof localStorage === 'undefined') return null;
+	const raw = localStorage.getItem(SUPABASE_SESSION_STORAGE_KEY);
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== 'object') return null;
+		if (
+			parsed.currentSession &&
+			typeof parsed.currentSession === 'object' &&
+			'access_token' in parsed.currentSession
+		) {
+			return parsed.currentSession as CachedSupabaseSession;
+		}
+		if ('access_token' in parsed) {
+			return parsed as CachedSupabaseSession;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export interface FetchProfileOptions {
+	token: string;
+	apiBase?: string;
+	signal?: AbortSignal;
+}
+
+export async function fetchProfileFromApi(
+	opts: FetchProfileOptions,
+): Promise<DroidProfile | null> {
+	const base = opts.apiBase ?? PROFILE_DEFAULT_API_BASE;
+	const res = await fetch(`${base}/api/v1/profile/me`, {
+		method: 'GET',
+		headers: {
+			Authorization: `Bearer ${opts.token}`,
+			Accept: 'application/json',
+		},
+		signal: opts.signal,
+	});
+	if (!res.ok) return null;
+	try {
+		const json = (await res.json()) as DroidProfile;
+		if (!json || !json.user_id) return null;
+		return json;
+	} catch {
+		return null;
+	}
+}
+
+export async function fetchAndCacheProfile(
+	opts: FetchProfileOptions,
+): Promise<DroidProfile | null> {
+	const profile = await fetchProfileFromApi(opts);
+	if (profile) setProfileCache(profile);
+	return profile;
+}
+
+export interface ProfileFastPaintResult {
+	session: CachedSupabaseSession;
+	profile: DroidProfile;
+	stale: boolean;
+}
+
+export function readProfileForFastPaint(): ProfileFastPaintResult | null {
+	const session = readSupabaseSessionFromStorage();
+	if (!session?.user?.id || !session.access_token) return null;
+	const entry = $profileCache.get();
+	if (!entry || entry.user_id !== session.user.id) return null;
+	return {
+		session,
+		profile: entry.profile,
+		stale: Date.now() - entry.cached_at > PROFILE_CACHE_TTL_MS,
+	};
+}

package/src/lib/state/staff.ts

@@ -0,0 +1,128 @@
+import { persistentAtom } from '@nanostores/persistent';
+import { $auth, setAuth, AuthPresets } from './auth';
+
+export interface StaffPermsEnvelope {
+	bitmask: number;
+	cached_at: number;
+	user_id: string;
+}
+
+const STAFF_CACHE_KEY = 'cache:staff:perms';
+const SUPABASE_DEFAULT_URL = 'https://supabase.kbve.com';
+export const STAFF_CACHE_TTL_MS = 10 * 60 * 1000;
+
+export const $staffPermissions = persistentAtom<StaffPermsEnvelope | null>(
+	STAFF_CACHE_KEY,
+	null,
+	{
+		encode: (value) => JSON.stringify(value),
+		decode: (raw) => {
+			if (!raw || raw === 'null') return null;
+			try {
+				return JSON.parse(raw) as StaffPermsEnvelope;
+			} catch {
+				return null;
+			}
+		},
+	},
+);
+
+export function getStaffPermsFromCache(userId: string): number | null {
+	const entry = $staffPermissions.get();
+	if (!entry) return null;
+	if (entry.user_id !== userId) return null;
+	if (Date.now() - entry.cached_at > STAFF_CACHE_TTL_MS) return null;
+	return entry.bitmask;
+}
+
+export function setStaffPermsCache(userId: string, bitmask: number): void {
+	if (!userId) return;
+	$staffPermissions.set({ bitmask, cached_at: Date.now(), user_id: userId });
+}
+
+export function clearStaffPermsCache(): void {
+	$staffPermissions.set(null);
+}
+
+export interface FetchStaffPermsOptions {
+	token: string;
+	apikey: string;
+	supabaseUrl?: string;
+	signal?: AbortSignal;
+}
+
+export async function fetchStaffPermissionsFromApi(
+	opts: FetchStaffPermsOptions,
+): Promise<number | null> {
+	const base = opts.supabaseUrl ?? SUPABASE_DEFAULT_URL;
+	const res = await fetch(`${base}/rest/v1/rpc/staff_permissions`, {
+		method: 'POST',
+		headers: {
+			Authorization: `Bearer ${opts.token}`,
+			'Content-Type': 'application/json',
+			apikey: opts.apikey,
+		},
+		body: '{}',
+		signal: opts.signal,
+	});
+	if (!res.ok) return null;
+	try {
+		const data = await res.json();
+		if (typeof data === 'number') return data;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export async function fetchAndCacheStaffPermissions(
+	opts: FetchStaffPermsOptions & { userId: string },
+): Promise<number | null> {
+	const bitmask = await fetchStaffPermissionsFromApi(opts);
+	if (bitmask === null) return null;
+	setStaffPermsCache(opts.userId, bitmask);
+	return bitmask;
+}
+
+/**
+ * Apply STAFF flag to `$auth` if the cached staff permissions for
+ * `userId` are non-zero. Returns the bitmask (or null when no cache /
+ * stale / non-matching user).
+ */
+export function applyStaffFlagFromCache(userId: string): number | null {
+	const bitmask = getStaffPermsFromCache(userId);
+	if (bitmask === null) return null;
+	if (bitmask > 0) {
+		const state = $auth.get();
+		if (state.tone === 'auth' && state.id === userId) {
+			setAuth({ flags: AuthPresets.STAFF });
+		}
+	}
+	return bitmask;
+}
+
+/**
+ * Compose: synchronously paint STAFF flag from cache, then refresh in
+ * the background. Caller decides whether to await the returned
+ * promise.
+ */
+export function bootStaffPermissions(opts: {
+	userId: string;
+	token: string;
+	apikey: string;
+	supabaseUrl?: string;
+}): { cachedBitmask: number | null; refresh: Promise<number | null> } {
+	const cachedBitmask = applyStaffFlagFromCache(opts.userId);
+	const refresh = fetchAndCacheStaffPermissions(opts)
+		.then((bitmask) => {
+			if (bitmask !== null && bitmask > 0) {
+				const state = $auth.get();
+				if (state.tone === 'auth' && state.id === opts.userId) {
+					setAuth({ flags: AuthPresets.STAFF });
+				}
+			}
+			return bitmask;
+		})
+		.catch(() => null);
+	return { cachedBitmask, refresh };
+}