@mohasinac/appkit 2.3.0 → 2.3.1

package/dist/features/admin/schemas/firestore.js

@@ -0,0 +1,251 @@
+/**
+ * Admin Feature Firestore Document Types & Constants
+ * Covers: notifications, chat rooms, site settings
+ */
+export const NOTIFICATIONS_COLLECTION = "notifications";
+export const NOTIFICATIONS_INDEXED_FIELDS = [
+    "userId",
+    "isRead",
+    "createdAt",
+    "type",
+];
+export const NOTIFICATION_FIELDS = {
+    ID: "id",
+    USER_ID: "userId",
+    TYPE: "type",
+    PRIORITY: "priority",
+    TITLE: "title",
+    MESSAGE: "message",
+    IMAGE_URL: "imageUrl",
+    ACTION_URL: "actionUrl",
+    ACTION_LABEL: "actionLabel",
+    IS_READ: "isRead",
+    READ_AT: "readAt",
+    RELATED_ID: "relatedId",
+    RELATED_TYPE: "relatedType",
+    CREATED_AT: "createdAt",
+    UPDATED_AT: "updatedAt",
+    TYPE_VALUES: {
+        ORDER_PLACED: "order_placed",
+        ORDER_CONFIRMED: "order_confirmed",
+        ORDER_SHIPPED: "order_shipped",
+        ORDER_DELIVERED: "order_delivered",
+        ORDER_CANCELLED: "order_cancelled",
+        BID_PLACED: "bid_placed",
+        BID_OUTBID: "bid_outbid",
+        BID_WON: "bid_won",
+        BID_LOST: "bid_lost",
+        REVIEW_APPROVED: "review_approved",
+        REVIEW_REPLIED: "review_replied",
+        PRODUCT_AVAILABLE: "product_available",
+        PROMOTION: "promotion",
+        SYSTEM: "system",
+        WELCOME: "welcome",
+        OFFER_RECEIVED: "offer_received",
+        OFFER_RESPONDED: "offer_responded",
+        OFFER_EXPIRED: "offer_expired",
+        OFFER_COUNTER_ACCEPTED: "offer_counter_accepted",
+        REFUND_INITIATED: "refund_initiated",
+    },
+    PRIORITY_VALUES: {
+        LOW: "low",
+        NORMAL: "normal",
+        HIGH: "high",
+    },
+};
+export const DEFAULT_NOTIFICATION_DATA = {
+    priority: "normal",
+    isRead: false,
+};
+export const NOTIFICATION_PUBLIC_FIELDS = [
+    "id",
+    "type",
+    "priority",
+    "title",
+    "message",
+    "imageUrl",
+    "actionUrl",
+    "actionLabel",
+    "isRead",
+    "readAt",
+    "relatedId",
+    "relatedType",
+    "createdAt",
+];
+export const notificationQueryHelpers = {
+    byUser: (userId) => ["userId", "==", userId],
+    unread: (userId) => [
+        ["userId", "==", userId],
+        ["isRead", "==", false],
+    ],
+    byType: (type) => ["type", "==", type],
+};
+export const CHAT_ROOM_COLLECTION = "chatRooms";
+export const CHAT_ROOM_INDEXED_FIELDS = [
+    "buyerId",
+    "sellerId",
+    "orderId",
+    "participantIds",
+    "adminDeleted",
+    "updatedAt",
+];
+export const CHAT_ROOM_FIELDS = {
+    ID: "id",
+    BUYER_ID: "buyerId",
+    SELLER_ID: "sellerId",
+    ORDER_ID: "orderId",
+    PRODUCT_ID: "productId",
+    PRODUCT_TITLE: "productTitle",
+    BUYER_NAME: "buyerName",
+    SELLER_NAME: "sellerName",
+    LAST_MESSAGE: "lastMessage",
+    LAST_MESSAGE_AT: "lastMessageAt",
+    CREATED_AT: "createdAt",
+    UPDATED_AT: "updatedAt",
+    DELETED_BY: "deletedBy",
+    IS_GROUP: "isGroup",
+    PARTICIPANT_IDS: "participantIds",
+    ADMIN_DELETED: "adminDeleted",
+};
+export const DEFAULT_CHAT_ROOM_DATA = {
+    buyerId: "",
+    sellerId: "",
+    orderId: "",
+    buyerName: "",
+    sellerName: "",
+    deletedBy: [],
+    isGroup: false,
+    participantIds: [],
+    adminDeleted: false,
+};
+export const chatRoomQueryHelpers = {
+    byBuyer: (buyerId) => ["buyerId", "==", buyerId],
+    bySeller: (sellerId) => ["sellerId", "==", sellerId],
+    byOrder: (orderId) => ["orderId", "==", orderId],
+    active: () => ["adminDeleted", "==", false],
+};
+export const SITE_SETTINGS_COLLECTION = "siteSettings";
+export const SITE_SETTINGS_INDEXED_FIELDS = [];
+export const DEFAULT_SITE_SETTINGS_DATA = {
+    id: "global",
+    siteName: "My Store",
+    motto: "Your Marketplace, Your Rules",
+    payment: {
+        razorpayEnabled: true,
+        upiManualEnabled: true,
+        codEnabled: true,
+    },
+    commissions: {
+        razorpayFeePercent: 5,
+        codDepositPercent: 10,
+        sellerShippingFixed: 0,
+        platformShippingPercent: 10,
+        platformShippingFixedMin: 0,
+    },
+    featureFlags: {
+        chats: true,
+        smsVerification: true,
+        translations: false,
+        wishlists: true,
+        auctions: true,
+        reviews: true,
+        events: true,
+        blog: true,
+        coupons: true,
+        notifications: true,
+        sellerRegistration: true,
+        preOrders: false,
+    },
+    shipping: {
+        estimatedDays: 5,
+        minOrderForFree: 0,
+    },
+    returns: {
+        windowDays: 7,
+    },
+    announcementBar: {
+        enabled: true,
+        message: "🎉 Up to 15% Off on Pokémon TCG this week — Use code SAVE15",
+    },
+};
+export const SITE_SETTINGS_PUBLIC_FIELDS = [
+    "siteName",
+    "motto",
+    "logo",
+    "background",
+    "contact.email",
+    "contact.phone",
+    "payment",
+    "commissions",
+    "socialLinks",
+    "seo",
+    "features",
+    "featureFlags",
+    "faq.variables",
+    "announcementBar",
+];
+export const DEFAULT_TRUST_BAR_ITEMS = [
+    { icon: "??", label: "Free Shipping", visible: true },
+    { icon: "??", label: "Easy Returns", visible: true },
+    { icon: "??", label: "Secure Payment", visible: true },
+    { icon: "??", label: "24/7 Support", visible: true },
+    { icon: "?", label: "Authentic Sellers", visible: true },
+];
+export const FEATURE_FLAG_META = [
+    {
+        key: "chats",
+        labelKey: "chats",
+        descKey: "chatsDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "smsVerification",
+        labelKey: "smsVerification",
+        descKey: "smsVerificationDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "translations",
+        labelKey: "translations",
+        descKey: "translationsDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "auctions",
+        labelKey: "auctions",
+        descKey: "auctionsDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "reviews",
+        labelKey: "reviews",
+        descKey: "reviewsDesc",
+        icon: "?",
+        category: "platform",
+    },
+    {
+        key: "notifications",
+        labelKey: "notifications",
+        descKey: "notificationsDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "sellerRegistration",
+        labelKey: "sellerRegistration",
+        descKey: "sellerRegistrationDesc",
+        icon: "??",
+        category: "platform",
+    },
+    {
+        key: "preOrders",
+        labelKey: "preOrders",
+        descKey: "preOrdersDesc",
+        icon: "??",
+        category: "platform",
+    },
+];

package/dist/features/admin/schemas/index.d.ts

@@ -0,0 +1 @@
+export * from "./firestore";

package/dist/features/admin/schemas/index.js

@@ -0,0 +1 @@
+export * from "./firestore";

package/dist/features/admin/server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @mohasinac/appkit/features/admin/server
+ *
+ * Server-only entry point for admin API route handlers.
+ */
+export * from "./actions";
+export { notificationRepository } from "./repository/notification.repository";
+export { chatRepository } from "./repository/chat.repository";
+export type { ChatRoomDocument, ChatRoomCreateInput, } from "./repository/chat.repository";
+export { siteSettingsRepository } from "./repository/site-settings.repository";
+export { GET as adminProductsGET } from "./api/products/route";
+export { GET as adminCouponsGET } from "./api/coupons/route";
+export { GET as adminReviewsGET } from "./api/reviews/route";
+export { GET as adminBidsGET } from "./api/bids/route";

package/dist/features/admin/server.js

@@ -0,0 +1,13 @@
+/**
+ * @mohasinac/appkit/features/admin/server
+ *
+ * Server-only entry point for admin API route handlers.
+ */
+export * from "./actions";
+export { notificationRepository } from "./repository/notification.repository";
+export { chatRepository } from "./repository/chat.repository";
+export { siteSettingsRepository } from "./repository/site-settings.repository";
+export { GET as adminProductsGET } from "./api/products/route";
+export { GET as adminCouponsGET } from "./api/coupons/route";
+export { GET as adminReviewsGET } from "./api/reviews/route";
+export { GET as adminBidsGET } from "./api/bids/route";

package/dist/features/admin/types/index.d.ts

@@ -0,0 +1,61 @@
+import type React from "react";
+import type { TableColumn } from "../../../contracts";
+export type { AdminProduct, AdminProductStatus, AdminProductDrawerMode, } from "./product.types";
+export { ADMIN_PRODUCT_STATUS_OPTIONS } from "./product.types";
+/**
+ * Admin-specific column definition that narrows `render` to `React.ReactNode`.
+ * Extends `TableColumn<T>` from `@mohasinac/contracts` so it is compatible
+ * with column arrays built from the base type.
+ */
+export interface AdminTableColumn<T = Record<string, unknown>> extends Omit<TableColumn<T>, "render"> {
+    render?: (row: T) => React.ReactNode;
+}
+export interface DashboardStats {
+    totalOrders?: number;
+    totalRevenue?: number;
+    totalUsers?: number;
+    totalProducts?: number;
+    pendingOrders?: number;
+    pendingReviews?: number;
+    newUsersToday?: number;
+    currency?: string;
+}
+export interface AdminListParams {
+    q?: string;
+    page?: number;
+    perPage?: number;
+    sort?: string;
+    filters?: string;
+}
+export interface AdminListResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+}
+export interface AnalyticsMonthEntry {
+    month: string;
+    orders: number;
+    revenue: number;
+}
+export interface AnalyticsTopProduct {
+    productId: string;
+    title: string;
+    revenue: number;
+    orders: number;
+    mainImage?: string;
+}
+export interface AnalyticsSummary {
+    totalOrders: number;
+    totalRevenue: number;
+    newOrdersThisMonth: number;
+    revenueThisMonth: number;
+    totalProducts?: number;
+    publishedProducts?: number;
+}
+export interface AdminAnalyticsData {
+    summary: AnalyticsSummary;
+    ordersByMonth: AnalyticsMonthEntry[];
+    topProducts: AnalyticsTopProduct[];
+}

package/dist/features/admin/types/index.js

@@ -0,0 +1 @@
+export { ADMIN_PRODUCT_STATUS_OPTIONS } from "./product.types";

package/dist/features/admin/types/product.types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Admin-specific product types for product management UI.
+ *
+ * These types extend/complement the core ProductItem with admin-only fields
+ * for managing auctions, pre-orders, stock, pricing, and lifecycle.
+ */
+export type AdminProductStatus = "draft" | "published" | "out_of_stock" | "discontinued" | "sold";
+export type AdminProductDrawerMode = "create" | "edit" | "delete" | null;
+/**
+ * Admin product form/management type.
+ *
+ * Combines core product data with admin-specific fields for:
+ * - Auction management (starting bid, reserve, auto-extend)
+ * - Pre-order management (delivery date, deposit %)
+ * - Promotion and pricing
+ * - Stock and shipping
+ */
+export interface AdminProduct {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    categoryId?: string;
+    subcategory?: string;
+    brand?: string;
+    price: number;
+    currency: string;
+    stockQuantity: number;
+    availableQuantity: number;
+    mainImage: string;
+    images: string[];
+    video?: {
+        url: string;
+        thumbnailUrl: string;
+        duration?: number;
+        trimStart?: number;
+        trimEnd?: number;
+    };
+    status: AdminProductStatus;
+    sellerId: string;
+    sellerName: string;
+    sellerEmail: string;
+    featured: boolean;
+    tags: string[];
+    shippingInfo?: string;
+    returnPolicy?: string;
+    condition?: "new" | "used" | "refurbished" | "broken";
+    insurance?: boolean;
+    insuranceCost?: number;
+    shippingPaidBy?: "seller" | "buyer";
+    isAuction?: boolean;
+    auctionEndDate?: string;
+    startingBid?: number;
+    currentBid?: number;
+    bidCount?: number;
+    reservePrice?: number;
+    buyNowPrice?: number;
+    minBidIncrement?: number;
+    autoExtendable?: boolean;
+    auctionExtensionMinutes?: number;
+    auctionOriginalEndDate?: string;
+    auctionShippingPaidBy?: "seller" | "winner";
+    isPromoted?: boolean;
+    promotionEndDate?: string;
+    pickupAddressId?: string;
+    isPreOrder?: boolean;
+    preOrderDeliveryDate?: string;
+    preOrderDepositPercent?: number;
+    preOrderMaxQuantity?: number;
+    preOrderProductionStatus?: "upcoming" | "in_production" | "ready_to_ship";
+    preOrderCancellable?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const ADMIN_PRODUCT_STATUS_OPTIONS: {
+    value: AdminProductStatus;
+    label: string;
+}[];

package/dist/features/admin/types/product.types.js

@@ -0,0 +1,13 @@
+/**
+ * Admin-specific product types for product management UI.
+ *
+ * These types extend/complement the core ProductItem with admin-only fields
+ * for managing auctions, pre-orders, stock, pricing, and lifecycle.
+ */
+export const ADMIN_PRODUCT_STATUS_OPTIONS = [
+    { value: "draft", label: "Draft" },
+    { value: "published", label: "Published" },
+    { value: "out_of_stock", label: "Out of Stock" },
+    { value: "discontinued", label: "Discontinued" },
+    { value: "sold", label: "Sold" },
+];

package/dist/features/auctions/actions/bid-actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bid Domain Actions (appkit/features/auctions)
+ *
+ * Business logic for auction bidding. Auth, rate-limiting, and
+ * input validation are handled by the calling server action.
+ */
+import type { BidDocument } from "../schemas";
+import type { FirebaseSieveResult } from "../../../providers/db-firebase";
+export interface PlaceBidInput {
+    productId: string;
+    bidAmount: number;
+    autoMaxBid?: number;
+}
+export interface PlaceBidResult {
+    bid: BidDocument;
+}
+export declare function placeBid(userId: string, userEmail: string, input: PlaceBidInput): Promise<PlaceBidResult>;
+export declare function listBidsByProduct(productId: string, params?: {
+    page?: number;
+    pageSize?: number;
+}): Promise<FirebaseSieveResult<Omit<BidDocument, "userEmail">>>;
+export declare function getBidById(id: string): Promise<BidDocument | null>;

package/dist/features/auctions/actions/bid-actions.js

@@ -0,0 +1,106 @@
+/**
+ * Bid Domain Actions (appkit/features/auctions)
+ *
+ * Business logic for auction bidding. Auth, rate-limiting, and
+ * input validation are handled by the calling server action.
+ */
+import { serverLogger } from "../../../monitoring";
+import { bidRepository } from "../repository/bid.repository";
+import { productRepository } from "../../products/repository/products.repository";
+import { userRepository } from "../../auth/repository/user.repository";
+import { unitOfWork } from "../../../core/unit-of-work";
+import { getAdminRealtimeDb } from "../../../providers/db-firebase";
+import { maskPublicBid } from "../../../security";
+import { ERROR_MESSAGES, AuthorizationError, ValidationError, NotFoundError, } from "../../../errors";
+import { getDefaultCurrency } from "../../../core/baseline-resolver";
+import { resolveDate } from "../../../utils";
+// --- Domain Functions ----------------------------------------------------------
+export async function placeBid(userId, userEmail, input) {
+    const { productId, bidAmount, autoMaxBid } = input;
+    const product = await productRepository.findById(productId);
+    if (!product)
+        throw new NotFoundError(ERROR_MESSAGES.BID.AUCTION_NOT_FOUND);
+    if (!product.isAuction)
+        throw new ValidationError(ERROR_MESSAGES.BID.NOT_AN_AUCTION);
+    if (product.auctionEndDate) {
+        const endDate = resolveDate(product.auctionEndDate);
+        if (endDate && endDate.getTime() < Date.now()) {
+            throw new ValidationError(ERROR_MESSAGES.BID.AUCTION_ENDED);
+        }
+    }
+    if (product.sellerId === userId) {
+        throw new AuthorizationError(ERROR_MESSAGES.BID.OWN_AUCTION);
+    }
+    const minimumBid = (product.currentBid ?? 0) > 0
+        ? product.currentBid
+        : (product.startingBid ?? product.price);
+    if (bidAmount <= minimumBid) {
+        throw new ValidationError(ERROR_MESSAGES.BID.BID_TOO_LOW);
+    }
+    const profile = await userRepository.findById(userId);
+    const bid = await bidRepository.create({
+        productId,
+        productTitle: product.title,
+        userId,
+        userName: profile?.displayName ?? userEmail ?? "Anonymous",
+        userEmail: profile?.email ?? userEmail ?? "",
+        bidAmount,
+        currency: product.currency || getDefaultCurrency(),
+        bidDate: new Date(),
+        ...(autoMaxBid ? { autoMaxBid } : {}),
+    });
+    const allBids = await bidRepository.findBy("productId", productId);
+    await unitOfWork.runBatch((batch) => {
+        for (const b of allBids) {
+            unitOfWork.bids.updateInBatch(batch, b.id, {
+                isWinning: b.id === bid.id,
+                status: b.id === bid.id ? "active" : "outbid",
+            });
+        }
+        unitOfWork.products.updateInBatch(batch, productId, {
+            currentBid: bidAmount,
+            bidCount: (product.bidCount ?? 0) + 1,
+        });
+    });
+    try {
+        const rtdb = getAdminRealtimeDb();
+        await rtdb.ref(`/auction-bids/${productId}`).set({
+            currentBid: bidAmount,
+            bidCount: (product.bidCount ?? 0) + 1,
+            lastBid: {
+                amount: bidAmount,
+                bidderName: "Bidder",
+                timestamp: Date.now(),
+            },
+            updatedAt: Date.now(),
+        });
+    }
+    catch (rtdbErr) {
+        serverLogger.warn("placeBid: RTDB write failed", {
+            error: rtdbErr,
+            productId,
+        });
+    }
+    serverLogger.info("placeBid", {
+        bidId: bid.id,
+        productId,
+        userId,
+        bidAmount,
+    });
+    return { bid };
+}
+export async function listBidsByProduct(productId, params) {
+    const result = await bidRepository.list({
+        filters: `productId==${productId}`,
+        sorts: "-bidAmount",
+        page: params?.page ?? 1,
+        pageSize: params?.pageSize ?? 20,
+    });
+    return {
+        ...result,
+        items: result.items.map(({ userEmail: _strip, ...rest }) => maskPublicBid(rest)),
+    };
+}
+export async function getBidById(id) {
+    return bidRepository.findById(id);
+}

package/dist/features/auctions/actions/index.d.ts

@@ -0,0 +1 @@
+export * from "./bid-actions";

package/dist/features/auctions/actions/index.js

@@ -0,0 +1 @@
+export * from "./bid-actions";

package/dist/features/auctions/api/route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * feat-auctions — Next.js App Router API handler (GET /api/bids)
+ *
+ * 2-line stub:
+ * ```ts
+ * // app/api/bids/route.ts
+ * export { GET } from "@mohasinac/feat-auctions";
+ * ```
+ *
+ * Requires `db` registered in providers.config via `registerProviders()`.
+ * Collection: "bids"
+ */
+import { NextResponse } from "next/server.js";
+export declare function GET(request: Request): Promise<NextResponse>;

package/dist/features/auctions/api/route.js

@@ -0,0 +1,67 @@
+/**
+ * feat-auctions — Next.js App Router API handler (GET /api/bids)
+ *
+ * 2-line stub:
+ * ```ts
+ * // app/api/bids/route.ts
+ * export { GET } from "@mohasinac/feat-auctions";
+ * ```
+ *
+ * Requires `db` registered in providers.config via `registerProviders()`.
+ * Collection: "bids"
+ */
+import { NextResponse } from "next/server.js";
+import { getProviders } from "../../../contracts";
+function param(url, key) {
+    return url.searchParams.get(key);
+}
+function numParam(url, key, fallback) {
+    const v = url.searchParams.get(key);
+    const n = v !== null ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : fallback;
+}
+// --- GET /api/bids ------------------------------------------------------------
+// Query params:
+//   auctionId — filter bids for a specific auction product (recommended)
+//   bidderId  — filter bids placed by a specific user
+//   sort      — Sieve sort field (default: "-amount" = highest bid first)
+//   page / pageSize — pagination
+export async function GET(request) {
+    try {
+        const url = new URL(request.url);
+        const auctionId = param(url, "auctionId");
+        const bidderId = param(url, "bidderId");
+        const sort = param(url, "sort") ?? "-amount";
+        const page = numParam(url, "page", 1);
+        const pageSize = numParam(url, "pageSize", 50);
+        const parts = [];
+        if (auctionId)
+            parts.push(`auctionId==${auctionId}`);
+        if (bidderId)
+            parts.push(`bidderId==${bidderId}`);
+        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("bids");
+        const result = await repo.findAll({
+            filters,
+            sort,
+            page,
+            perPage: pageSize,
+        });
+        const body = {
+            items: result.data,
+            total: result.total,
+            hasMore: result.data.length === pageSize,
+        };
+        const response = NextResponse.json({ success: true, data: body });
+        response.headers.set("Cache-Control", "public, max-age=10, s-maxage=15, stale-while-revalidate=30");
+        return response;
+    }
+    catch (error) {
+        console.error("[feat-auctions] GET /api/bids failed", error);
+        return NextResponse.json({ success: false, error: "Failed to fetch bids" }, { status: 500 });
+    }
+}

package/dist/features/auctions/columns/index.d.ts

@@ -0,0 +1,14 @@
+import type { TableColumn, ColumnExtensionOpts } from "../../../contracts";
+import type { AuctionItem, BidRecord } from "../types";
+/**
+ * Default admin column definitions for an auction table.
+ *
+ * @example
+ * const columns = buildAuctionColumns<MyAuction>({
+ *   extras: [{ key: "reservePrice", header: "Reserve", render: (a) => a.reservePrice ?? "—" }],
+ * });
+ */
+export declare const auctionAdminColumns: TableColumn<AuctionItem>[];
+export declare function buildAuctionColumns<T extends AuctionItem = AuctionItem>(opts?: ColumnExtensionOpts<T>): TableColumn<T>[];
+export declare const bidAdminColumns: TableColumn<BidRecord>[];
+export declare function buildBidColumns<T extends BidRecord = BidRecord>(opts?: ColumnExtensionOpts<T>): TableColumn<T>[];