@razakalpha/convngx 0.2.0 → 0.2.2

package/README.md

@@ -1,4 +1,4 @@
-# convNGX
+# @razakalpha/convngx
 
 Angular-first utilities for Convex with Better Auth:
 - DI-wrapped Convex client with Better Auth token refresh
@@ -8,13 +8,17 @@ Angular-first utilities for Convex with Better Auth:
 
 Demo app: projects/example-chat (Angular + Convex + Better Auth)
 
-## Install peer deps
+## Installation
 
-Use your app's package.json; this library provides Angular wrappers and expects Convex + Better Auth to be available.
+Install the package and its peer dependencies:
 
 ```bash
-npm i convex @convex-dev/better-auth better-auth
+npm install @razakalpha/convngx convex @convex-dev/better-auth better-auth
 ```
+
+### Peer Dependencies
+
+This library provides Angular wrappers and expects Convex + Better Auth to be available in your project.
 ## Assumptions
 
 This library assumes your Convex backend uses Better Auth (via `@convex-dev/better-auth`) and exposes the Better Auth HTTP endpoints on your Convex site (e.g. `https://YOUR.convex.site`). The Angular providers wire the Convex client to Better Auth, handle proactive token refresh, and optionally support cross‑domain OTT handoff.
@@ -25,7 +29,7 @@ Register the provider once in your bootstrap:
 
 ```ts
 import { bootstrapApplication } from '@angular/platform-browser';
-import { provideConvexAngular } from 'convngx';
+import { provideConvexAngular } from '@razakalpha/convngx';
 import { AppComponent } from './app';
 
 bootstrapApplication(AppComponent, {
@@ -45,7 +49,7 @@ bootstrapApplication(AppComponent, {
 Inject the Convex client anywhere:
 
 ```ts
-import { injectConvex } from 'convngx';
+import { injectConvex } from '@razakalpha/convngx';
 
 const convex = injectConvex();
 // convex.query(...), convex.watchQuery(...), convex.mutation(...), convex.action(...)
@@ -58,7 +62,7 @@ Angular Resource wrapper around Convex watchQuery with smart gating, keep-last,
 Core usage:
 
 ```ts
-import { convexLiveResource } from 'convngx';
+import { convexLiveResource } from '@razakalpha/convngx';
 import { api } from '@/convex/_generated/api';
 
 // Live updated with angular resource api
@@ -110,7 +114,7 @@ function convexLiveResource<Q extends FunctionReference<'query'>>(
 
 Global default for keep mode (optional DI)
 ```ts
-import { provideConvexResourceOptions } from 'convngx';
+import { provideConvexResourceOptions } from '@razakalpha/convngx';
 
 bootstrapApplication(App, {
   providers: [
@@ -126,7 +130,7 @@ Implementation: src/lib/resources/live.resource.ts
 A mutation helper that returns an imperative `run()` plus resource-shaped state and derived signals. Supports optimistic updates, callbacks, basic concurrency controls, and retries.
 
 ```ts
-import { convexMutationResource } from 'convngx';
+import { convexMutationResource } from '@razakalpha/convngx';
 import { api } from '@/convex/_generated/api';
 
 // Minimal
@@ -182,7 +186,7 @@ Implementation: src/lib/resources/mutation.resource.ts
 Identical ergonomics to mutations but calls `convex.action`. Useful for long-running or external API calls.
 
 ```ts
-import { convexActionResource } from 'convngx';
+import { convexActionResource } from '@razakalpha/convngx';
 import { api } from '@/convex/_generated/api';
 
 const exportData = convexActionResource(api.reports.export, {
@@ -238,7 +242,7 @@ Example service (from the chat app) that derives a reactive `isAuthenticated`:
 ```ts
 // projects/example-chat/src/app/state/convex-auth.state.ts
 import { Injectable, computed, inject, signal } from '@angular/core';
-import { CONVEX, type ConvexAngularClient } from 'convngx';
+import { CONVEX, type ConvexAngularClient } from '@razakalpha/convngx';
 
 @Injectable({ providedIn: 'root' })
 export class ConvexAuthState {
@@ -271,7 +275,7 @@ Snippet from the chat component:
 
 ```ts
 import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
-import { convexLiveResource, convexMutationResource } from 'convngx';
+import { convexLiveResource, convexMutationResource } from '@razakalpha/convngx';
 import { api } from 'convex/_generated/api';
 
 @Component({ /* ... */ })
@@ -307,7 +311,7 @@ export class ChatComponent {
 ## Build
 
 ```bash
-ng build convngx-angular
+ng build alpha-convngx
 ```
 
 Outputs to dist/convngx.

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.0",
-  "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.2",
+  "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,89 @@
+/**
+ * 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;
+          const { data } = await auth.convex.token();
+          return data?.token ?? null;
+        };
+
+        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)!;
+  }
+}