@mohasinac/appkit 4.59.0 → 4.60.0

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

@@ -0,0 +1,173 @@
+"use server";
+/**
+ * Grievance intake — a record, a clock, and a place in the queue.
+ *
+ * ## What was wrong (D18)
+ *
+ * There was **no intake at all**: no form, no route, no API endpoint. The
+ * public `/grievance` page's only instruction was a `mailto:` to the generic
+ * support address, so nothing recorded a grievance, timestamped it, or tracked
+ * any statutory clock. `/report` is for scam and entity reports, not money.
+ *
+ * ## What this builds, and what it deliberately does NOT
+ *
+ * Built: the record, the acknowledgement timestamp, the resolution deadline,
+ * the structured disputed amount, and a `paymentCases` row so the deadline sits
+ * in the one queue an operator already reads.
+ *
+ * 🛑 **NOT built: anything published.** The Consumer Protection (E-Commerce)
+ * Rules 2020 require a NAMED individual as grievance officer, and this project
+ * publishes the business name with designation "Support" and the same generic
+ * support email — so there is no escalation tier (D17). It also publishes no
+ * timeline anywhere.
+ *
+ * I am not asserting the statutory periods from memory, and the reason is
+ * asymmetric: **a published timeline we then miss is worse than the present
+ * silence.** So the clock runs against `GRIEVANCE_PERIODS`, whose defaults are
+ * deliberately shorter than any plausible statutory period — firing early is
+ * harmless, firing late is the thing the regime punishes — and the public page
+ * stays untouched until the owner supplies the officer and the real numbers.
+ */
+import { wrapAction } from "../../../shared/types/action-result.js";
+import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { ValidationError } from "../../../../errors/index.js";
+import { supportRepository } from "../../../../features/support/repository/support.repository.js";
+import { GRIEVANCE_PERIODS, TicketCategoryValues, } from "../../../../features/support/schemas/firestore.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+const DETAIL_MIN = 30;
+const DETAIL_MAX = 5000;
+/**
+ * File a grievance.
+ *
+ * 🛑 The acknowledgement is stamped at intake, SYNCHRONOUSLY, and that is the
+ * one thing here that must not be best-effort. An acknowledgement timestamp is
+ * the evidence that we received the complaint on the day we say we did; writing
+ * it fire-and-forget would mean the clock's start could silently fail to
+ * record, and a clock whose start is unknown cannot be shown to have been met.
+ *
+ * The `paymentCases` row IS best-effort, because it is a convenience surface —
+ * losing it costs visibility, not evidence.
+ */
+export async function fileGrievanceAction(input) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["user", "buyer", "seller", "admin"]);
+        const subject = input.subject?.trim() ?? "";
+        const detail = input.detail?.trim() ?? "";
+        if (subject.length < 5) {
+            throw new ValidationError("Please give your grievance a short subject line.");
+        }
+        if (detail.length < DETAIL_MIN) {
+            throw new ValidationError(`Please describe the grievance in at least ${DETAIL_MIN} characters — a complaint with no account of the problem cannot be investigated or evidenced.`);
+        }
+        if (detail.length > DETAIL_MAX) {
+            throw new ValidationError(`Please keep the description under ${DETAIL_MAX} characters.`);
+        }
+        if (input.disputedAmount !== undefined &&
+            (!Number.isFinite(input.disputedAmount) || input.disputedAmount < 0)) {
+            throw new ValidationError("The disputed amount must be a positive number of rupees.");
+        }
+        const now = new Date();
+        const dueAt = new Date(now.getTime() + GRIEVANCE_PERIODS.resolveHours * 3600000);
+        /*
+         * `description`, not `message` — the create input is a `Pick` of the plain
+         * document and that is the field's real name. I wrote `message` first; an
+         * excess property would have been a compile error, which is the signal
+         * working as intended rather than a cast hiding it.
+         */
+        const ticket = await supportRepository.createTicket({
+            userId: user.uid,
+            /*
+             * Both REQUIRED by `SupportTicketCreateInput`, which is a `Pick` of the
+             * PLAIN document — so plaintext here is correct, and the repository
+             * encrypts on write. Omitting them was a compile error rather than a
+             * silent gap, which is the Pick working as intended.
+             */
+            userEmail: user.email ?? "",
+            userDisplayName: user.name ?? user.email ?? "Buyer",
+            category: TicketCategoryValues.GRIEVANCE,
+            subject,
+            description: detail,
+            ...(input.orderId ? { orderId: input.orderId } : {}),
+            /*
+             * Both stamped at creation. `acknowledgedAt` is "we have it" and is
+             * automatic; `firstResponseAt` is deliberately NOT set — that is a
+             * human replying, and letting an automatic receipt satisfy it would make
+             * the response metric meaningless.
+             */
+            acknowledgedAt: now,
+            dueAt,
+            ...(input.disputedAmount !== undefined ? { disputedAmount: input.disputedAmount } : {}),
+        });
+        /*
+         * Into the operator queue with the SAME `dueAt`, because a grievance with a
+         * deadline is structurally a chargeback with a deadline: an external clock
+         * we did not set and cannot extend. Phase 3's queue already sorts by
+         * nearest `dueAt` and the daily digest already prints it, so this needs no
+         * new surface — which is the whole reason that queue was built as one
+         * collection rather than three.
+         */
+        void paymentCasesRepository()
+            .openOrObserve({
+            kind: "grievance",
+            subjectId: ticket.id,
+            severity: "error",
+            title: `Grievance — ${subject}`,
+            detail: [
+                `A formal grievance has been filed and a statutory clock is running.`,
+                "",
+                `Ticket: ${ticket.id}`,
+                input.orderId ? `Order: ${input.orderId}` : "Order: (not order-specific)",
+                input.disputedAmount !== undefined
+                    ? `Disputed amount: ${input.disputedAmount}`
+                    : "Disputed amount: not stated",
+                `Acknowledged: ${now.toISOString()}`,
+                `Due: ${dueAt.toISOString()}`,
+                "",
+                detail,
+                "",
+                `🛑 The periods are internal DEFAULTS (${GRIEVANCE_PERIODS.acknowledgeHours}h ack /`,
+                `${GRIEVANCE_PERIODS.resolveHours / 24}d resolve), chosen shorter than any plausible`,
+                `statutory period so the clock fires early. Nothing is published yet.`,
+            ].join("\n"),
+            entityType: "user",
+            entityId: user.uid,
+            dueAt,
+            ...(input.disputedAmount !== undefined ? { amountAtRisk: input.disputedAmount } : {}),
+            ...(input.orderId ? { orderIds: [input.orderId] } : {}),
+            now,
+        })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        serverLogger.warn("grievance filed", {
+            ticketId: ticket.id,
+            orderId: input.orderId,
+            dueAt: dueAt.toISOString(),
+        });
+        return { ticketId: ticket.id, dueAt: dueAt.toISOString() };
+    });
+}
+/**
+ * Stamp the first human response.
+ *
+ * 🛑 Separate from the ticket's ordinary reply path on purpose: it is
+ * write-once (`!existing.firstResponseAt`), so a second reply cannot move the
+ * metric forward and make a slow first response look fast. The same
+ * write-once discipline `resolvedAt` already uses.
+ */
+export async function recordGrievanceFirstResponseAction(ticketId) {
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["admin", "moderator", "employee"]);
+        const existing = (await supportRepository.findById(ticketId));
+        if (!existing)
+            throw new ValidationError(`Ticket ${ticketId} not found`);
+        if (existing.firstResponseAt)
+            return; // write-once, idempotent
+        await supportRepository.update(ticketId, {
+            firstResponseAt: new Date(),
+        });
+        serverLogger.info("grievance first response recorded", { ticketId, by: user.uid });
+    });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * grievance — server surface.
+ *
+ * Two actions. Narrow on purpose (Root Cause #18): the intake and the
+ * write-once first-response stamp. Everything else about a grievance is an
+ * ordinary support ticket and uses the support repository directly.
+ */
+export { fileGrievanceAction, recordGrievanceFirstResponseAction, type FileGrievanceInput, } from "./actions";

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

@@ -0,0 +1,8 @@
+/**
+ * grievance — server surface.
+ *
+ * Two actions. Narrow on purpose (Root Cause #18): the intake and the
+ * write-once first-response stamp. Everything else about a grievance is an
+ * ordinary support ticket and uses the support repository directly.
+ */
+export { fileGrievanceAction, recordGrievanceFirstResponseAction, } from "./actions.js";

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

@@ -7,6 +7,28 @@ import { GROUPED_LISTINGS_COLLECTION, } from "../../../../features/grouped/schem
 import { productRepository, groupedListingsRepository } from "../../../../repositories/index.js";
 import { PRODUCT_FIELDS, CATEGORY_FIELDS } from "../../../../constants/field-names.js";
 import { GROUPED_LISTINGS_FEATURED_LIMIT, GROUPED_LISTINGS_PAGE_SIZE, GROUPED_LISTINGS_SITEMAP_LIMIT, } from "../../../shared/features/grouped/config.js";
+import { isListingTypeEnabled } from "../../../shared/listing-types/feature-flags.js";
+import { normalizeListingType } from "../../../../features/products/utils/listing-type.js";
+import { getSiteSettingsSafe } from "../site-settings/safe-settings.js";
+/**
+ * Drop members whose listing type the admin has switched off.
+ *
+ * 🛑 One helper for all three hydrators rather than the same `.filter()`
+ * repeated three times — three copies of one rule is how the next person
+ * updates two of them (Root Cause #75).
+ *
+ * `isListingTypeEnabled` reads a missing flag as ENABLED and
+ * `getSiteSettingsSafe` returns null on failure, so a settings read that fails
+ * shows every member rather than emptying the carousel — the right failure
+ * direction for a discovery surface.
+ */
+async function withEnabledMembers(groups) {
+    const settings = await getSiteSettingsSafe();
+    return groups.map((group) => ({
+        ...group,
+        items: group.items.filter((p) => isListingTypeEnabled(normalizeListingType(p), settings)),
+    }));
+}
 function mapDoc(doc) {
     const data = doc.data();
     const ts = (v) => {
@@ -127,7 +149,7 @@ export const getGroupsForProduct = cache(async (productId) => {
  */
 export const getGroupsWithItemsForProduct = cache(async (productId) => {
     const groups = await getGroupsForProduct(productId);
-    return Promise.all(groups.map(async (group) => {
+    const hydrated = await Promise.all(groups.map(async (group) => {
         const otherIds = group.productIds.filter((id) => id !== productId);
         const items = await Promise.all(otherIds.map((id) => safeRead(() => productRepository.findByIdOrSlug(id), {
             route: "/products",
@@ -136,6 +158,7 @@ export const getGroupsWithItemsForProduct = cache(async (productId) => {
         })));
         return { ...group, items: items.filter((p) => p !== null) };
     }));
+    return withEnabledMembers(hydrated);
 });
 /** Groups tagged to a category, hydrated with all member products — for the category detail page's GroupedListingsCarousel. */
 export const getGroupsForCategory = cache(async (categorySlug) => {
@@ -144,10 +167,11 @@ export const getGroupsForCategory = cache(async (categorySlug) => {
         serverLogger.warn("grouped-data: getGroupsForCategory failed — returning empty", { categorySlug, error: err instanceof Error ? err.message : String(err) });
         return [];
     });
-    return Promise.all(groups.map(async (group) => {
+    const hydrated = await Promise.all(groups.map(async (group) => {
         const items = await Promise.all(group.productIds.map((id) => productRepository.findByIdOrSlug(id).catch(() => null)));
         return { ...group, items: items.filter((p) => p !== null) };
     }));
+    return withEnabledMembers(hydrated);
 });
 /** Groups tagged to a brand, hydrated with all member products — for the brand detail page's GroupedListingsCarousel. */
 export const getGroupsForBrand = cache(async (brandSlug) => {
@@ -156,10 +180,11 @@ export const getGroupsForBrand = cache(async (brandSlug) => {
         serverLogger.warn("grouped-data: getGroupsForBrand failed — returning empty", { brandSlug, error: err instanceof Error ? err.message : String(err) });
         return [];
     });
-    return Promise.all(groups.map(async (group) => {
+    const hydrated = await Promise.all(groups.map(async (group) => {
         const items = await Promise.all(group.productIds.map((id) => productRepository.findByIdOrSlug(id).catch(() => null)));
         return { ...group, items: items.filter((p) => p !== null) };
     }));
+    return withEnabledMembers(hydrated);
 });
 export async function listSitemapGroupedListings() {
     try {

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

@@ -1,7 +1,8 @@
 "use server";
 import { wrapAction } from "@mohasinac/appkit/server";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
-import { eventRepository, productRepository } from "../../../../repositories/index.js";
+import { eventRepository, productRepository, orderRepository } from "../../../../repositories/index.js";
+import { serverLogger } from "../../../../monitoring/index.js";
 import { lotteryEntryRepository } from "../../../../features/lottery/repository/lottery-entry.repository.js";
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
 import { ValidationError } from "../../../shared/errors/index.js";
@@ -73,10 +74,89 @@ export async function submitLotteryPullAction(input) {
         if (existingUserPulls >= lotteryConfig.maxPullsPerUser) {
             throw new LotteryError("USER_LIMIT_REACHED", "You have reached the maximum number of pulls for this lottery.");
         }
-        // Enforce maxPullsPerTransaction
+        /*
+         * ── D52: THE TRANSACTION MUST BE A REAL, PAID, CALLER-OWNED ORDER ──────
+         *
+         * 🛑 Before this, `data.transactionId` was a user-supplied STRING
+         * (`z.string().min(4)`) and the only thing checked was a COUNT of prior
+         * entries carrying the same string. Nothing verified that the transaction
+         * existed, that it was paid, or that it belonged to the caller — and
+         * `paymentTime` was user-supplied too.
+         *
+         * So **anyone could claim a lottery slot for free** by typing any
+         * four-character string, up to `maxPullsPerUser`, and then another
+         * `maxPullsPerUser` under the next string. On a lottery whose slots carry
+         * real prices and real prizes.
+         *
+         * The code knew: `// FUTURE_FINANCIAL_DB: external_tx_id →
+         * lottery_transactions.external_tx_id`, pointing at a collection that does
+         * not exist. The gap was marked and left open.
+         *
+         * It does not need that collection: a prize-draw entry is bought through
+         * the ordinary cart, so a paid ORDER is the payment record we already
+         * have. `maxPullsPerTransaction` then does what its name says — it bounds
+         * pulls per PAYMENT rather than per guessed string.
+         *
+         * 🛑 THE TWO SOURCES HAVE DIFFERENT PAYMENT REALITIES, and pretending
+         * otherwise would either leave the hole open or break a working feature.
+         *
+         * · A PRODUCT-sourced lottery is a `prize-draw` listing bought through the
+         *   ordinary cart, so a paid ORDER exists and is verifiable. Required.
+         *
+         * · An EVENT-sourced lottery carries real slot prices (the seed has both
+         *   `uniform` and `variable` events) and has **no cart or checkout path at
+         *   all** — an event is not a product and cannot be added to a cart. So
+         *   the typed `transactionId` was the ENTIRE payment record: an
+         *   honour-system reference with nothing behind it.
+         *
+         *   Requiring an order here would break every event lottery. Accepting the
+         *   string silently is the hole. So the entry is accepted and marked
+         *   `isFlagged` for admin review BEFORE the draw — `flagLotteryEntry`
+         *   already exists for exactly this, and an admin can clear or void it.
+         *   That makes the unverified state VISIBLE instead of indistinguishable
+         *   from a paid one.
+         *
+         * 🛑 This is a stopgap, not a fix, and it is the honest one available
+         * without building a checkout path for events. The real fix is to make an
+         * event lottery purchasable (or free), which is a product decision.
+         */
+        let paymentUnverified = false;
+        if (data.sourceType === "product") {
+            const payingOrder = await orderRepository.findById(data.transactionId);
+            /*
+             * "Not found" and "not yours" share one message DELIBERATELY.
+             * Distinguishing them confirms that an order id exists and belongs to
+             * someone else, which is an enumeration oracle over order ids.
+             */
+            if (!payingOrder || payingOrder.userId !== user.uid) {
+                throw new LotteryError("TX_ALREADY_USED", "That order could not be found. Enter the order ID from your confirmation email.");
+            }
+            if (payingOrder.paymentStatus !== "paid") {
+                throw new LotteryError("TX_ALREADY_USED", "That order has not been paid yet. Once the payment is confirmed you can claim your slot.");
+            }
+            /*
+             * The order must contain THIS prize draw, or one paid order could be
+             * spent across every open lottery on the site.
+             *
+             * Both shapes are checked: `items[]` is the fan-out form, and the flat
+             * `productId` is the PRIMARY field on an order — CLAUDE.md's own
+             * correction records that `items` is OPTIONAL and the flat fields are
+             * not legacy residue, so checking only one misses real orders.
+             */
+            const orderCoversSource = payingOrder.productId === sourceId ||
+                (payingOrder.items ?? []).some((i) => i.productId === sourceId);
+            if (!orderCoversSource) {
+                throw new LotteryError("TX_ALREADY_USED", "That order does not include this prize draw. Check the order ID.");
+            }
+        }
+        else {
+            paymentUnverified = true;
+            serverLogger.warn("[lottery] event pull accepted with an UNVERIFIED payment reference — flagged for admin review", { eventId: sourceId, uid: user.uid, transactionId: data.transactionId });
+        }
+        // Enforce maxPullsPerTransaction — now per PAYMENT, not per guessed string.
         const existingTxPulls = await lotteryEntryRepository.countByTransactionId(sourceId, sourceField, data.transactionId);
         if (existingTxPulls >= lotteryConfig.maxPullsPerTransaction) {
-            throw new LotteryError("TX_ALREADY_USED", "This transaction ID has already been used the maximum number of times.");
+            throw new LotteryError("TX_ALREADY_USED", "This order has already been used for the maximum number of pulls.");
         }
         // Atomically: pick slot + create entry + mark slot booked
         const db = getAdminDb();
@@ -139,7 +219,22 @@ export async function submitLotteryPullAction(input) {
             userLotteryNumber,
             assignedPrizeSlotNumber: assignedSlot.slotNumber,
             status: "drawn",
-            isFlagged: false,
+            /*
+             * D52 — an EVENT pull carries no verifiable payment (events have no
+             * cart path), so it is flagged on creation rather than recorded as if it
+             * were paid. A product pull reached here only after its order was
+             * verified paid, caller-owned and covering this draw, so it is not
+             * flagged.
+             *
+             * This is what makes the unverified state visible to an admin before the
+             * draw instead of indistinguishable from a paid one.
+             */
+            isFlagged: paymentUnverified,
+            ...(paymentUnverified
+                ? {
+                    flagNote: "Payment reference not verified — event lotteries have no checkout path, so this reference was typed by the entrant. Confirm the payment before the draw.",
+                }
+                : {}),
             submittedAt: new Date(),
             drawnAt: new Date(),
         };

package/dist/_internal/server/features/order-completion/actions.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Order completion — per-item ratings, and the two ways an order completes.
+ *
+ * ## The owner's rule, 2026-10-21
+ *
+ * > *"Points only get issued on successful purchases after buyer put reviews…
+ * > they are also assigned if the user [raises] no issues or updates after 7
+ * > days of delivery — no further disputes should be entertained as well."*
+ *
+ * > *"Auto assigned after 7 days of delivery, when order is marked complete; if
+ * > review is given and order marked complete by the buyer before — immediate
+ * > disburse."*
+ *
+ * > *"Like in Zomato, each item of the order can be individually rated and a
+ * > comment can be given — use that."*
+ *
+ * So completion has exactly two writers, and they are not equivalent:
+ *
+ * | writer | when | effect |
+ * |---|---|---|
+ * | `obligationSweep` (`order-complete`) | 7 days after delivery, nothing contested | completes; points award |
+ * | `markOrderCompleteAction` | the buyer, having rated at least one item | completes NOW; **immediate disburse** |
+ *
+ * 🛑 **The "immediate disburse" half needs no extra mechanism, and that is the
+ * nicest property of the design.** `payout-release` is already
+ * `blockedBy: ["order-complete", …]`, so a buyer completing early opens the
+ * seller's payout gate early as a CONSEQUENCE rather than as a second
+ * decision. The buyer confirming satisfaction is precisely the signal a quiet
+ * period exists to wait for — so when it arrives, waiting out the rest of the
+ * period is pure dead time for the seller.
+ */
+import { type ActionResult } from "../../../shared/types/action-result";
+/** The lines of an order a buyer can rate — one entry per order line. */
+export interface RateableOrderItem {
+    orderItemId: string;
+    productId: string;
+    productTitle: string;
+    /** The buyer's existing rating for this line, when they have left one. */
+    existingRating?: number;
+}
+/**
+ * Which lines of this order the buyer may rate, and which they already have.
+ *
+ * 🛑 Reads the buyer's OWN reviews (`findByUser`) rather than each product's
+ * reviews (`findByProduct`). A product can carry thousands of reviews and a
+ * buyer carries a handful, so this is bounded by the right dimension —
+ * `findByProduct` on a popular bey would be an unbounded read to answer a
+ * question about one person (Rule #6).
+ */
+export declare function getRateableItemsAction(orderId: string): Promise<ActionResult<RateableOrderItem[]>>;
+export interface RateOrderItemInput {
+    orderId: string;
+    orderItemId: string;
+    rating: number;
+    comment: string;
+    title?: string;
+    images?: string[];
+}
+/**
+ * Rate ONE line of an order — the Zomato-style per-item review.
+ *
+ * 🛑 Gated on DELIVERY, not on completion. A buyer must be able to rate before
+ * marking the order complete, because rating is the precondition for the fast
+ * completion path — gating it on completion would make the fast path
+ * unreachable, which is a circular dependency that would look like a bug in
+ * the button.
+ */
+export declare function rateOrderItemAction(input: RateOrderItemInput): Promise<ActionResult<{
+    reviewId: string;
+}>>;
+/**
+ * The buyer marks the order complete — the FAST path.
+ *
+ * Requires at least one rated line, per the owner's rule (*"if review is given
+ * and order marked complete by the buyer"*).
+ *
+ * 🛑 **At least one, not all.** Requiring every line would make a six-item
+ * order's completion hostage to the one item the buyer has no opinion about —
+ * and the buyer's alternative is simply to wait 7 days and be completed
+ * automatically with no review at all, which is strictly worse for everyone.
+ * One rating is the signal; demanding six is a toll.
+ *
+ * 🛑 It REFUSES while anything is contested, and the check is the obligation
+ * policy's own `precondition` rather than a second hand-written copy — so the
+ * buyer-initiated path and the 7-day sweep cannot disagree about what "nothing
+ * contested" means.
+ */
+export declare function markOrderCompleteAction(orderId: string): Promise<ActionResult<{
+    completedAt: string;
+    payoutUnblocked: boolean;
+    pointsAwarded: number;
+}>>;