@mohasinac/appkit 4.14.0 → 4.15.0

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/** The statuses a human review can produce. `pending` is the initial state. */
+export declare const REPORT_REVIEWER_STATUSES: readonly ["under-review", "actioned", "dismissed"];
+/**
+ * The two that CLOSE a report — the server stamps `resolvedAt` for these and
+ * for no others. Exported so the route and any future consumer share one
+ * answer to "is this report finished", rather than each spelling out the pair.
+ */
+export declare const REPORT_TERMINAL_STATUSES: readonly ["actioned", "dismissed"];
+/**
+ * 🛑 `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 reportReviewFormSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["under-review", "actioned", "dismissed"]>;
+    resolution: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}>, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}>;
+export type ReportReviewFormValues = z.infer<typeof reportReviewFormSchema>;
+/** Route contract — identical; a review is one atomic decision. */
+export declare const reportReviewUpdateSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["under-review", "actioned", "dismissed"]>;
+    resolution: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}>, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}, {
+    status: "dismissed" | "under-review" | "actioned";
+    resolution?: string | undefined;
+}>;

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

@@ -0,0 +1,111 @@
+/*
+ * WHY: `PATCH /api/admin/reports/[id]` spread the raw request body straight
+ *      into Firestore, exactly as the moderation route did:
+ *
+ *          const body = await parseJsonBody<Record<string, JsonValue>>(request);
+ *          await reportsRepository.update(id, { ...body, assignedTo: user.uid });
+ *
+ *      No Zod on the route, none on either client surface. `status` was never
+ *      checked against the real `ReportStatus` union, and any key at all could
+ *      be written onto a report — `reporterId`, `entityId`, `evidenceUrls`,
+ *      or something invented.
+ *
+ * ## 🛑 And it was actively corrupting `resolvedAt`
+ *
+ *      BOTH client surfaces — the list page's inline controls and
+ *      `ReportDetailActions` — sent:
+ *
+ *          resolvedAt: status === "actioned" || status === "dismissed"
+ *            ? new Date() : undefined
+ *
+ *      `new Date()` does not survive `JSON.stringify`. It arrives at the route
+ *      as an ISO **string**, and the raw spread wrote that string into a field
+ *      `ReportDocument` declares as `Date`. Seeded reports hold real
+ *      Timestamps, so the collection carries BOTH shapes for one field —
+ *      the sort of split that later reads as "the date filter is broken" long
+ *      after the cause is out of sight (Recurrent Root Cause #47).
+ *
+ *      Nothing renders `resolvedAt` today, which is the only reason it was
+ *      never noticed. It is a latent corruption, not a cosmetic one.
+ *
+ * WHAT: One schema shared by the route and both client surfaces — and
+ *       `resolvedAt` is REMOVED from the client contract entirely. The server
+ *       stamps it, the same way the moderation route already stamps
+ *       `reviewedAt`. A timestamp the client cannot send is a timestamp the
+ *       client cannot send in the wrong type.
+ *
+ * ## A reviewer may only set the three statuses a REVIEW produces
+ *
+ * `ReportStatus` has four values; `pending` is the state a report is born in.
+ * The settable subset is declared `satisfies readonly ReportStatus[]` rather
+ * than restated, so a value outside the real union is a COMPILE error instead
+ * of a filter that silently matches nothing (Recurrent Root Cause #33).
+ *
+ * EXPORTS:
+ *   reportReviewFormSchema, reportReviewUpdateSchema,
+ *   REPORT_REVIEWER_STATUSES, REPORT_TERMINAL_STATUSES,
+ *   type ReportReviewFormValues
+ *
+ * @tag domain:store-extensions,reports
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:admin/reports pages,/api/admin/reports/[id]
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/** The statuses a human review can produce. `pending` is the initial state. */
+export const REPORT_REVIEWER_STATUSES = [
+    "under-review",
+    "actioned",
+    "dismissed",
+];
+/**
+ * The two that CLOSE a report — the server stamps `resolvedAt` for these and
+ * for no others. Exported so the route and any future consumer share one
+ * answer to "is this report finished", rather than each spelling out the pair.
+ */
+export const REPORT_TERMINAL_STATUSES = [
+    "actioned",
+    "dismissed",
+];
+/**
+ * 🛑 `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 reportReviewFormSchema = z
+    .object({
+    status: annotate(z.enum(REPORT_REVIEWER_STATUSES), {
+        section: "review",
+        sectionLabel: "Report decision",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "pair",
+    }),
+    resolution: annotate(z.string().max(1000, "Keep the resolution under 1000 characters.").optional(), {
+        section: "review",
+        order: 2,
+        row: "full",
+        kind: "textarea",
+        help: "Required when actioning or dismissing — the reporter may see a summary.",
+    }),
+    // `resolvedAt` is deliberately NOT a field. See the header.
+})
+    .strict()
+    .superRefine((v, ctx) => {
+    // Taking a report for review needs no note; closing one does. "Actioned"
+    // with an empty resolution tells the reporter, and the next admin, nothing
+    // about what was actually done.
+    if (REPORT_TERMINAL_STATUSES.includes(v.status) &&
+        !v.resolution?.trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["resolution"],
+            message: "Say what was done about this report before closing it.",
+        });
+    }
+});
+/** Route contract — identical; a review is one atomic decision. */
+export const reportReviewUpdateSchema = reportReviewFormSchema;

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

@@ -0,0 +1,148 @@
+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 shippingConfigFormSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    method: z.ZodEnum<["free", "flat", "weight", "express", "pickup", "custom"]>;
+    flatRate: z.ZodOptional<z.ZodNumber>;
+    pricePerKg: z.ZodOptional<z.ZodNumber>;
+    freeAbove: z.ZodOptional<z.ZodNumber>;
+    expressSurcharge: z.ZodOptional<z.ZodNumber>;
+    estimatedDays: z.ZodOptional<z.ZodNumber>;
+    isDefault: z.ZodBoolean;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}>, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}>;
+export type ShippingConfigFormValues = z.infer<typeof shippingConfigFormSchema>;
+/** `storeId` is absent — the route sets it from the session, never the body. */
+export declare const shippingConfigCreateSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    method: z.ZodEnum<["free", "flat", "weight", "express", "pickup", "custom"]>;
+    flatRate: z.ZodOptional<z.ZodNumber>;
+    pricePerKg: z.ZodOptional<z.ZodNumber>;
+    freeAbove: z.ZodOptional<z.ZodNumber>;
+    expressSurcharge: z.ZodOptional<z.ZodNumber>;
+    estimatedDays: z.ZodOptional<z.ZodNumber>;
+    isDefault: z.ZodBoolean;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}>, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}, {
+    label: string;
+    isDefault: boolean;
+    isActive: boolean;
+    method: "flat" | "weight" | "custom" | "free" | "express" | "pickup";
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+}>;
+/**
+ * Update contract — partial, and `.strict()` so an unknown key is a 400 rather
+ * than a silent write. The per-method completeness rules do not apply: a PATCH
+ * may legitimately carry only `isActive`.
+ */
+export declare const shippingConfigUpdateSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodEnum<["free", "flat", "weight", "express", "pickup", "custom"]>>;
+    flatRate: z.ZodOptional<z.ZodNumber>;
+    pricePerKg: z.ZodOptional<z.ZodNumber>;
+    freeAbove: z.ZodOptional<z.ZodNumber>;
+    expressSurcharge: z.ZodOptional<z.ZodNumber>;
+    estimatedDays: z.ZodOptional<z.ZodNumber>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    isActive?: boolean | undefined;
+    method?: "flat" | "weight" | "custom" | "free" | "express" | "pickup" | undefined;
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+    zones?: string[] | undefined;
+}, {
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    isActive?: boolean | undefined;
+    method?: "flat" | "weight" | "custom" | "free" | "express" | "pickup" | undefined;
+    estimatedDays?: number | undefined;
+    freeAbove?: number | undefined;
+    flatRate?: number | undefined;
+    pricePerKg?: number | undefined;
+    expressSurcharge?: number | undefined;
+    zones?: string[] | undefined;
+}>;

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

@@ -0,0 +1,104 @@
+/*
+ * WHY: `POST /api/store/shipping-configs` spread the raw request body into
+ *      `.create()` and the PATCH handed it straight to `.update()` — no Zod on
+ *      either, and neither page validated anything. A shipping rule is money:
+ *      a `flatRate` of `"abc"`, a negative `freeAbove`, or an invented key are
+ *      all things that were persisted verbatim.
+ * WHAT: One schema for the pages AND the routes.
+ *
+ * ## The numeric fields are `.coerce` on purpose
+ *
+ * The pages hold them as strings from `<input type="number">`. Coercing here
+ * rather than at each call site means every consumer gets a real number and
+ * no page has to remember a `Number()` cast — the kind of per-callsite
+ * conversion that produces a `NaN` in Firestore the first time someone forgets.
+ *
+ * EXPORTS:
+ *   shippingConfigFormSchema, shippingConfigCreateSchema,
+ *   shippingConfigUpdateSchema, type ShippingConfigFormValues
+ *
+ * @tag domain:store-extensions
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:store/shipping-configs pages,/api/store/shipping-configs
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/** Mirrors `ShippingMethod` in ./firestore. */
+const shippingMethodSchema = z.enum(["free", "flat", "weight", "express", "pickup", "custom"]);
+/** A non-negative money/threshold amount, coerced from the form's string. */
+const amount = (label) => z.coerce.number({ invalid_type_error: `${label} must be a number.` }).min(0, `${label} cannot be negative.`);
+/**
+ * 🛑 `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 shippingConfigFormSchema = z
+    .object({
+    label: annotate(z.string().min(1, "Give this rule a name.").max(80), {
+        section: "basics", sectionLabel: "Shipping Rule", sectionRequired: true,
+        quick: true, order: 1, row: "pair",
+    }),
+    method: annotate(shippingMethodSchema, {
+        section: "basics", quick: true, order: 2, row: "pair",
+    }),
+    flatRate: annotate(amount("Flat rate").optional(), {
+        section: "rates", sectionLabel: "Rates", order: 1, row: "pair",
+    }),
+    pricePerKg: annotate(amount("Price per kg").optional(), {
+        section: "rates", order: 2, row: "pair",
+    }),
+    freeAbove: annotate(amount("Free above").optional(), {
+        section: "rates", order: 3, row: "pair",
+    }),
+    expressSurcharge: annotate(amount("Express surcharge").optional(), {
+        section: "rates", order: 4, row: "pair",
+    }),
+    estimatedDays: annotate(z.coerce.number().int("Estimated days must be a whole number.").min(0).max(365).optional(), { section: "rates", order: 5, row: "pair" }),
+    isDefault: annotate(z.boolean(), {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
+    }),
+    isActive: annotate(z.boolean(), {
+        section: "visibility", order: 2, row: "quarter",
+    }),
+})
+    .superRefine((v, ctx) => {
+    // A rate rule with no rate is not a rule. Checked per method, because the
+    // required field differs and a blanket `.min(1)` would make every rate
+    // mandatory for a free/pickup rule that has none.
+    const need = (path, label) => {
+        if (v[path] == null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [path],
+                message: `A "${label}" rule needs a ${path === "flatRate" ? "flat rate" : "price per kg"}.`,
+            });
+        }
+    };
+    if (v.method === "flat")
+        need("flatRate", "flat");
+    if (v.method === "weight")
+        need("pricePerKg", "weight");
+});
+/** `storeId` is absent — the route sets it from the session, never the body. */
+export const shippingConfigCreateSchema = shippingConfigFormSchema;
+/**
+ * Update contract — partial, and `.strict()` so an unknown key is a 400 rather
+ * than a silent write. The per-method completeness rules do not apply: a PATCH
+ * may legitimately carry only `isActive`.
+ */
+export const shippingConfigUpdateSchema = z
+    .object({
+    label: z.string().min(1).max(80).optional(),
+    method: shippingMethodSchema.optional(),
+    flatRate: amount("Flat rate").optional(),
+    pricePerKg: amount("Price per kg").optional(),
+    freeAbove: amount("Free above").optional(),
+    expressSurcharge: amount("Express surcharge").optional(),
+    estimatedDays: z.coerce.number().int().min(0).max(365).optional(),
+    zones: z.array(z.string()).optional(),
+    isDefault: z.boolean().optional(),
+    isActive: z.boolean().optional(),
+})
+    .strict();

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

@@ -0,0 +1,54 @@
+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, so annotating
+ * before `.optional()` silently loses the metadata.
+ */
+export declare const storeCategoryFormSchema: z.ZodObject<{
+    label: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    coverImageUrl: z.ZodOptional<z.ZodString>;
+    displayOrder: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    displayOrder: number;
+    description?: string | undefined;
+    slug?: string | undefined;
+    coverImageUrl?: string | undefined;
+}, {
+    label: string;
+    displayOrder: number;
+    description?: string | undefined;
+    slug?: string | undefined;
+    coverImageUrl?: string | undefined;
+}>;
+export type StoreCategoryFormValues = z.infer<typeof storeCategoryFormSchema>;
+/**
+ * The server's create contract.
+ *
+ * Identical fields, but `slug` is REQUIRED here: the client derives it from
+ * the label when blank, and a category with no slug has no URL. Keeping the
+ * derivation on the client and the requirement on the server means the route
+ * never has to guess what the user meant.
+ */
+export declare const storeCategoryCreateSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    coverImageUrl: z.ZodOptional<z.ZodString>;
+    displayOrder: z.ZodNumber;
+} & {
+    slug: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    slug: string;
+    displayOrder: number;
+    description?: string | undefined;
+    coverImageUrl?: string | undefined;
+}, {
+    label: string;
+    slug: string;
+    displayOrder: number;
+    description?: string | undefined;
+    coverImageUrl?: string | undefined;
+}>;

package/dist/features/store-extensions/schemas/store-category-form.js

@@ -0,0 +1,73 @@
+/*
+ * WHY: `/store/categories/new` collected five fields through raw <Input>s with
+ *      no <Form>, no schema and no check of any kind, and `POST
+ *      /api/store/categories` spread the raw request body straight into
+ *      `storeCategoriesRepository.create()`. Neither side validated anything,
+ *      so an entirely empty storefront category could be created — and any
+ *      extra key a caller sent was written verbatim into Firestore.
+ * WHAT: One schema for both sides. The client parses it to show inline errors
+ *       before submitting; the route parses it to decide what is allowed to
+ *       reach the database.
+ *
+ * ## Why one schema and not two
+ *
+ * A client copy and a server copy of the same rules is how they come to
+ * disagree — and when they do, the client's is the one users see while the
+ * server's is the one that decides. The route strips unknown keys BECAUSE it
+ * parses this: `storeId` is set from the session, never from the body, so a
+ * caller cannot write a category into someone else's store by adding a field.
+ *
+ * `productIds` and `isActive` are deliberately absent: they are managed after
+ * creation (assigning products, toggling visibility), not typed into the
+ * create form, and the repository supplies their defaults.
+ *
+ * EXPORTS:
+ *   storeCategoryFormSchema, storeCategoryCreateSchema,
+ *   type StoreCategoryFormValues
+ *
+ * @tag domain:store-extensions
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:store/categories/new,POST /api/store/categories
+ * @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, so annotating
+ * before `.optional()` silently loses the metadata.
+ */
+export const storeCategoryFormSchema = z.object({
+    label: annotate(z.string().min(1, "Label is required").max(80, "Keep the label under 80 characters."), {
+        section: "basics", sectionLabel: "Category", sectionRequired: true,
+        quick: true, order: 1, row: "full",
+    }),
+    slug: annotate(z.string().max(80, "Keep the slug under 80 characters.").optional(), {
+        section: "basics", order: 2, row: "full",
+        // T1 calculated: derived from the label when left blank, then frozen —
+        // the same create-only rule every other slug in this codebase follows,
+        // because renaming one breaks inbound links.
+        tier: "t1-derive",
+        help: "Left blank, this is generated from the label.",
+    }),
+    description: annotate(z.string().max(500, "Keep the description under 500 characters.").optional(), {
+        section: "basics", order: 3, row: "full",
+    }),
+    coverImageUrl: annotate(z.string().optional(), {
+        section: "media", sectionLabel: "Media", order: 1, row: "full", kind: "media",
+    }),
+    displayOrder: annotate(z.coerce.number().int("Display order must be a whole number.").min(0, "Display order cannot be negative."), { section: "visibility", sectionLabel: "Visibility", order: 1, row: "pair" }),
+});
+/**
+ * The server's create contract.
+ *
+ * Identical fields, but `slug` is REQUIRED here: the client derives it from
+ * the label when blank, and a category with no slug has no URL. Keeping the
+ * derivation on the client and the requirement on the server means the route
+ * never has to guess what the user meant.
+ */
+export const storeCategoryCreateSchema = storeCategoryFormSchema.extend({
+    slug: z.string().min(1, "Slug is required").max(80),
+});