@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/collector-drops/actions/bid-actions.js

@@ -0,0 +1,454 @@
+import { normalizeError } from "../../../errors/normalize.js";
+/**
+ * Bid Domain Actions (appkit/features/collector-drops)
+ *
+ * Business logic for collector drop bidding. Auth, rate-limiting, and
+ * input validation are handled by the calling server action.
+ */
+import { SIEVE_OP, sieveFilter } from "../../../utils/sieve-builder.js";
+import { sortBy } from "../../../constants/sort.js";
+import { serverLogger } from "../../../monitoring/index.js";
+import { bidRepository } from "../repository/bid.repository.js";
+import { productRepository } from "../../products/repository/products.repository.js";
+import { isCollectorDropListing } from "../../products/utils/listing-type.js";
+import { userRepository } from "../../auth/repository/user.repository.js";
+import { isSoftBanned } from "../../auth/server/checkSoftBan.js";
+import { unitOfWork } from "../../../core/unit-of-work.js";
+import { storeRepository } from "../../stores/repository/store.repository.js";
+import { siteSettingsRepository } from "../../admin/repository/site-settings.repository.js";
+import { getAdminRealtimeDb } from "../../../providers/db-firebase/index.js";
+import { maskPublicBid } from "../../../security/index.js";
+import { isBuyNowAvailable, resolveMinBid, resolveMinBidIncrement, } from "../../../_internal/shared/features/collector-drops/config.js";
+import { sendNotification } from "../../admin/actions/notification-actions.js";
+import { BID_MESSAGES } from "../../../_internal/server/jobs/handlers/messages.js";
+import { ERROR_MESSAGES, AuthorizationError, ValidationError, NotFoundError, } from "../../../errors/index.js";
+import { BID_ERROR_CODES } from "../../../errors/error-codes.js";
+import { increment } from "../../../contracts/field-ops.js";
+import { getDefaultCurrency } from "../../../core/baseline-resolver.js";
+import { cartRepository } from "../../cart/repository/cart.repository.js";
+import { COLLECTOR_DROP_BUYOUT_WINDOW_MINUTES, COLLECTOR_DROP_BUYOUT_WINDOW_MS, COLLECTOR_DROP_CHECKOUT_URL, } from "../../../_internal/shared/checkout/lanes.js";
+import { resolveDate } from "../../../utils/index.js";
+import { safeRead } from "../../../errors/safe-read.js";
+// --- Domain Functions ----------------------------------------------------------
+/**
+ * Load the bidder's profile and refuse if they carry an active `place_bids`
+ * soft ban. Returns the profile so the caller pays for exactly one read.
+ *
+ * 🛑 This belongs in the DOMAIN function, not in a route.
+ *
+ * Admins can issue a `place_bids` soft ban and `BID_ERROR_CODES.USER_BANNED`
+ * has always existed with a display-map entry and client copy — but nothing
+ * ever threw it. The only `isSoftBanned(user, "place_bids")` call in the
+ * codebase sat in `POST /api/collector-drops/[id]/buy-now`, a route with zero callers,
+ * while the live path (the `placeBidAction` / `buyNowAction` server actions)
+ * checked nothing. A banned user could bid and buy out freely. Enforcing it
+ * here means every caller — action, route, or job — is covered by
+ * construction.
+ */
+async function assertCanBid(userId) {
+    const profile = await userRepository.findById(userId);
+    if (profile && isSoftBanned(profile, "place_bids")) {
+        const ban = profile.softBans?.find((b) => b.action === "place_bids");
+        throw new AuthorizationError(`Your account is restricted from bidding. Reason: ${ban?.reason ?? "Policy violation"}.`, { code: BID_ERROR_CODES.USER_BANNED });
+    }
+    return profile ?? null;
+}
+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.COLLECTOR_DROP_NOT_FOUND);
+    if (!isCollectorDropListing(product))
+        throw new ValidationError(ERROR_MESSAGES.BID.NOT_A_COLLECTOR_DROP);
+    if (product.isSold) {
+        throw new ValidationError(ERROR_MESSAGES.BID.COLLECTOR_DROP_ENDED, { code: BID_ERROR_CODES.COLLECTOR_DROP_ENDED });
+    }
+    if (product.collectorDropEndDate) {
+        const endDate = resolveDate(product.collectorDropEndDate);
+        if (endDate && endDate.getTime() < Date.now()) {
+            throw new ValidationError(ERROR_MESSAGES.BID.COLLECTOR_DROP_ENDED, { code: BID_ERROR_CODES.COLLECTOR_DROP_ENDED });
+        }
+    }
+    if (product.storeId) {
+        const store = await storeRepository.findById(product.storeId);
+        if (store?.ownerId === userId) {
+            throw new AuthorizationError(ERROR_MESSAGES.BID.OWN_COLLECTOR_DROP);
+        }
+    }
+    // Before any write. The profile is reused below for the bid's denormalised
+    // userName/userEmail, so the ban check costs no extra read.
+    const profile = await assertCanBid(userId);
+    // A collector drop with no bids yet prices off its starting bid, and that starting
+    // bid is itself acceptable — see ResolveMinBidOptions.hasBids.
+    const hasBids = (product.currentBid ?? 0) > 0 || (product.bidCount ?? 0) > 0;
+    const baseBid = hasBids
+        ? (product.currentBid ?? product.startingBid ?? product.price)
+        : (product.startingBid ?? product.price);
+    const settings = await siteSettingsRepository.getSingleton();
+    const tiers = settings.collectorDropConfig?.bidIncrementTiers ?? [];
+    const minIncrement = resolveMinBidIncrement(baseBid, tiers, product.minBidIncrement);
+    // Identical derivation to the bid form's, via the one shared helper — the
+    // form seeds `resolveMinBid(...)` and this rejects below it, so the two can
+    // never disagree about what the collector drop will accept.
+    const minAcceptableBid = resolveMinBid(baseBid, tiers, product.minBidIncrement, { hasBids });
+    // Proxy-bid semantics (eBay style): the buyer's `bidAmount` is treated as
+    // their **maximum** they're willing to pay; the visible price only steps up
+    // in `minIncrement` units as needed to stay ahead of the previous high bid.
+    // If `autoMaxBid` is supplied explicitly it takes precedence over bidAmount
+    // as the cap (lets clients separate desired-step from secret-cap).
+    const newCap = Math.max(bidAmount, autoMaxBid ?? bidAmount);
+    if (newCap < minAcceptableBid) {
+        // Both rejections stay distinguishable: "below the standing price" and
+        // "above it but short of the increment" are different mistakes and the
+        // form maps their codes to different copy. With no bids yet only the
+        // former is reachable, since the minimum IS the starting bid.
+        const isIncrementViolation = hasBids && newCap > baseBid;
+        throw new ValidationError(isIncrementViolation
+            ? ERROR_MESSAGES.BID.INCREMENT_TOO_LOW
+            : ERROR_MESSAGES.BID.BID_TOO_LOW, {
+            code: isIncrementViolation
+                ? BID_ERROR_CODES.INCREMENT_VIOLATED
+                : BID_ERROR_CODES.TOO_LOW,
+        });
+    }
+    // A failure here is not "no previous winner" — it silently uncaps the
+    // auto-bid ceiling below, which is a money path.
+    const previousWinner = await safeRead(() => bidRepository.getWinningBid(productId), { route: "bid-actions/placeBid", key: "bids.getWinningBid", fallback: null });
+    const prevCap = previousWinner?.data
+        ? (previousWinner.data.autoMaxBid ?? previousWinner.data.bidAmount ?? baseBid)
+        : baseBid;
+    const prevVisible = previousWinner?.data?.bidAmount ?? baseBid;
+    const sameBidder = previousWinner?.data?.userId === userId;
+    // Decide who wins after this submission and what the visible price becomes.
+    // Tie goes to the existing leader (first-bidder advantage), matching eBay.
+    let newBidWins;
+    let visibleBid;
+    let bumpedPreviousVisible = null;
+    if (sameBidder) {
+        // Raising your own cap. You stay winning; visible stays put.
+        newBidWins = true;
+        visibleBid = prevVisible;
+    }
+    else if (!hasBids) {
+        // Opening bid: the price displays at the seller's starting bid, not at
+        // `startingBid + increment`, because there is nobody to outpace yet. Under
+        // proxy semantics the submission is a maximum, so without this an opening
+        // max of ₹500 on a ₹100 collector drop would be recorded at ₹200 for no reason.
+        newBidWins = true;
+        visibleBid = baseBid;
+    }
+    else if (!previousWinner || newCap > prevCap) {
+        newBidWins = true;
+        const target = Math.max(prevCap + minIncrement, baseBid + minIncrement);
+        visibleBid = Math.min(newCap, target);
+    }
+    else {
+        // newCap <= prevCap → previous winner keeps it. Bump their visible up to
+        // outpace the new bid (capped at their own max).
+        newBidWins = false;
+        const target = newCap + minIncrement;
+        visibleBid = newCap;
+        bumpedPreviousVisible = Math.min(prevCap, target);
+    }
+    const bid = await bidRepository.createBid({
+        productId,
+        productTitle: product.title,
+        userId,
+        userName: profile?.displayName ?? userEmail ?? "Anonymous",
+        /*
+         * 🛑 Revealed, not passed through. `profile` comes from a user read, which
+         * is ciphertext-by-default now — and `createBid` ENCRYPTS what it is given,
+         * so the raw value would be encrypted a SECOND time and become
+         * undecryptable. The `userEmail` parameter is already plaintext.
+         */
+        userEmail: (profile ? userRepository.revealUser(profile).email : null) ?? userEmail ?? "",
+        bidAmount: visibleBid,
+        currency: product.currency || getDefaultCurrency(),
+        bidDate: new Date(),
+        autoMaxBid: newCap,
+    });
+    await unitOfWork.runBatch((batch) => {
+        if (previousWinner && previousWinner.data.id !== bid.id) {
+            if (newBidWins) {
+                unitOfWork.bids.updateInBatch(batch, previousWinner.data.id, {
+                    isWinning: false,
+                    status: "outbid",
+                });
+            }
+            else if (bumpedPreviousVisible !== null && bumpedPreviousVisible !== prevVisible) {
+                unitOfWork.bids.updateInBatch(batch, previousWinner.data.id, {
+                    bidAmount: bumpedPreviousVisible,
+                });
+            }
+        }
+        unitOfWork.bids.updateInBatch(batch, bid.id, {
+            isWinning: newBidWins,
+            status: newBidWins ? "active" : "outbid",
+        });
+        const finalCurrentBid = newBidWins ? visibleBid : (bumpedPreviousVisible ?? prevVisible);
+        unitOfWork.products.updateInBatch(batch, productId, {
+            currentBid: finalCurrentBid,
+            bidCount: increment(1),
+            leadingBidderId: newBidWins ? userId : (previousWinner?.data?.userId ?? userId),
+            bidsHaveStarted: true,
+        });
+    });
+    const finalVisibleForRtdb = newBidWins ? visibleBid : (bumpedPreviousVisible ?? prevVisible);
+    const finalBidCountForRtdb = (product.bidCount ?? 0) + 1;
+    try {
+        const rtdb = getAdminRealtimeDb();
+        await rtdb.ref(`/collector-drop-bids/${productId}`).set({
+            currentBid: finalVisibleForRtdb,
+            bidCount: finalBidCountForRtdb,
+            lastBid: {
+                amount: finalVisibleForRtdb,
+                bidderName: bid.userName,
+                timestamp: Date.now(),
+            },
+            updatedAt: Date.now(),
+        });
+    }
+    catch (rtdbErr) {
+        void normalizeError(rtdbErr);
+        serverLogger.warn("placeBid: RTDB write failed", {
+            error: rtdbErr,
+            productId,
+        });
+    }
+    // Outbid notification.
+    //
+    // This used to live in the `onBidPlaced` Firestore trigger, which derived the
+    // outbid user by re-reading `getWinningBid()` AFTER the fact. That read raced
+    // the batch above (the bid doc is created before the batch commits, so the
+    // trigger could observe either side of it) and so notified the wrong user, or
+    // nobody, non-deterministically. Here the outcome is already known exactly:
+    // `previousWinner` plus `newBidWins` say who lost the lead and who kept it.
+    //
+    // Best-effort, like the RTDB mirror above — a failed notification must never
+    // fail a bid that has already been committed.
+    const outbidUserId = newBidWins && previousWinner && previousWinner.data.userId !== userId
+        ? previousWinner.data.userId
+        : null;
+    if (outbidUserId) {
+        try {
+            await sendNotification({
+                userId: outbidUserId,
+                type: "bid_outbid",
+                priority: "high",
+                title: BID_MESSAGES.OUTBID_TITLE,
+                message: BID_MESSAGES.OUTBID_MESSAGE(product.title, product.currency || getDefaultCurrency(), finalVisibleForRtdb),
+                relatedId: productId,
+                relatedType: "product",
+            });
+        }
+        catch (notifyErr) {
+            void normalizeError(notifyErr);
+            serverLogger.warn("placeBid: outbid notification failed", {
+                error: notifyErr,
+                productId,
+                outbidUserId,
+            });
+        }
+    }
+    serverLogger.info("placeBid", {
+        bidId: bid.id,
+        productId,
+        userId,
+        bidAmount: visibleBid,
+        maxProxyBid: newCap,
+        winning: newBidWins,
+        outbidUserId,
+    });
+    return { bid };
+}
+export async function buyNowCollectorDrop(userId, userName, userEmail, input) {
+    const { productId: productRef } = input;
+    // Collector Drop URLs are slug-based, and this action is reachable from a route
+    // param, so accept either. Deliberately id-FIRST rather than
+    // `findByIdOrSlug`, which queries by slug first and would therefore cost two
+    // reads on the common id path (Rule #6) — here the fallback query only runs
+    // when the id lookup actually misses.
+    //
+    // This was masked because every seeded collector drop has `slug === id`. Any collector drop
+    // whose slug differs threw NotFoundError, which the caller then swallowed.
+    const product = (await productRepository.findById(productRef)) ??
+        (await productRepository.findBySlug(productRef));
+    if (!product)
+        throw new NotFoundError(ERROR_MESSAGES.BID.COLLECTOR_DROP_NOT_FOUND);
+    if (!isCollectorDropListing(product))
+        throw new ValidationError(ERROR_MESSAGES.BID.NOT_A_COLLECTOR_DROP);
+    // 🛑 Every downstream write (the bid, the locked cart line, the notification)
+    // must key on the canonical document id, never on the ref the caller passed.
+    const productId = String(product.id);
+    if (product.isSold) {
+        throw new ValidationError(ERROR_MESSAGES.BID.COLLECTOR_DROP_ENDED, { code: BID_ERROR_CODES.COLLECTOR_DROP_ENDED });
+    }
+    if (product.collectorDropEndDate) {
+        const endDate = resolveDate(product.collectorDropEndDate);
+        if (endDate && endDate.getTime() < Date.now()) {
+            throw new ValidationError(ERROR_MESSAGES.BID.COLLECTOR_DROP_ENDED, { code: BID_ERROR_CODES.COLLECTOR_DROP_ENDED });
+        }
+    }
+    if (product.storeId) {
+        const store = await storeRepository.findById(product.storeId);
+        if (store?.ownerId === userId) {
+            throw new AuthorizationError(ERROR_MESSAGES.BID.OWN_COLLECTOR_DROP);
+        }
+    }
+    // Same guard as `placeBid` — a buyout IS a bid (it writes a real
+    // `BidDocument` with `isBuyout: true`), so a `place_bids` ban must block it.
+    // The profile is reused for the bid's denormalised name/email below.
+    const profile = await assertCanBid(userId);
+    const buyNowPrice = typeof product.buyNowPrice === "number" ? product.buyNowPrice : null;
+    if (buyNowPrice === null || buyNowPrice <= 0) {
+        throw new ValidationError(ERROR_MESSAGES.BID.BUY_NOW_NO_PRICE, { code: BID_ERROR_CODES.BUY_NOW_NO_PRICE });
+    }
+    // The standing price this buyout has to beat. Read from the bids as well as
+    // the product because `product.currentBid` is a denormalised mirror, and a
+    // pending buyout deliberately never writes to it (see BidDocument.isBuyout) —
+    // so the bids are the authority here and buyout bids are excluded from it.
+    const activeBids = await bidRepository.getActiveByProduct(productId);
+    const standingBid = Math.max(product.currentBid ?? 0, ...activeBids.filter((e) => e.data.isBuyout !== true).map((e) => e.data.bidAmount ?? 0), 0);
+    // Replaces the old `bidsHaveStarted` gate. Buy Now used to vanish the instant
+    // anybody bid, eBay-style, which hid it on almost every real collector drop. What
+    // actually matters is whether it is still a better deal than the bidding.
+    /*
+     * 🛑 `reservePrice` is passed HERE above all: this is the server-side money
+     * gate for a buyout. Omitting it is what let a Buy-Now below the seller's
+     * floor complete (D53) — the reserve was enforced only in
+     * `collectorDropSettlement`, i.e. only on the competitive path.
+     */
+    if (!isBuyNowAvailable({
+        buyNowPrice,
+        currentBid: standingBid,
+        isEnded: false,
+        isSold: product.isSold,
+        reservePrice: product.reservePrice,
+    })) {
+        throw new ValidationError(ERROR_MESSAGES.BID.BUY_NOW_UNAVAILABLE, {
+            code: BID_ERROR_CODES.BUY_NOW_UNAVAILABLE,
+        });
+    }
+    // Idempotency, NOT exclusivity. Re-clicking Buy Now (or a double submit) must
+    // not stack a second hold on the same buyer — but a DIFFERENT buyer holding
+    // one is fine and deliberate: whoever pays first gets it.
+    const existingHold = activeBids.find((e) => e.data.isBuyout === true && e.data.userId === userId);
+    if (existingHold) {
+        return {
+            cartLocked: true,
+            productId,
+            amount: existingHold.data.bidAmount,
+            currency: existingHold.data.currency,
+            bidId: existingHold.data.id,
+            checkoutDeadline: new Date(Date.now() + COLLECTOR_DROP_BUYOUT_WINDOW_MS),
+            checkoutUrl: COLLECTOR_DROP_CHECKOUT_URL,
+        };
+    }
+    // The product's own currency, not the site default — the cart line, the bid
+    // and the listing all have to agree, and settlement uses the bid's currency.
+    const currency = product.currency || getDefaultCurrency();
+    // A real bid at the buy-now price — this is what "the bid placed is the
+    // buyout price by the buyer" means. It starts `active`/`isWinning: false`
+    // like any other bid (bidRepository.create forces both) and is promoted to
+    // `won` by claimCollectorDropForCheckout when the order actually lands.
+    const bid = await bidRepository.createBid({
+        productId,
+        productTitle: product.title,
+        userId,
+        userName: profile?.displayName ?? userName ?? userEmail ?? "Anonymous",
+        /*
+         * 🛑 Revealed, not passed through. `profile` comes from a user read, which
+         * is ciphertext-by-default now — and `createBid` ENCRYPTS what it is given,
+         * so the raw value would be encrypted a SECOND time and become
+         * undecryptable. The `userEmail` parameter is already plaintext.
+         */
+        userEmail: (profile ? userRepository.revealUser(profile).email : null) ?? userEmail ?? "",
+        bidAmount: buyNowPrice,
+        currency,
+        bidDate: new Date(),
+        autoMaxBid: buyNowPrice,
+        isBuyout: true,
+    });
+    // Clamped to the collector drop's own end: a buyout that hasn't been paid for by the
+    // time the clock runs out fails anyway, because settlement will have awarded
+    // the item to whoever actually won the bidding. Showing a deadline past that
+    // point would promise a window that does not exist.
+    const collectorDropEnd = product.collectorDropEndDate ? resolveDate(product.collectorDropEndDate) : null;
+    const softDeadline = Date.now() + COLLECTOR_DROP_BUYOUT_WINDOW_MS;
+    const checkoutDeadline = new Date(collectorDropEnd ? Math.min(softDeadline, collectorDropEnd.getTime()) : softDeadline);
+    // Locked cart line, not an order — see BuyNowCollectorDropResult above. Written
+    // through the repository directly (collector drops are canAddToCart:false for
+    // user-initiated adds), the same deliberate bypass checkoutOffer uses.
+    await cartRepository.addItem(userId, {
+        productId,
+        productTitle: product.title,
+        productImage: product.mainImage ?? "",
+        price: buyNowPrice,
+        currency,
+        quantity: 1,
+        storeId: product.storeId,
+        storeName: product.storeName ?? "",
+        listingType: "collector-drop",
+        isCollectorDropWin: true,
+        isBuyout: true,
+        collectorDropId: productId,
+        bidId: bid.id,
+        lockedPrice: buyNowPrice,
+        checkoutDeadline,
+        locked: true,
+    });
+    // Best-effort, exactly like placeBid's outbid notice: the hold is already
+    // committed and a failed notification must never undo it.
+    try {
+        await sendNotification({
+            userId,
+            type: "bid_won",
+            priority: "high",
+            title: BID_MESSAGES.BUY_NOW_HELD_TITLE,
+            message: BID_MESSAGES.BUY_NOW_HELD_MESSAGE(product.title, currency, buyNowPrice, COLLECTOR_DROP_BUYOUT_WINDOW_MINUTES),
+            relatedId: productId,
+            relatedType: "product",
+            actionUrl: COLLECTOR_DROP_CHECKOUT_URL,
+            actionLabel: BID_MESSAGES.BUY_NOW_HELD_ACTION,
+        });
+    }
+    catch (notifyErr) {
+        void normalizeError(notifyErr);
+        serverLogger.warn("buyNowCollectorDrop: hold notification failed", {
+            error: notifyErr,
+            productId,
+            userId,
+        });
+    }
+    serverLogger.info("buyNowCollectorDrop", {
+        productId,
+        userId,
+        bidId: bid.id,
+        amount: buyNowPrice,
+        checkoutDeadline: checkoutDeadline.toISOString(),
+    });
+    return {
+        cartLocked: true,
+        productId,
+        amount: buyNowPrice,
+        currency,
+        bidId: bid.id,
+        checkoutDeadline,
+        checkoutUrl: COLLECTOR_DROP_CHECKOUT_URL,
+    };
+}
+export async function listBidsByProduct(productId, params) {
+    const result = await bidRepository.list({
+        filters: sieveFilter("productId", SIEVE_OP.EQ, productId),
+        sorts: sortBy("bidDate", "DESC"),
+        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/collector-drops/api/route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * feat-collectorDrops — Next.js App Router API handler (GET /api/bids)
+ *
+ * 2-line stub:
+ * ```ts
+ * // app/api/bids/route.ts
+ * export { GET } from "@mohasinac/feat-collectorDrops";
+ * ```
+ *
+ * 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/collector-drops/api/route.js

@@ -0,0 +1,62 @@
+/**
+ * feat-collectorDrops — Next.js App Router API handler (GET /api/bids)
+ *
+ * 2-line stub:
+ * ```ts
+ * // app/api/bids/route.ts
+ * export { GET } from "@mohasinac/feat-collectorDrops";
+ * ```
+ *
+ * Requires `db` registered in providers.config via `registerProviders()`.
+ * Collection: "bids"
+ */
+import { NextResponse } from "next/server.js";
+import { getProviders } from "../../../contracts/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { numParam, param } from "../../../utils/search-params.js";
+// --- GET /api/bids ------------------------------------------------------------
+// Query params:
+//   collectorDropId — filter bids for a specific collector drop 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 collectorDropId = param(url, "collectorDropId");
+        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 (collectorDropId)
+            parts.push(`collectorDropId==${collectorDropId}`);
+        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,
+            pageSize: 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) {
+        void normalizeError(error);
+        console.error("[feat-collectorDrops] GET /api/bids failed", error);
+        return NextResponse.json({ success: false, error: "Failed to fetch bids" }, { status: 500 });
+    }
+}

package/dist/features/collector-drops/columns/index.d.ts

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

package/dist/features/collector-drops/columns/index.js

@@ -0,0 +1,63 @@
+import { buildColumns } from "../../../ui/columns/index.js";
+// --- Collector Drop columns ----------------------------------------------------------
+/**
+ * Default admin column definitions for a collector drop table.
+ *
+ * @example
+ * const columns = buildCollectorDropColumns<MyCollectorDrop>({
+ *   extras: [{ key: "reservePrice", header: "Reserve", render: (a) => a.reservePrice ?? "—" }],
+ * });
+ */
+export const collectorDropAdminColumns = [
+    { key: "title", header: "Title", sortable: true },
+    {
+        key: "startingBid",
+        header: "Starting Bid",
+        sortable: true,
+        render: (a) => `${a.currency} ${a.startingBid.toLocaleString()}`,
+    },
+    {
+        key: "currentBid",
+        header: "Current Bid",
+        sortable: true,
+        render: (a) => a.currentBid != null
+            ? `${a.currency} ${a.currentBid.toLocaleString()}`
+            : "No bids",
+    },
+    {
+        key: "bidCount",
+        header: "Bids",
+        sortable: true,
+        render: (a) => a.bidCount.toLocaleString(),
+    },
+    { key: "status", header: "Status", sortable: true },
+    {
+        key: "featured",
+        header: "Featured",
+        render: (a) => (a.featured ? "Yes" : "No"),
+    },
+    { key: "collectorDropEndDate", header: "Ends At", sortable: true },
+    { key: "createdAt", header: "Created", sortable: true },
+];
+export function buildCollectorDropColumns(opts) {
+    return buildColumns(collectorDropAdminColumns, opts);
+}
+// --- Bid columns --------------------------------------------------------------
+export const bidAdminColumns = [
+    { key: "bidderDisplayName", header: "Bidder" },
+    {
+        key: "amount",
+        header: "Amount",
+        sortable: true,
+        render: (b) => `${b.currency} ${b.amount.toLocaleString()}`,
+    },
+    {
+        key: "isWinning",
+        header: "Winning",
+        render: (b) => (b.isWinning ? "Yes" : "—"),
+    },
+    { key: "placedAt", header: "Placed At", sortable: true },
+];
+export function buildBidColumns(opts) {
+    return buildColumns(bidAdminColumns, opts);
+}

package/dist/features/collector-drops/components/CollapsibleBidHistory.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { ChevronDown } from "lucide-react";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row } from "../../../ui/components/Layout.js";
+import { Span } from "../../../ui/components/Typography.js";
+import { Pagination } from "../../../ui/components/Pagination.js";
+import { BidHistory } from "../../products/components/BidHistory.js";
+import { useBids } from "../hooks/useBids.js";
+const __O = {
+    hidden: "overflow-hidden",
+};
+/** Shared shape mapper — SSR's raw bid docs and useBids()'s client-fetched
+ *  pages both go through this so every page (SSR page 1, client pages 2+)
+ *  renders identically. */
+export function toBidHistoryEntry(b) {
+    const placedAtRaw = b.bidDate ?? b.createdAt ?? b.bidAt ?? "";
+    return {
+        id: String(b.id ?? ""),
+        bidderId: String(b.userId ?? b.bidderId ?? ""),
+        bidderName: b.bidderName ?? b.userName,
+        amount: typeof b.bidAmount === "number" ? b.bidAmount : typeof b.amount === "number" ? b.amount : 0,
+        placedAt: placedAtRaw instanceof Date ? placedAtRaw.toISOString() : placedAtRaw,
+    };
+}
+export function CollapsibleBidHistory({ productId, initialData, currency, pageSize = 5 }) {
+    const [open, setOpen] = useState(false);
+    const [page, setPage] = useState(1);
+    const { bids: rawBids, totalPages, isLoading } = useBids({ productId, page, pageSize }, { initialData, enabled: open });
+    // `useBids` sorts newest-first and bids only ever increase, so on page 1 the
+    // most recent bid IS the current leading one — derived from position, no
+    // extra field or read needed.
+    const bids = rawBids.map((b, i) => ({
+        ...toBidHistoryEntry(b),
+        isLeading: page === 1 && i === 0,
+    }));
+    const total = initialData.total;
+    return (_jsxs(Div, { className: `mt-6 ${__O.hidden}`, border: "subtle", rounded: "xl", children: [_jsxs(Button, { type: "button", variant: "ghost", onClick: () => setOpen((v) => !v), paddingX: "md", paddingY: "md", rounded: "none", className: "w-full justify-between bg-[var(--appkit-color-surface)]/60 hover:bg-[var(--appkit-color-surface-elevated)]", "aria-expanded": open, children: [_jsxs(Span, { size: "sm", weight: "semibold", className: "tracking-wide", color: "muted", transform: "uppercase", children: ["Bid History", total > 0 && (_jsx(Span, { size: "xs", weight: "medium", className: "ml-2 normal-case tracking-normal", rounded: "full", padding: "pill-xs", surface: "subtle", color: "muted", children: total }))] }), _jsx(ChevronDown, { className: `h-4 w-4 flex-shrink-0 transition-transform duration-200 ${open ? "rotate-180 text-[var(--appkit-color-primary)]" : "text-zinc-400"}` })] }), open && (_jsxs(Div, { surface: "default", padding: "md", children: [_jsx(BidHistory, { bids: bids, isLoading: isLoading && bids.length === 0, isEmpty: !isLoading && bids.length === 0, currency: currency }), totalPages > 1 && (_jsx(Row, { justify: "center", className: "mt-4", children: _jsx(Pagination, { currentPage: page, totalPages: totalPages, onPageChange: setPage, size: "sm" }) }))] }))] }));
+}