@mohasinac/appkit 4.60.1 → 4.62.0

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/media/limits.d.ts

@@ -27,6 +27,16 @@ export type MediaKind = "image" | "video" | "pdf";
 export declare const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export declare const PRODUCT_MAX_VIDEOS = 1;
+/**
+ * Photos a buyer may attach to one review.
+ *
+ * 🛑 Deliberately NOT `PRODUCT_MAX_IMAGES`, which is 24 and is a SELLER's
+ * ceiling for a whole listing. `audit-media-limit-literals` suggests that
+ * constant for any `images: z.array(…).max(n)`, and taking the suggestion
+ * here would have quadrupled what a review accepts — the right shape, the
+ * wrong number. A review is a few photos of one thing.
+ */
+export declare const REVIEW_MAX_IMAGES = 6;
 /**
  * Highest legal `index` in a product media filename.
  *

package/dist/_internal/shared/media/limits.js

@@ -41,6 +41,16 @@ export const MAX_VIDEO_BYTES = 50 * MEGABYTE;
 export const PRODUCT_MAX_IMAGES = 24;
 /** Videos per listing. Bounded by `ProductDocument.video` being singular. */
 export const PRODUCT_MAX_VIDEOS = 1;
+/**
+ * Photos a buyer may attach to one review.
+ *
+ * 🛑 Deliberately NOT `PRODUCT_MAX_IMAGES`, which is 24 and is a SELLER's
+ * ceiling for a whole listing. `audit-media-limit-literals` suggests that
+ * constant for any `images: z.array(…).max(n)`, and taking the suggestion
+ * here would have quadrupled what a review accepts — the right shape, the
+ * wrong number. A review is a few photos of one thing.
+ */
+export const REVIEW_MAX_IMAGES = 6;
 /**
  * Highest legal `index` in a product media filename.
  *

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/_internal/shared/types/action-result.js

@@ -1,5 +1,6 @@
 import { normalizeError } from "../../../errors/normalize.js";
 import { mapToHttpError } from "../../../errors/error-mapping.js";
+import { toApiIssues } from "../../../errors/error-envelope.js";
 import { describeCauseChain } from "../../../errors/describe-cause.js";
 import { reportActionError } from "./action-error-reporter.js";
 /**
@@ -57,7 +58,20 @@ export async function wrapAction(fn) {
             ok: false,
             code: mapped.code,
             error: mapped.message,
-            ...(mapped.issues ? { issues: mapped.issues } : {}),
+            /*
+             * 🛑 `toApiIssues`, not the raw issues — this was the ONE producer in
+             * the codebase that skipped the scrubber, and it is the one with 221
+             * call sites.
+             *
+             * A raw `ZodIssue` carries `received`: the value the user actually
+             * submitted. On a failed signup, address save or payout-details save
+             * that is an email, a phone number or a bank account, echoed straight
+             * back into the client payload. `toApiIssues` narrows each issue to
+             * `{ message, path?, code? }`, which is exactly why it exists — every
+             * other producer (`routeHandler`, `createApiHandler`, the offer
+             * actions) already routes through it.
+             */
+            ...(mapped.issues ? { issues: toApiIssues(mapped.issues) } : {}),
         };
     }
 }

package/dist/client/api/surface-error.js

@@ -1,6 +1,6 @@
 import { isApiError } from "./ApiError.js";
 import { ApiClientError } from "../../http/ApiClient.js";
-import { applyZodIssues, hasAttachableIssue } from "../../ui/forms/apply-zod-issues.js";
+import { applyZodIssues, hasAttachableIssue, rootLevelMessages } from "../../ui/forms/apply-zod-issues.js";
 import { normalizeError } from "../../errors/normalize.js";
 import { getErrorDisplay, toUserMessage } from "../../errors/error-display-map.js";
 import { HTTP_ERROR_CODES } from "../../errors/error-mapping.js";
@@ -36,7 +36,21 @@ export function surfaceError(err, opts) {
     const issues = issuesOf(err);
     if (setFieldError && hasAttachableIssue(issues)) {
         applyZodIssues(issues, (name, message) => setFieldError(name, message ?? ""));
-        return; // inline errors only — no toast
+        /*
+         * 🛑 Root-level issues are NOT covered by the line above and must still be
+         * surfaced, or a cross-field rule fails silently.
+         *
+         * `applyZodIssues` skips any issue with an empty `path` — there is no
+         * field to put it on. For a mixed response (one field error plus one
+         * cross-field `.refine()`, the shape of "passwords must match" or "end
+         * date must be after start date") `hasAttachableIssue` is true, so we used
+         * to take this branch and `return` with the refine message discarded: the
+         * save was refused and nothing on screen said why.
+         */
+        for (const message of rootLevelMessages(issues)) {
+            showToast(message, "error");
+        }
+        return; // field errors inline; only the unattachable ones toast
     }
     if (hasStableErrorCode(err)) {
         const display = getErrorDisplay(err.code);

package/dist/client/api/useApiMutation.js

@@ -3,6 +3,7 @@ import * as React from "react";
 import { useMutation, } from "@tanstack/react-query";
 import { useToast } from "../../ui/components/Toast.js";
 import { surfaceError } from "./surface-error.js";
+import { toUserMessage } from "../../errors/error-display-map.js";
 export function useApiMutation(options) {
     const { showToast, updateToast } = useToast();
     const loadingIdRef = React.useRef(null);
@@ -40,7 +41,22 @@ export function useApiMutation(options) {
         onSettled: (data, err, variables, context, ctx) => {
             if (loadingIdRef.current) {
                 if (err) {
-                    updateToast(loadingIdRef.current, "error", err instanceof Error ? err.message : "Action failed");
+                    /*
+                     * 🛑 This was `err instanceof Error ? err.message : "Action failed"`
+                     * — verbatim the inverted ternary `audit-raw-error-text`'s own
+                     * header calls "the dominant shape", sitting two lines below the
+                     * correct `surfaceError` call in the same hook. The authored
+                     * sentence showed only when the value was NOT an Error, i.e. almost
+                     * never, so the normal case published the raw message.
+                     *
+                     * It was dormant only because `loadingMessage` currently has no
+                     * call sites; the first consumer to set one would have got two
+                     * toasts, one of them raw. `updateToast` is also absent from that
+                     * audit's SINKS list, so nothing would have caught it.
+                     */
+                    updateToast(loadingIdRef.current, "error", toUserMessage(err?.code, undefined, {
+                        fallback: "Action failed",
+                    }));
                 }
                 else if (!successMessage) {
                     updateToast(loadingIdRef.current, "success", "Done");

package/dist/client.d.ts

@@ -455,7 +455,7 @@ export type { OwnerQuickActionsProps, OwnerQuickActionsResource } from "./featur
 export type { StoreListingEntitlements } from "./features/seller/hooks/useStoreListingEntitlements";
 export type { ListingTypePlugin } from "./_internal/shared/listing-types/_registry";
 export type { ListingType } from "./features/products/types/index";
-export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits";
+export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, REVIEW_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits";
 export type { MediaKind, AllowedImageMime, AllowedVideoMime, AllowedDocMime, AllowedMime, } from "./_internal/shared/media/limits";
 export { ScamAwarenessModal } from "./features/scams/components/ScamAwarenessModal";
 export type { ScamAwarenessModalProps } from "./features/scams/components/ScamAwarenessModal";

package/dist/client.js

@@ -493,7 +493,7 @@ export { YourPurchaseStrip } from "./features/orders/components/YourPurchaseStri
 export { ReviewFormDrawer, reviewFormSchema } from "./features/reviews/components/ReviewFormDrawer.js";
 export { PurchaseReviewAffordance } from "./features/reviews/components/PurchaseReviewAffordance.js";
 // Media upload limits — shared by client uploaders + server sign/finalize routes.
-export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits.js";
+export { MEGABYTE, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MAX_LABEL, MAX_BYTES, ALLOWED_IMAGE_MIMES, IMAGE_ACCEPT_ATTR, ALLOWED_VIDEO_MIMES, ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_TYPES_LABEL, MIME_TO_EXT, PDF_MAGIC, VIDEO_CONVERSION_HINTS, classifyMime, isAllowedMime, maxBytesFor, getConversionHint, PRODUCT_MAX_IMAGES, REVIEW_MAX_IMAGES, PRODUCT_MAX_VIDEOS, PRODUCT_IMAGE_INDEX_MAX, } from "./_internal/shared/media/limits.js";
 export { ScamAwarenessModal } from "./features/scams/components/ScamAwarenessModal.js";
 export { SellerTrustBadge } from "./features/scams/components/SellerTrustBadge.js";
 // [CLIENT-ONLY] — Admin panel components for action/nav permission management.

package/dist/constants/api-endpoints.d.ts

@@ -535,6 +535,7 @@ export declare const SELLER_ENDPOINTS: {
     readonly BUNDLES: "/api/store/bundles";
     /** Tickets raised ABOUT this store (W11). */
     readonly SUPPORT: "/api/store/support";
+    readonly SUPPORT_TICKET_BY_ID: (id: string) => string;
     readonly BUNDLE_BY_ID: (id: string) => string;
     readonly ORDERS_ASSIGN: (orderId: string) => string;
     readonly PRODUCT_BY_ID: (id: string) => string;
@@ -1061,6 +1062,7 @@ export declare const API_ENDPOINTS: {
         readonly BUNDLES: "/api/store/bundles";
         /** Tickets raised ABOUT this store (W11). */
         readonly SUPPORT: "/api/store/support";
+        readonly SUPPORT_TICKET_BY_ID: (id: string) => string;
         readonly BUNDLE_BY_ID: (id: string) => string;
         readonly ORDERS_ASSIGN: (orderId: string) => string;
         readonly PRODUCT_BY_ID: (id: string) => string;
@@ -1608,6 +1610,7 @@ export declare const API_ROUTES: {
         readonly BUNDLES: "/api/store/bundles";
         /** Tickets raised ABOUT this store (W11). */
         readonly SUPPORT: "/api/store/support";
+        readonly SUPPORT_TICKET_BY_ID: (id: string) => string;
         readonly BUNDLE_BY_ID: (id: string) => string;
         readonly ORDERS_ASSIGN: (orderId: string) => string;
         readonly PRODUCT_BY_ID: (id: string) => string;

package/dist/constants/api-endpoints.js

@@ -690,6 +690,7 @@ export const SELLER_ENDPOINTS = {
     BUNDLES: "/api/store/bundles",
     /** Tickets raised ABOUT this store (W11). */
     SUPPORT: "/api/store/support",
+    SUPPORT_TICKET_BY_ID: (id) => `/api/store/support/${id}`,
     BUNDLE_BY_ID: (id) => `/api/store/bundles/${id}`,
     ORDERS_ASSIGN: (orderId) => `/api/store/orders/${orderId}/assign`,
     PRODUCT_BY_ID: (id) => `/api/store/products/${id}`,

package/dist/constants/field-names.d.ts

@@ -982,6 +982,23 @@ export declare const COMMON_FIELDS: {
     readonly IS_ACTIVE: "isActive";
     readonly ORDER: "order";
 };
+/**
+ * The idempotency rows behind a refund.
+ *
+ * 🛑 `STATE` is the claim's own lifecycle ("claimed" → settled), NOT a
+ * postal state. `audit-route-nav-field-constants` matches a raw field
+ * string against every constant that happens to share its VALUE, so it
+ * suggested `ADDRESS_FIELDS.STATE` here — right string, wrong concept, and
+ * taking the suggestion would have made the query read as address filtering.
+ */
+export declare const REFUND_CLAIM_FIELDS: {
+    readonly STATE: "state";
+    readonly CLAIMED_AT: "claimedAt";
+};
+/** Observed market prices, keyed by the taxonomy node they were seen under. */
+export declare const PRICE_OBSERVATION_FIELDS: {
+    readonly CATEGORY_ID: "categoryId";
+};
 export declare const OAUTH_STATE_VALUES: {
     readonly PENDING: "pending";
     readonly USED: "used";

package/dist/constants/field-names.js

@@ -1175,6 +1175,29 @@ export const COMMON_FIELDS = {
     ORDER: "order",
 };
 // ============================================================================
+// REFUND CLAIMS
+// ============================================================================
+/**
+ * The idempotency rows behind a refund.
+ *
+ * 🛑 `STATE` is the claim's own lifecycle ("claimed" → settled), NOT a
+ * postal state. `audit-route-nav-field-constants` matches a raw field
+ * string against every constant that happens to share its VALUE, so it
+ * suggested `ADDRESS_FIELDS.STATE` here — right string, wrong concept, and
+ * taking the suggestion would have made the query read as address filtering.
+ */
+export const REFUND_CLAIM_FIELDS = {
+    STATE: "state",
+    CLAIMED_AT: "claimedAt",
+};
+// ============================================================================
+// PRICE OBSERVATIONS
+// ============================================================================
+/** Observed market prices, keyed by the taxonomy node they were seen under. */
+export const PRICE_OBSERVATION_FIELDS = {
+    CATEGORY_ID: "categoryId",
+};
+// ============================================================================
 // OAUTH STATE VALUES
 // ============================================================================
 export const OAUTH_STATE_VALUES = {

package/dist/core/server-action.js

@@ -1,6 +1,6 @@
 import { normalizeError } from "../errors/normalize.js";
 import { toApiIssues } from "../errors/error-envelope.js";
-import { HTTP_ERROR_CODES } from "../errors/error-mapping.js";
+import { HTTP_ERROR_CODES, mapToHttpError } from "../errors/error-mapping.js";
 /**
  * createServerAction — @mohasinac/appkit/core
  *
@@ -97,11 +97,27 @@ export function createServerAction(options) {
         }
         catch (err) {
             void normalizeError(err);
-            const message = err instanceof Error ? err.message : "An unexpected error occurred";
+            /*
+             * 🛑 This never got the Rule #9 fix its sibling `wrapAction` did.
+             *
+             * It took `err.message` verbatim — unscrubbed for 5xx, so a thrown
+             * Node/bundler error's internals reached the client — and emitted NO
+             * `code`, so `toUserMessage(result.code)` downstream could only ever
+             * resolve to the generic sentence.
+             *
+             * It has no in-repo callers, but it is exported from the public barrel,
+             * so it is a trap for the next consumer rather than a live bug. Route it
+             * through the same mapper `wrapAction` uses: `mapToHttpError` scrubs 5xx
+             * messages in production and carries the real one in `internalMessage`
+             * for recorders only.
+             */
+            const mapped = mapToHttpError(err, {
+                isProduction: process.env.NODE_ENV === "production",
+            });
             logger.error(`[createServerAction] handler error in "${actionName}"`, {
                 err,
             });
-            result = { ok: false, error: message };
+            result = { ok: false, code: mapped.code, error: mapped.message };
         }
         // -- 4. After hooks (per-action → global) ------------------------------
         try {

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";

package/dist/errors/error-mapping.js

@@ -42,6 +42,31 @@ function isZodLikeError(err) {
         "issues" in err &&
         Array.isArray(err.issues));
 }
+/**
+ * The issues carried by a `ValidationError`, whichever of the two shapes the
+ * thrower used.
+ *
+ * 🛑 `new ValidationError(msg, parsed.error.issues)` silently lost everything.
+ * `ValidationError` forwards its second argument to `AppError.data`, and the
+ * old test was `isZodLikeError(err.data)` — which requires `"issues" in data`.
+ * An ARRAY has no `.issues` property (`"issues" in [] === false`), so passing
+ * `parsed.error.issues` (the obvious thing to pass, and what four routes do)
+ * produced a 400 with no field information at all. Only passing the whole
+ * `ZodError` worked.
+ *
+ * `media/finalize/route.ts` even carried a comment asserting the opposite —
+ * "carries `issues` through to the client, so the caller learns WHICH field it
+ * got wrong". It did not.
+ *
+ * Accept both, so the next caller cannot get it wrong either way.
+ */
+function issuesFromErrorData(data) {
+    if (Array.isArray(data))
+        return data.length > 0 ? data : undefined;
+    if (isZodLikeError(data))
+        return data.issues;
+    return undefined;
+}
 function isFirestoreLikeError(err) {
     if (typeof err !== "object" || err === null)
         return false;
@@ -110,7 +135,7 @@ function classifyError(err, opts) {
             status: 400,
             code: HTTP_ERROR_CODES.VALIDATION_FAILED,
             message: err.message,
-            issues: isZodLikeError(err.data) ? err.data.issues : undefined,
+            issues: issuesFromErrorData(err.data),
         };
     }
     if (err instanceof AuthenticationError) {

package/dist/errors/firestore-codes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Firestore / gRPC error-code predicates, in one place.
+ *
+ * ## Why this file exists
+ *
+ * `isAlreadyExists` had been written THREE times — in the gateway-events,
+ * payment-cases and protection-claims repositories, two of them byte-identical
+ * — and each copy duck-typed the caught error the same way:
+ *
+ *     const code = (err as { code?: unknown }).code;
+ *
+ * That is past the Rule of Three, and `audit-unknown-leakage` was reporting all
+ * six of those field reads: casting to `{ code?: unknown }` narrows the OBJECT
+ * and leaves the FIELD unknown, so every comparison below it is unchecked.
+ * Naming the shape once gives the comparisons a real type and leaves one
+ * implementation to fix when the SDK changes what it throws.
+ *
+ * ## 🛑 Why three checks and not one
+ *
+ * The Admin SDK has surfaced this condition as a numeric gRPC code, as a string
+ * code, and as a bare message, depending on version and transport. All three
+ * are tested, and the message test is in ADDITION to the codes rather than
+ * instead of them — a stringly-typed guard alone is what breaks silently on an
+ * SDK bump, and the failure mode is a create that reports success while having
+ * collided.
+ */
+/** gRPC status 6. The numeric form, which is what the Admin SDK usually sets. */
+export declare const GRPC_ALREADY_EXISTS = 6;
+/**
+ * Did Firestore refuse this write because the document already exists?
+ *
+ * The one question every `createWithId`-style insert needs answered, and the
+ * reason it matters is that "already there" is usually SUCCESS for an
+ * idempotent writer — a claim, a case or an inbox row that a retry re-sends.
+ * Treating it as a failure turns a safe retry into a 500.
+ */
+export declare function isAlreadyExistsError(err: unknown): boolean;