@mr.dj2u/library-registry 0.2.0 → 0.3.0

package/assets/mds/src/features/onboarding-state/adapters/zustand-supabase-onboarding-state-adapter.ts

@@ -0,0 +1,53 @@
+import { useEffect } from 'react';
+
+import { useAuth } from '../auth/auth-provider';
+import {
+  configureLegalAcceptanceAdapter,
+  setLegalAcceptanceUserId,
+} from '../legal/legal-acceptance-config';
+import { getSupabaseClient } from '../../services/supabase';
+import {
+  configureOnboardingStateAdapter,
+  getOnboardingStateAdapter,
+  setOnboardingStateUserId,
+} from './onboarding-state-core';
+import type { SupabaseClientFactory } from './onboarding-state-supabase';
+import {
+  getPersistedOnboardingState,
+  setPersistedOnboardingState,
+} from './onboarding-store';
+import {
+  createZustandSupabaseLegalAcceptanceAdapter,
+  createZustandSupabaseOnboardingStateAdapter,
+} from './onboarding-state-zustand-supabase';
+
+const cache = {
+  getState: getPersistedOnboardingState,
+  setState: setPersistedOnboardingState,
+};
+
+const getClient: SupabaseClientFactory = () =>
+  getSupabaseClient() as ReturnType<SupabaseClientFactory>;
+
+export const onboardingStateAdapter = createZustandSupabaseOnboardingStateAdapter(getClient, cache);
+export const legalAcceptanceAdapter = createZustandSupabaseLegalAcceptanceAdapter(getClient, cache);
+
+configureOnboardingStateAdapter(onboardingStateAdapter);
+configureLegalAcceptanceAdapter(legalAcceptanceAdapter);
+
+export function OnboardingPersistenceSync() {
+  const auth = useAuth();
+
+  useEffect(() => {
+    const userId = auth.user?.id;
+    setOnboardingStateUserId(userId);
+    setLegalAcceptanceUserId(userId);
+
+    if (!userId) {
+      return;
+    }
+    void getOnboardingStateAdapter().syncPending?.(userId);
+  }, [auth.user?.id]);
+
+  return null;
+}

package/assets/mds/src/features/onboarding-state/onboarding-state-core.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { createMemoryOnboardingStateAdapter } from './onboarding-state-memory';
+import type { OnboardingState, OnboardingStateAdapter } from './onboarding-state-types';
+
+let onboardingStateAdapter: OnboardingStateAdapter = createMemoryOnboardingStateAdapter();
+type OnboardingStateListener = (state?: OnboardingState) => void;
+
+const onboardingStateListeners = new Set<OnboardingStateListener>();
+let currentOnboardingUserId: string | undefined;
+
+function notifyOnboardingStateChanged(state?: OnboardingState): void {
+  for (const listener of onboardingStateListeners) {
+    listener(state);
+  }
+}
+
+export function configureOnboardingStateAdapter(adapter: OnboardingStateAdapter): void {
+  onboardingStateAdapter = adapter;
+  notifyOnboardingStateChanged();
+}
+
+export function getOnboardingStateAdapter(): OnboardingStateAdapter {
+  return onboardingStateAdapter;
+}
+
+export function setOnboardingStateUserId(userId?: string | null): void {
+  currentOnboardingUserId = userId ?? undefined;
+}
+
+export function subscribeToOnboardingStateChanges(listener: OnboardingStateListener): () => void {
+  onboardingStateListeners.add(listener);
+  return () => {
+    onboardingStateListeners.delete(listener);
+  };
+}
+
+export async function markOnboardingComplete(input?: {
+  userId?: string;
+  completedAt?: string;
+}): Promise<OnboardingState> {
+  const next = await onboardingStateAdapter.markComplete({
+    ...input,
+    userId: input?.userId ?? currentOnboardingUserId,
+  });
+  notifyOnboardingStateChanged(next);
+  return next;
+}
+
+export function useOnboardingState(userId?: string) {
+  const adapter = onboardingStateAdapter;
+  const [state, setState] = useState<OnboardingState | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | undefined>();
+
+  const refresh = useCallback(async () => {
+    setIsLoading(true);
+    setError(undefined);
+    try {
+      const next = await adapter.loadState(userId);
+      setState(next);
+      return next;
+    } catch (caught) {
+      const message = caught instanceof Error ? caught.message : 'Unable to load onboarding state.';
+      setError(message);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [adapter, userId]);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      void refresh();
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [refresh]);
+
+  useEffect(
+    () =>
+      subscribeToOnboardingStateChanges((nextState) => {
+        if (nextState) {
+          setState(nextState);
+          setError(undefined);
+          setIsLoading(false);
+          return;
+        }
+        void refresh();
+      }),
+    [refresh],
+  );
+
+  return {
+    adapter,
+    state,
+    isLoading,
+    error,
+    refresh,
+    markComplete: async (input?: { completedAt?: string }) => {
+      const next = await adapter.markComplete({ userId, completedAt: input?.completedAt });
+      setState(next);
+      setError(undefined);
+      setIsLoading(false);
+      notifyOnboardingStateChanged(next);
+      return next;
+    },
+  };
+}

package/assets/mds/src/features/onboarding-state/onboarding-state-memory.ts

@@ -0,0 +1,106 @@
+import {
+  createEmptyOnboardingState,
+  upsertLegalAcceptance,
+  type OnboardingDocumentAcceptance,
+  type OnboardingState,
+  type OnboardingStateAdapter,
+} from './onboarding-state-types';
+
+export type MemoryLegalDocument = {
+  documentId: OnboardingDocumentAcceptance['documentId'];
+  acceptanceVersion: string;
+};
+
+export type MemoryLegalSnapshot = {
+  status: 'needs-legal' | 'complete';
+  requiredDocuments: MemoryLegalDocument[];
+  acceptedDocumentKeys: string[];
+};
+
+export type MemoryLegalAcceptanceAdapter = {
+  loadRequiredLegalAcceptances(
+    requiredDocuments: MemoryLegalDocument[],
+    userId?: string,
+  ): Promise<MemoryLegalSnapshot>;
+  acceptLegalDocument(
+    document: MemoryLegalDocument,
+    input?: { userId?: string; flowId?: string; flowVersion?: number },
+  ): Promise<void>;
+};
+
+type MemoryStore = {
+  state: OnboardingState | null;
+};
+
+export function createMemoryOnboardingStore(initial?: OnboardingState | null): MemoryStore {
+  return { state: initial ?? null };
+}
+
+export function createMemoryOnboardingStateAdapter(
+  store: MemoryStore = createMemoryOnboardingStore(),
+): OnboardingStateAdapter {
+  return {
+    mode: 'memory',
+    async loadState() {
+      return store.state ? { ...store.state, legalAcceptances: [...store.state.legalAcceptances] } : null;
+    },
+    async saveState(state: OnboardingState) {
+      store.state = {
+        ...state,
+        legalAcceptances: [...state.legalAcceptances],
+      };
+    },
+    async markComplete(input) {
+      const current = store.state ?? createEmptyOnboardingState();
+      const next = {
+        ...current,
+        completedAt: input?.completedAt ?? new Date().toISOString(),
+        currentStep: 'complete',
+      };
+      store.state = next;
+      return next;
+    },
+  };
+}
+
+export function createMemoryLegalAcceptanceAdapter(
+  store: MemoryStore = createMemoryOnboardingStore(),
+): MemoryLegalAcceptanceAdapter {
+  return {
+    async loadRequiredLegalAcceptances(requiredDocuments: MemoryLegalDocument[]) {
+      const acceptedDocumentKeys = (store.state?.legalAcceptances ?? []).map(
+        (item) => `${item.documentId}@${item.documentVersion}`,
+      );
+      const accepted = new Set(acceptedDocumentKeys);
+      const missingDocuments = requiredDocuments.filter(
+        (document) => !accepted.has(`${document.documentId}@${document.acceptanceVersion}`),
+      );
+
+      return {
+        status: missingDocuments.length > 0 ? 'needs-legal' : 'complete',
+        requiredDocuments: missingDocuments,
+        acceptedDocumentKeys,
+      };
+    },
+
+    async acceptLegalDocument(document, input) {
+      const current = store.state ?? createEmptyOnboardingState();
+      store.state = upsertLegalAcceptance(current, {
+        documentId: document.documentId,
+        documentVersion: document.acceptanceVersion,
+        acceptedAt: new Date().toISOString(),
+        userId: input?.userId,
+        flowId: input?.flowId,
+        flowVersion: input?.flowVersion,
+      });
+    },
+  };
+}
+
+export function createMemoryOnboardingPersistence(store: MemoryStore = createMemoryOnboardingStore()) {
+  return {
+    store,
+    onboarding: createMemoryOnboardingStateAdapter(store),
+    legal: createMemoryLegalAcceptanceAdapter(store),
+  };
+}

package/assets/mds/src/features/onboarding-state/onboarding-state-supabase.ts

@@ -0,0 +1,246 @@
+import type { MemoryLegalAcceptanceAdapter, MemoryLegalDocument } from './onboarding-state-memory';
+import {
+  createEmptyOnboardingState,
+  DEFAULT_ONBOARDING_FLOW_ID,
+  DEFAULT_ONBOARDING_FLOW_VERSION,
+  type OnboardingDocumentAcceptance,
+  type OnboardingState,
+  type OnboardingStateAdapter,
+} from './onboarding-state-types';
+
+export type SupabaseOnboardingRow = {
+  user_id: string;
+  flow_id: string;
+  flow_version: number;
+  status: string;
+  current_step: string | null;
+  completed_at: string | null;
+};
+
+export type SupabaseLegalRow = {
+  user_id: string;
+  document_id: string;
+  document_version: string;
+  flow_id: string | null;
+  accepted_at: string;
+};
+
+export type SupabaseResult<T> = {
+  data: T | null;
+  error: { message: string } | null;
+};
+
+export type SupabaseOnboardingClient = {
+  from(table: string): {
+    select(columns: string): {
+      eq(column: string, value: string): PromiseLike<SupabaseResult<unknown>> & {
+        maybeSingle(): PromiseLike<SupabaseResult<unknown>>;
+      };
+    };
+    upsert(
+      values: Record<string, unknown>,
+      options?: { onConflict?: string },
+    ): PromiseLike<SupabaseResult<null>>;
+    insert(values: Record<string, unknown>): PromiseLike<SupabaseResult<null>>;
+  };
+};
+
+export type SupabaseClientFactory = () => SupabaseOnboardingClient;
+
+function requireUserId(userId?: string): string {
+  if (!userId) {
+    throw new Error('Supabase onboarding persistence requires a signed-in user id.');
+  }
+  return userId;
+}
+
+function isIgnorableInsertError(message: string): boolean {
+  return /duplicate|unique/i.test(message);
+}
+
+function isMissingColumnError(message: string, columnName: string): boolean {
+  return message.includes(columnName) && /column|schema cache|not find/i.test(message);
+}
+
+const LEGACY_COMPLETED_AT_FALLBACK = '1970-01-01T00:00:00.000Z';
+
+function toOnboardingState(
+  row: SupabaseOnboardingRow | null,
+  legalRows: SupabaseLegalRow[],
+): OnboardingState | null {
+  if (!row && legalRows.length === 0) {
+    return null;
+  }
+
+  return {
+    flowId: row?.flow_id ?? DEFAULT_ONBOARDING_FLOW_ID,
+    flowVersion: row?.flow_version ?? DEFAULT_ONBOARDING_FLOW_VERSION,
+    currentStep: row?.current_step ?? undefined,
+    completedAt:
+      row?.completed_at ??
+      (row?.status === 'complete' ? LEGACY_COMPLETED_AT_FALLBACK : undefined),
+    legalAcceptances: legalRows.map((item) => ({
+      documentId: item.document_id as OnboardingDocumentAcceptance['documentId'],
+      documentVersion: item.document_version,
+      acceptedAt: item.accepted_at,
+      userId: item.user_id,
+      flowId: item.flow_id ?? undefined,
+    })),
+    pendingSync: false,
+  };
+}
+
+async function loadRemote(
+  getClient: SupabaseClientFactory,
+  userId: string,
+): Promise<OnboardingState | null> {
+  const client = getClient();
+  const onboardingQuery = client
+    .from('user_onboarding_state')
+    .select('user_id, flow_id, flow_version, status, current_step, completed_at')
+    .eq('user_id', userId);
+  const onboardingResult = await onboardingQuery.maybeSingle();
+  if (onboardingResult.error) {
+    throw new Error(onboardingResult.error.message);
+  }
+
+  const legalResult = await client
+    .from('user_legal_acceptances')
+    .select('user_id, document_id, document_version, flow_id, accepted_at')
+    .eq('user_id', userId);
+  if (legalResult.error) {
+    throw new Error(legalResult.error.message);
+  }
+
+  return toOnboardingState(
+    (onboardingResult.data as SupabaseOnboardingRow | null) ?? null,
+    (legalResult.data as SupabaseLegalRow[] | null) ?? [],
+  );
+}
+
+export function createSupabaseOnboardingStateAdapter(
+  getClient: SupabaseClientFactory,
+): OnboardingStateAdapter {
+  return {
+    mode: 'supabase',
+    async loadState(userId) {
+      if (!userId) {
+        return null;
+      }
+      return loadRemote(getClient, userId);
+    },
+    async saveState(state, userId) {
+      const id = requireUserId(userId);
+      const result = await getClient()
+        .from('user_onboarding_state')
+        .upsert(
+          {
+            user_id: id,
+            flow_id: state.flowId,
+            flow_version: state.flowVersion,
+            status: state.completedAt ? 'complete' : 'in_progress',
+            current_step: state.currentStep ?? null,
+            completed_at: state.completedAt ?? null,
+            updated_at: new Date().toISOString(),
+          },
+          { onConflict: 'user_id' },
+        );
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+    },
+    async markComplete(input) {
+      const id = requireUserId(input?.userId);
+      const current = createEmptyOnboardingState();
+      const next = {
+        ...current,
+        completedAt: input?.completedAt ?? new Date().toISOString(),
+        currentStep: 'complete',
+        pendingSync: false,
+      };
+      const result = await getClient()
+        .from('user_onboarding_state')
+        .upsert(
+          {
+            user_id: id,
+            flow_id: next.flowId,
+            flow_version: next.flowVersion,
+            status: 'complete',
+            current_step: next.currentStep ?? null,
+            completed_at: next.completedAt ?? null,
+            updated_at: new Date().toISOString(),
+          },
+          { onConflict: 'user_id' },
+        );
+      if (result.error) {
+        throw new Error(result.error.message);
+      }
+      return next;
+    },
+  };
+}
+
+export function createSupabaseLegalAcceptanceAdapter(
+  getClient: SupabaseClientFactory,
+): MemoryLegalAcceptanceAdapter {
+  return {
+    async loadRequiredLegalAcceptances(requiredDocuments: MemoryLegalDocument[], userId?: string) {
+      if (!userId) {
+        return {
+          status: 'needs-legal',
+          requiredDocuments,
+          acceptedDocumentKeys: [],
+        };
+      }
+
+      const legalResult = await getClient()
+        .from('user_legal_acceptances')
+        .select('user_id, document_id, document_version, flow_id, accepted_at')
+        .eq('user_id', userId);
+      if (legalResult.error) {
+        throw new Error(legalResult.error.message);
+      }
+
+      const acceptedDocumentKeys = ((legalResult.data as SupabaseLegalRow[] | null) ?? []).map(
+        (item) => `${item.document_id}@${item.document_version}`,
+      );
+      const accepted = new Set(acceptedDocumentKeys);
+      const missingDocuments = requiredDocuments.filter(
+        (document) => !accepted.has(`${document.documentId}@${document.acceptanceVersion}`),
+      );
+
+      return {
+        status: missingDocuments.length > 0 ? 'needs-legal' : 'complete',
+        requiredDocuments: missingDocuments,
+        acceptedDocumentKeys,
+      };
+    },
+
+    async acceptLegalDocument(document, input) {
+      const userId = requireUserId(input?.userId);
+      const payload = {
+        user_id: userId,
+        document_id: document.documentId,
+        document_version: document.acceptanceVersion,
+        acceptance_version: document.acceptanceVersion,
+        flow_id: input?.flowId ?? DEFAULT_ONBOARDING_FLOW_ID,
+        accepted_at: new Date().toISOString(),
+        metadata: {
+          flowVersion: input?.flowVersion ?? DEFAULT_ONBOARDING_FLOW_VERSION,
+        },
+      };
+      let result = await getClient().from('user_legal_acceptances').insert(payload);
+      if (
+        result.error &&
+        isMissingColumnError(result.error.message, 'acceptance_version')
+      ) {
+        const modernPayload: Record<string, unknown> = { ...payload };
+        delete modernPayload.acceptance_version;
+        result = await getClient().from('user_legal_acceptances').insert(modernPayload);
+      }
+      if (result.error && !isIgnorableInsertError(result.error.message)) {
+        throw new Error(result.error.message);
+      }
+    },
+  };
+}

package/assets/mds/src/features/onboarding-state/onboarding-state-types.ts

@@ -0,0 +1,64 @@
+export type OnboardingPersistenceMode =
+  | 'memory'
+  | 'zustand-local'
+  | 'supabase'
+  | 'zustand-supabase';
+
+export const DEFAULT_ONBOARDING_FLOW_ID = 'mds/onboarding';
+export const DEFAULT_ONBOARDING_FLOW_VERSION = 1;
+
+export type OnboardingDocumentAcceptance = {
+  documentId: 'terms' | 'privacy';
+  documentVersion: string;
+  acceptedAt: string;
+  userId?: string;
+  flowId?: string;
+  flowVersion?: number;
+};
+
+export type OnboardingState = {
+  flowId: string;
+  flowVersion: number;
+  currentStep?: string;
+  completedAt?: string;
+  legalAcceptances: OnboardingDocumentAcceptance[];
+  pendingSync?: boolean;
+};
+
+export type OnboardingStateAdapter = {
+  mode: OnboardingPersistenceMode;
+  loadState(userId?: string): Promise<OnboardingState | null>;
+  saveState(state: OnboardingState, userId?: string): Promise<void>;
+  markComplete(input?: { userId?: string; completedAt?: string }): Promise<OnboardingState>;
+  syncPending?(userId: string): Promise<OnboardingState>;
+};
+
+export function createEmptyOnboardingState(
+  input: Partial<OnboardingState> = {},
+): OnboardingState {
+  return {
+    flowId: input.flowId ?? DEFAULT_ONBOARDING_FLOW_ID,
+    flowVersion: input.flowVersion ?? DEFAULT_ONBOARDING_FLOW_VERSION,
+    currentStep: input.currentStep,
+    completedAt: input.completedAt,
+    legalAcceptances: input.legalAcceptances ?? [],
+    pendingSync: input.pendingSync,
+  };
+}
+
+export function upsertLegalAcceptance(
+  state: OnboardingState,
+  acceptance: OnboardingDocumentAcceptance,
+): OnboardingState {
+  const remaining = state.legalAcceptances.filter(
+    (item) =>
+      !(
+        item.documentId === acceptance.documentId &&
+        item.documentVersion === acceptance.documentVersion
+      ),
+  );
+  return {
+    ...state,
+    legalAcceptances: [...remaining, acceptance],
+  };
+}

package/assets/mds/src/features/onboarding-state/onboarding-state-zustand-supabase.ts

@@ -0,0 +1,120 @@
+import type { MemoryLegalAcceptanceAdapter, MemoryLegalDocument } from './onboarding-state-memory';
+import {
+  createSupabaseLegalAcceptanceAdapter,
+  createSupabaseOnboardingStateAdapter,
+  type SupabaseClientFactory,
+} from './onboarding-state-supabase';
+import {
+  createEmptyOnboardingState,
+  upsertLegalAcceptance,
+  type OnboardingState,
+  type OnboardingStateAdapter,
+} from './onboarding-state-types';
+
+export type OnboardingStateCache = {
+  getState(): OnboardingState;
+  setState(state: OnboardingState): void;
+};
+
+export function createZustandSupabaseOnboardingStateAdapter(
+  getClient: SupabaseClientFactory,
+  cache: OnboardingStateCache,
+): OnboardingStateAdapter {
+  const remote = createSupabaseOnboardingStateAdapter(getClient);
+
+  return {
+    mode: 'zustand-supabase',
+    async loadState(userId) {
+      const cached = cache.getState();
+      if (!userId) {
+        return { ...cached, pendingSync: true };
+      }
+
+      const remoteState = await remote.loadState(userId);
+      if (!remoteState) {
+        return { ...cached, pendingSync: Boolean(cached.completedAt || cached.currentStep) };
+      }
+
+      const merged: OnboardingState = {
+        ...remoteState,
+        currentStep: remoteState.currentStep ?? cached.currentStep,
+        completedAt: remoteState.completedAt ?? cached.completedAt,
+        legalAcceptances: remoteState.legalAcceptances,
+        pendingSync: false,
+      };
+      cache.setState(merged);
+      return merged;
+    },
+    async saveState(state, userId) {
+      cache.setState({ ...state, pendingSync: !userId });
+      if (userId) {
+        await remote.saveState({ ...state, pendingSync: false }, userId);
+        cache.setState({ ...state, pendingSync: false });
+      }
+    },
+    async markComplete(input) {
+      const current = cache.getState();
+      const next = {
+        ...current,
+        completedAt: input?.completedAt ?? new Date().toISOString(),
+        currentStep: 'complete',
+        pendingSync: !input?.userId,
+      };
+      cache.setState(next);
+      if (input?.userId) {
+        const remoteState = await remote.markComplete(input);
+        cache.setState({ ...remoteState, pendingSync: false });
+        return { ...remoteState, pendingSync: false };
+      }
+      return next;
+    },
+    async syncPending(userId) {
+      const cached = cache.getState();
+      const remoteState = await remote.loadState(userId);
+      if (remoteState) {
+        cache.setState({ ...remoteState, pendingSync: false });
+        return { ...remoteState, pendingSync: false };
+      }
+      if (cached.completedAt || cached.currentStep) {
+        await remote.saveState({ ...cached, pendingSync: false }, userId);
+        cache.setState({ ...cached, pendingSync: false });
+      }
+      return { ...cache.getState(), pendingSync: false };
+    },
+  };
+}
+
+export function createZustandSupabaseLegalAcceptanceAdapter(
+  getClient: SupabaseClientFactory,
+  cache: OnboardingStateCache,
+): MemoryLegalAcceptanceAdapter {
+  const remote = createSupabaseLegalAcceptanceAdapter(getClient);
+
+  return {
+    async loadRequiredLegalAcceptances(requiredDocuments: MemoryLegalDocument[], userId?: string) {
+      if (!userId) {
+        return {
+          status: 'needs-legal',
+          requiredDocuments,
+          acceptedDocumentKeys: [],
+        };
+      }
+      return remote.loadRequiredLegalAcceptances(requiredDocuments, userId);
+    },
+
+    async acceptLegalDocument(document, input) {
+      if (!input?.userId) {
+        const next = upsertLegalAcceptance(cache.getState() ?? createEmptyOnboardingState(), {
+          documentId: document.documentId,
+          documentVersion: document.acceptanceVersion,
+          acceptedAt: new Date().toISOString(),
+          flowId: input?.flowId,
+          flowVersion: input?.flowVersion,
+        });
+        cache.setState({ ...next, pendingSync: true });
+        return;
+      }
+      await remote.acceptLegalDocument(document, input);
+    },
+  };
+}