@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/store-extensions/schemas/google-config-form.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import type { StoreGoogleConfigDocument } from "./firestore";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const storeGoogleConfigUpdateSchema: z.ZodObject<{
+    isConnected: z.ZodOptional<z.ZodBoolean>;
+    placeId: z.ZodOptional<z.ZodString>;
+    businessName: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}>;
+export type StoreGoogleConfigFormValues = z.infer<typeof storeGoogleConfigUpdateSchema>;
+/**
+ * What the seller's own settings page may see.
+ *
+ * An ALLOW-list, built as a new object — never the document with keys deleted.
+ * A deny-list publishes every field nobody thought to remove, including ones
+ * the interface does not declare, which is exactly how a decrypted API token
+ * and an unmasked ad-credentials blob reached anonymous callers before
+ * (Recurrent Root Cause #70).
+ *
+ * PUBLIC (to the store owner):
+ *   storeId, isConnected — what the page renders
+ *   placeId, businessName — what the page lets them edit
+ *   averageRating, totalReviews, lastSyncedAt — sync output they need to see
+ *   id, createdAt, updatedAt — ordinary record metadata
+ *
+ * PRIVATE:
+ *   oauthRefreshToken — a long-lived Google credential with no reader and no
+ *     writer anywhere in either tree. It was being sent to the browser on every
+ *     load simply because the route returned the document whole.
+ */
+export declare function toSellerGoogleConfig(doc: StoreGoogleConfigDocument): {
+    id: string;
+    storeId: string;
+    isConnected: boolean;
+    placeId: string | undefined;
+    businessName: string | undefined;
+    averageRating: number | undefined;
+    totalReviews: number | undefined;
+    lastSyncedAt: Date | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+};
+export type SellerGoogleConfig = ReturnType<typeof toSellerGoogleConfig>;

package/dist/features/store-extensions/schemas/google-config-form.js

@@ -0,0 +1,105 @@
+/*
+ * WHY: `PUT /api/store/google-reviews` spread the raw request body into
+ *      Firestore on both the create and the update branch, with `storeId`
+ *      pinned and nothing else checked.
+ *
+ * ## 🛑 The field that makes this worth doing carefully
+ *
+ * `StoreGoogleConfigDocument` declares `oauthRefreshToken` — a long-lived
+ * Google credential. The raw spread meant a request body could set it, and the
+ * sibling `GET` returns the document WHOLE, so it was also being sent to the
+ * browser on every load of the seller's Google Reviews settings page.
+ *
+ * It is scoped to the caller's own store, so this is not a cross-tenant leak.
+ * It is still a secret in a page payload for no reason: a repo-wide grep finds
+ * **no reader and no writer** for that field anywhere — nothing sets it and
+ * nothing consumes it. Per the public-projection rule, a field nobody can name
+ * a reader for is private by default.
+ *
+ * So this schema deliberately does NOT declare it, and the route projects it
+ * out of the response. The field itself is left on the document rather than
+ * deleted — removing a schema field is a data-model change and deserves its
+ * own decision, not a drive-by inside a validation fix.
+ *
+ * ## `averageRating` / `totalReviews` / `lastSyncedAt` are absent too
+ *
+ * Those are SYNC OUTPUT — what Google last told us. A seller typing their own
+ * review count in is not configuration, it is fabricating the number the
+ * storefront displays.
+ *
+ * EXPORTS:
+ *   storeGoogleConfigUpdateSchema, toSellerGoogleConfig,
+ *   type StoreGoogleConfigFormValues, type SellerGoogleConfig
+ *
+ * @tag domain:store-extensions,google-reviews
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/store/google-reviews
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const storeGoogleConfigUpdateSchema = z
+    .object({
+    isConnected: annotate(z.boolean().optional(), {
+        section: "google",
+        sectionLabel: "Google Reviews",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "quarter",
+    }),
+    placeId: annotate(z.string().max(256).optional(), {
+        section: "google",
+        quick: true,
+        order: 2,
+        row: "pair",
+        help: "The Google Place ID for this store's listing.",
+    }),
+    businessName: annotate(z.string().max(200).optional(), {
+        section: "google",
+        quick: true,
+        order: 3,
+        row: "pair",
+    }),
+})
+    .strict();
+/**
+ * What the seller's own settings page may see.
+ *
+ * An ALLOW-list, built as a new object — never the document with keys deleted.
+ * A deny-list publishes every field nobody thought to remove, including ones
+ * the interface does not declare, which is exactly how a decrypted API token
+ * and an unmasked ad-credentials blob reached anonymous callers before
+ * (Recurrent Root Cause #70).
+ *
+ * PUBLIC (to the store owner):
+ *   storeId, isConnected — what the page renders
+ *   placeId, businessName — what the page lets them edit
+ *   averageRating, totalReviews, lastSyncedAt — sync output they need to see
+ *   id, createdAt, updatedAt — ordinary record metadata
+ *
+ * PRIVATE:
+ *   oauthRefreshToken — a long-lived Google credential with no reader and no
+ *     writer anywhere in either tree. It was being sent to the browser on every
+ *     load simply because the route returned the document whole.
+ */
+export function toSellerGoogleConfig(doc) {
+    return {
+        id: doc.id,
+        storeId: doc.storeId,
+        isConnected: doc.isConnected,
+        placeId: doc.placeId,
+        businessName: doc.businessName,
+        averageRating: doc.averageRating,
+        totalReviews: doc.totalReviews,
+        lastSyncedAt: doc.lastSyncedAt,
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt,
+    };
+}

package/dist/features/store-extensions/schemas/item-request-create-form.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const itemRequestCreateSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    brand: z.ZodOptional<z.ZodString>;
+    maxBudget: z.ZodOptional<z.ZodNumber>;
+    imageUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    description: string;
+    brand?: string | undefined;
+    category?: string | undefined;
+    imageUrls?: string[] | undefined;
+    maxBudget?: number | undefined;
+}, {
+    title: string;
+    description: string;
+    brand?: string | undefined;
+    category?: string | undefined;
+    imageUrls?: string[] | undefined;
+    maxBudget?: number | undefined;
+}>;
+export type ItemRequestCreateValues = z.infer<typeof itemRequestCreateSchema>;

package/dist/features/store-extensions/schemas/item-request-create-form.js

@@ -0,0 +1,80 @@
+/*
+ * WHY: `POST /api/item-requests` spread the raw body into Firestore, and this
+ *      one is READ BY THE PUBLIC — `GET /api/item-requests` is `auth: false`
+ *      and returns the open list to anyone.
+ *
+ *          const body = await parseJsonBody<FirestoreDocument>(request);
+ *          await itemRequestsRepository.create({ ...body, opUserId, ..., replies: [], replyCount: 0 });
+ *
+ *      So an unvalidated write here is an unvalidated PUBLISH. A request could
+ *      be created with no title and no description, and a caller could set
+ *      `approvedAt` / `approvedBy` — the fields that record a moderator having
+ *      cleared it.
+ *
+ *      `status`, `replies` and `replyCount` were pinned server-side, so the
+ *      approval GATE itself held; what a caller could forge was the RECORD of
+ *      approval, which is the part a human reads when deciding whether it has
+ *      already been looked at.
+ *
+ * WHAT: The create contract — title and description required, budget bounded,
+ *       and nothing a moderator owns.
+ *
+ * ## `maxBudget` is coerced and bounded
+ *
+ * It arrives from a number input as a string. Uncoerced it was written to
+ * Firestore as a string, and a later numeric comparison against it would sort
+ * lexically — the quiet half of the same class as the `resolvedAt` string that
+ * was being written into a Date field on the reports route.
+ *
+ * EXPORTS: itemRequestCreateSchema, type ItemRequestCreateValues
+ *
+ * @tag domain:store-extensions,item-requests
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/item-requests
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const itemRequestCreateSchema = z
+    .object({
+    title: annotate(z
+        .string()
+        .min(3, "Give the request a title of at least 3 characters.")
+        .max(200, "Keep the title under 200 characters."), {
+        section: "basics",
+        sectionLabel: "What are you looking for?",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "full",
+    }),
+    description: annotate(z
+        .string()
+        .min(10, "Describe what you're after in at least 10 characters.")
+        .max(5000, "Keep the description under 5000 characters."), { section: "basics", quick: true, order: 2, row: "full", kind: "textarea" }),
+    category: annotate(z.string().max(120).optional(), {
+        section: "basics",
+        order: 3,
+        row: "pair",
+    }),
+    brand: annotate(z.string().max(120).optional(), {
+        section: "basics",
+        order: 4,
+        row: "pair",
+    }),
+    // Coerced — see the header. Bounded so a typo cannot record a budget that
+    // reads as real money.
+    maxBudget: annotate(z.coerce
+        .number()
+        .min(0, "A budget cannot be negative.")
+        .max(10000000, "That budget looks like a typo.")
+        .optional(), { section: "basics", order: 5, row: "pair", kind: "number" }),
+    imageUrls: annotate(z.array(z.string().url("Each image must be a URL.")).max(10).optional(), { section: "media", sectionLabel: "Photos", order: 1, row: "full", kind: "media" }),
+})
+    .strict();

package/dist/features/store-extensions/schemas/listing-template-form.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const listingTemplateFormSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    listingType: z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "bundle", "classified", "digital-code", "live", "art", "stickers"]>;
+    defaults: z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>;
+    isShared: z.ZodBoolean;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    listingType: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle";
+    isActive: boolean;
+    isShared: boolean;
+    defaults: Record<string, import("../../..").FirestoreValue>;
+    description?: string | undefined;
+}, {
+    name: string;
+    listingType: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle";
+    isActive: boolean;
+    isShared: boolean;
+    defaults: Record<string, import("../../..").FirestoreValue>;
+    description?: string | undefined;
+}>;
+export type ListingTemplateFormValues = z.infer<typeof listingTemplateFormSchema>;
+/**
+ * Create contract. `storeId`/`ownerId` are deliberately absent: the route sets
+ * both from the session, so a caller cannot create a template inside someone
+ * else's store by adding a field to the body.
+ */
+export declare const listingTemplateCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    listingType: z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "bundle", "classified", "digital-code", "live", "art", "stickers"]>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    isShared: z.ZodOptional<z.ZodBoolean>;
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    listingType: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle";
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    isShared?: boolean | undefined;
+    defaults?: Record<string, import("../../..").FirestoreValue> | undefined;
+}, {
+    name: string;
+    listingType: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle";
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    isShared?: boolean | undefined;
+    defaults?: Record<string, import("../../..").FirestoreValue> | undefined;
+}>;
+/** Update contract — every field optional, and the same ownership fields absent. */
+export declare const listingTemplateUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "bundle", "classified", "digital-code", "live", "art", "stickers"]>>;
+    defaults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>>;
+    isShared: z.ZodOptional<z.ZodBoolean>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+    description?: string | undefined;
+    listingType?: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle" | undefined;
+    isActive?: boolean | undefined;
+    isShared?: boolean | undefined;
+    defaults?: Record<string, import("../../..").FirestoreValue> | undefined;
+}, {
+    name?: string | undefined;
+    description?: string | undefined;
+    listingType?: "art" | "stickers" | "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | "bundle" | undefined;
+    isActive?: boolean | undefined;
+    isShared?: boolean | undefined;
+    defaults?: Record<string, import("../../..").FirestoreValue> | undefined;
+}>;

package/dist/features/store-extensions/schemas/listing-template-form.js

@@ -0,0 +1,87 @@
+/*
+ * WHY: `/store/listing-templates/[id]/edit` was a wholly broken page. The route
+ *      it calls — `/api/store/listing-templates/[id]` — did not exist, while
+ *      `src/constants/api.ts` defined the endpoint, the edit page called it
+ *      three times (GET on load, PATCH on save, DELETE), and the list page
+ *      rendered an Edit button pointing straight at it. A seller clicking Edit
+ *      got a page that 404'd on load, on save and on delete.
+ *      Root Cause #37's dead-route shape, with a real page and a real button
+ *      in front of it.
+ * WHAT: One schema for the listing-template form AND the route that receives
+ *       it, so the two cannot drift.
+ *
+ * ## `defaults` stays open on purpose
+ *
+ * It is a JSON blob of per-listing-type field defaults — the whole point is
+ * that it holds whatever fields the target listing type has. `z.record()`
+ * rather than a named shape: modelling it would mean restating every listing
+ * type's field set here, and getting that wrong strips a seller's saved
+ * defaults on the next save (`z.object()` drops unknown keys). The page
+ * already `JSON.parse`s it and reports malformed JSON.
+ *
+ * EXPORTS:
+ *   listingTemplateFormSchema, listingTemplateCreateSchema,
+ *   listingTemplateUpdateSchema, type ListingTemplateFormValues
+ *
+ * @tag domain:store-extensions
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:store/listing-templates pages,/api/store/listing-templates
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { LISTING_TEMPLATE_TYPES } from "./firestore";
+import { firestoreValueSchema } from "../../../schemas/firestore-value";
+/**
+ * Derived from the runtime array, never restated. A hand-written copy here
+ * would be the eleventh independent enumeration of this union — and the tenth
+ * had already drifted, which is how `art`/`stickers` came to be unsaveable as
+ * templates while `bundle` lingered.
+ */
+const listingTemplateTypeSchema = z.enum(LISTING_TEMPLATE_TYPES);
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const listingTemplateFormSchema = z.object({
+    name: annotate(z.string().min(1, "Name is required").max(120, "Keep the name under 120 characters."), {
+        section: "basics", sectionLabel: "Template", sectionRequired: true,
+        quick: true, order: 1, row: "full",
+    }),
+    description: annotate(z.string().max(500, "Keep the description under 500 characters.").optional(), {
+        section: "basics", order: 2, row: "full",
+    }),
+    listingType: annotate(listingTemplateTypeSchema, {
+        section: "basics", quick: true, order: 3, row: "pair",
+    }),
+    // Typed as a Firestore value tree, not `unknown`: `unknown` does not satisfy
+    // `ListingTemplateDocument.defaults` (a `FirestoreDocument`), and casting at
+    // the repository call to paper over that would defeat the only type-level
+    // signal that the shapes agree.
+    defaults: annotate(z.record(firestoreValueSchema), {
+        section: "defaults", sectionLabel: "Default field values",
+        order: 1, row: "full", kind: "list",
+        help: "JSON applied to a new listing when this template is chosen.",
+    }),
+    isShared: annotate(z.boolean(), {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
+    }),
+    isActive: annotate(z.boolean(), {
+        section: "visibility", order: 2, row: "quarter",
+    }),
+});
+/**
+ * Create contract. `storeId`/`ownerId` are deliberately absent: the route sets
+ * both from the session, so a caller cannot create a template inside someone
+ * else's store by adding a field to the body.
+ */
+export const listingTemplateCreateSchema = listingTemplateFormSchema.partial({
+    description: true,
+    isShared: true,
+    isActive: true,
+    defaults: true,
+});
+/** Update contract — every field optional, and the same ownership fields absent. */
+export const listingTemplateUpdateSchema = listingTemplateFormSchema.partial();

package/dist/features/store-extensions/schemas/moderation-review-form.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+/**
+ * The statuses a human review can produce.
+ *
+ * `satisfies readonly ModerationStatus[]` is load-bearing: it is what stops
+ * this becoming an independent, drifting copy of the union.
+ */
+export declare const MODERATION_REVIEWER_STATUSES: readonly ["approved", "rejected"];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const moderationReviewFormSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["approved", "rejected"]>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}>, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}>;
+export type ModerationReviewFormValues = z.infer<typeof moderationReviewFormSchema>;
+/**
+ * Route contract. Identical to the form contract — a review is a single
+ * atomic decision, so there is no partial variant.
+ */
+export declare const moderationReviewUpdateSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["approved", "rejected"]>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}>, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}, {
+    status: "approved" | "rejected";
+    reason?: string | undefined;
+}>;

package/dist/features/store-extensions/schemas/moderation-review-form.js

@@ -0,0 +1,101 @@
+/*
+ * WHY: `PATCH /api/admin/moderation/[id]` spread the raw request body straight
+ *      into Firestore:
+ *
+ *          const body = await parseJsonBody<Record<string, JsonValue>>(request);
+ *          await moderationQueueRepository.update(id, { ...body, reviewerId, reviewedAt });
+ *
+ *      There was no Zod anywhere on this path — not on the route, not on
+ *      either of the two client surfaces that call it. Under `ROLES_ADMIN_MOD`
+ *      a caller could write ANY key onto a moderation record, including
+ *      `entityId`, `ownerId`, `submittedAt` or an invented one, and could set
+ *      `status` to any string at all — the real `ModerationStatus` union was
+ *      never consulted.
+ *
+ *      Two client surfaces call it and neither validated: the queue page's
+ *      inline Approve/Reject controls and `ModerationDetailActions`. Both let
+ *      a rejection be submitted with an EMPTY reason, so content could be
+ *      blocked with no record of why.
+ * WHAT: One schema shared by the route and both client surfaces.
+ *
+ * ## A reviewer may only set the two statuses a REVIEW produces
+ *
+ * `ModerationStatus` has four values, but `pending` is the initial state and
+ * `auto-approved` is what the system writes when nothing needed a human. A
+ * reviewer setting either by hand would be falsifying the record — so the
+ * settable set is the subset below, declared `satisfies readonly
+ * ModerationStatus[]` rather than restated, which makes a value outside the
+ * real union a COMPILE error instead of a filter that matches nothing
+ * (Recurrent Root Cause #33).
+ *
+ * ## `reviewerId` / `reviewedAt` are absent on purpose
+ *
+ * The route sets both from the session and the server clock. Accepting them
+ * here would let a caller attribute a review to somebody else, or backdate it.
+ *
+ * EXPORTS:
+ *   moderationReviewFormSchema, moderationReviewUpdateSchema,
+ *   MODERATION_REVIEWER_STATUSES, type ModerationReviewFormValues
+ *
+ * @tag domain:store-extensions,moderation
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:admin/moderation pages,/api/admin/moderation/[id]
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/**
+ * The statuses a human review can produce.
+ *
+ * `satisfies readonly ModerationStatus[]` is load-bearing: it is what stops
+ * this becoming an independent, drifting copy of the union.
+ */
+export const MODERATION_REVIEWER_STATUSES = [
+    "approved",
+    "rejected",
+];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const moderationReviewFormSchema = z
+    .object({
+    status: annotate(z.enum(MODERATION_REVIEWER_STATUSES), {
+        section: "review",
+        sectionLabel: "Review decision",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "pair",
+    }),
+    reason: annotate(z.string().max(500, "Keep the reason under 500 characters.").optional(), {
+        section: "review",
+        order: 2,
+        row: "full",
+        kind: "textarea",
+        help: "Required when rejecting — this is the record of why the media was blocked.",
+    }),
+})
+    // Unknown keys are a 400, not a silent drop. A plain `z.object()` would
+    // STRIP them, which is the quieter half of the same bug: the caller is told
+    // the write succeeded and the key it sent simply vanished.
+    .strict()
+    .superRefine((v, ctx) => {
+    // An approval needs no justification; a rejection does. Blocking someone's
+    // media with an empty `reason` leaves the owner, and the next reviewer,
+    // with no way to know what was wrong with it.
+    if (v.status === "rejected" && !v.reason?.trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["reason"],
+            message: "Give a reason for the rejection.",
+        });
+    }
+});
+/**
+ * Route contract. Identical to the form contract — a review is a single
+ * atomic decision, so there is no partial variant.
+ */
+export const moderationReviewUpdateSchema = moderationReviewFormSchema;