@mohasinac/appkit 4.60.0 → 4.61.0

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

@@ -1,5 +1,16 @@
 "use server";
-import { wrapAction } from "@mohasinac/appkit/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";
 /**
  * processRefundAction — append a refund event to an order.
  *
@@ -235,7 +246,8 @@ export async function processRefundAction(input) {
         const isFull = wouldBeFullRefund(order, input.amount, siteSettings?.commissions?.gstPercent);
         const event = {
             refundId,
-            type: input.type,
+            // Derived from the authoritative `isFull` above, never from a caller.
+            type: isFull ? "full" : "partial",
             amount: input.amount,
             ...(input.itemIds?.length ? { itemIds: input.itemIds } : {}),
             reasonCode: input.reasonCode,

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

@@ -1,4 +1,4 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
+import { type ActionResult } from "../../../shared/types/action-result";
 export declare function createReviewAction(input: unknown): Promise<ActionResult<unknown>>;
 export declare function replyToReviewAction(input: unknown): Promise<ActionResult<unknown>>;
 export declare function deleteReviewAction(input: unknown): Promise<ActionResult<unknown>>;

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

@@ -1,5 +1,16 @@
 "use server";
-import { wrapAction } from "@mohasinac/appkit/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 { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
 import { isAdminUser } from "../../../../features/auth/role-predicates.js";
 import { reviewRepository, productRepository, userRepository, } from "../../../../repositories/index.js";

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

@@ -1,4 +1,4 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
+import { type ActionResult } from "../../../shared/types/action-result";
 import { type WishlistItem } from "../../../../repositories";
 export declare function addToWishlistAction(productId: string, extras?: {
     productType?: WishlistItem["productType"];

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

@@ -1,6 +1,17 @@
 "use server";
 import { normalizeError } from "../../../../errors/normalize.js";
-import { wrapAction } from "@mohasinac/appkit/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 { requireRoleUser } from "../../../../providers/auth-firebase/helpers.js";
 import { wishlistRepository, WishlistFullError, } from "../../../../repositories/index.js";
 import { WISHLIST_MAX } from "../../../shared/features/wishlist/config.js";

package/dist/_internal/server/jobs/core/obligationSweep.js

@@ -279,7 +279,6 @@ async function performAction(ctx, obligation, order) {
             }
             const result = await processRefundAction({
                 orderId: order.id,
-                type: "full",
                 amount: capacity.remaining,
                 reasonCode: order.returnReasonCode ?? "not_as_described",
                 reasonNote: `Auto-resolved in the buyer's favour — ${policy.describe}`,

package/dist/_internal/server/jobs/core/paymentReconcile.js

@@ -36,7 +36,8 @@ import { gatewayEventsRepository } from "../../../../features/gateway-events/rep
 import { GATEWAY_EVENT_MAX_ATTEMPTS, } from "../../../../features/gateway-events/schemas/firestore.js";
 import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 import { orderRepository } from "../../../../features/orders/repository/orders.repository.js";
-import { REFUND_CLAIMS_COLLECTION } from "../../../../features/orders/schemas/firestore.js";
+import { REFUND_CLAIMS_COLLECTION, REFUND_CLAIM_FIELDS, ORDER_COLLECTION, } from "../../../../features/orders/schemas/firestore.js";
+import { ORDER_FIELDS } from "../../../../constants/field-names.js";
 import { reconcileDisputes } from "../../features/payment-cases/disputes.js";
 import { refundableBase, committedRefundTotal, MONEY_EPSILON, } from "../../../shared/checkout/refundable-base.js";
 /** How far back R2 looks. Two days of overlap, so a run that fails is covered by the next. */
@@ -137,7 +138,81 @@ export async function reconcileStuckGatewayEvents(ctx) {
     }
     return { redispatched, escalated, reads: stuck.length };
 }
-/* ──────────────── R2: the gateway has it — do we? ───────────────────────── */
+/**
+ * "The gateway captured a different amount from the one the order records."
+ *
+ * Extracted from the sweep below, where it sat inside
+ * fn → `for record` → `for order` → `if` and the whole case literal was a
+ * brace too deep. Pure construction — no branching, and `recorded` is passed
+ * in rather than re-derived, so the one money rule still lives at the call
+ * site (Root Cause #75).
+ */
+async function openAmountMismatchCase(record, orderId, recorded, now) {
+    await paymentCasesRepository().openOrObserve({
+        kind: "amount_mismatch",
+        subjectId: `${record.id}:${orderId}`,
+        severity: "error",
+        title: `Captured ${record.amount} but recorded ${recorded} — ${orderId}`,
+        detail: [
+            `The gateway captured a different amount from the one the order records.`,
+            `Either the buyer was over-charged or the order under-states what was paid.`,
+            "",
+            `Gateway: ${record.gateway}`,
+            `Payment: ${record.id}`,
+            `Order: ${orderId}`,
+            `Captured: ${record.amount} ${record.currency}`,
+            `Order total: ${recorded}`,
+            `Difference: ${(record.amount - recorded).toFixed(2)}`,
+        ].join("\n"),
+        entityType: "order",
+        entityId: orderId,
+        amountAtRisk: Math.abs(record.amount - recorded),
+        orderIds: [orderId],
+        gatewayPaymentId: record.id,
+        now,
+    });
+}
+/**
+ * "Our refund total disagrees with the gateway's."
+ *
+ * Same extraction as `openAmountMismatchCase`. `ours` and `base` are both
+ * computed by the caller from the shared helpers, so this never re-derives a
+ * refund figure of its own.
+ *
+ * 🛑 The severity split is the whole point and must not be flattened: the
+ * gateway having refunded MORE than we recorded is money that left without a
+ * record (`error`); our side showing more is a refund reserved and never
+ * completed (`warning`).
+ */
+async function openRefundMismatchCase(record, orderId, ours, base, now) {
+    await paymentCasesRepository().openOrObserve({
+        kind: "refund_mismatch",
+        subjectId: `${record.id}:refunds`,
+        severity: record.amountRefunded > ours ? "error" : "warning",
+        title: `Refund total disagrees with the gateway — ${orderId}`,
+        detail: [
+            record.amountRefunded > ours
+                ? `🛑 The gateway has refunded MORE than our records show. Money has left that we did not record.`
+                : `Our records show more refunded than the gateway did — a refund may have been reserved and never completed.`,
+            "",
+            `Gateway: ${record.gateway}`,
+            `Payment: ${record.id}`,
+            `Order: ${orderId}`,
+            `Gateway refunded: ${record.amountRefunded}`,
+            `Our committed refunds: ${ours}`,
+            `Refundable base: ${base}`,
+            record.refundStatus ? `Gateway refund status: ${record.refundStatus}` : null,
+        ]
+            .filter((l) => l !== null)
+            .join("\n"),
+        entityType: "order",
+        entityId: orderId,
+        amountAtRisk: Math.abs(record.amountRefunded - ours),
+        orderIds: [orderId],
+        gatewayPaymentId: record.id,
+        now,
+    });
+}
 async function reconcileGatewayPayments(ctx) {
     const payment = getProviders().payment;
     let examined = 0;
@@ -232,29 +307,7 @@ async function reconcileGatewayPayments(ctx) {
                 const recorded = order.totalPrice ?? 0;
                 if (Math.abs(recorded - record.amount) > MONEY_EPSILON) {
                     amountMismatch += 1;
-                    await paymentCasesRepository().openOrObserve({
-                        kind: "amount_mismatch",
-                        subjectId: `${record.id}:${order.id}`,
-                        severity: "error",
-                        title: `Captured ${record.amount} but recorded ${recorded} — ${order.id}`,
-                        detail: [
-                            `The gateway captured a different amount from the one the order records.`,
-                            `Either the buyer was over-charged or the order under-states what was paid.`,
-                            "",
-                            `Gateway: ${record.gateway}`,
-                            `Payment: ${record.id}`,
-                            `Order: ${order.id}`,
-                            `Captured: ${record.amount} ${record.currency}`,
-                            `Order total: ${recorded}`,
-                            `Difference: ${(record.amount - recorded).toFixed(2)}`,
-                        ].join("\n"),
-                        entityType: "order",
-                        entityId: order.id,
-                        amountAtRisk: Math.abs(record.amount - recorded),
-                        orderIds: [order.id],
-                        gatewayPaymentId: record.id,
-                        now: ctx.now,
-                    });
+                    await openAmountMismatchCase(record, order.id, recorded, ctx.now);
                 }
                 /*
                  * Refund check — the gateway's `amount_refunded` against our own
@@ -265,33 +318,7 @@ async function reconcileGatewayPayments(ctx) {
                 const ours = committedRefundTotal(order);
                 if (Math.abs(ours - record.amountRefunded) > MONEY_EPSILON) {
                     refundMismatch += 1;
-                    await paymentCasesRepository().openOrObserve({
-                        kind: "refund_mismatch",
-                        subjectId: `${record.id}:refunds`,
-                        severity: record.amountRefunded > ours ? "error" : "warning",
-                        title: `Refund total disagrees with the gateway — ${order.id}`,
-                        detail: [
-                            record.amountRefunded > ours
-                                ? `🛑 The gateway has refunded MORE than our records show. Money has left that we did not record.`
-                                : `Our records show more refunded than the gateway did — a refund may have been reserved and never completed.`,
-                            "",
-                            `Gateway: ${record.gateway}`,
-                            `Payment: ${record.id}`,
-                            `Order: ${order.id}`,
-                            `Gateway refunded: ${record.amountRefunded}`,
-                            `Our committed refunds: ${ours}`,
-                            `Refundable base: ${refundableBase(order)}`,
-                            record.refundStatus ? `Gateway refund status: ${record.refundStatus}` : null,
-                        ]
-                            .filter((l) => l !== null)
-                            .join("\n"),
-                        entityType: "order",
-                        entityId: order.id,
-                        amountAtRisk: Math.abs(record.amountRefunded - ours),
-                        orderIds: [order.id],
-                        gatewayPaymentId: record.id,
-                        now: ctx.now,
-                    });
+                    await openRefundMismatchCase(record, order.id, ours, refundableBase(order), ctx.now);
                 }
             }
         }
@@ -321,8 +348,8 @@ async function reconcileStaleRefundClaims(ctx) {
     try {
         const snap = await ctx.db
             .collection(REFUND_CLAIMS_COLLECTION)
-            .where("state", "==", "claimed")
-            .where("claimedAt", "<", cutoff)
+            .where(REFUND_CLAIM_FIELDS.STATE, "==", "claimed")
+            .where(REFUND_CLAIM_FIELDS.CLAIMED_AT, "<", cutoff)
             .limit(50)
             .get();
         for (const doc of snap.docs) {
@@ -404,9 +431,9 @@ async function reconcileUnpaidCancellations(ctx) {
     let stale = 0;
     try {
         const snap = await ctx.db
-            .collection("orders")
-            .where("status", "==", "cancelled")
-            .where("refundStatus", "==", "pending")
+            .collection(ORDER_COLLECTION)
+            .where(ORDER_FIELDS.STATUS, "==", "cancelled")
+            .where(ORDER_FIELDS.REFUND_STATUS, "==", "pending")
             .limit(100)
             .get();
         /*

package/dist/_internal/server/jobs/core/testDataCleanup.d.ts

@@ -14,7 +14,7 @@ import type { JobContext } from "../runtime/types";
  * (This used to be shared with testerSandboxRefresh.ts, which was removed when
  * the tester runner took over fixture state — see scheduled.ts.)
  */
-export declare const TEST_DATA_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events"];
+export declare const TEST_DATA_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events", "orders", "obligations", "protectionClaims"];
 export interface TestDataCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */
     force?: boolean;

package/dist/_internal/server/jobs/core/testDataCleanup.js

@@ -41,7 +41,28 @@ import { BID_FIELDS } from "../../../../constants/field-names.js";
  * is both `test` AND `isTestData`. `audit-seed-purpose` R6 now asserts every
  * entry here declares the field, so the `offers` shape cannot return.
  */
-export const TEST_DATA_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events"];
+/*
+ * 🛑 Every schema that declares `isTestData` must appear here, or the field is
+ * WRITE-ONLY and the row is never swept — a flag that reads as "this will be
+ * cleaned up" and never is.
+ *
+ * `orders`, `obligations` and `protectionClaims` were added 2026-10-22 after
+ * `audit-seed-purpose`'s inverse rule found all three declaring the field with
+ * no entry. They are the propagation chain: an order carries the flag, writing
+ * an obligation copies it (`orders.repository.ts` → `repo.open({ …isTestData
+ * })`), and a claim inherits it in turn — so a test order left three
+ * generations of descendants behind that nothing would ever collect.
+ */
+export const TEST_DATA_COLLECTIONS = [
+    "categories",
+    "stores",
+    "products",
+    "blogPosts",
+    "events",
+    "orders",
+    "obligations",
+    "protectionClaims",
+];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 export async function runTestDataCleanup(ctx, opts = {}) {
     const cutoff = opts.force ? null : new Date();

package/dist/_internal/server/jobs/handlers/onShipmentAllocationSync.js

@@ -1,5 +1,6 @@
 import { allocateShipmentCosts } from "../../../../features/shipments/utils/cost-allocation.js";
 import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { safeRead } from "../../../../errors/safe-read.js";
 /*
  * ── D58: the admin saw 6 while this used 4 ───────────────────────────────
  *
@@ -97,10 +98,21 @@ async function recomputeShipmentAllocation(shipmentId, ctx) {
      * single shipment, not a sweep, so the read is bounded — and the
      * alternative (keep ignoring the admin control) is the defect.
      */
-    const laborSettings = await siteSettingsRepository
-        .getSingleton()
-        .then((s) => s.laborRate)
-        .catch(() => undefined);
+    /*
+     * `safeRead`, not `.catch(() => undefined)`.
+     *
+     * The fallback is unchanged — a settings read that fails must not stop the
+     * allocation, and `settingsMaxHours` being absent simply means "no admin
+     * ceiling". What changes is that the failure is now RECORDED: a bare catch
+     * returning `undefined` is indistinguishable from an admin who never set a
+     * ceiling, so the labour cap could silently stop being enforced with
+     * nothing anywhere to say so. `installDegradedReadReporter` persists it.
+     */
+    const laborSettings = await safeRead(() => siteSettingsRepository.getSingleton().then((s) => s.laborRate), {
+        route: "job:onShipmentAllocationSync",
+        key: "siteSettings:laborRate",
+        fallback: undefined,
+    });
     const settingsMaxHours = laborSettings?.maxHoursPerDay;
     const { perLot, totals } = allocateShipmentCosts({
         lots: allocationInputs,

package/dist/_internal/shared/features/promotions/schema.d.ts

@@ -36,6 +36,25 @@ export declare const createCouponSchema: z.ZodObject<{
         minPurchase?: number | undefined;
         maxDiscount?: number | undefined;
     }>;
+    bxgy: z.ZodOptional<z.ZodObject<{
+        buyQuantity: z.ZodNumber;
+        getQuantity: z.ZodNumber;
+        maxItemPrice: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodNumber, number, number>, number, number>>;
+        applicableProducts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        applicableCategories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    }, {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    }>>;
     usage: z.ZodObject<{
         totalLimit: z.ZodOptional<z.ZodNumber>;
         perUserLimit: z.ZodDefault<z.ZodNumber>;
@@ -91,6 +110,13 @@ export declare const createCouponSchema: z.ZodObject<{
         endDate: string;
         startDate: string;
     };
+    bxgy?: {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    } | undefined;
     restrictions?: {
         firstTimeUserOnly: boolean;
         applicableProducts?: string[] | undefined;
@@ -115,6 +141,13 @@ export declare const createCouponSchema: z.ZodObject<{
         startDate: string;
         isActive?: boolean | undefined;
     };
+    bxgy?: {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    } | undefined;
     restrictions?: {
         firstTimeUserOnly?: boolean | undefined;
         applicableProducts?: string[] | undefined;
@@ -139,6 +172,25 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         minPurchase?: number | undefined;
         maxDiscount?: number | undefined;
     }>>;
+    bxgy: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        buyQuantity: z.ZodNumber;
+        getQuantity: z.ZodNumber;
+        maxItemPrice: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodNumber, number, number>, number, number>>;
+        applicableProducts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        applicableCategories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    }, {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    }>>>;
     usage: z.ZodOptional<z.ZodObject<{
         totalLimit: z.ZodOptional<z.ZodNumber>;
         perUserLimit: z.ZodDefault<z.ZodNumber>;
@@ -184,6 +236,13 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         minPurchase: number;
         maxDiscount?: number | undefined;
     } | undefined;
+    bxgy?: {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    } | undefined;
     usage?: {
         perUserLimit: number;
         totalLimit?: number | undefined;
@@ -207,6 +266,13 @@ export declare const updateCouponSchema: z.ZodObject<Omit<{
         minPurchase?: number | undefined;
         maxDiscount?: number | undefined;
     } | undefined;
+    bxgy?: {
+        buyQuantity: number;
+        getQuantity: number;
+        maxItemPrice?: number | undefined;
+        applicableProducts?: string[] | undefined;
+        applicableCategories?: string[] | undefined;
+    } | undefined;
     usage?: {
         totalLimit?: number | undefined;
         perUserLimit?: number | undefined;

package/dist/_internal/shared/features/promotions/schema.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { COUPON_CODE_PATTERN } from "./config.js";
+import { bxgyConfigSchema } from "../../../../features/promotions/schemas/index.js";
 export const applyCouponSchema = z.object({
     code: z.string().regex(COUPON_CODE_PATTERN, "Invalid coupon code format").toUpperCase(),
     cartTotal: z.number().min(0),
@@ -17,6 +18,12 @@ export const createCouponSchema = z.object({
         maxDiscount: z.number().min(0).optional(),
         minPurchase: z.number().min(0).default(0),
     }),
+    /*
+     * 🛑 Without this, `z.object()` strips the config the `buy_x_get_y` member
+     * of the enum above depends on — see the fuller note on `bxgyConfigSchema`.
+     * Imported rather than restated so all five write paths move together.
+     */
+    bxgy: bxgyConfigSchema.optional(),
     usage: z.object({
         totalLimit: z.number().int().min(1).optional(),
         perUserLimit: z.number().int().min(1).default(1),

package/dist/_internal/shared/obligations/deadlines.js

@@ -33,7 +33,17 @@
 import { addBusinessDays } from "../time/business-days.js";
 import { OBLIGATION_POLICIES, durationToMinutes, } from "../../../features/obligations/constants/policies.js";
 import { ALL_OBLIGATION_KINDS, } from "../../../features/obligations/schemas/firestore.js";
-import { windowMinutes } from "../../../features/tester/seed-data/tester-window.js";
+/*
+ * 🛑 From _internal/shared/tester, NOT features/tester/seed-data.
+ *
+ * appkit/package.json excludes "!dist/features/tester/seed-data" from the
+ * published tarball, so this production module importing from there left the
+ * package with a DANGLING import: it resolved locally (the dir exists in a
+ * local build) and broke the consumer Turbopack build, which installs the
+ * tarball — "Module not found: tester-window.js". Nothing in appkit could see
+ * it; only a real deploy could.
+ */
+import { windowMinutes } from "../tester/window.js";
 /**
  * How much a test fixture's deadlines are compressed.
  *

package/dist/_internal/shared/tester/window.d.ts

@@ -0,0 +1,25 @@
+/** Reproduces the historical 1h/2h/3h auction stagger when nothing overrides it. */
+export declare const DEFAULT_TESTER_WINDOW_MINUTES = 180;
+/** Below this nothing is observable — a page load alone can outlast it. */
+export declare const MIN_TESTER_WINDOW_MINUTES = 5;
+/** The sandbox TTL is 7 days; a window longer than that outlives its own fixtures. */
+export declare const MAX_TESTER_WINDOW_MINUTES: number;
+/**
+ * Length of the testing window, in minutes.
+ *
+ * Read at call time rather than captured at module scope so a caller that sets the
+ * env var before importing a seed file still wins. Anything unparseable, non-finite
+ * or out of range falls back to the default rather than throwing: a malformed env
+ * var must not be able to brick `appkit-seed load`.
+ */
+export declare function windowMinutes(): number;
+/**
+ * A point `fraction` of the way through the window, measured from now.
+ *
+ * `windowOffset(0)` is now, `windowOffset(1)` is the window's end. Fractions above 1
+ * are allowed and mean "after this run" — that is how a fixture says "still open when
+ * testing finishes" without hard-coding a duration.
+ */
+export declare function windowOffset(fraction: number): Date;
+/** The mirror of windowOffset, into the past — for fixtures that must already be closed. */
+export declare function windowAgo(fraction: number): Date;

package/dist/_internal/shared/tester/window.js

@@ -0,0 +1,66 @@
+/*
+ * WHY: Every time-bound tester fixture — auction end dates, coupon validity, event
+ *      start/end, prize-draw reveal windows, offer expiry, lottery draw windows —
+ *      must open and close INSIDE one testing session. Hand-written offsets like
+ *      `Date.now() + 2 * 60 * 60 * 1000` cannot do that: they bake in a duration
+ *      nobody can shorten, so a case reading "watch the auction actually end" is
+ *      untestable without sitting there for two hours.
+ *
+ *      This file is the one knob. Fixtures express WHEN as a fraction of the run
+ *      window; the window's real length comes from TESTER_WINDOW_MINUTES.
+ *
+ * WHAT: windowMinutes() / windowOffset(fraction) / windowAgo(fraction).
+ *
+ * 🛑 The default is 180 minutes ON PURPOSE — it reproduces the pre-existing 1h/2h/3h
+ *    auction stagger exactly (fractions 1/3, 2/3, 1), so an ordinary `appkit-seed load`
+ *    behaves as it always has. Only the automated runner shortens it. Changing this
+ *    default silently re-times every fixture for human testers too.
+ *
+ * @tag domain:tester
+ * @tag layer:seed
+ * @tag pattern:none
+ * @tag access:server-only
+ * @tag consumers:seed-data/*-tester-seed-data.ts
+ * @tag sideEffects:none
+ */
+/** Reproduces the historical 1h/2h/3h auction stagger when nothing overrides it. */
+export const DEFAULT_TESTER_WINDOW_MINUTES = 180;
+/** Below this nothing is observable — a page load alone can outlast it. */
+export const MIN_TESTER_WINDOW_MINUTES = 5;
+/** The sandbox TTL is 7 days; a window longer than that outlives its own fixtures. */
+export const MAX_TESTER_WINDOW_MINUTES = 7 * 24 * 60;
+/**
+ * Length of the testing window, in minutes.
+ *
+ * Read at call time rather than captured at module scope so a caller that sets the
+ * env var before importing a seed file still wins. Anything unparseable, non-finite
+ * or out of range falls back to the default rather than throwing: a malformed env
+ * var must not be able to brick `appkit-seed load`.
+ */
+export function windowMinutes() {
+    const raw = process.env.TESTER_WINDOW_MINUTES;
+    if (!raw)
+        return DEFAULT_TESTER_WINDOW_MINUTES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_TESTER_WINDOW_MINUTES;
+    if (parsed < MIN_TESTER_WINDOW_MINUTES)
+        return MIN_TESTER_WINDOW_MINUTES;
+    if (parsed > MAX_TESTER_WINDOW_MINUTES)
+        return MAX_TESTER_WINDOW_MINUTES;
+    return parsed;
+}
+/**
+ * A point `fraction` of the way through the window, measured from now.
+ *
+ * `windowOffset(0)` is now, `windowOffset(1)` is the window's end. Fractions above 1
+ * are allowed and mean "after this run" — that is how a fixture says "still open when
+ * testing finishes" without hard-coding a duration.
+ */
+export function windowOffset(fraction) {
+    return new Date(Date.now() + fraction * windowMinutes() * 60000);
+}
+/** The mirror of windowOffset, into the past — for fixtures that must already be closed. */
+export function windowAgo(fraction) {
+    return windowOffset(-fraction);
+}

package/dist/client.d.ts

@@ -31,6 +31,7 @@ export { BUILT_IN_THEMES, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, REQUIRED_GRAD
 export type { GradientKey, RequiredThemeToken, ThemeMode, ThemeRecord, } from "./tokens/themes";
 export { ConfirmDeleteModal } from "./ui/components/ConfirmDeleteModal";
 export { EmptyState } from "./ui/components/EmptyState";
+export { FilterChipGroup } from "./ui/components/FilterChipGroup";
 export { Skeleton } from "./ui/components/Skeleton";
 export { IconBox } from "./ui/components/IconBox";
 export type { IconBoxProps, IconBoxRounded, IconBoxSize, IconBoxTone, } from "./ui/components/IconBox";

package/dist/client.js

@@ -52,6 +52,9 @@ export { BUILT_IN_THEMES, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, REQUIRED_GRAD
 export { ConfirmDeleteModal } from "./ui/components/ConfirmDeleteModal.js";
 // S-STORE — pure-UI primitives + Seller view consumed by new dashboard pages
 export { EmptyState } from "./ui/components/EmptyState.js";
+/* FilterChipGroup — a client UI primitive that existed, was used by
+   `ProtectionClaimsClient`, and was never exported here. */
+export { FilterChipGroup } from "./ui/components/FilterChipGroup.js";
 export { Skeleton } from "./ui/components/Skeleton.js";
 // IconBox — square-icon container primitive; was exported from index.ts only,
 // missing here even though CLAUDE.md documents it as a client-usable pattern.

package/dist/core/unit-of-work.js

@@ -13,7 +13,21 @@ import { normalizeError } from "../errors/normalize.js";
 // db-firebase reaches firebase-admin only through `import type` plus its own
 // bare-specifier runtime requires. See CLAUDE.md Root Cause #24.
 import { getAdminDb } from "../providers/db-firebase/index.js";
-import { DatabaseError } from "../errors/index.js";
+/*
+ * 🛑 From `errors/database-error`, NEVER the `../errors` barrel.
+ *
+ * That barrel re-exports `error-handler`, which does
+ * `import { NextResponse } from "next/server.js"` — and its own comment above
+ * that line says "only import in server/API-route contexts". This module is
+ * reachable from the Firebase Functions entry
+ * (`jobs.js → repositories → unit-of-work`), so the barrel dragged Next's
+ * whole server runtime into the tsup bundle. It failed with four errors that
+ * name neither this file nor the barrel: two unresolved
+ * `react-server-dom-webpack/*` requires and two `.wasm` files from
+ * `@vercel/og`. Nothing in appkit's own typecheck can see it; only
+ * `npm --prefix functions run build` can. Root Cause #18.
+ */
+import { DatabaseError } from "../errors/database-error.js";
 import { userRepository, tokenRepository, sessionRepository, } from "../features/auth/repository/index.js";
 import { addressesRepository } from "../features/addresses/repository/addresses.repository.js";
 import { cartRepository } from "../features/cart/repository/cart.repository.js";