@mohasinac/appkit 2.1.3 → 2.3.0

package/src/providers/db-firebase/browser-stub.ts

@@ -1,47 +0,0 @@
-/**
- * Browser stub for @mohasinac/appkit/providers/db-firebase
- *
- * This file is served to the browser webpack build via the "browser"
- * condition in package.json exports.  All firebase-admin SDK code must
- * only run on the server; this stub exists solely to satisfy the
- * static-analysis graph without pulling any Node.js-only dependencies
- * into the client bundle.
- *
- * None of these functions are ever called in the browser — they are
- * defined here only so that webpack can resolve the module without error
- * and tree-shake the unused exports away.
- */
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-export function getAdminApp(): never {
-  throw new Error("getAdminApp is server-only");
-}
-export function getAdminAuth(): never {
-  throw new Error("getAdminAuth is server-only");
-}
-export function getAdminDb(): never {
-  throw new Error("getAdminDb is server-only");
-}
-export function getAdminStorage(): never {
-  throw new Error("getAdminStorage is server-only");
-}
-export function getAdminRealtimeDb(): never {
-  throw new Error("getAdminRealtimeDb is server-only");
-}
-export function _resetAdminSingletons(): void {
-  // no-op in browser
-}
-export function removeUndefined<T>(obj: T): T {
-  return obj;
-}
-export function prepareForFirestore(data: any): any {
-  return data;
-}
-export function deserializeTimestamps<T>(data: any): T {
-  return data as T;
-}
-export const FirebaseRepository: any = null;
-export const FirebaseSieveRepository: any = null;
-export const FirebaseRealtimeRepository: any = null;
-export const firebaseDbProvider: any = null;

package/src/providers/db-firebase/helpers.ts

@@ -1,88 +0,0 @@
-/**
- * Firestore serialisation helpers.
- *
- * These utilities are the single adapter boundary between raw Firestore
- * documents and application-level objects.
- */
-
-// ─── Undefined removal ────────────────────────────────────────────────────────
-
-/**
- * Recursively remove `undefined` values from an object.
- * Firestore rejects writes that contain `undefined` fields.
- */
-export function removeUndefined<T extends Record<string, unknown>>(
-  obj: T,
-): Partial<T> {
-  const result: Record<string, unknown> = {};
-
-  for (const key of Object.keys(obj)) {
-    const value = obj[key];
-    if (value === undefined) continue;
-
-    if (
-      value !== null &&
-      typeof value === "object" &&
-      !Array.isArray(value) &&
-      !(value instanceof Date) &&
-      !(
-        value as { constructor?: { name?: string } }
-      ).constructor?.name?.includes("Timestamp")
-    ) {
-      const cleaned = removeUndefined(value as Record<string, unknown>);
-      if (Object.keys(cleaned).length > 0) {
-        result[key] = cleaned;
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result as Partial<T>;
-}
-
-/**
- * Strip `undefined` values before any Firestore write.
- * Call this on every `create()` / `update()` payload.
- */
-export function prepareForFirestore<T extends Record<string, unknown>>(
-  data: T,
-): Partial<T> {
-  return removeUndefined(data);
-}
-
-// ─── Timestamp deserialisation ────────────────────────────────────────────────
-
-/**
- * Recursively convert Firestore `Timestamp` instances to plain `Date` objects.
- *
- * React Server Components cannot serialise Firestore `Timestamp` class instances
- * to Client Components.  `Date` objects are serialised as ISO strings.
- */
-export function deserializeTimestamps<T>(obj: T): T {
-  if (obj === null || obj === undefined) return obj;
-
-  // Firestore Timestamp — has .toDate() but is not a plain Date
-  if (
-    typeof obj === "object" &&
-    !(obj instanceof Date) &&
-    typeof (obj as { toDate?: unknown }).toDate === "function"
-  ) {
-    return (obj as unknown as { toDate(): Date }).toDate() as unknown as T;
-  }
-
-  if (Array.isArray(obj)) {
-    return obj.map(deserializeTimestamps) as unknown as T;
-  }
-
-  if (typeof obj === "object" && !(obj instanceof Date)) {
-    return Object.fromEntries(
-      Object.entries(obj as object).map(([k, v]) => [
-        k,
-        deserializeTimestamps(v),
-      ]),
-    ) as unknown as T;
-  }
-
-  return obj;
-}

package/src/providers/db-firebase/index.ts

@@ -1,60 +0,0 @@
-/**
- * @mohasinac/db-firebase
- *
- * Firebase Firestore + Realtime DB implementation of the repository contracts.
- *
- * @example
- * ```ts
- * import { FirebaseRepository } from "@mohasinac/db-firebase";
- * import type { Product } from "@/types";
- *
- * export class ProductRepository extends FirebaseRepository<Product> {
- *   constructor() { super("products"); }
- * }
- * ```
- */
-
-// Admin SDK singletons
-export {
-  getAdminApp,
-  getAdminAuth,
-  getAdminDb,
-  getAdminStorage,
-  getAdminRealtimeDb,
-  _resetAdminSingletons,
-} from "./admin";
-
-// Serialisation helpers
-export {
-  removeUndefined,
-  prepareForFirestore,
-  deserializeTimestamps,
-} from "./helpers";
-
-// Repository base classes
-export { FirebaseRepository } from "./base";
-export { FirebaseSieveRepository } from "./sieve";
-export { FirebaseRealtimeRepository } from "./realtime";
-
-// IDbProvider implementation — registers Firebase as the database backend.
-// Wire once in providers.config.ts: db: firebaseDbProvider
-import { FirebaseRepository } from "./base";
-import type { IDbProvider, IRepository } from "../../contracts";
-import type { DocumentData } from "firebase-admin/firestore";
-
-export const firebaseDbProvider: IDbProvider = {
-  getRepository<T>(collection: string): IRepository<T> {
-    return new FirebaseRepository<T & DocumentData>(
-      collection,
-    ) as unknown as IRepository<T>;
-  },
-};
-
-// Types re-exported for consumers
-export type {
-  SieveModel,
-  SieveFields,
-  SieveFieldConfig,
-  SieveOptions,
-  SieveResult,
-} from "./sieve";

package/src/providers/db-firebase/realtime.ts

@@ -1,185 +0,0 @@
-/**
- * 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 type {
-  IRealtimeRepository,
-  PagedResult,
-  SieveQuery,
-  WhereOp,
-} from "../../contracts";
-import type { DocumentData } from "firebase-admin/firestore";
-import { getAdminRealtimeDb } from "./admin";
-
-export abstract class FirebaseRealtimeRepository<
-  T extends DocumentData,
-> implements IRealtimeRepository<T> {
-  protected readonly path: string;
-
-  constructor(rtdbPath: string) {
-    this.path = rtdbPath;
-  }
-
-  protected get rtdb() {
-    return getAdminRealtimeDb();
-  }
-
-  protected nodeRef(id?: string) {
-    return id ? this.rtdb.ref(`${this.path}/${id}`) : this.rtdb.ref(this.path);
-  }
-
-  // ── IReadRepository ────────────────────────────────────────────────────────
-
-  async findById(id: string): Promise<T | null> {
-    const snap = await this.nodeRef(id).get();
-    if (!snap.exists()) return null;
-    return { id, ...snap.val() } as unknown as T;
-  }
-
-  async findAll(query?: SieveQuery): Promise<PagedResult<T>> {
-    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() as Record<string, Omit<T, "id">>;
-    let data: T[] = Object.entries(raw).map(
-      ([id, val]) => ({ id, ...val }) as unknown as T,
-    );
-
-    // Basic server-side sort (RTDB has no native multi-field sort)
-    if (query?.sort) {
-      const key = query.sort as keyof T;
-      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: keyof T, _op: WhereOp, value: unknown): Promise<T[]> {
-    // RTDB Admin SDK supports orderByChild + equalTo for == only
-    const snap = await this.nodeRef()
-      .orderByChild(field as string)
-      .equalTo(value as string | number | boolean | null)
-      .get();
-    if (!snap.exists()) return [];
-    const raw = snap.val() as Record<string, Omit<T, "id">>;
-    return Object.entries(raw).map(
-      ([id, val]) => ({ id, ...val }) as unknown as T,
-    );
-  }
-
-  // ── IWriteRepository ───────────────────────────────────────────────────────
-
-  async create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T> {
-    const now = Date.now();
-    const payload = { ...data, createdAt: now, updatedAt: now };
-    const ref = await this.nodeRef().push(payload);
-    return { id: ref.key as string, ...payload } as unknown as T;
-  }
-
-  async update(id: string, data: Partial<T>): Promise<T> {
-    const payload = { ...data, updatedAt: Date.now() };
-    await this.nodeRef(id).update(payload as object);
-    const snap = await this.nodeRef(id).get();
-    return { id, ...snap.val() } as unknown as T;
-  }
-
-  async delete(id: string): Promise<void> {
-    await this.nodeRef(id).remove();
-  }
-
-  async batchCreate(
-    items: Array<Omit<T, "id" | "createdAt" | "updatedAt">>,
-  ): Promise<T[]> {
-    return Promise.all(items.map((item) => this.create(item)));
-  }
-
-  async batchDelete(ids: string[]): Promise<void> {
-    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: string, cb: (data: T | null) => void): () => void {
-    const ref = this.nodeRef(id);
-    const handler = (snap: {
-      exists(): boolean;
-      val(): Record<string, unknown> | null;
-    }) => {
-      cb(snap.exists() ? ({ id, ...snap.val() } as unknown as T) : null);
-    };
-    ref.on("value", handler as never);
-    return () => ref.off("value", handler as never);
-  }
-
-  subscribeWhere(
-    field: keyof T,
-    value: unknown,
-    cb: (items: T[]) => void,
-  ): () => void {
-    const ref = this.nodeRef()
-      .orderByChild(field as string)
-      .equalTo(value as string | number | boolean | null);
-
-    const handler = (snap: {
-      exists(): boolean;
-      val(): Record<string, Record<string, unknown>> | null;
-    }) => {
-      if (!snap.exists()) {
-        cb([]);
-        return;
-      }
-      const raw = snap.val()!;
-      cb(Object.entries(raw).map(([id, v]) => ({ id, ...v }) as unknown as T));
-    };
-    ref.on("value", handler as never);
-    return () => ref.off("value", handler as never);
-  }
-}

package/src/providers/db-firebase/sieve.ts

@@ -1,136 +0,0 @@
-/**
- * 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 { SieveProcessorBase } from "@mohasinac/sievejs/services";
-import { createFirebaseAdapter } from "@mohasinac/sievejs/adapters/firebase";
-
-import { FirebaseRepository } from "./base";
-import { deserializeTimestamps } from "./helpers";
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-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;
-}
-
-const SIEVE_DEFAULTS: Required<SieveOptions> = {
-  caseSensitive: false,
-  defaultPageSize: 20,
-  maxPageSize: 100,
-  throwExceptions: false,
-};
-
-// ─── Class ────────────────────────────────────────────────────────────────────
-
-export 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 async sieveQuery<TResult extends DocumentData = T>(
-    model: SieveModel,
-    fields: SieveFields,
-    options?: SieveOptions & { baseQuery?: CollectionReference | Query },
-  ): Promise<SieveResult<TResult>> {
-    const { baseQuery, ...sieveOptions } = options ?? {};
-    const merged = { ...SIEVE_DEFAULTS, ...sieveOptions };
-    const base = baseQuery ?? this.getCollection();
-
-    const processor = new SieveProcessorBase({
-      adapter: createFirebaseAdapter() as never,
-      autoLoadConfig: false,
-      options: merged,
-      fields,
-    } as never);
-
-    // Count (no docs fetched)
-    const filteredQ = processor.apply(model, base, {
-      applyPagination: false,
-    } as never) as unknown as Query;
-    const total: number = (await filteredQ.count().get()).data().count;
-
-    // Paginated result
-    const pagedQ = processor.apply(model, base) as unknown as Query;
-    const snap = await pagedQ.get();
-
-    const items = snap.docs.map(
-      (d) =>
-        deserializeTimestamps({ id: d.id, ...d.data() }) as unknown as TResult,
-    );
-
-    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/src/providers/email-resend/index.ts

@@ -1,16 +0,0 @@
-/**
- * @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/src/providers/email-resend/provider.ts

@@ -1,103 +0,0 @@
-/**
- * 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";
-import type {
-  IEmailProvider,
-  EmailOptions,
-  EmailResult,
-} from "../../contracts";
-
-export interface ResendProviderOptions {
-  /** Resend API key. Defaults to `process.env.RESEND_API_KEY`. */
-  apiKey?: string;
-  /** Default "From" email address. */
-  fromEmail?: string;
-  /** Default "From" display name. */
-  fromName?: string;
-}
-
-/**
- * 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: ResendProviderOptions = {},
-): IEmailProvider {
-  const resolveKey = (): string =>
-    options.apiKey ?? process.env.RESEND_API_KEY?.trim() ?? "";
-
-  const resolveFrom = (): string => {
-    const name =
-      options.fromName ?? process.env.EMAIL_FROM_NAME?.trim() ?? "App";
-    const email =
-      options.fromEmail ??
-      process.env.EMAIL_FROM?.trim() ??
-      `noreply@${process.env.NEXT_PUBLIC_SITE_URL?.trim().replace(/^https?:\/\//, "") ?? "example.com"}`;
-    return `${name} <${email}>`;
-  };
-
-  return {
-    async send(opts: EmailOptions): Promise<EmailResult> {
-      const resend = new Resend(resolveKey());
-      const { data, error } = await resend.emails.send({
-        from: opts.from ?? resolveFrom(),
-        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,
-      } as Parameters<Resend["emails"]["send"]>[0]);
-
-      if (error) {
-        throw Object.assign(
-          new Error(
-            `Resend send failed: ${(error as { message?: string }).message ?? String(error)}`,
-          ),
-          { cause: error },
-        );
-      }
-
-      const accepted = Array.isArray(opts.to) ? opts.to : [opts.to];
-      return {
-        id: (data as { id?: string } | null)?.id ?? "",
-        accepted,
-        rejected: [],
-      };
-    },
-
-    async sendBatch(optsList: EmailOptions[]): Promise<EmailResult[]> {
-      return Promise.all(optsList.map((o) => this.send(o)));
-    },
-  };
-}