@mohasinac/appkit 2.1.3 → 2.3.0

package/src/features/cron/jobs/auction-expiry.job.ts

@@ -1,76 +0,0 @@
-import type { IRepository } from "../../../contracts";
-import { createCronJob } from "../registry";
-
-/**
- * Built-in job: Close live auctions whose `endTime` has passed.
- *
- * Run interval: every 5 minutes (recommended).
- * Requires an `IRepository<AuctionDocument>` injected at registration time.
- *
- * @example
- * ```ts
- * import { getProviders } from "../../../contracts";
- * import { createAuctionExpiryJob } from "@mohasinac/appkit/cron";
- *
- * const { db } = getProviders();
- * export const auctionExpiry = createAuctionExpiryJob(
- *   db!.getRepository("auctions")
- * );
- * ```
- */
-
-interface AuctionDocument {
-  id: string;
-  status: string;
-  endTime: string | number;
-  highestBidAmount?: number;
-  closedAt?: string;
-}
-
-export function createAuctionExpiryJob(
-  auctionRepo: IRepository<AuctionDocument>,
-) {
-  return createCronJob(
-    {
-      name: "auctions_expire",
-      description: "Close live auctions whose endTime has passed.",
-      schedule: "every 5 minutes",
-      timezone: "UTC",
-      memory: "256MB",
-      timeoutSeconds: 60,
-    },
-    async (ctx) => {
-      const result = await auctionRepo.findAll({
-        filters: `status==live,endTime<=${ctx.scheduleTime}`,
-        perPage: 500,
-      });
-
-      let processed = 0;
-      let errors = 0;
-
-      for (const auction of result.data) {
-        try {
-          const status =
-            (auction.highestBidAmount ?? 0) > 0
-              ? "ended_with_winner"
-              : "ended_no_winner";
-
-          await auctionRepo.update(auction.id, {
-            status,
-            closedAt: new Date().toISOString(),
-          } as Partial<AuctionDocument>);
-
-          processed++;
-        } catch {
-          errors++;
-        }
-      }
-
-      return {
-        summary: `Closed ${processed} auctions (${errors} errors)`,
-        processed,
-        errors,
-      };
-    },
-  );
-}

package/src/features/cron/jobs/preorder-reminder.job.ts

@@ -1,64 +0,0 @@
-import type { IRepository } from "../../../contracts";
-import { createCronJob } from "../registry";
-
-/**
- * Built-in job: Mark pre-orders as "shipping_soon" when their
- * `expectedShippingDate` falls within the next 7 days.
- *
- * Run interval: "every 24 hours" or via daily cron.
- */
-
-interface PreOrderDocument {
-  id: string;
-  status: string;
-  expectedShippingDate?: string;
-}
-
-export function createPreOrderReminderJob(
-  preOrderRepo: IRepository<PreOrderDocument>,
-) {
-  const sevenDaysFromNow = () => {
-    const d = new Date();
-    d.setDate(d.getDate() + 7);
-    return d.toISOString();
-  };
-
-  return createCronJob(
-    {
-      name: "pre_orders_reminder",
-      description:
-        "Flag pre-orders whose expectedShippingDate is within 7 days.",
-      schedule: "every 24 hours",
-      timezone: "UTC",
-      memory: "256MB",
-      timeoutSeconds: 60,
-    },
-    async () => {
-      const cutoff = sevenDaysFromNow();
-      const result = await preOrderRepo.findAll({
-        filters: `status==confirmed,expectedShippingDate<=${cutoff}`,
-        perPage: 500,
-      });
-
-      let processed = 0;
-      let errors = 0;
-
-      for (const order of result.data) {
-        try {
-          await preOrderRepo.update(order.id, {
-            status: "shipping_soon",
-          } as Partial<PreOrderDocument>);
-          processed++;
-        } catch {
-          errors++;
-        }
-      }
-
-      return {
-        summary: `Flagged ${processed} pre-orders as shipping_soon (${errors} errors)`,
-        processed,
-        errors,
-      };
-    },
-  );
-}

package/src/features/cron/registry.ts

@@ -1,115 +0,0 @@
-import type {
-  CronJobDefinition,
-  CronRegistry,
-  CronRegistrySummary,
-  JobContext,
-  JobResult,
-  ScheduledJobFn,
-} from "./types";
-
-// ─── Global Registry ──────────────────────────────────────────────────────────
-
-const registry: CronRegistry = new Map();
-
-// ─── createCronJob ────────────────────────────────────────────────────────────
-
-/**
- * Factory that creates a fully-typed cron job definition and registers it
- * in the global CronRegistry.
- *
- * @example
- * ```ts
- * export const auctionExpiryJob = createCronJob(
- *   {
- *     name: "auctions_expire",
- *     description: "Close live auctions whose endTime has passed.",
- *     schedule: "every 5 minutes",
- *     timezone: "Asia/Kolkata",
- *   },
- *   async (ctx) => {
- *     // ... implementation
- *     return { summary: "Done", processed: 12, errors: 0 };
- *   },
- * );
- * ```
- */
-export function createCronJob(
-  options: Omit<CronJobDefinition, "handler">,
-  handler: ScheduledJobFn,
-): CronJobDefinition {
-  const definition: CronJobDefinition = {
-    timezone: "UTC",
-    memory: "256MB",
-    timeoutSeconds: 60,
-    ...options,
-    handler,
-  };
-
-  if (registry.has(definition.name)) {
-    throw new Error(
-      `[CronRegistry] Duplicate job name: "${definition.name}". Each job must have a unique name.`,
-    );
-  }
-
-  registry.set(definition.name, definition);
-  return definition;
-}
-
-// ─── Registry Accessors ───────────────────────────────────────────────────────
-
-/** Returns the global registry map (read-only view). */
-export function getCronRegistry(): ReadonlyMap<string, CronJobDefinition> {
-  return registry;
-}
-
-/** Returns a serialisable summary of all registered jobs. */
-export function getCronRegistrySummary(): CronRegistrySummary {
-  const jobs = Array.from(registry.values()).map((j) => ({
-    name: j.name,
-    description: j.description,
-    schedule: j.schedule,
-    timezone: j.timezone ?? "UTC",
-  }));
-  return { count: jobs.length, jobs };
-}
-
-/** Finds a registered job by name, or returns undefined. */
-export function findCronJob(name: string): CronJobDefinition | undefined {
-  return registry.get(name);
-}
-
-/**
- * Reset — only for use in unit tests.
- * @internal
- */
-export function _resetCronRegistry(): void {
-  registry.clear();
-}
-
-// ─── runJob (test / CI helper) ────────────────────────────────────────────────
-
-/**
- * Manually invoke any registered job by name.
- * Useful in integration tests and one-off admin scripts.
- *
- * @example
- * ```ts
- * const result = await runJob("auctions_expire", {
- *   scheduleTime: new Date().toISOString(),
- * });
- * ```
- */
-export async function runJob(
-  name: string,
-  ctx?: Partial<Omit<JobContext, "jobName">>,
-): Promise<JobResult> {
-  const job = registry.get(name);
-  if (!job) {
-    throw new Error(`[CronRegistry] No job registered with name: "${name}"`);
-  }
-  return job.handler({
-    scheduleTime: ctx?.scheduleTime ?? new Date().toISOString(),
-    jobName: name,
-    messageData: ctx?.messageData,
-  });
-}

package/src/features/cron/types.ts

@@ -1,83 +0,0 @@
-/**
- * Cron job types for @mohasinac/appkit/cron.
- *
- * Provides a strongly-typed system for defining, registering, and dispatching
- * scheduled Firebase Function jobs (onSchedule + Pub/Sub).
- *
- * No Firebase SDK imported here — types only.
- */
-
-// ─── Job context ──────────────────────────────────────────────────────────────
-
-/** Context passed into every scheduled job at runtime. */
-export interface JobContext {
-  /** ISO 8601 string of the time this job was scheduled to run. */
-  scheduleTime: string;
-  /** Logical name registered in the CronRegistry. */
-  jobName: string;
-  /** Optional pub/sub message data (base64 decoded string). */
-  messageData?: string;
-}
-
-/** Result returned from every job handler. */
-export interface JobResult {
-  /** Human-readable summary of what happened. */
-  summary: string;
-  /** Number of records/items processed. */
-  processed: number;
-  /** Number of errors encountered (0 = clean run). */
-  errors: number;
-  /** Any extra key/value metadata the job wants to surface. */
-  meta?: Record<string, unknown>;
-}
-
-// ─── Job definition ───────────────────────────────────────────────────────────
-
-/** The async function that runs when the job is triggered. */
-export type ScheduledJobFn = (ctx: JobContext) => Promise<JobResult>;
-
-/** A pub/sub triggered job function. */
-export type PubSubJobFn = (
-  data: string | null,
-  ctx: Omit<JobContext, "messageData">,
-) => Promise<JobResult>;
-
-/** Full job definition stored in the registry. */
-export interface CronJobDefinition {
-  /** Unique name for this job (used in logs and pub/sub topic). */
-  name: string;
-  /** Human-readable description. */
-  description: string;
-  /**
-   * Cron schedule string (Firebase/Cloud Scheduler format).
-   * Example: "every 5 minutes" | "0 * * * *"
-   */
-  schedule: string;
-  /** Timezone for the schedule. Default: "UTC". */
-  timezone?: string;
-  /** Memory allocation for the Function. Default: "256MB". */
-  memory?: "128MB" | "256MB" | "512MB" | "1GB" | "2GB";
-  /** Timeout in seconds. Default: 60. */
-  timeoutSeconds?: number;
-  /** The async handler that runs on each invocation. */
-  handler: ScheduledJobFn;
-}
-
-/** Options for createCronJob() factory. */
-export type CreateCronJobOptions = Omit<CronJobDefinition, "handler">;
-
-// ─── Registry types ───────────────────────────────────────────────────────────
-
-/** Map of job name → definition. */
-export type CronRegistry = Map<string, CronJobDefinition>;
-
-/** Summary of all registered jobs (for logging / health-check routes). */
-export interface CronRegistrySummary {
-  count: number;
-  jobs: Array<{
-    name: string;
-    description: string;
-    schedule: string;
-    timezone: string;
-  }>;
-}

package/src/features/events/api/[id]/route.ts

@@ -1,123 +0,0 @@
-/**
- * feat-events — single event detail (GET /api/events/[id])
- *
- * 2-line stub:
- * ```ts
- * // app/api/events/[id]/route.ts
- * export { eventIdGET as GET } from "@mohasinac/feat-events";
- * ```
- *
- * Returns a single active or ended event (draft/paused → 404).
- * For poll events with resultsVisibility='always': includes live vote counts.
- * For survey events with hasLeaderboard: includes top-10 leaderboard (PII stripped).
- *
- * Requires `db` registered in providers.config via `registerProviders()`.
- * Collections: "events", "eventEntries"
- */
-
-import { NextResponse } from "next/server.js";
-import { getProviders } from "../../../../contracts";
-import type { EventItem, EventEntryItem } from "../../types/index";
-
-type RouteContext = { params: Promise<{ id: string }> };
-
-// ─── GET /api/events/[id] ─────────────────────────────────────────────────────
-export async function GET(
-  _request: Request,
-  context: RouteContext,
-): Promise<NextResponse> {
-  try {
-    const { id } = await context.params;
-
-    const { db } = getProviders();
-    if (!db) {
-      return NextResponse.json(
-        { success: false, error: "Database provider not registered" },
-        { status: 503 },
-      );
-    }
-
-    const eventsRepo = db.getRepository<EventItem>("events");
-    const event = await eventsRepo.findById(id);
-
-    if (!event || event.status === "draft" || event.status === "paused") {
-      return NextResponse.json(
-        { success: false, error: "Event not found" },
-        { status: 404 },
-      );
-    }
-
-    // Strip internal field
-    const { createdBy: _createdBy, ...publicEvent } = event as EventItem & {
-      createdBy?: string;
-    };
-
-    const entriesRepo = db.getRepository<EventEntryItem>("eventEntries");
-
-    // For poll events with resultsVisibility='always': compute live vote tallies
-    let pollResults: {
-      optionId: string;
-      label: string;
-      count: number;
-      percent: number;
-    }[] = [];
-    if (
-      event.type === "poll" &&
-      event.pollConfig?.resultsVisibility === "always"
-    ) {
-      const allEntries = await entriesRepo.findAll({
-        filters: `eventId==${id}`,
-        perPage: 1000,
-      });
-
-      const voteCounts: Record<string, number> = {};
-      for (const entry of allEntries.data) {
-        for (const optionId of entry.pollVotes ?? []) {
-          voteCounts[optionId] = (voteCounts[optionId] ?? 0) + 1;
-        }
-      }
-
-      const total = allEntries.total || 1;
-      pollResults = (event.pollConfig.options ?? []).map((opt) => ({
-        optionId: opt.id,
-        label: opt.label,
-        count: voteCounts[opt.id] ?? 0,
-        percent: Math.round(((voteCounts[opt.id] ?? 0) / total) * 100),
-      }));
-    }
-
-    // For survey events with leaderboard: top-10 approved entries, PII stripped
-    let leaderboard: unknown[] = [];
-    if (event.type === "survey" && event.surveyConfig?.hasLeaderboard) {
-      const leaderboardResult = await entriesRepo.findAll({
-        filters: `eventId==${id},reviewStatus==approved`,
-        sort: "points",
-        order: "desc",
-        perPage: 10,
-      });
-
-      leaderboard = leaderboardResult.data.map((entry) => {
-        const {
-          userId: _userId,
-          userEmail: _userEmail,
-          ...rest
-        } = entry as EventEntryItem & {
-          userId?: string;
-          userEmail?: string;
-        };
-        return rest;
-      });
-    }
-
-    return NextResponse.json({
-      success: true,
-      data: { ...publicEvent, pollResults, leaderboard },
-    });
-  } catch (error) {
-    console.error("[feat-events] GET /api/events/[id] failed", error);
-    return NextResponse.json(
-      { success: false, error: "Failed to fetch event" },
-      { status: 500 },
-    );
-  }
-}

package/src/features/events/api/route.ts

@@ -1,110 +0,0 @@
-/**
- * feat-events — Next.js App Router API handler (GET /api/events)
- *
- * Consuming projects can create a 2-line stub:
- *
- * ```ts
- * // app/api/events/route.ts
- * export { GET } from "@mohasinac/feat-events";
- * ```
- */
-
-import { NextResponse } from "next/server.js";
-import { getProviders } from "../../../contracts";
-import type { EventItem, EventListResponse } from "../types/index";
-
-function param(url: URL, key: string): string | null {
-  return url.searchParams.get(key);
-}
-
-function numParam(url: URL, key: string, fallback: number): number {
-  const v = url.searchParams.get(key);
-  const n = v !== null ? Number(v) : NaN;
-  return Number.isFinite(n) ? n : fallback;
-}
-
-const SAFE_EVENT_FILTER_FIELDS = new Set([
-  "status",
-  "title",
-  "type",
-  "startsAt",
-  "endsAt",
-  "createdAt",
-]);
-
-function validateSieveFilters(
-  raw: string,
-  allowedFields: ReadonlySet<string>,
-): string {
-  return raw
-    .split(",")
-    .map((c) => c.trim())
-    .filter((c) => {
-      const m = c.match(/^([^<>=!@]+)\s*(?:==|!=|<=|>=|<|>|@=\*?)/);
-      return m ? allowedFields.has(m[1].trim()) : false;
-    })
-    .join(",");
-}
-
-// ——— GET /api/events ————————————————————————————————
-export async function GET(request: Request): Promise<NextResponse> {
-  try {
-    const url = new URL(request.url);
-    const page = numParam(url, "page", 1);
-    const pageSize = numParam(url, "pageSize", 24);
-    const sort = param(url, "sorts") ?? param(url, "sort") ?? "-startsAt";
-
-    const parts: string[] = ["status==active"];
-    const q = param(url, "q");
-    if (q) parts.push(`title@=*${q}`);
-    const raw = param(url, "filters");
-    if (raw) {
-      const safe = validateSieveFilters(raw, SAFE_EVENT_FILTER_FIELDS);
-      if (safe) parts.push(safe);
-    }
-    const filters = parts.join(",");
-
-    const { db } = getProviders();
-    if (!db) {
-      return NextResponse.json(
-        { success: false, error: "Database provider not registered" },
-        { status: 503 },
-      );
-    }
-
-    const repo = db.getRepository<EventItem>("events");
-    const result = await repo.findAll({
-      filters,
-      sort,
-      page,
-      perPage: pageSize,
-    });
-
-    const totalPages = Math.max(1, Math.ceil(result.total / pageSize));
-
-    // Strip internal fields (createdBy) before returning
-    const items = result.data.map((event) => {
-      const { createdBy: _createdBy, ...publicEvent } = event as EventItem & {
-        createdBy?: string;
-      };
-      return publicEvent as EventItem;
-    });
-
-    const body: EventListResponse = {
-      items: items as EventItem[],
-      total: result.total,
-      page: result.page,
-      pageSize,
-      totalPages,
-      hasMore: result.page < totalPages,
-    };
-
-    return NextResponse.json({ success: true, data: body });
-  } catch (error) {
-    console.error("[feat-events] GET /api/events failed", error);
-    return NextResponse.json(
-      { success: false, error: "Failed to fetch events" },
-      { status: 500 },
-    );
-  }
-}

package/src/features/events/columns/index.ts

@@ -1,54 +0,0 @@
-import type { TableColumn, ColumnExtensionOpts } from "../../../contracts";
-import type { EventItem } from "../types";
-
-/**
- * Default admin column definitions for an event table.
- *
- * @example
- * const columns = buildEventColumns<MyEvent>({
- *   overrides: { title: { render: (e) => <Link href={e.id}>{e.title}</Link> } },
- *   extras: [{ key: "brandId", header: "Brand", render: (e) => e.brandId ?? "—" }],
- * });
- */
-export const eventAdminColumns: TableColumn<EventItem>[] = [
-  { key: "title", header: "Title", sortable: true },
-  { key: "type", header: "Type", sortable: true },
-  { key: "status", header: "Status", sortable: true },
-  { key: "startsAt", header: "Starts At", sortable: true },
-  { key: "endsAt", header: "Ends At", sortable: true },
-  {
-    key: "totalEntries",
-    header: "Entries",
-    sortable: true,
-    render: (e) => e.stats.totalEntries.toLocaleString(),
-  },
-  {
-    key: "flaggedEntries",
-    header: "Flagged",
-    render: (e) => e.stats.flaggedEntries.toLocaleString(),
-  },
-  { key: "createdAt", header: "Created", sortable: true },
-];
-
-/**
- * Build a merged column list from the base event columns.
- *
- * @example
- * const cols = buildEventColumns<MyEvent>({
- *   omit: ["flaggedEntries"],
- *   extras: [{ key: "rewardPoints", header: "Points", render: (e) => e.rewardPoints }],
- * });
- */
-export function buildEventColumns<T extends EventItem = EventItem>(
-  opts?: ColumnExtensionOpts<T>,
-): TableColumn<T>[] {
-  const base = eventAdminColumns as TableColumn<T>[];
-  const omit = new Set(opts?.omit ?? []);
-  const cols = base
-    .filter((col) => !omit.has(col.key))
-    .map((col) => {
-      const ovr = opts?.overrides?.[col.key];
-      return ovr ? { ...col, ...ovr } : col;
-    });
-  return opts?.extras ? [...cols, ...opts.extras] : cols;
-}

package/src/features/events/components/AdminEventEntriesView.tsx

@@ -1,39 +0,0 @@
-import React from "react";
-
-export interface AdminEventEntriesViewProps {
-  /** Back-link and event title header */
-  renderHeader?: () => React.ReactNode;
-  /** Stats banner (total / approved / flagged counts) */
-  renderStats?: () => React.ReactNode;
-  /** Filter bar (status dropdown, sort, search) */
-  renderFilters?: () => React.ReactNode;
-  /** Entries data table */
-  renderTable: () => React.ReactNode;
-  /** Pagination footer */
-  renderPagination?: () => React.ReactNode;
-  /** Entry review side-drawer */
-  renderReviewDrawer?: () => React.ReactNode;
-  isLoading?: boolean;
-  className?: string;
-}
-
-export function AdminEventEntriesView({
-  renderHeader,
-  renderStats,
-  renderFilters,
-  renderTable,
-  renderPagination,
-  renderReviewDrawer,
-  className = "",
-}: AdminEventEntriesViewProps) {
-  return (
-    <div className={`space-y-4 ${className}`}>
-      {renderHeader?.()}
-      {renderStats?.()}
-      {renderFilters?.()}
-      {renderTable()}
-      {renderPagination?.()}
-      {renderReviewDrawer?.()}
-    </div>
-  );
-}