@mohasinac/appkit 2.3.0 → 2.3.2

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

@@ -0,0 +1,138 @@
+/**
+ * FirebaseRealtimeRepository<T>
+ *
+ * Abstract base implementing `IRealtimeRepository<T>` from `@mohasinac/contracts`
+ * against Firebase Realtime Database (Admin SDK).
+ *
+ * Realtime DB does not support Firestore-style queries; `findAll()` loads the
+ * entire collection node.  Use this only for small, high-churn datasets (e.g.
+ * presence, chat, live-bid prices).
+ *
+ * Usage:
+ * ```ts
+ * class PresenceRepository extends FirebaseRealtimeRepository<PresenceEntry> {
+ *   constructor() { super("presence"); }
+ * }
+ * ```
+ */
+import { getAdminRealtimeDb } from "./admin";
+export class FirebaseRealtimeRepository {
+    constructor(rtdbPath) {
+        this.path = rtdbPath;
+    }
+    get rtdb() {
+        return getAdminRealtimeDb();
+    }
+    nodeRef(id) {
+        return id ? this.rtdb.ref(`${this.path}/${id}`) : this.rtdb.ref(this.path);
+    }
+    // -- IReadRepository --------------------------------------------------------
+    async findById(id) {
+        const snap = await this.nodeRef(id).get();
+        if (!snap.exists())
+            return null;
+        return { id, ...snap.val() };
+    }
+    async findAll(query) {
+        const snap = await this.nodeRef().get();
+        if (!snap.exists()) {
+            return {
+                data: [],
+                total: 0,
+                page: 1,
+                perPage: query?.perPage ?? 20,
+                totalPages: 0,
+            };
+        }
+        const raw = snap.val();
+        let data = Object.entries(raw).map(([id, val]) => ({ id, ...val }));
+        // Basic server-side sort (RTDB has no native multi-field sort)
+        if (query?.sort) {
+            const key = query.sort;
+            const dir = query.order === "desc" ? -1 : 1;
+            data = data.slice().sort((a, b) => {
+                const av = a[key];
+                const bv = b[key];
+                if (av === bv)
+                    return 0;
+                return (av < bv ? -1 : 1) * dir;
+            });
+        }
+        const total = data.length;
+        const perPage = Math.max(1, query?.perPage ?? 20);
+        const page = Math.max(1, query?.page ?? 1);
+        const offset = (page - 1) * perPage;
+        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / perPage));
+        return {
+            data: data.slice(offset, offset + perPage),
+            total,
+            page,
+            perPage,
+            totalPages,
+        };
+    }
+    async findWhere(field, _op, value) {
+        // RTDB Admin SDK supports orderByChild + equalTo for == only
+        const snap = await this.nodeRef()
+            .orderByChild(field)
+            .equalTo(value)
+            .get();
+        if (!snap.exists())
+            return [];
+        const raw = snap.val();
+        return Object.entries(raw).map(([id, val]) => ({ id, ...val }));
+    }
+    // -- IWriteRepository -------------------------------------------------------
+    async create(data) {
+        const now = Date.now();
+        const payload = { ...data, createdAt: now, updatedAt: now };
+        const ref = await this.nodeRef().push(payload);
+        return { id: ref.key, ...payload };
+    }
+    async update(id, data) {
+        const payload = { ...data, updatedAt: Date.now() };
+        await this.nodeRef(id).update(payload);
+        const snap = await this.nodeRef(id).get();
+        return { id, ...snap.val() };
+    }
+    async delete(id) {
+        await this.nodeRef(id).remove();
+    }
+    async batchCreate(items) {
+        return Promise.all(items.map((item) => this.create(item)));
+    }
+    async batchDelete(ids) {
+        await Promise.all(ids.map((id) => this.delete(id)));
+    }
+    // -- IRealtimeRepository ---------------------------------------------------
+    /**
+     * Subscribe to a single RTDB node.
+     * Returns an unsubscribe function.
+     *
+     * NOTE: The Admin SDK `onValue` callback runs in-process but is not browser-side.
+     * For browser real-time, use the client SDK directly.
+     */
+    subscribe(id, cb) {
+        const ref = this.nodeRef(id);
+        const handler = (snap) => {
+            cb(snap.exists() ? { id, ...snap.val() } : null);
+        };
+        ref.on("value", handler);
+        return () => ref.off("value", handler);
+    }
+    subscribeWhere(field, value, cb) {
+        const ref = this.nodeRef()
+            .orderByChild(field)
+            .equalTo(value);
+        const handler = (snap) => {
+            if (!snap.exists()) {
+                cb([]);
+                return;
+            }
+            const raw = snap.val();
+            cb(Object.entries(raw).map(([id, v]) => ({ id, ...v })));
+        };
+        ref.on("value", handler);
+        return () => ref.off("value", handler);
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ */
+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";
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Shared Realtime Database path constants for auth/payment/bulk event channels.
+ */
+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",
+};

package/dist/providers/db-firebase/sieve.d.ts

@@ -0,0 +1,75 @@
+/**
+ * FirebaseSieveRepository<T>
+ *
+ * Extends `FirebaseRepository<T>` with a full Sieve DSL query (filters, sorts,
+ * page, pageSize) pushed entirely to Firestore — no in-memory iteration.
+ *
+ * Uses `@mohasinac/sievejs` for parsing the Sieve filter / sort grammar.
+ *
+ * Usage in subclasses:
+ * ```ts
+ * async list(model: SieveModel, baseQuery?: CollectionReference | Query) {
+ *   return this.sieveQuery<ProductDocument>(model, {
+ *     title:     { canFilter: true, canSort: true },
+ *     price:     { canFilter: true, canSort: true },
+ *     createdAt: { canFilter: true, canSort: true },
+ *   }, { baseQuery });
+ * }
+ * ```
+ */
+import type { CollectionReference, DocumentData, Query } from "firebase-admin/firestore";
+import { FirebaseRepository } from "./base";
+export type SieveFieldConfig = {
+    /** Override the Firestore document field name. Defaults to the key name. */
+    path?: string;
+    canFilter?: boolean;
+    canSort?: boolean;
+};
+export type SieveFields = Record<string, SieveFieldConfig>;
+export interface SieveModel {
+    /** Comma-delimited filter expressions, e.g. `status==published,price>=100` */
+    filters?: string;
+    /** Comma-delimited sort fields, `-` prefix = descending, e.g. `-createdAt,title` */
+    sorts?: string;
+    page?: number | string;
+    pageSize?: number | string;
+}
+export interface SieveOptions {
+    caseSensitive?: boolean;
+    defaultPageSize?: number;
+    maxPageSize?: number;
+    throwExceptions?: boolean;
+}
+export interface SieveResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+export type FirebaseSieveFieldConfig = SieveFieldConfig;
+export type FirebaseSieveFields = SieveFields;
+export type FirebaseSieveOptions = SieveOptions;
+export type FirebaseSieveResult<T> = SieveResult<T>;
+/**
+ * Apply Sieve DSL to a CollectionReference/Query without requiring repository subclassing.
+ */
+export declare function applySieveToFirestore<T extends DocumentData>(params: {
+    baseQuery: CollectionReference | Query;
+    model: SieveModel;
+    fields: SieveFields;
+    options?: SieveOptions;
+}): Promise<SieveResult<T>>;
+export declare abstract class FirebaseSieveRepository<T extends DocumentData> extends FirebaseRepository<T> {
+    /**
+     * Run a Sieve DSL query against Firestore at the DB layer.
+     *
+     * @param model     Parsed from HTTP query-string params.
+     * @param fields    Per-field filter / sort allowlist.
+     * @param options   Override defaults or supply a pre-filtered `baseQuery`.
+     */
+    protected sieveQuery<TResult extends DocumentData = T>(model: SieveModel, fields: SieveFields, options?: SieveOptions & {
+        baseQuery?: CollectionReference | Query;
+    }): Promise<SieveResult<TResult>>;
+}

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

@@ -0,0 +1,101 @@
+/**
+ * FirebaseSieveRepository<T>
+ *
+ * Extends `FirebaseRepository<T>` with a full Sieve DSL query (filters, sorts,
+ * page, pageSize) pushed entirely to Firestore — no in-memory iteration.
+ *
+ * Uses `@mohasinac/sievejs` for parsing the Sieve filter / sort grammar.
+ *
+ * Usage in subclasses:
+ * ```ts
+ * async list(model: SieveModel, baseQuery?: CollectionReference | Query) {
+ *   return this.sieveQuery<ProductDocument>(model, {
+ *     title:     { canFilter: true, canSort: true },
+ *     price:     { canFilter: true, canSort: true },
+ *     createdAt: { canFilter: true, canSort: true },
+ *   }, { baseQuery });
+ * }
+ * ```
+ */
+import { SieveProcessorBase } from "@mohasinac/sievejs/services";
+import { createFirebaseAdapter } from "@mohasinac/sievejs/adapters/firebase";
+import { FirebaseRepository } from "./base";
+import { deserializeTimestamps, getFirestoreCount } from "./helpers";
+const SIEVE_DEFAULTS = {
+    caseSensitive: false,
+    defaultPageSize: 20,
+    maxPageSize: 100,
+    throwExceptions: false,
+};
+/**
+ * Apply Sieve DSL to a CollectionReference/Query without requiring repository subclassing.
+ */
+export async function applySieveToFirestore(params) {
+    const { baseQuery, model, fields, options } = params;
+    const merged = { ...SIEVE_DEFAULTS, ...(options ?? {}) };
+    const processor = new SieveProcessorBase({
+        adapter: createFirebaseAdapter(),
+        autoLoadConfig: false,
+        options: merged,
+        fields,
+    });
+    const filteredQ = processor.apply(model, baseQuery, {
+        applyPagination: false,
+    });
+    const total = await getFirestoreCount(filteredQ);
+    const pagedQ = processor.apply(model, baseQuery);
+    const snap = await pagedQ.get();
+    const items = snap.docs.map((d) => deserializeTimestamps({ id: d.id, ...d.data() }));
+    const page = Math.max(1, Number(model.page ?? 1));
+    const pageSize = Math.min(merged.maxPageSize, Math.max(1, Number(model.pageSize ?? merged.defaultPageSize)));
+    const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
+    return {
+        items,
+        total,
+        page,
+        pageSize,
+        totalPages,
+        hasMore: page < totalPages,
+    };
+}
+// --- Class --------------------------------------------------------------------
+export class FirebaseSieveRepository extends FirebaseRepository {
+    /**
+     * Run a Sieve DSL query against Firestore at the DB layer.
+     *
+     * @param model     Parsed from HTTP query-string params.
+     * @param fields    Per-field filter / sort allowlist.
+     * @param options   Override defaults or supply a pre-filtered `baseQuery`.
+     */
+    async sieveQuery(model, fields, options) {
+        const { baseQuery, ...sieveOptions } = options ?? {};
+        const merged = { ...SIEVE_DEFAULTS, ...sieveOptions };
+        const base = baseQuery ?? this.getCollection();
+        const processor = new SieveProcessorBase({
+            adapter: createFirebaseAdapter(),
+            autoLoadConfig: false,
+            options: merged,
+            fields,
+        });
+        // Count (no docs fetched)
+        const filteredQ = processor.apply(model, base, {
+            applyPagination: false,
+        });
+        const total = await getFirestoreCount(filteredQ);
+        // Paginated result
+        const pagedQ = processor.apply(model, base);
+        const snap = await pagedQ.get();
+        const items = snap.docs.map((d) => deserializeTimestamps({ id: d.id, ...d.data() }));
+        const page = Math.max(1, Number(model.page ?? 1));
+        const pageSize = Math.min(merged.maxPageSize, Math.max(1, Number(model.pageSize ?? merged.defaultPageSize)));
+        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
+        return {
+            items,
+            total,
+            page,
+            pageSize,
+            totalPages,
+            hasMore: page < totalPages,
+        };
+    }
+}

package/dist/providers/email-resend/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @mohasinac/email-resend
+ *
+ * Resend implementation of `IEmailProvider` from `@mohasinac/contracts`.
+ *
+ * @example
+ * ```ts
+ * import { createResendProvider } from "@mohasinac/email-resend";
+ *
+ * const email = createResendProvider({ apiKey: process.env.RESEND_API_KEY });
+ * await email.send({ to: "user@example.com", subject: "Hello", html: "<p>Hi!</p>" });
+ * ```
+ */
+export { createResendProvider } from "./provider";
+export type { ResendProviderOptions } from "./provider";

package/dist/providers/email-resend/index.js

@@ -0,0 +1,14 @@
+/**
+ * @mohasinac/email-resend
+ *
+ * Resend implementation of `IEmailProvider` from `@mohasinac/contracts`.
+ *
+ * @example
+ * ```ts
+ * import { createResendProvider } from "@mohasinac/email-resend";
+ *
+ * const email = createResendProvider({ apiKey: process.env.RESEND_API_KEY });
+ * await email.send({ to: "user@example.com", subject: "Hello", html: "<p>Hi!</p>" });
+ * ```
+ */
+export { createResendProvider } from "./provider";

package/dist/providers/email-resend/provider.d.ts

@@ -0,0 +1,43 @@
+/**
+ * createResendProvider — IEmailProvider
+ *
+ * Factory that returns an `IEmailProvider` backed by the Resend API.
+ *
+ * @example
+ * ```ts
+ * import { createResendProvider } from "@mohasinac/email-resend";
+ *
+ * const email = createResendProvider({
+ *   apiKey:    process.env.RESEND_API_KEY!,
+ *   fromEmail: "noreply@example.com",
+ *   fromName:  "My App",
+ * });
+ *
+ * await email.send({ to: "user@example.com", subject: "Hello", html: "<p>Hi</p>" });
+ * ```
+ */
+import type { IEmailProvider } from "../../contracts";
+type ResolvedValue = string | Promise<string>;
+type ValueResolver = string | (() => ResolvedValue);
+export interface ResendProviderOptions {
+    /** Resend API key. Defaults to `process.env.RESEND_API_KEY`. */
+    apiKey?: ValueResolver;
+    /** Default "From" email address. */
+    fromEmail?: ValueResolver;
+    /** Default "From" display name. */
+    fromName?: ValueResolver;
+}
+/**
+ * Create an `IEmailProvider` backed by Resend.
+ *
+ * The API key and from-address are resolved lazily so that runtime
+ * key rotations (e.g. DB-stored credentials) are picked up without
+ * a server restart.  Pass a factory function to `apiKey` if you need
+ * dynamic resolution:
+ *
+ * ```ts
+ * createResendProvider({ apiKey: () => getKeyFromDb() })
+ * ```
+ */
+export declare function createResendProvider(options?: ResendProviderOptions): IEmailProvider;
+export {};

package/dist/providers/email-resend/provider.js

@@ -0,0 +1,75 @@
+/**
+ * createResendProvider — IEmailProvider
+ *
+ * Factory that returns an `IEmailProvider` backed by the Resend API.
+ *
+ * @example
+ * ```ts
+ * import { createResendProvider } from "@mohasinac/email-resend";
+ *
+ * const email = createResendProvider({
+ *   apiKey:    process.env.RESEND_API_KEY!,
+ *   fromEmail: "noreply@example.com",
+ *   fromName:  "My App",
+ * });
+ *
+ * await email.send({ to: "user@example.com", subject: "Hello", html: "<p>Hi</p>" });
+ * ```
+ */
+import { Resend } from "resend";
+async function resolveValue(value, fallback) {
+    if (typeof value === "function") {
+        const resolved = await value();
+        return resolved?.trim() || fallback;
+    }
+    return value?.trim() || fallback;
+}
+/**
+ * Create an `IEmailProvider` backed by Resend.
+ *
+ * The API key and from-address are resolved lazily so that runtime
+ * key rotations (e.g. DB-stored credentials) are picked up without
+ * a server restart.  Pass a factory function to `apiKey` if you need
+ * dynamic resolution:
+ *
+ * ```ts
+ * createResendProvider({ apiKey: () => getKeyFromDb() })
+ * ```
+ */
+export function createResendProvider(options = {}) {
+    return {
+        async send(opts) {
+            const apiKey = await resolveValue(options.apiKey, process.env.RESEND_API_KEY?.trim() ?? "");
+            const fromName = await resolveValue(options.fromName, process.env.EMAIL_FROM_NAME?.trim() ?? "App");
+            const fromEmail = await resolveValue(options.fromEmail, process.env.EMAIL_FROM?.trim() ??
+                `noreply@${process.env.NEXT_PUBLIC_SITE_URL?.trim().replace(/^https?:\/\//, "") ?? "example.com"}`);
+            const resend = new Resend(apiKey);
+            const { data, error } = await resend.emails.send({
+                from: opts.from ?? `${fromName} <${fromEmail}>`,
+                to: opts.to,
+                subject: opts.subject,
+                html: opts.html,
+                text: opts.text,
+                reply_to: opts.replyTo,
+                attachments: opts.attachments?.map((a) => ({
+                    filename: a.filename,
+                    content: a.content,
+                    content_type: a.contentType,
+                })),
+                headers: opts.headers,
+            });
+            if (error) {
+                throw Object.assign(new Error(`Resend send failed: ${error.message ?? String(error)}`), { cause: error });
+            }
+            const accepted = Array.isArray(opts.to) ? opts.to : [opts.to];
+            return {
+                id: data?.id ?? "",
+                accepted,
+                rejected: [],
+            };
+        },
+        async sendBatch(optsList) {
+            return Promise.all(optsList.map((o) => this.send(o)));
+        },
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { IClientAuthProvider } from "../../contracts/client-auth";
+/**
+ * Firebase Auth client SDK implementation of IClientAuthProvider.
+ */
+export declare class FirebaseClientAuthProvider implements IClientAuthProvider {
+    signInWithEmailAndPassword(email: string, password: string): Promise<void>;
+    applyActionCode(code: string): Promise<void>;
+    sendPasswordResetEmail(email: string): Promise<void>;
+    confirmPasswordReset(code: string, newPassword: string): Promise<void>;
+    reauthenticateAndChangePassword(currentPassword: string, newPassword: string): Promise<void>;
+    reloadCurrentUser(): Promise<void>;
+}

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

@@ -0,0 +1,29 @@
+import { applyActionCode as fbApplyActionCode, confirmPasswordReset as fbConfirmPasswordReset, EmailAuthProvider, getAuth, reauthenticateWithCredential, sendPasswordResetEmail as fbSendPasswordResetEmail, signInWithEmailAndPassword as fbSignInWithEmailAndPassword, updatePassword, } from "firebase/auth";
+/**
+ * Firebase Auth client SDK implementation of IClientAuthProvider.
+ */
+export class FirebaseClientAuthProvider {
+    async signInWithEmailAndPassword(email, password) {
+        await fbSignInWithEmailAndPassword(getAuth(), email, password);
+    }
+    async applyActionCode(code) {
+        await fbApplyActionCode(getAuth(), code);
+    }
+    async sendPasswordResetEmail(email) {
+        await fbSendPasswordResetEmail(getAuth(), email);
+    }
+    async confirmPasswordReset(code, newPassword) {
+        await fbConfirmPasswordReset(getAuth(), code, newPassword);
+    }
+    async reauthenticateAndChangePassword(currentPassword, newPassword) {
+        const user = getAuth().currentUser;
+        if (!user?.email)
+            throw new Error("No authenticated user.");
+        const credential = EmailAuthProvider.credential(user.email, currentPassword);
+        await reauthenticateWithCredential(user, credential);
+        await updatePassword(user, newPassword);
+    }
+    async reloadCurrentUser() {
+        await getAuth().currentUser?.reload();
+    }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Firebase Client SDK provider implementations.
+ *
+ * Consumer apps import these and register them in their client-side
+ * provider setup (e.g., a `Providers` component or layout).
+ */
+export { FirebaseClientRealtimeProvider } from "./realtime";
+export type { FirebaseClientRealtimeConfig } from "./realtime";
+export { FirebaseClientAuthProvider } from "./auth";

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

@@ -0,0 +1,8 @@
+/**
+ * Firebase Client SDK provider implementations.
+ *
+ * Consumer apps import these and register them in their client-side
+ * provider setup (e.g., a `Providers` component or layout).
+ */
+export { FirebaseClientRealtimeProvider } from "./realtime";
+export { FirebaseClientAuthProvider } from "./auth";

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

@@ -0,0 +1,18 @@
+import type { IClientRealtimeProvider, RealtimeSnapshot, Unsubscribe } from "../../contracts/client-realtime";
+export interface FirebaseClientRealtimeConfig {
+    /** Firebase client config for initializing the app */
+    firebaseConfig: Record<string, string | undefined>;
+    /** Name for the Firebase app instance (avoids colliding with the default app) */
+    appName?: string;
+}
+/**
+ * Firebase Realtime Database implementation of IClientRealtimeProvider.
+ */
+export declare class FirebaseClientRealtimeProvider implements IClientRealtimeProvider {
+    private app;
+    private db;
+    constructor(config: FirebaseClientRealtimeConfig);
+    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

@@ -0,0 +1,38 @@
+import { getApps, initializeApp } from "firebase/app";
+import { getDatabase, ref, onValue, off, } from "firebase/database";
+import { getAuth, signInWithCustomToken, signOut } from "firebase/auth";
+/**
+ * Firebase Realtime Database implementation of IClientRealtimeProvider.
+ */
+export class FirebaseClientRealtimeProvider {
+    constructor(config) {
+        const appName = config.appName ?? "appkit-realtime";
+        this.app =
+            getApps().find((a) => a.name === appName) ??
+                initializeApp(config.firebaseConfig, appName);
+        this.db = getDatabase(this.app);
+    }
+    async signInWithToken(token) {
+        await signInWithCustomToken(getAuth(this.app), token);
+    }
+    async signOut() {
+        try {
+            await signOut(getAuth(this.app));
+        }
+        catch {
+            // no-op — signing out of a secondary app can fail harmlessly
+        }
+    }
+    subscribe(path, onData, onError) {
+        const dbRef = ref(this.db, path);
+        const unsubscribe = onValue(dbRef, onData, onError);
+        return () => {
+            if (typeof unsubscribe === "function") {
+                unsubscribe();
+            }
+            else {
+                off(dbRef);
+            }
+        };
+    }
+}