@razakalpha/convngx 0.2.3 → 0.2.4

package/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/convngx",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

package/package.json

@@ -1,26 +1,26 @@
-{
-  "name": "@razakalpha/convngx",
-  "version": "0.2.3",
-  "peerDependencies": {
-    "@angular/common": "^20.1.0",
-    "@angular/core": "^20.1.0",
-    "convex": "^1.25.0",
-    "@convex-dev/better-auth": "^0.7.0",
-    "better-auth": "^1.3.0"
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  },
-  "sideEffects": false,
-  "module": "fesm2022/razakalpha-convngx.mjs",
-  "typings": "index.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./fesm2022/razakalpha-convngx.mjs"
-    }
-  }
-}
+{
+  "name": "@razakalpha/convngx",
+  "version": "0.2.4",
+  "peerDependencies": {
+    "@angular/common": "^20.1.0",
+    "@angular/core": "^20.1.0",
+    "convex": "^1.25.0",
+    "@convex-dev/better-auth": "^0.7.0",
+    "better-auth": "^1.3.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/razakalpha-convngx.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/razakalpha-convngx.mjs"
+    }
+  }
+}

package/src/lib/auth/auth-client.provider.ts

@@ -0,0 +1,35 @@
+import { InjectionToken, Provider } from '@angular/core';
+import { createAuthClient } from 'better-auth/client';
+import { convexClient, crossDomainClient } from '@convex-dev/better-auth/client/plugins';
+
+type AuthConfig = {
+  baseURL: string;
+  plugins: [ReturnType<typeof convexClient>, ReturnType<typeof crossDomainClient>];
+  fetchOptions: { credentials: 'include' };
+};
+
+export type AuthClient = ReturnType<typeof createAuthClient<AuthConfig>>;
+
+export interface ProvideAuthClientOptions {
+  baseURL: string;
+  fetchOptions?: RequestInit;
+}
+
+/**
+ * Un-typed DI token. We don't re-export types; callers who create the client
+ * get full type safety from better-auth directly.
+ */
+export const AUTH_CLIENT = new InjectionToken<AuthClient>('AUTH_CLIENT');
+
+/** Provide a configured Better Auth client via DI (default convex+crossDomain plugins) */
+export function provideAuthClient(opts: ProvideAuthClientOptions): Provider {
+  return {
+    provide: AUTH_CLIENT,
+    useFactory: () =>
+      createAuthClient({
+        baseURL: opts.baseURL,
+        plugins: [convexClient(), crossDomainClient()],
+        fetchOptions: { credentials: 'include', ...(opts.fetchOptions ?? {}) },
+      }),
+  };
+}

package/src/lib/auth/convex-better-auth.provider.ts

@@ -0,0 +1,110 @@
+/**
+ * Convex + Better Auth providers.
+ * - provideConvexBetterAuth: Registers a ConvexAngularClient in DI and wires Better Auth token fetching.
+ * - provideBetterAuthOttBootstrap: Optional environment initializer to handle cross-domain one-time-token.
+ *
+ * No functional changes—cleaned comments and added docs.
+ */
+import { inject, provideEnvironmentInitializer, Provider } from '@angular/core';
+import { AUTH_CLIENT } from './auth-client.provider';
+import { CONVEX } from '../core/inject-convex.token';
+import { ConvexAngularClient, FetchAccessToken } from '../core/convex-angular-client';
+
+/** Minimal surface this library relies on from Better Auth client */
+interface AuthClientRequired {
+  convex: { token: () => Promise<{ data?: { token?: string } | null }> };
+  crossDomain: {
+    oneTimeToken: {
+      verify: (args: { token: string }) => Promise<{ data?: { session?: { token?: string } } }>;
+    };
+  };
+  getSession: (o?: { fetchOptions?: RequestInit }) => Promise<unknown>;
+  updateSession: () => void;
+}
+export interface ConvexBetterAuthOptions {
+  /** Convex deployment URL, e.g. https://xxx.convex.cloud */
+  convexUrl: string;
+  /** Milliseconds before JWT expiry to refresh (default 45s in this provider) */
+  authSkewMs?: number;
+
+  authClient?: AuthClientRequired; // Optional user-provided Better Auth client
+}
+
+/**
+ * Registers the Convex client in DI and connects it to Better Auth for JWT retrieval.
+ * Consumers still need to provide the Better Auth HTTP client via provideAuthClient().
+ */
+export function provideConvexBetterAuth(opts: ConvexBetterAuthOptions): Provider[] {
+  return [
+    {
+      provide: CONVEX,
+      useFactory: () => {
+        const client = new ConvexAngularClient(opts.convexUrl, {
+          authSkewMs: opts.authSkewMs ?? 45_000,
+        });
+
+        const auth = inject(AUTH_CLIENT) as AuthClientRequired;
+
+        const fetchAccessToken: FetchAccessToken = async ({ forceRefreshToken }) => {
+          if (!forceRefreshToken) return null;
+
+          // Retry logic for transient failures (e.g., session not fully propagated)
+          let lastError: any;
+          for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+              if (attempt > 0) {
+                // Wait before retry: 50ms, then 100ms
+                const delay = attempt * 50;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+              }
+
+              const { data } = await auth.convex.token();
+              return data?.token ?? null;
+            } catch (err: any) {
+              lastError = err;
+              // Only retry on "Failed to fetch" errors
+              if (attempt < 2 && err?.message === 'Failed to fetch') {
+                continue;
+              }
+              throw err;
+            }
+          }
+          throw lastError;
+        };
+
+        client.setAuth(fetchAccessToken);
+        void client.warmAuth();
+        return client;
+      },
+    },
+  ];
+}
+
+/**
+ * Optional environment initializer to handle OTT (?ott=...) once and upgrade to a cookie session.
+ * Keep separate from main provider for explicit opt-in.
+ */
+export function provideBetterAuthOttBootstrap() {
+  return provideEnvironmentInitializer(() => {
+    (async () => {
+      const auth = inject(AUTH_CLIENT) as AuthClientRequired;
+      const url = new URL(window.location.href);
+      const ott = url.searchParams.get('ott');
+      if (!ott) return;
+
+      const result = await auth.crossDomain.oneTimeToken.verify({ token: ott });
+      const session = result?.data?.session;
+      if (session?.token) {
+        await auth.getSession({
+          fetchOptions: {
+            credentials: 'include',
+            headers: { Authorization: `Bearer ${session.token}` },
+          },
+        });
+        auth.updateSession();
+      }
+      url.searchParams.delete('ott');
+      window.history.replaceState({}, '', url.toString());
+    })();
+  });
+}

package/src/lib/convex-angular.spec.ts

@@ -0,0 +1,23 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ConvexAngular } from './convex-angular';
+
+describe('ConvexAngular', () => {
+  let component: ConvexAngular;
+  let fixture: ComponentFixture<ConvexAngular>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ConvexAngular]
+    })
+    .compileComponents();
+
+    fixture = TestBed.createComponent(ConvexAngular);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

package/src/lib/convex-angular.ts

@@ -0,0 +1,15 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'lib-convex-angular',
+  imports: [],
+  template: `
+    <p>
+      convNGX works!
+    </p>
+  `,
+  styles: ``
+})
+export class ConvexAngular {
+
+}

package/src/lib/core/convex-angular-client.ts

@@ -0,0 +1,351 @@
+/**
+ * ConvexAngularClient
+ * - Wraps Convex BaseConvexClient + ConvexHttpClient
+ * - Integrates Better Auth via pluggable fetcher (setAuth)
+ * - Caches JWT in sessionStorage with BroadcastChannel sync
+ * - Auto-refreshes auth token ahead of expiry with jitter
+ * - Provides:
+ *   - watchQuery: live subscription with localQueryResult + onUpdate
+ *   - query: HTTP one-shot with in-flight de-dupe + 401 retry
+ *   - mutation: supports optimisticUpdate passthrough
+ *   - action: HTTP call with 401 retry
+ * - Does not change any runtime behavior – documentation and structure only.
+ */
+// src/app/convex-angular-client.ts
+import {
+  BaseConvexClient,
+  type BaseConvexClientOptions,
+  type OptimisticUpdate,
+  ConvexHttpClient,
+} from 'convex/browser';
+import {
+  FunctionReference,
+  FunctionArgs,
+  FunctionReturnType,
+  getFunctionName,
+} from 'convex/server';
+import type { Value } from 'convex/values';
+import type { FetchAccessToken, AuthSnapshot } from './types';
+export type { FetchAccessToken, AuthSnapshot } from './types';
+import { AUTH_KEY, AUTH_CH, jwtExpMs, stableStringify, safeSession } from './helpers';
+
+type QueryToken = string;
+
+type WatchHandle<Q extends FunctionReference<'query'>> = {
+  localQueryResult(): FunctionReturnType<Q> | undefined;
+  onUpdate(cb: () => void): () => void;
+  unsubscribe(): void;
+};
+
+type Entry = {
+  name: string;
+  args: Record<string, Value>;
+  listeners: Set<() => void>;
+  unsubscribe: () => void;
+};
+
+type StoredToken = { value: string; exp: number };
+
+/* helpers moved to ./helpers (no behavior change) */
+
+
+const bc =
+  typeof BroadcastChannel !== 'undefined'
+    ? new BroadcastChannel(AUTH_CH)
+    : (null as BroadcastChannel | null);
+
+export class ConvexAngularClient {
+  private authListeners = new Set<(s: AuthSnapshot) => void>();
+  private lastSnap?: AuthSnapshot;
+  // ==== internals ====
+  private emitAuth() {
+    const snap = this.getAuthSnapshot();
+    // de-dupe emissions
+    if (
+      this.lastSnap &&
+      this.lastSnap.isAuthenticated === snap.isAuthenticated &&
+      this.lastSnap.token === snap.token
+    ) {
+      return;
+    }
+    this.lastSnap = snap;
+    for (const cb of this.authListeners) cb(snap);
+  }
+
+  private base: BaseConvexClient;
+  private http: ConvexHttpClient;
+  private byToken = new Map<QueryToken, Entry>();
+
+  private fetchToken?: FetchAccessToken;
+  private inflightToken?: Promise<string | null>;
+  private token?: StoredToken;
+
+  private refreshTimer?: number;
+  private inflightHttp = new Map<string, Promise<any>>();
+  private authLocked = false;
+
+  private readonly skewMs: number;
+
+  constructor(url: string, opts?: BaseConvexClientOptions & { authSkewMs?: number }) {
+    this.skewMs = opts?.authSkewMs ?? 30_000;
+
+    this.base = new BaseConvexClient(
+      url,
+      (updatedTokens: QueryToken[]) => {
+        for (const t of updatedTokens) {
+          const e = this.byToken.get(t);
+          if (!e) continue;
+          for (const cb of e.listeners) cb();
+        }
+      },
+      opts,
+    );
+
+    this.http = new ConvexHttpClient(url);
+
+    // pick up cached token
+    const raw = safeSession.get(AUTH_KEY);
+    if (raw) {
+      try {
+        const t: StoredToken = JSON.parse(raw);
+        if (t?.value && t?.exp && Date.now() < t.exp - this.skewMs) {
+          this.token = t;
+          this.http.setAuth(t.value);
+          this.scheduleRefresh();
+        }
+      } catch {}
+    }
+    // 3) BroadcastChannel: keep as-is (clear only on 'clear', set on 'set')
+    bc?.addEventListener('message', (ev: MessageEvent) => {
+      const d: any = ev.data;
+      if (d?.type === 'set') {
+        if (this.authLocked) return; // ignore while logging out
+        this.applyToken(d.token?.value ?? null);
+      } else if (d?.type === 'clear') {
+        this.applyToken(null);
+      }
+    });
+
+    // visibility/network pokes
+    const poke = () => {
+      if (!this.freshTokenInCache()) void this.getToken(true);
+    };
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', poke);
+      document.addEventListener?.('visibilitychange', () => {
+        if (document.visibilityState === 'visible') poke();
+      });
+    }
+  }
+
+  setAuth(fetcher: FetchAccessToken) {
+    this.fetchToken = fetcher;
+    this.base.setAuth(
+      async ({ forceRefreshToken }) => (this.authLocked ? null : this.getToken(forceRefreshToken)),
+      () => {
+        // identity changed (connect/reconnect). Do NOT clear token here.
+        // If we're truly logged out, next HTTP/WS use will 401 and we clear then.
+        this.inflightToken = undefined;
+        this.emitAuth(); // soft notify, no flip to false
+      },
+    );
+  }
+
+  /** Optional: call once on app start */
+  async warmAuth(): Promise<void> {
+    await this.getToken(true);
+  }
+
+  private freshTokenInCache(): string | null {
+    if (!this.token) return null;
+    return Date.now() < this.token.exp - this.skewMs ? this.token.value : null;
+  }
+
+  // ==== public auth helpers ====
+  onAuth(cb: (s: AuthSnapshot) => void): () => void {
+    cb(this.getAuthSnapshot());
+    this.authListeners.add(cb);
+    return () => this.authListeners.delete(cb);
+  }
+
+  logoutLocal(lock = true) {
+    if (lock) this.authLocked = true;
+    this.inflightToken = undefined;
+    this.applyToken(null); // this is the ONLY place we hard clear locally
+  }
+
+  // 5) snapshot uses token presence (not freshness)
+  getAuthSnapshot() {
+    return {
+      isAuthenticated: !!this.token?.value,
+      token: this.token?.value ?? null,
+      exp: this.token?.exp,
+    };
+  }
+
+  /** Allow re-auth then fetch a fresh token (use after successful sign-in) */
+  async refreshAuth(): Promise<void> {
+    this.authLocked = false;
+    await this.getToken(true);
+  }
+
+  // 4) applyToken: always emit after mutation (you already fixed this)
+  private applyToken(token: string | null) {
+    if (!token) {
+      this.token = undefined;
+      this.http.clearAuth();
+      safeSession.del(AUTH_KEY);
+      bc?.postMessage({ type: 'clear' });
+      if (this.refreshTimer) window.clearTimeout(this.refreshTimer);
+    } else {
+      if (this.authLocked) {
+        this.emitAuth();
+        return;
+      }
+      const exp = jwtExpMs(token);
+      this.token = { value: token, exp };
+      this.http.setAuth(token);
+      safeSession.set(AUTH_KEY, JSON.stringify(this.token));
+      bc?.postMessage({ type: 'set', token: this.token });
+      this.scheduleRefresh();
+    }
+    this.emitAuth();
+  }
+
+  private scheduleRefresh() {
+    if (!this.token) return;
+    if (this.refreshTimer) window.clearTimeout(this.refreshTimer);
+    const jitter = 2_000 + Math.floor(Math.random() * 2_000);
+    const due = Math.max(0, this.token.exp - this.skewMs - Date.now() - jitter);
+    this.refreshTimer = window.setTimeout(() => {
+      void this.getToken(true);
+    }, due);
+  }
+
+  private async getToken(force: boolean): Promise<string | null> {
+    if (!this.fetchToken || this.authLocked) return null; // 🔒 deny any token
+    const cached = this.freshTokenInCache();
+    if (!force && cached) return cached;
+
+    if (!this.inflightToken) {
+      this.inflightToken = (async () => {
+        const t = await this.fetchToken!({ forceRefreshToken: true });
+        // ignore token if we got locked while waiting
+        if (this.authLocked) {
+          this.emitAuth(); // ensure listeners see current (likely false)
+          return null;
+        }
+        this.applyToken(t ?? null);
+        return t ?? null;
+      })().finally(() => setTimeout(() => (this.inflightToken = undefined), 0));
+    }
+    return await this.inflightToken;
+  }
+
+  private async ensureHttpAuth(): Promise<void> {
+    await this.getToken(false);
+  }
+
+  // ——— live query ———
+  watchQuery<Q extends FunctionReference<'query'>>(q: Q, args: FunctionArgs<Q>): WatchHandle<Q> {
+    const name = getFunctionName(q);
+    const valueArgs = (args ?? {}) as unknown as Record<string, Value>;
+    const { queryToken, unsubscribe } = this.base.subscribe(name, valueArgs);
+
+    const entry: Entry = { name, args: valueArgs, listeners: new Set(), unsubscribe };
+    this.byToken.set(queryToken, entry);
+
+    return {
+      localQueryResult: () =>
+        this.base.localQueryResult(name, valueArgs) as FunctionReturnType<Q> | undefined,
+      onUpdate: (cb) => {
+        entry.listeners.add(cb);
+        return () => entry.listeners.delete(cb);
+      },
+      unsubscribe: () => {
+        entry.unsubscribe();
+        this.byToken.delete(queryToken);
+      },
+    };
+  }
+
+  // ——— mutation ———
+  async mutation<M extends FunctionReference<'mutation'>>(
+    m: M,
+    args: FunctionArgs<M>,
+    opts?: { optimisticUpdate?: OptimisticUpdate<FunctionArgs<M>> },
+  ): Promise<FunctionReturnType<M>> {
+    const name = getFunctionName(m);
+    return this.base.mutation(
+      name,
+      args as any,
+      opts?.optimisticUpdate ? { optimisticUpdate: opts.optimisticUpdate as any } : undefined,
+    );
+  }
+  // ——— action (no dedupe) ———
+  async action<A extends FunctionReference<'action'> & { _args: Record<string, never> }>(
+    a: A,
+  ): Promise<FunctionReturnType<A>>;
+  async action<A extends FunctionReference<'action'>>(
+    a: A,
+    args: FunctionArgs<A>,
+  ): Promise<FunctionReturnType<A>>;
+  async action<A extends FunctionReference<'action'>>(
+    a: A,
+    args?: FunctionArgs<A>,
+  ): Promise<FunctionReturnType<A>> {
+    await this.ensureHttpAuth();
+
+    const call = () => this.http.action(a, ...(args ? ([args] as any) : []));
+
+    try {
+      return await call();
+    } catch (e: any) {
+      const status = e?.status ?? e?.response?.status;
+      if (this.fetchToken && status === 401) {
+        await this.getToken(true);
+        return await call();
+      }
+      throw e;
+    }
+  }
+
+  // ——— one-shot query (HTTP with de-dupe) ———
+  async query<Q extends FunctionReference<'query'> & { _args: Record<string, never> }>(
+    q: Q,
+  ): Promise<FunctionReturnType<Q>>;
+  async query<Q extends FunctionReference<'query'>>(
+    q: Q,
+    args: FunctionArgs<Q>,
+  ): Promise<FunctionReturnType<Q>>;
+  async query<Q extends FunctionReference<'query'>>(
+    q: Q,
+    args?: FunctionArgs<Q>,
+  ): Promise<FunctionReturnType<Q>> {
+    await this.ensureHttpAuth();
+
+    const name = getFunctionName(q);
+    const key = name + ':' + (args ? stableStringify(args) : '');
+
+    if (!this.inflightHttp.has(key)) {
+      this.inflightHttp.set(
+        key,
+        (async () => {
+          try {
+            return await this.http.query(q, ...(args ? ([args] as any) : []));
+          } catch (e: any) {
+            const status = e?.status ?? e?.response?.status;
+            if (this.fetchToken && status === 401) {
+              await this.getToken(true);
+              return await this.http.query(q, ...(args ? ([args] as any) : []));
+            }
+            throw e;
+          } finally {
+            setTimeout(() => this.inflightHttp.delete(key), 0);
+          }
+        })(),
+      );
+    }
+    return this.inflightHttp.get(key)!;
+  }
+}

package/src/lib/core/helpers.ts

@@ -0,0 +1,60 @@
+/**
+ * Internal helpers for ConvexAngularClient.
+ * NOTE: Pure refactor; functionality unchanged.
+ */
+
+export const AUTH_KEY = 'convex:jwt';
+export const AUTH_CH = 'convex-auth';
+
+/** Decode JWT exp claim (ms). Returns 0 if invalid. */
+export function jwtExpMs(jwt: string): number {
+  try {
+    const payload = JSON.parse(atob(jwt.split('.')[1] || ''));
+    return typeof payload?.exp === 'number' ? payload.exp * 1000 : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Canonical JSON stringify for stable de-dupe keys. */
+export function stableStringify(input: unknown): string {
+  const seen = new WeakSet<object>();
+  const norm = (v: any): any => {
+    if (v === null || typeof v !== 'object') return v;
+    if (seen.has(v)) return v;
+    seen.add(v);
+    if (Array.isArray(v)) return v.map(norm);
+    return Object.keys(v)
+      .sort()
+      .reduce((acc: any, k) => {
+        acc[k] = norm(v[k]);
+        return acc;
+      }, {});
+  };
+  return JSON.stringify(norm(input));
+}
+
+/** sessionStorage helpers (some browsers may throw on access) */
+export const safeSession = {
+  get: (k: string): string | null => {
+    try {
+      return typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(k) : null;
+    } catch {
+      return null;
+    }
+  },
+  set: (k: string, v: string) => {
+    try {
+      if (typeof sessionStorage !== 'undefined') sessionStorage.setItem(k, v);
+    } catch {
+      /* no-op */
+    }
+  },
+  del: (k: string) => {
+    try {
+      if (typeof sessionStorage !== 'undefined') sessionStorage.removeItem(k);
+    } catch {
+      /* no-op */
+    }
+  },
+};

package/src/lib/core/inject-convex.token.ts

@@ -0,0 +1,12 @@
+/**
+* Injection token and helper for accessing the Convex client from DI.
+* Keep this tiny and stable — many helpers rely on it.
+*/
+import { inject, InjectionToken } from '@angular/core';
+import { ConvexAngularClient } from './convex-angular-client';
+
+/** DI token for the configured ConvexAngularClient instance */
+export const CONVEX = new InjectionToken<ConvexAngularClient>('CONVEX');
+
+/** Convenience helper to inject the Convex client */
+export const injectConvex = () => inject(CONVEX);

package/src/lib/core/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared types for Convex Angular core.
+ * Pure extraction for readability; no behavior changes.
+ */
+
+/** Auth token fetcher used by ConvexAngularClient.setAuth */
+export type FetchAccessToken = (o: { forceRefreshToken: boolean }) => Promise<string | null>;
+
+/** Snapshot of current auth state (token presence-based) */
+export type AuthSnapshot = {
+  isAuthenticated: boolean;
+  token: string | null;
+  exp?: number;
+};