@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/_internal/server/features/checkout/split-settlement.d.ts

@@ -0,0 +1,100 @@
+import type { FeeCommissionRates } from "../../../shared/fees/calculator";
+import { type BuiltSplitInstructions, type SplitCandidateGroup, type SplitSettlementLine } from "../../../shared/checkout/settlement-split";
+import type { SplitInstruction } from "../../../../contracts/payment";
+import type { StoreSettlementVendor } from "../../../../features/stores/schemas/firestore";
+export interface CaptureSplitGroupInput {
+    /** The order splitter's own key. One store per group, by construction. */
+    storeId: string;
+    lines: readonly SplitSettlementLine[];
+    /** Buyer points redeemed against THIS group, in rupees. */
+    pointsFunded: number;
+    /**
+     * This store's vendor registrations, per gateway, exactly as
+     * `resolveShippingCost` returns them — from the store read it already
+     * performs, so the caller pays no extra Firestore read (Rule #6).
+     */
+    settlementVendors?: Record<string, StoreSettlementVendor>;
+}
+export interface CaptureSplitInput {
+    /** The gateway that will collect, i.e. `provider.name`. */
+    gateway: string;
+    /** `siteSettings.payment.platformStoreId`. Unset ⇒ every store is third-party. */
+    platformStoreId?: string | null;
+    commissions: FeeCommissionRates;
+    groups: readonly CaptureSplitGroupInput[];
+}
+export interface ResolvedCaptureSplit extends BuiltSplitInstructions {
+    /** The candidate groups, keyed by store — what `recordSplitSettlementPayouts` needs. */
+    groupByStore: Map<string, SplitCandidateGroup>;
+}
+/**
+ * The per-vendor split for ONE capture, resolved from figures the caller has
+ * already computed.
+ *
+ * ## 🛑 Nothing here re-derives a money rule
+ *
+ * The amounts go through `vendorSettlementForGroup` →
+ * `computePayoutDeduction` — the identical function both payout sweeps use — so
+ * what the aggregator is told to settle and what we would otherwise have paid
+ * are the same arithmetic. The GROUPING is the caller's, from
+ * `splitCartIntoOrderGroups`, which is the only grouping in the system (Root
+ * Cause #65/#75).
+ *
+ * ## 🛑 The platform's OWN store is never split out
+ *
+ * Its stock settles into the platform's own account, which is where it belongs
+ * and is the reason a platform-only cart needs no splitting gateway at all. A
+ * split instruction naming our own store would ask the aggregator to pay us out
+ * of its escrow.
+ *
+ * 🛑 Measured against the SETTING, never the `PLATFORM_STORE_ID` constant.
+ * Unset means every store is third-party — the same fail-closed input
+ * `cartVendorComposition` uses — because a hardcoded brand literal must not
+ * make an authorisation decision for every install of this package (see that
+ * constant's own 🛑).
+ *
+ * 🛑 It RETURNS a refusal list rather than throwing, so the caller can build
+ * the message and keep the refusal before any payment session exists. A
+ * non-empty `blocked` MUST refuse the capture; "split what we can" leaves the
+ * rest in the platform's account, which is the commingling.
+ *
+ * Pure — no IO, no clock. The reads happened in the caller.
+ */
+export declare function resolveCaptureSplit(input: CaptureSplitInput): ResolvedCaptureSplit;
+export interface SplitSettlementPayoutInput {
+    /** The gateway that collected and split, e.g. `"cashfree"`. */
+    gateway: string;
+    /** Our own merchant order id for the capture — the join key to the orders. */
+    merchantOrderId: string;
+    /** Exactly what was sent to the gateway. */
+    splits: readonly SplitInstruction[];
+    /** The same groups the splits were built from, by `storeId`. */
+    groupByStore: ReadonlyMap<string, SplitCandidateGroup>;
+    commissions: FeeCommissionRates;
+}
+/**
+ * Record each vendor's instructed share as a `processing` payout.
+ *
+ * 🛑 BEST-EFFORT, PER VENDOR, and never allowed to fail the capture. The
+ * payment session already exists by the time this runs; throwing here would
+ * leave the buyer unable to pay for a cart that was lawfully collectable, which
+ * is strictly worse than a missing bookkeeping row. Each failure is reported
+ * loudly — a seller whose settlement was not recorded still gets paid by the
+ * aggregator, but our own books and the double-payment guard are then both
+ * short, so this must show up as a pattern rather than as silence (Root Cause
+ * #59).
+ *
+ * 🛑 It reads the OWNER to name the payee, which is one Firestore read per
+ * third-party vendor. That is deliberate against Rule #6's budget: a payout row
+ * with no payee name or email is unreadable in the seller's own list and
+ * unsearchable in the admin's (`buildTokensIndexFor` derives
+ * `sellerTokensIndex` from exactly those two fields). A multi-vendor cart is
+ * rare and N is small.
+ *
+ * 🛑 `revealUser`, never the raw document. `UserRepository` is
+ * ciphertext-by-default, and `createPayout`-family writes re-encrypt
+ * `sellerEmail` — so passing the stored value would store
+ * ciphertext-of-ciphertext and make `sellerEmailIndex` unmatchable. The
+ * identical note is on both payout sweeps.
+ */
+export declare function recordSplitSettlementPayouts(input: SplitSettlementPayoutInput): Promise<void>;

package/dist/_internal/server/features/checkout/split-settlement.js

@@ -0,0 +1,205 @@
+/*
+ * WHY: A split capture pays the seller out of the aggregator's escrow, so the
+ *      platform never holds their share — and therefore nothing in our own
+ *      records would otherwise show that they were paid at all. Two things
+ *      depend on there being a record:
+ *
+ *        1. the SELLER has to be able to see what they were paid and why;
+ *        2. the orders this capture produces must not ALSO be swept into a
+ *           manual payout. `getPaidOutOrderIds` counts `pending`, `processing`
+ *           and `paid`, and `OrderDocument.splitSettlement` is stamped at
+ *           settle from the rows written here — both guards read this write.
+ *
+ * WHAT: The one place a `payouts` row is created for a share the GATEWAY
+ *       settled, written at capture, where the instruction is known exactly.
+ *
+ * ## 🛑 WRITTEN AT CAPTURE, NOT AT SETTLE, AND THAT IS THE POINT
+ *
+ * The capture request is the only one that holds the vendor registrations and
+ * the exact per-vendor amounts it sent. The settle request runs later, against
+ * a cart that can have changed in between — which is why
+ * `verifyAndPlaceGatewayOrderAction` carries a settlement-compliance detector
+ * rather than trusting its own recomputation. Writing the record here and
+ * READING it there means the order states the amount that was instructed, not
+ * one recomputed from different inputs.
+ *
+ * ## 🛑 `orderIds: []`, deliberately and unavoidably
+ *
+ * The orders do not exist yet: they are created after the buyer completes
+ * payment, in a different request. An empty array is the honest shape — the
+ * join is `settlementReference`, which is the capture's own merchant order id
+ * and is carried onto every order this capture produces as `paymentId`. It is
+ * stated here because `getPaidOutOrderIds` reads `orderIds` and will therefore
+ * find nothing in these rows: the order-side guard
+ * (`OrderDocument.splitSettlement` + `orderNeedsManualPayout`) is what actually
+ * prevents the double payment, and it must not be removed on the belief that
+ * this row covers it.
+ *
+ * EXPORTS: resolveCaptureSplit, recordSplitSettlementPayouts,
+ *          type CaptureSplitInput, type CaptureSplitGroupInput,
+ *          type ResolvedCaptureSplit, type SplitSettlementPayoutInput
+ *
+ * @tag domain:checkout,payments,payouts
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:api/payment/create-order
+ * @tag sideEffects:writes payouts
+ */
+import { payoutRepository, storeRepository, userRepository, sellerProfileRepository } from "../../../../repositories/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { getDefaultCurrency } from "../../../../core/baseline-resolver.js";
+import { commissionRecordRates } from "../../../shared/checkout/order-math.js";
+import { buildSplitInstructions, vendorSettlementForGroup, } from "../../../shared/checkout/settlement-split.js";
+/**
+ * The per-vendor split for ONE capture, resolved from figures the caller has
+ * already computed.
+ *
+ * ## 🛑 Nothing here re-derives a money rule
+ *
+ * The amounts go through `vendorSettlementForGroup` →
+ * `computePayoutDeduction` — the identical function both payout sweeps use — so
+ * what the aggregator is told to settle and what we would otherwise have paid
+ * are the same arithmetic. The GROUPING is the caller's, from
+ * `splitCartIntoOrderGroups`, which is the only grouping in the system (Root
+ * Cause #65/#75).
+ *
+ * ## 🛑 The platform's OWN store is never split out
+ *
+ * Its stock settles into the platform's own account, which is where it belongs
+ * and is the reason a platform-only cart needs no splitting gateway at all. A
+ * split instruction naming our own store would ask the aggregator to pay us out
+ * of its escrow.
+ *
+ * 🛑 Measured against the SETTING, never the `PLATFORM_STORE_ID` constant.
+ * Unset means every store is third-party — the same fail-closed input
+ * `cartVendorComposition` uses — because a hardcoded brand literal must not
+ * make an authorisation decision for every install of this package (see that
+ * constant's own 🛑).
+ *
+ * 🛑 It RETURNS a refusal list rather than throwing, so the caller can build
+ * the message and keep the refusal before any payment session exists. A
+ * non-empty `blocked` MUST refuse the capture; "split what we can" leaves the
+ * rest in the platform's account, which is the commingling.
+ *
+ * Pure — no IO, no clock. The reads happened in the caller.
+ */
+export function resolveCaptureSplit(input) {
+    const platformStoreId = input.platformStoreId?.trim() ? input.platformStoreId.trim() : null;
+    const groupByStore = new Map();
+    for (const group of input.groups) {
+        groupByStore.set(group.storeId, {
+            storeId: group.storeId,
+            lines: group.lines,
+            pointsFunded: group.pointsFunded,
+            /*
+             * 🛑 The registration for THE GATEWAY THAT WILL COLLECT, not whichever
+             * one happens to be first. A store can be registered with one aggregator
+             * and not another, and settling against the wrong registration is a split
+             * instruction naming a vendor the collecting gateway has never heard of.
+             */
+            vendor: group.settlementVendors?.[input.gateway] ?? null,
+            isPlatformStore: platformStoreId !== null && group.storeId === platformStoreId,
+        });
+    }
+    const built = buildSplitInstructions([...groupByStore.values()], input.commissions);
+    return { ...built, groupByStore };
+}
+/**
+ * Record each vendor's instructed share as a `processing` payout.
+ *
+ * 🛑 BEST-EFFORT, PER VENDOR, and never allowed to fail the capture. The
+ * payment session already exists by the time this runs; throwing here would
+ * leave the buyer unable to pay for a cart that was lawfully collectable, which
+ * is strictly worse than a missing bookkeeping row. Each failure is reported
+ * loudly — a seller whose settlement was not recorded still gets paid by the
+ * aggregator, but our own books and the double-payment guard are then both
+ * short, so this must show up as a pattern rather than as silence (Root Cause
+ * #59).
+ *
+ * 🛑 It reads the OWNER to name the payee, which is one Firestore read per
+ * third-party vendor. That is deliberate against Rule #6's budget: a payout row
+ * with no payee name or email is unreadable in the seller's own list and
+ * unsearchable in the admin's (`buildTokensIndexFor` derives
+ * `sellerTokensIndex` from exactly those two fields). A multi-vendor cart is
+ * rare and N is small.
+ *
+ * 🛑 `revealUser`, never the raw document. `UserRepository` is
+ * ciphertext-by-default, and `createPayout`-family writes re-encrypt
+ * `sellerEmail` — so passing the stored value would store
+ * ciphertext-of-ciphertext and make `sellerEmailIndex` unmatchable. The
+ * identical note is on both payout sweeps.
+ */
+export async function recordSplitSettlementPayouts(input) {
+    const currency = getDefaultCurrency();
+    for (const split of input.splits) {
+        const group = input.groupByStore.get(split.storeId);
+        if (!group) {
+            serverLogger.error("recordSplitSettlementPayouts: a split instruction has no matching order group — the settlement was NOT recorded", { merchantOrderId: input.merchantOrderId, storeId: split.storeId });
+            continue;
+        }
+        try {
+            const { taxableValue, deduction } = vendorSettlementForGroup(group, input.commissions);
+            const store = await storeRepository.findById(split.storeId);
+            const owner = store?.ownerId ? await userRepository.findById(store.ownerId) : null;
+            const ownerPlain = owner ? userRepository.revealUser(owner) : null;
+            // payoutDetails is seller-only data — sellerProfiles, not users.
+            const ownerProfile = store?.ownerId ? await sellerProfileRepository.findById(store.ownerId) : null;
+            const ownerProfilePlain = ownerProfile ? sellerProfileRepository.revealProfile(ownerProfile) : null;
+            await payoutRepository.createSplitSettlementPayout({
+                payeeType: "store",
+                storeId: split.storeId,
+                // `displayName` is plaintext by D1; the email fallback must be revealed.
+                sellerName: (owner?.displayName ?? ownerPlain?.email ?? store?.storeName ?? split.storeId),
+                sellerEmail: ownerPlain?.email ?? "",
+                /*
+                 * 🛑 `orderIds: []` — the orders do not exist yet. See the header: the
+                 * join is `settlementReference`, and the double-payment guard is on the
+                 * ORDER, not here.
+                 */
+                orderIds: [],
+                amount: deduction.netAmount,
+                grossAmount: taxableValue,
+                platformFee: deduction.platformFee,
+                gatewayFee: deduction.gatewayFee,
+                gstAmount: deduction.gstOnFee,
+                /*
+                 * The three rate fields, from one helper so this writer cannot drift
+                 * from the payout sweeps. Its `gstRate` is GST on our COMMISSION, not
+                 * the buyer's tax on the goods — see the helper.
+                 */
+                ...commissionRecordRates(input.commissions),
+                currency,
+                /*
+                 * The destination the AGGREGATOR will use, which is the one the seller
+                 * registered with. Falls back to bank transfer when the owner cannot be
+                 * read — the field is required and a wrong label on a settlement we did
+                 * not make is cosmetic, whereas failing the capture is not.
+                 */
+                paymentMethod: ownerProfilePlain?.payoutDetails?.method === "upi" ? "upi" : "bank_transfer",
+                /*
+                 * 🛑 The UPI id is NOT copied onto this row. A manual payout row carries
+                 * it because an admin reads it to make the transfer; nobody will ever
+                 * dispatch this one, and a settled destination duplicated here is PII
+                 * at rest for no reader. Same argument as the real `accountNumber`
+                 * never being copied onto a payout.
+                 */
+                notes: `Settled directly to the seller by ${input.gateway} out of the payment ` +
+                    `for ${input.merchantOrderId}. Not a manual payout — do not dispatch.`,
+                settlementGateway: input.gateway,
+                settlementVendorId: split.vendorId,
+                settlementReference: input.merchantOrderId,
+            });
+        }
+        catch (err) {
+            const normalized = normalizeError(err);
+            serverLogger.error("recordSplitSettlementPayouts: could not record a gateway settlement — the seller WILL still be paid by the gateway, but our books and the double-payment guard are short for this store", {
+                merchantOrderId: input.merchantOrderId,
+                storeId: split.storeId,
+                vendorId: split.vendorId,
+                error: normalized.message,
+            });
+        }
+    }
+}

package/dist/_internal/server/features/checkout/upi-resolution.js

@@ -1,5 +1,6 @@
 import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
 import { userRepository } from "../../../../features/auth/repository/user.repository.js";
+import { sellerProfileRepository } from "../../../../features/seller/repository/seller-profile.repository.js";
 import { isSellerUser } from "../../../../features/auth/role-predicates.js";
 /**
  * Resolves the UPI VPA to show a buyer paying manually for an order — the
@@ -21,7 +22,13 @@ export async function resolveDisplayedUpiId(storeId, siteContactUpiVpa) {
     const owner = await userRepository.findById(store.ownerId);
     if (!owner || !isSellerUser(owner))
         return siteDefault;
-    const payoutDetails = owner.payoutDetails;
+    // payoutDetails is seller-only data — sellerProfiles, not users. Decrypted
+    // via revealProfile — a prior direct `owner.payoutDetails.upiId` read here
+    // (pre-dating the sellerProfiles split) returned ciphertext, since
+    // UserRepository.mapDoc is ciphertext-by-default; reading unrevealed would
+    // have stored an unreadable `order.displayedUpiId`.
+    const ownerProfile = await sellerProfileRepository.findById(store.ownerId);
+    const payoutDetails = ownerProfile ? sellerProfileRepository.revealProfile(ownerProfile).payoutDetails : undefined;
     if (payoutDetails?.method === "upi" && payoutDetails.upiId) {
         return payoutDetails.upiId;
     }

package/dist/_internal/server/features/clearance/actions.d.ts

@@ -0,0 +1,2 @@
+import { type ActionResult } from "../../../shared/types/action-result";
+export declare function enterClearanceAction(input: unknown): Promise<ActionResult<unknown>>;

package/dist/_internal/server/features/clearance/actions.js

@@ -0,0 +1,33 @@
+"use server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../shared/types/action-result.js";
+import { productRepository } from "../../../../features/products/repository/products.repository.js";
+import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { assertClearanceOpen } from "./service.js";
+export async function enterClearanceAction(input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const { prizeDrawId } = input;
+        if (!prizeDrawId)
+            throw new Error("prizeDrawId is required.");
+        const product = await productRepository.findByIdOrSlug(prizeDrawId);
+        if (!product)
+            throw new Error("Prize draw not found.");
+        assertClearanceOpen(product);
+        // Increment the entry count — server-side only, not exposed to the client adapter.
+        await productRepository.update(prizeDrawId, {
+            prizeCurrentEntries: (product.prizeCurrentEntries ?? 0) + 1,
+        });
+        return { entryRecorded: true, userId: user.uid };
+    });
+}

package/dist/_internal/server/features/clearance/data.d.ts

@@ -0,0 +1 @@
+export declare const getClearanceForDetail: (slugOrId: string) => Promise<import("../../../..").ProductDocument | null>;

package/dist/_internal/server/features/clearance/data.js

@@ -0,0 +1,2 @@
+import { makeGetListingForDetail } from "../shared/listing-data-factory.js";
+export const getClearanceForDetail = makeGetListingForDetail("clearance");

package/dist/_internal/server/features/clearance/index.d.ts

@@ -0,0 +1,4 @@
+export { getClearanceForDetail } from "./data";
+export { enterClearanceAction } from "./actions";
+export { assertClearanceOpen } from "./service";
+export { renderClearanceOg, renderClearanceOgImage, type ClearanceOgData, } from "./og";

package/dist/_internal/server/features/clearance/index.js

@@ -0,0 +1,4 @@
+export { getClearanceForDetail } from "./data.js";
+export { enterClearanceAction } from "./actions.js";
+export { assertClearanceOpen } from "./service.js";
+export { renderClearanceOg, renderClearanceOgImage, } from "./og.js";

package/dist/_internal/server/features/clearance/og.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Prize Draw OG image renderer — OG-coverage-followup 2026-05-23.
+ * Migrated to renderOgLayout factory 2026-05-24 (Session 5 W1-1).
+ */
+import type { ReactElement } from "react";
+export interface ClearanceOgData {
+    title: string;
+    pricePerEntryLabel?: string | null;
+    imageUrl?: string | null;
+    revealStatus?: "pending" | "open" | "closed" | null;
+    entriesLabel?: string | null;
+}
+interface ClearanceDocLike {
+    title?: string | null;
+    name?: string | null;
+    pricePerEntry?: number | null;
+    price?: number | null;
+    currency?: string | null;
+    mainImage?: string | null;
+    images?: ({
+        url: string;
+    } | string | null | undefined)[] | null;
+    prizeRevealStatus?: "pending" | "open" | "closed" | null;
+    prizeMaxEntries?: number | null;
+    prizeCurrentEntries?: number | null;
+}
+export declare function renderClearanceOg(doc: ClearanceDocLike | null | undefined, opts: {
+    siteName: string;
+    baseUrl?: string;
+}): ReactElement;
+export declare function renderClearanceOgImage(data: ClearanceOgData, siteName: string): ReactElement;
+export {};

package/dist/_internal/server/features/clearance/og.js

@@ -0,0 +1,47 @@
+/**
+ * Prize Draw OG image renderer — OG-coverage-followup 2026-05-23.
+ * Migrated to renderOgLayout factory 2026-05-24 (Session 5 W1-1).
+ */
+import { renderOgLayout } from "../seo/og-layout.js";
+import { resolveOgImageUrl } from "../seo/og.js";
+export function renderClearanceOg(doc, opts) {
+    const entryPrice = doc?.pricePerEntry ?? doc?.price ?? null;
+    // "Free entry" is kept — it is a fact about the draw, not a disclosed amount,
+    // and it is the half of this chip that actually earns a click. The priced case
+    // renders nothing: an OG image is a public URL with the value burned into the
+    // pixels, which no sign-in gate or paywall markup can reach.
+    const pricePerEntryLabel = typeof entryPrice === "number" && entryPrice > 0 ? null : "Free entry";
+    const max = doc?.prizeMaxEntries ?? null;
+    const current = doc?.prizeCurrentEntries ?? 0;
+    const entriesLabel = typeof max === "number" && max > 0
+        ? `${Math.max(0, max - current).toLocaleString("en-IN")} of ${max.toLocaleString("en-IN")} entries left`
+        : null;
+    return renderClearanceOgImage({
+        title: doc?.title ?? doc?.name ?? "Clearance",
+        pricePerEntryLabel,
+        imageUrl: resolveOgImageUrl(doc?.mainImage ||
+            (typeof doc?.images?.[0] === "string" ? doc.images[0] : doc?.images?.[0]?.url) ||
+            null, opts.baseUrl),
+        revealStatus: doc?.prizeRevealStatus ?? null,
+        entriesLabel,
+    }, opts.siteName);
+}
+const REVEAL_BADGE_TEXT = {
+    pending: "Reveal pending",
+    open: "Reveal open",
+    closed: "Reveal closed",
+};
+export function renderClearanceOgImage(data, siteName) {
+    const badges = [
+        data.pricePerEntryLabel,
+        data.revealStatus ? REVEAL_BADGE_TEXT[data.revealStatus] : null,
+    ].filter((s) => Boolean(s));
+    return renderOgLayout({
+        title: data.title,
+        subtitle: data.entriesLabel ?? undefined,
+        imageUrl: data.imageUrl,
+        siteName: `${siteName} · Clearance`,
+        badges: badges.length > 0 ? badges : undefined,
+        theme: { accentColor: "#fbbf24" },
+    });
+}

package/dist/_internal/server/features/clearance/service.d.ts

@@ -0,0 +1,3 @@
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+/** Assert the clearance draw is accepting entries (published, reveal not started, slots not exhausted). */
+export declare function assertClearanceOpen(product: ProductDocument): void;

package/dist/_internal/server/features/clearance/service.js

@@ -0,0 +1,19 @@
+import { ValidationError, CapacityError, ExpiredError } from "../../../shared/errors/index.js";
+/** Assert the clearance draw is accepting entries (published, reveal not started, slots not exhausted). */
+export function assertClearanceOpen(product) {
+    if (product.listingType !== "clearance") {
+        throw new ValidationError("Not a clearance listing.");
+    }
+    if (product.status !== "published") {
+        throw new ValidationError("Clearance draw is not active.");
+    }
+    const max = product.prizeMaxEntries ?? null;
+    const current = product.prizeCurrentEntries ?? 0;
+    if (typeof max === "number" && current >= max) {
+        throw new CapacityError("Clearance draw is fully subscribed.");
+    }
+    const reveal = product.prizeRevealWindowStart;
+    if (reveal && new Date(reveal) <= new Date()) {
+        throw new ExpiredError("Clearance entry window");
+    }
+}

package/dist/_internal/server/features/collector-drops/actions.js

@@ -0,0 +1,76 @@
+"use server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../shared/types/action-result.js";
+import { safeRead } from "../../../../errors/safe-read.js";
+import { bidRepository, productRepository, userRepository, siteSettingsRepository } from "../../../../repositories/index.js";
+import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { placeBidActionSchema } from "../../../shared/features/collector-drops/schema.js";
+import { assertCollectorDropActive, assertBidAmount, assertNotCollectorDropOwner, shouldAutoExtend, computeExtendedEndDate, } from "./service.js";
+import { ValidationError } from "../../../shared/errors/index.js";
+export async function placeBidAction(input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const parsed = placeBidActionSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid bid input");
+        const { collectorDropId, amount } = parsed.data;
+        const product = await assertCollectorDropActive(collectorDropId);
+        assertNotCollectorDropOwner(product, user.uid);
+        const settings = await siteSettingsRepository.getSingleton();
+        assertBidAmount(product, amount, settings.collectorDropConfig?.bidIncrementTiers ?? []);
+        const profile = await safeRead(() => userRepository.findById(user.uid), {
+            route: "collectorDrop:placeBid",
+            key: "collectorDrops.placeBid.bidderProfile",
+            fallback: null,
+        });
+        const userName = profile?.displayName ?? user.name ?? "Anonymous";
+        // (Removed: a `setWinningBid("__placeholder__", collectorDropId)` call whose
+        // rejection was swallowed. It accomplished NOTHING. setWinningBid builds a
+        // single batch — mark every bid for the product `outbid`, then update the
+        // winning bid's own doc — and `__placeholder__` is not a real bid id, so
+        // `batch.commit()` always threw and DISCARDED the whole batch, outbid
+        // marking included. It cost a full-collection query and an exception per
+        // bid placed, and the real `setWinningBid(bid.id, …)` below already marks
+        // every other bid for this product as outbid.)
+        const bid = await bidRepository.createBid({
+            productId: collectorDropId,
+            productTitle: product.title ?? collectorDropId,
+            userId: user.uid,
+            userName,
+            userEmail: user.email ?? "",
+            bidAmount: amount,
+            currency: product.currency ?? "INR",
+            bidDate: new Date(),
+        });
+        // Now set this new bid as the winning bid
+        await bidRepository.setWinningBid(bid.id, collectorDropId);
+        // `bidsHaveStarted` and `leadingBidderId` are set by the primary bid path
+        // (`features/collector-drops/actions/bid-actions.ts`) but were missing here, so a
+        // bid placed through this legacy entrypoint left both mirrors stale —
+        // CLAUDE.md Root Cause #42.
+        const updates = {
+            currentBid: amount,
+            bidCount: (product.bidCount ?? 0) + 1,
+            leadingBidderId: user.uid,
+            bidsHaveStarted: true,
+        };
+        if (shouldAutoExtend(product)) {
+            updates.collectorDropEndDate = computeExtendedEndDate(product);
+            if (!product.collectorDropOriginalEndDate) {
+                updates.collectorDropOriginalEndDate = product.collectorDropEndDate;
+            }
+        }
+        await productRepository.update(collectorDropId, updates);
+        return bid;
+    });
+}

package/dist/_internal/server/features/collector-drops/data.d.ts

@@ -0,0 +1,2 @@
+export declare const getCollectorDropForDetail: (slugOrId: string) => Promise<import("../../../..").ProductDocument | null>;
+export declare const getProductFeaturesForCollectorDrop: (storeId: string | null) => Promise<import("../../../..").ProductFeatureDocument[]>;

package/dist/_internal/server/features/collector-drops/data.js

@@ -0,0 +1,3 @@
+import { makeGetListingForDetail, getProductFeaturesForStore } from "../shared/listing-data-factory.js";
+export const getCollectorDropForDetail = makeGetListingForDetail("collector-drop");
+export const getProductFeaturesForCollectorDrop = getProductFeaturesForStore;

package/dist/_internal/server/features/collector-drops/index.d.ts

@@ -0,0 +1,5 @@
+export { getCollectorDropForDetail, getProductFeaturesForCollectorDrop } from "./data";
+export { assertCollectorDropActive, assertBidAmount, assertNotCollectorDropOwner, computeMinBid, shouldAutoExtend } from "./service";
+export { placeBidAction } from "./actions";
+export { COLLECTOR_DROPS_PAGE_SIZE, COLLECTOR_DROPS_ACTIVE_LIMIT, COLLECTOR_DROP_DEFAULT_EXTENSION_MINUTES, COLLECTOR_DROP_MIN_BID_INCREMENT, COLLECTOR_DROP_SNIPING_WINDOW_SECONDS, } from "../../../shared/features/collector-drops/config";
+export { renderCollectorDropOgImage, renderCollectorDropOg, type CollectorDropOgData } from "./og";

package/dist/_internal/server/features/collector-drops/index.js

@@ -0,0 +1,5 @@
+export { getCollectorDropForDetail, getProductFeaturesForCollectorDrop } from "./data.js";
+export { assertCollectorDropActive, assertBidAmount, assertNotCollectorDropOwner, computeMinBid, shouldAutoExtend } from "./service.js";
+export { placeBidAction } from "./actions.js";
+export { COLLECTOR_DROPS_PAGE_SIZE, COLLECTOR_DROPS_ACTIVE_LIMIT, COLLECTOR_DROP_DEFAULT_EXTENSION_MINUTES, COLLECTOR_DROP_MIN_BID_INCREMENT, COLLECTOR_DROP_SNIPING_WINDOW_SECONDS, } from "../../../shared/features/collector-drops/config.js";
+export { renderCollectorDropOgImage, renderCollectorDropOg } from "./og.js";

package/dist/_internal/server/features/collector-drops/og.d.ts

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+export interface CollectorDropOgData {
+    title: string;
+    endsLabel?: string | null;
+    imageUrl?: string | null;
+}
+interface CollectorDropDocLike {
+    title?: string | null;
+    collectorDropEndDate?: Date | string | null;
+    mainImage?: string | null;
+    images?: ({
+        url: string;
+    } | string | null | undefined)[] | null;
+}
+/** High-level OG renderer — accepts the raw collector drop document from `getCollectorDropForDetail`. */
+export declare function renderCollectorDropOg(doc: CollectorDropDocLike | null | undefined, opts: {
+    siteName: string;
+    locale?: string;
+    baseUrl?: string;
+}): ReactElement;
+export declare function renderCollectorDropOgImage(data: CollectorDropOgData, siteName: string): ReactElement;
+export {};

package/dist/_internal/server/features/collector-drops/og.js

@@ -0,0 +1,30 @@
+import { renderOgLayout } from "../seo/og-layout.js";
+import { resolveOgImageUrl } from "../seo/og.js";
+/** High-level OG renderer — accepts the raw collector drop document from `getCollectorDropForDetail`. */
+export function renderCollectorDropOg(doc, opts) {
+    const locale = opts.locale ?? "en-IN";
+    const endDate = doc?.collectorDropEndDate
+        ? doc.collectorDropEndDate instanceof Date
+            ? doc.collectorDropEndDate
+            : new Date(doc.collectorDropEndDate)
+        : null;
+    const endsLabel = endDate
+        ? `Ends ${endDate.toLocaleDateString(locale, { day: "numeric", month: "short", year: "numeric" })}`
+        : null;
+    return renderCollectorDropOgImage({
+        title: doc?.title ?? "Live Collector Drop",
+        endsLabel,
+        imageUrl: resolveOgImageUrl(doc?.mainImage ||
+            (typeof doc?.images?.[0] === "string" ? doc.images[0] : doc?.images?.[0]?.url) ||
+            null, opts.baseUrl),
+    }, opts.siteName);
+}
+export function renderCollectorDropOgImage(data, siteName) {
+    return renderOgLayout({
+        title: data.title,
+        imageUrl: data.imageUrl,
+        siteName: `${siteName} · Live Collector Drop`,
+        accentSlot: data.endsLabel,
+        theme: { accentColor: "#f59e0b" },
+    });
+}