@mohasinac/appkit 4.30.18 → 4.30.19

package/dist/providers/db-firebase/index.js

@@ -27,7 +27,6 @@ export { firebaseFieldOps } from "./field-ops";
 export { FirebaseRepository } from "./base";
 export { BaseRepository } from "./base.repository";
 export { FirebaseSieveRepository } from "./sieve";
-export { FirebaseRealtimeRepository } from "./realtime";
 // Re-export RTDB paths
 export { RTDB_PATHS } from "./rtdb-paths";
 import { FirebaseRepository as _FirebaseRepository } from "./base";

package/dist/providers/db-firebase/rtdb-paths.d.ts

@@ -1,13 +1,22 @@
 /**
- * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ * Shared Realtime Database path constants for the auth/payment/bulk event channels.
+ *
+ * 🛑 Only paths that are actually referenced through this constant belong here.
+ * Five keys were removed on 2026-08-29 — `PRESENCE`, `CHAT`, `NOTIFICATIONS`,
+ * `LIVE_UPDATES`, `SEED_EVENTS` — every one with **zero consumers**, because
+ * each live call site hardcodes its path string instead. A constant nobody uses
+ * is not a source of truth; it is a second place for the value to be wrong, and
+ * three of those five named RTDB nodes that no longer exist at all.
+ *
+ * If you add a key, migrate the call sites to it in the same change.
+ *
+ * This module has NO imports on purpose — that is what lets `browser-stub.ts`
+ * re-export it rather than keep the byte-for-byte duplicate it used to carry.
+ * The stub is the `browser` resolution target, so that duplicate meant client
+ * code and server code were reading two independently-maintained copies.
  */
 export declare const RTDB_PATHS: {
-    readonly PRESENCE: "presence";
-    readonly CHAT: "chat";
-    readonly NOTIFICATIONS: "notifications";
-    readonly LIVE_UPDATES: "live_updates";
     readonly AUTH_EVENTS: "auth_events";
     readonly PAYMENT_EVENTS: "payment_events";
     readonly BULK_EVENTS: "bulk_events";
-    readonly SEED_EVENTS: "seed_events";
 };

package/dist/providers/db-firebase/rtdb-paths.js

@@ -1,13 +1,22 @@
 /**
- * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ * Shared Realtime Database path constants for the auth/payment/bulk event channels.
+ *
+ * 🛑 Only paths that are actually referenced through this constant belong here.
+ * Five keys were removed on 2026-08-29 — `PRESENCE`, `CHAT`, `NOTIFICATIONS`,
+ * `LIVE_UPDATES`, `SEED_EVENTS` — every one with **zero consumers**, because
+ * each live call site hardcodes its path string instead. A constant nobody uses
+ * is not a source of truth; it is a second place for the value to be wrong, and
+ * three of those five named RTDB nodes that no longer exist at all.
+ *
+ * If you add a key, migrate the call sites to it in the same change.
+ *
+ * This module has NO imports on purpose — that is what lets `browser-stub.ts`
+ * re-export it rather than keep the byte-for-byte duplicate it used to carry.
+ * The stub is the `browser` resolution target, so that duplicate meant client
+ * code and server code were reading two independently-maintained copies.
  */
 export const RTDB_PATHS = {
-    PRESENCE: "presence",
-    CHAT: "chat",
-    NOTIFICATIONS: "notifications",
-    LIVE_UPDATES: "live_updates",
     AUTH_EVENTS: "auth_events",
     PAYMENT_EVENTS: "payment_events",
     BULK_EVENTS: "bulk_events",
-    SEED_EVENTS: "seed_events",
 };

package/dist/providers/db-firebase/rtdb-url.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the Realtime Database URL from the environment.
+ *
+ * Its own module, with **no imports**, because both `admin.ts` and
+ * `admin-app-lite.ts` need it and `admin-app-lite` exists precisely to avoid
+ * pulling in the full admin module. They previously carried byte-for-byte
+ * duplicate resolution logic, which meant the bug below existed twice.
+ *
+ * 🛑 Returns `undefined` rather than guessing.
+ *
+ * All six copies used to fall back to `https://${projectId}-default-rtdb.firebaseio.com`.
+ * That is the **us-central1** URL shape; this project's instance lives at
+ * `…-default-rtdb.asia-southeast1.firebasedatabase.app`. So whenever the env var
+ * was missing, every server RTDB write silently targeted a database that does
+ * not exist — and since all nine RTDB writers wrap their call in a swallowing
+ * try/catch, messaging, bids, job status and payment signalling would every one
+ * of them degrade to "nothing ever updates", with clean warn-level logs.
+ *
+ * A guessed URL cannot be correct for a non-default region, so guessing buys
+ * nothing and costs the ability to notice. With no `databaseURL`,
+ * `getAdminRealtimeDb()` fails loudly at first use instead, which is the
+ * outcome you want.
+ *
+ * `||` not `??`: an env var that is present but empty must fall through, and
+ * `??` only falls through on null/undefined.
+ */
+export declare function resolveRtdbUrl(): string | undefined;

package/dist/providers/db-firebase/rtdb-url.js

@@ -0,0 +1,50 @@
+/**
+ * Resolve the Realtime Database URL from the environment.
+ *
+ * Its own module, with **no imports**, because both `admin.ts` and
+ * `admin-app-lite.ts` need it and `admin-app-lite` exists precisely to avoid
+ * pulling in the full admin module. They previously carried byte-for-byte
+ * duplicate resolution logic, which meant the bug below existed twice.
+ *
+ * 🛑 Returns `undefined` rather than guessing.
+ *
+ * All six copies used to fall back to `https://${projectId}-default-rtdb.firebaseio.com`.
+ * That is the **us-central1** URL shape; this project's instance lives at
+ * `…-default-rtdb.asia-southeast1.firebasedatabase.app`. So whenever the env var
+ * was missing, every server RTDB write silently targeted a database that does
+ * not exist — and since all nine RTDB writers wrap their call in a swallowing
+ * try/catch, messaging, bids, job status and payment signalling would every one
+ * of them degrade to "nothing ever updates", with clean warn-level logs.
+ *
+ * A guessed URL cannot be correct for a non-default region, so guessing buys
+ * nothing and costs the ability to notice. With no `databaseURL`,
+ * `getAdminRealtimeDb()` fails loudly at first use instead, which is the
+ * outcome you want.
+ *
+ * `||` not `??`: an env var that is present but empty must fall through, and
+ * `??` only falls through on null/undefined.
+ */
+export function resolveRtdbUrl() {
+    // 🛑 Emulator first.
+    //
+    // `firebase.json` has declared a database emulator on port 9000 for a long
+    // time and NOTHING ever connected to it. Client writes were shielded only
+    // because every rule is `.write: false`; server writes use the Admin SDK and
+    // bypass rules entirely — so `npm run dev` wrote to PRODUCTION. A local bid
+    // overwrote the prod `auction-bids` node that live auction pages subscribe to,
+    // and a local message send wrote prod `chats/**`.
+    //
+    // `FIREBASE_DATABASE_EMULATOR_HOST` is the standard variable the Firebase CLI
+    // exports for exactly this, so honouring it costs one branch and makes
+    // `firebase emulators:start` do what everyone already assumed it did.
+    const emulatorHost = process.env.FIREBASE_DATABASE_EMULATOR_HOST?.trim();
+    if (emulatorHost) {
+        const ns = process.env.FIREBASE_ADMIN_PROJECT_ID?.trim() ||
+            process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID?.trim() ||
+            "default";
+        return `http://${emulatorHost}?ns=${ns}`;
+    }
+    return (process.env.FIREBASE_ADMIN_DATABASE_URL?.trim() ||
+        process.env.NEXT_PUBLIC_FIREBASE_DATABASE_URL?.trim() ||
+        undefined);
+}

package/dist/providers/firebase-client/realtime.d.ts

@@ -11,7 +11,27 @@ export interface FirebaseClientRealtimeConfig {
 export declare class FirebaseClientRealtimeProvider implements IClientRealtimeProvider {
     private app;
     private db;
+    private readonly config;
+    private readonly appName;
+    private readonly scoped;
     constructor(config: FirebaseClientRealtimeConfig);
+    /**
+     * A provider bound to its OWN Firebase app for this claim scope.
+     *
+     * 🛑 This is what makes concurrent channels safe. Firebase Auth state is
+     * per-app, so with one shared app every `signInWithToken` REPLACED the claims
+     * of every other live subscriber: a bulk job signing in with a
+     * `{ bulkJobId }`-only token instantly stripped `conversationIds` from an open
+     * messages subscription, and vice versa. Whoever signed in last won.
+     *
+     * Reference-counting fixed only the sign-OUT half of that (a finishing job no
+     * longer ends someone else's session). Sign-IN needed separate apps, because
+     * there is nothing to coordinate — two channels legitimately need two
+     * different claim sets at the same time.
+     *
+     * Apps are cached per scope and reused, so a remount does not leak one.
+     */
+    forScope(scope: string): IClientRealtimeProvider;
     signInWithToken(token: string): Promise<void>;
     signOut(): Promise<void>;
     subscribe(path: string, onData: (snapshot: RealtimeSnapshot) => void, onError?: (error: Error) => void): Unsubscribe;

package/dist/providers/firebase-client/realtime.js

@@ -7,12 +7,44 @@ import { getAuth, signInWithCustomToken, signOut } from "firebase/auth";
  */
 export class FirebaseClientRealtimeProvider {
     constructor(config) {
+        this.scoped = new Map();
         const appName = config.appName ?? "appkit-realtime";
+        this.config = config;
+        this.appName = appName;
         this.app =
             getApps().find((a) => a.name === appName) ??
                 initializeApp(config.firebaseConfig, appName);
         this.db = getDatabase(this.app);
     }
+    /**
+     * A provider bound to its OWN Firebase app for this claim scope.
+     *
+     * 🛑 This is what makes concurrent channels safe. Firebase Auth state is
+     * per-app, so with one shared app every `signInWithToken` REPLACED the claims
+     * of every other live subscriber: a bulk job signing in with a
+     * `{ bulkJobId }`-only token instantly stripped `conversationIds` from an open
+     * messages subscription, and vice versa. Whoever signed in last won.
+     *
+     * Reference-counting fixed only the sign-OUT half of that (a finishing job no
+     * longer ends someone else's session). Sign-IN needed separate apps, because
+     * there is nothing to coordinate — two channels legitimately need two
+     * different claim sets at the same time.
+     *
+     * Apps are cached per scope and reused, so a remount does not leak one.
+     */
+    forScope(scope) {
+        const existing = this.scoped.get(scope);
+        if (existing)
+            return existing;
+        // Firebase app names are freeform, but keep them predictable in devtools.
+        const safe = scope.replace(/[^a-zA-Z0-9_-]/g, "-");
+        const child = new FirebaseClientRealtimeProvider({
+            ...this.config,
+            appName: `${this.appName}-${safe}`,
+        });
+        this.scoped.set(scope, child);
+        return child;
+    }
     async signInWithToken(token) {
         await signInWithCustomToken(getAuth(this.app), token);
     }
@@ -21,8 +53,9 @@ export class FirebaseClientRealtimeProvider {
             await signOut(getAuth(this.app));
         }
         catch (_err) {
+            // A secondary Firebase app that was never signed in has nothing to sign
+            // out of; the caller's goal (no credential on this app) already holds.
             void normalizeError(_err);
-            // no-op — signing out of a secondary app can fail harmlessly
         }
     }
     subscribe(path, onData, onError) {

package/dist/providers.d.ts

@@ -12,7 +12,7 @@
 export { registerProviders, getProviders } from "./contracts/index";
 export { configureMarketDefaults } from "./core/baseline-resolver";
 export { firebaseAuthProvider, firebaseSessionProvider, createSessionCookieFromToken, createSessionCookie, verifyIdToken, verifySessionCookie, createMiddlewareAuthChain, requireAuth, requireRole, requireAuthUser, requireRoleUser, getUserFromRequest, requireAuthFromRequest, requireRoleFromRequest, revokeUserTokens, } from "./providers/auth-firebase/index";
-export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, FirebaseRealtimeRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
+export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
 export type { DocumentSnapshot } from "firebase-admin/firestore";
 export { firebaseStorageProvider } from "./providers/storage-firebase/index";
 export { createResendProvider } from "./providers/email-resend/index";

package/dist/providers.js

@@ -15,7 +15,7 @@ export { configureMarketDefaults } from "./core/baseline-resolver";
 // Auth (Firebase Admin)
 export { firebaseAuthProvider, firebaseSessionProvider, createSessionCookieFromToken, createSessionCookie, verifyIdToken, verifySessionCookie, createMiddlewareAuthChain, requireAuth, requireRole, requireAuthUser, requireRoleUser, getUserFromRequest, requireAuthFromRequest, requireRoleFromRequest, revokeUserTokens, } from "./providers/auth-firebase/index";
 // Database (Firebase Firestore / RTDB)
-export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, FirebaseRealtimeRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
+export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStorage, getAdminRealtimeDb, _resetAdminSingletons, FirebaseRepository, BaseRepository, FirebaseSieveRepository, RTDB_PATHS, firebaseFieldOps, removeUndefined, prepareForFirestore, deserializeTimestamps, } from "./providers/db-firebase/index";
 // Storage (Firebase Admin)
 export { firebaseStorageProvider } from "./providers/storage-firebase/index";
 // Email (Resend)

package/dist/react/hooks/use-action-dispatch.js

@@ -1,5 +1,6 @@
 "use client";
 import { normalizeError } from "../../errors/normalize";
+import { toUserMessage } from "../../errors/error-display-map";
 import { useCallback } from "react";
 import { useRouter } from "next/navigation";
 import { useToast } from "../../ui";
@@ -33,8 +34,13 @@ export function useActionDispatch(options) {
                         showToast(action.successMessage, "success");
                 }
                 catch (err) {
-                    void normalizeError(err);
-                    showToast(action.errorMessage ?? (err instanceof Error ? err.message : "Something went wrong."), "error");
+                    const e = normalizeError(err);
+                    // The action's own errorMessage still wins — it is the most
+                    // specific authored copy available. Only the tail changed: it now
+                    // resolves the error's CODE and ends in a constant, instead of
+                    // ending in the thrown value's developer-facing text.
+                    showToast(action.errorMessage ??
+                        toUserMessage(e.code, undefined, { fallback: "Something went wrong." }), "error");
                 }
                 break;
         }

package/dist/react/hooks/useFormStatePreservation.js

@@ -28,10 +28,12 @@ export function useFormStatePreservation({ values, onRestore, stripFields = [],
         try {
             const decoded = JSON.parse(atob(encoded));
             onRestore(decoded);
+            // The payload is user-supplied via the URL, so corrupt input is expected
+            // rather than exceptional. Discarding it restores the empty form, which is
+            // the same state as arriving without one.
         }
         catch (_err) {
             void normalizeError(_err);
-            // ignore corrupt payloads
         }
     }, [paramName, onRestore]);
     useEffect(() => {

package/dist/react/hooks/useRealtimeEvent.js

@@ -2,7 +2,7 @@
 import { normalizeError } from "../../errors/normalize";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { getClientRealtimeProvider, } from "../../contracts/client-realtime";
-import { acquireExternalRealtimeLease } from "../../contracts/realtime-session";
+import { acquireRealtimeSession } from "../../contracts/realtime-session";
 import { RealtimeEventType, RealtimeEventStatus, RTDBPayloadStatus, } from "./realtime-event-constants";
 // Re-exported for existing client import paths — the canonical definitions
 // now live in realtime-event-constants.ts (a plain, non-"use client" module)
@@ -32,8 +32,10 @@ export function useRealtimeEvent(config) {
     const unsubscribeRef = useRef(null);
     const timeoutRef = useRef(null);
     const eventIdRef = useRef(null);
-    /** Lease on the shared realtime session — see cleanup() for why. */
+    /** Lease on this event's realtime session — see cleanup() for why. */
     const releaseSessionRef = useRef(null);
+    /** Provider bound to THIS scope's app; subscribe through it, not the global. */
+    const scopedProviderRef = useRef(null);
     const cleanup = useCallback(() => {
         if (unsubscribeRef.current) {
             unsubscribeRef.current();
@@ -57,6 +59,7 @@ export function useRealtimeEvent(config) {
         // end one, and only once the last consumer has let go.
         releaseSessionRef.current?.();
         releaseSessionRef.current = null;
+        scopedProviderRef.current = null;
     }, []);
     const subscribe = useCallback((eventId, customToken) => {
         const { type, rtdbPath, realtimeProvider, timeoutMs = DEFAULT_TIMEOUT_MS, extractData, messages, onLogError, } = configRef.current;
@@ -72,12 +75,20 @@ export function useRealtimeEvent(config) {
         setData(null);
         (async () => {
             try {
-                await provider.signInWithToken(customToken);
-                // Hold a lease for as long as this subscription lives. This hook owns
-                // its own sign-in (the token carries a job-scoped `bulkJobId` claim),
-                // but it must still participate in the ref-count so its cleanup
-                // cannot end a session another channel is relying on.
-                releaseSessionRef.current = acquireExternalRealtimeLease();
+                // Sign in through the session, which gives this event its OWN Firebase
+                // app for the `event:*` scope.
+                //
+                // That isolation is the fix. Firebase Auth state is per-app, so while
+                // every channel shared one app, this hook's `{ bulkJobId }`-only token
+                // replaced the claims of any live messages or chat subscription the
+                // moment a job started — and theirs replaced this one's in return.
+                // Ref-counting had only stopped a FINISHING channel from signing the
+                // others out; it could not stop a STARTING one from signing itself in
+                // over them, because there was nothing to coordinate: two channels
+                // legitimately need two different claim sets at the same time.
+                const lease = await acquireRealtimeSession(`event:${type}:${eventId}`, () => Promise.resolve({ customToken, expiresAt: Date.now() + 3600000 }));
+                releaseSessionRef.current = lease.release;
+                scopedProviderRef.current = lease.provider;
             }
             catch (authErr) {
                 void normalizeError(authErr);
@@ -102,7 +113,7 @@ export function useRealtimeEvent(config) {
                 return;
             }
             setStatus(RealtimeEventStatus.PENDING);
-            unsubscribeRef.current = provider.subscribe(`${rtdbPath}/${eventId}`, (snapshot) => {
+            unsubscribeRef.current = (scopedProviderRef.current ?? provider).subscribe(`${rtdbPath}/${eventId}`, (snapshot) => {
                 if (!snapshot.exists())
                     return;
                 const raw = snapshot.val();

package/dist/ui/components/toolbar-collapse.js

@@ -48,11 +48,10 @@ export function readCollapsedPref(id) {
 export function writeCollapsedPref(id, value) {
     try {
         window.sessionStorage.setItem(STORAGE_PREFIX + id, value ? "1" : "0");
+        // sessionStorage blocked (private browsing). Collapsing still works this render, it just will not survive a re-mount.
     }
     catch (_err) {
         void normalizeError(_err);
-        // sessionStorage unavailable (private browsing, etc.) — collapsing still
-        // works for the current render, it just doesn't survive a re-mount.
     }
 }
 export function defaultCollapsedForViewport() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.30.18",
+  "version": "4.30.19",
   "license": "MIT",
   "publishConfig": {
     "access": "public"