@mohasinac/appkit 4.14.0 → 4.16.0

package/dist/features/store-extensions/components/ReviewDecisionModal.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Four surfaces asked a moderator to justify a decision, and not one of
+ *      them checked that they had. `admin/moderation/page.tsx` and
+ *      `ModerationDetailActions` each rendered their own reject-reason modal;
+ *      `admin/reports/page.tsx` and `ReportDetailActions` each rendered their
+ *      own resolution-note modal. All four submitted an empty string happily,
+ *      so media could be blocked and a report closed with no record of why.
+ *
+ * WHAT: One modal for both decisions.
+ *
+ * ## Why one component and not two
+ *
+ * The two are the same observable thing — *a decision plus a note that is
+ * required before it can be made* — differing only in vocabulary. Per the
+ * Duplication Decision Framework this is a consolidate, on two counts: the
+ * copies have the same prop surface, and a single validation fix would
+ * otherwise have needed four commits. The differences are all DATA (labels,
+ * which field carries the note, which schema validates it), not branching, so
+ * there are no conditional props to trade away.
+ *
+ * ## The note field is named by the caller
+ *
+ * Moderation calls it `reason`, reports call it `resolution`. Naming it
+ * generically here would mean translating on the way out, and a schema issue
+ * on `resolution` would then have no field to land on — the error would fall
+ * back to a banner, which is the thing this replaces.
+ *
+ * EXPORTS: ReviewDecisionModal, type ReviewDecisionModalProps
+ *
+ * @tag domain:store-extensions,moderation,reports
+ * @tag layer:component
+ * @tag pattern:form
+ * @tag access:client
+ * @tag consumers:admin/moderation,admin/reports
+ * @tag sideEffects:none
+ */
+import { useState } from "react";
+import { Modal } from "../../../ui/components/Modal";
+import { Button } from "../../../ui/components/Button";
+import { Row } from "../../../ui/components/Layout";
+import { Stack } from "../../../ui/components/Layout";
+import { Form } from "../../../ui/components/Form";
+import { FieldTextarea } from "../../../ui/forms/FieldTextarea";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
+import { applyZodIssues } from "../../../ui/forms/FormShell";
+import { useToast } from "../../../ui/components/Toast";
+import { normalizeError } from "../../../errors/normalize";
+export function ReviewDecisionModal({ isOpen, onClose, title, schema, status, noteField, noteLabel, noteHelp, notePlaceholder, confirmLabel, confirmVariant = "primary", onConfirm, }) {
+    const { showToast } = useToast();
+    const [note, setNote] = useState("");
+    const [submitting, setSubmitting] = useState(false);
+    const close = () => {
+        setNote("");
+        onClose();
+    };
+    return (_jsx(Modal, { isOpen: isOpen, onClose: close, title: title, size: "sm", children: _jsx(Form, { schema: schema, onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FormErrorSummary, {}), _jsx(FieldTextarea, { name: noteField, label: noteLabel, hint: noteHelp, rows: 4, required: true, value: note, onChange: setNote, placeholder: notePlaceholder }), _jsxs(Row, { justify: "end", gap: "sm", children: [_jsx(Button, { variant: "ghost", type: "button", onClick: close, disabled: submitting, children: "Cancel" }), _jsx(Button, { variant: confirmVariant, type: "submit", disabled: submitting, isLoading: submitting, onClick: async () => {
+                                    clearErrors();
+                                    const payload = { status, [noteField]: note };
+                                    const parsed = schema.safeParse(payload);
+                                    if (!parsed.success) {
+                                        applyZodIssues(parsed.error.issues, setFieldError);
+                                        return;
+                                    }
+                                    setSubmitting(true);
+                                    try {
+                                        await onConfirm(parsed.data);
+                                        close();
+                                    }
+                                    catch (err) {
+                                        // Deliberately stays OPEN on failure. Closing would discard
+                                        // the note the reviewer just typed, and a decision that did
+                                        // not save must not look like one that did.
+                                        void normalizeError(err);
+                                        showToast("Couldn't save that decision. Try again.", "error");
+                                    }
+                                    finally {
+                                        setSubmitting(false);
+                                    }
+                                }, children: confirmLabel })] })] })) }) }));
+}

package/dist/features/store-extensions/index.d.ts

@@ -1,4 +1,16 @@
 export * from "./schemas/firestore";
+export * from "./schemas/store-category-form";
+export * from "./schemas/listing-template-form";
+export * from "./schemas/payout-method-form";
+export * from "./schemas/shipping-config-form";
+export * from "./schemas/custom-role-form";
+export * from "./schemas/moderation-review-form";
+export * from "./schemas/report-review-form";
+export * from "./schemas/report-create-form";
+export * from "./schemas/item-request-create-form";
+export * from "./schemas/analytics-forms";
+export * from "./schemas/google-config-form";
+export * from "./schemas/admin-notification-form";
 export * from "./schemas/rbac";
 export * from "./repository/store-extensions.repositories";
 export * from "./repository/rbac.repositories";

package/dist/features/store-extensions/index.js

@@ -1,4 +1,16 @@
 export * from "./schemas/firestore";
+export * from "./schemas/store-category-form";
+export * from "./schemas/listing-template-form";
+export * from "./schemas/payout-method-form";
+export * from "./schemas/shipping-config-form";
+export * from "./schemas/custom-role-form";
+export * from "./schemas/moderation-review-form";
+export * from "./schemas/report-review-form";
+export * from "./schemas/report-create-form";
+export * from "./schemas/item-request-create-form";
+export * from "./schemas/analytics-forms";
+export * from "./schemas/google-config-form";
+export * from "./schemas/admin-notification-form";
 export * from "./schemas/rbac";
 export * from "./repository/store-extensions.repositories";
 export * from "./repository/rbac.repositories";

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

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { AdminNotificationCategory, AdminNotificationDocument } from "./rbac";
+export declare const ADMIN_NOTIFICATION_CATEGORIES: [AdminNotificationCategory, ...AdminNotificationCategory[]];
+type Severity = AdminNotificationDocument["severity"];
+export declare const ADMIN_NOTIFICATION_SEVERITIES: [Severity, ...Severity[]];
+/**
+ * 🛑 `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 adminNotificationCreateSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+    category: z.ZodEnum<[AdminNotificationCategory, ...AdminNotificationCategory[]]>;
+    severity: z.ZodEnum<["warning" | "error" | "info", ...("warning" | "error" | "info")[]]>;
+    audienceUserIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    entityType: z.ZodOptional<z.ZodString>;
+    entityId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    body: string;
+    category: AdminNotificationCategory;
+    severity: "warning" | "error" | "info";
+    entityId?: string | undefined;
+    entityType?: string | undefined;
+    audienceUserIds?: string[] | undefined;
+}, {
+    title: string;
+    body: string;
+    category: AdminNotificationCategory;
+    severity: "warning" | "error" | "info";
+    entityId?: string | undefined;
+    entityType?: string | undefined;
+    audienceUserIds?: string[] | undefined;
+}>;
+export type AdminNotificationCreateValues = z.infer<typeof adminNotificationCreateSchema>;
+export {};

package/dist/features/store-extensions/schemas/admin-notification-form.js

@@ -0,0 +1,114 @@
+/*
+ * WHY: `POST /api/admin/admin-notifications` spread the raw request body into
+ *      Firestore with only `isRead: false` pinned. The last unvalidated write
+ *      path in `src/app/api`.
+ *
+ *      `category` and `severity` are both closed unions that the admin
+ *      notification bell filters and colours by, and neither was checked — so
+ *      a notification could be stored with a category no filter chip matches
+ *      and a severity no badge renders, which is the shape that produces a row
+ *      visible in the raw collection and invisible in the UI (Recurrent Root
+ *      Cause #33).
+ *
+ *      `audienceUserIds` decides WHO SEES IT. Unvalidated and unbounded, it
+ *      could arrive as a string rather than an array — silently narrowing or
+ *      widening the audience of an admin notification.
+ *
+ * WHAT: The create contract.
+ *
+ * ## `isRead` / `readAt` are absent on purpose
+ *
+ * Both are per-admin read state, owned by the read/dismiss path. A creator
+ * marking its own notification as already read would file it straight into the
+ * history nobody looks at.
+ *
+ * EXPORTS:
+ *   adminNotificationCreateSchema, ADMIN_NOTIFICATION_CATEGORIES,
+ *   ADMIN_NOTIFICATION_SEVERITIES, type AdminNotificationCreateValues
+ *
+ * @tag domain:store-extensions,admin-notifications
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/admin/admin-notifications
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/*
+ * Keyed `Record<Union, true>` so BOTH mistakes are compile errors — a member
+ * added to the union and forgotten here, and a value here that is not real.
+ */
+const CATEGORY_MAP = {
+    system: true,
+    security: true,
+    moderation: true,
+    payouts: true,
+    fraud: true,
+    growth: true,
+};
+export const ADMIN_NOTIFICATION_CATEGORIES = Object.keys(CATEGORY_MAP);
+const SEVERITY_MAP = {
+    info: true,
+    warning: true,
+    error: true,
+};
+export const ADMIN_NOTIFICATION_SEVERITIES = Object.keys(SEVERITY_MAP);
+/**
+ * 🛑 `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 adminNotificationCreateSchema = z
+    .object({
+    title: annotate(z.string().min(1, "Give the notification a title.").max(200), {
+        section: "message",
+        sectionLabel: "Message",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "full",
+    }),
+    body: annotate(z.string().min(1, "Say what happened.").max(2000), {
+        section: "message",
+        quick: true,
+        order: 2,
+        row: "full",
+        kind: "textarea",
+    }),
+    category: annotate(z.enum(ADMIN_NOTIFICATION_CATEGORIES), {
+        section: "routing",
+        sectionLabel: "Routing",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "pair",
+    }),
+    severity: annotate(z.enum(ADMIN_NOTIFICATION_SEVERITIES), {
+        section: "routing",
+        quick: true,
+        order: 2,
+        row: "pair",
+    }),
+    // Empty (or omitted) means every admin — that is the documented meaning of
+    // the field, so an empty array must stay expressible and is NOT `.min(1)`.
+    // Capped because this is the audience of a broadcast.
+    audienceUserIds: annotate(z.array(z.string().min(1)).max(200).optional(), {
+        section: "routing",
+        order: 3,
+        row: "full",
+        kind: "list",
+        help: "Leave empty to notify every admin.",
+    }),
+    entityType: annotate(z.string().max(80).optional(), {
+        section: "link",
+        sectionLabel: "Linked record",
+        order: 1,
+        row: "pair",
+    }),
+    entityId: annotate(z.string().max(200).optional(), {
+        section: "link",
+        order: 2,
+        row: "pair",
+    }),
+})
+    .strict();

package/dist/features/store-extensions/schemas/analytics-forms.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import type { AlertOperator, AnalyticsCardType } from "./firestore";
+export declare const ANALYTICS_ALERT_OPERATORS: [AlertOperator, ...AlertOperator[]];
+export declare const ANALYTICS_CARD_TYPES: [AnalyticsCardType, ...AnalyticsCardType[]];
+/**
+ * 🛑 `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 analyticsAlertCreateSchema: z.ZodObject<{
+    label: z.ZodString;
+    metric: z.ZodString;
+    operator: z.ZodEnum<[AlertOperator, ...AlertOperator[]]>;
+    threshold: z.ZodNumber;
+    windowHours: z.ZodNumber;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    notifyChannels: z.ZodOptional<z.ZodArray<z.ZodEnum<["in-app", "email", "whatsapp"]>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    label: string;
+    operator: AlertOperator;
+    threshold: number;
+    metric: string;
+    windowHours: number;
+    isActive?: boolean | undefined;
+    notifyChannels?: ("email" | "whatsapp" | "in-app")[] | undefined;
+}, {
+    label: string;
+    operator: AlertOperator;
+    threshold: number;
+    metric: string;
+    windowHours: number;
+    isActive?: boolean | undefined;
+    notifyChannels?: ("email" | "whatsapp" | "in-app")[] | undefined;
+}>;
+export type AnalyticsAlertCreateValues = z.infer<typeof analyticsAlertCreateSchema>;
+export declare const analyticsCardCreateSchema: z.ZodObject<{
+    title: z.ZodString;
+    type: z.ZodEnum<[AnalyticsCardType, ...AnalyticsCardType[]]>;
+    metric: z.ZodString;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("../../..").FirestoreValue, z.ZodTypeDef, import("../../..").FirestoreValue>>>;
+    position: z.ZodOptional<z.ZodNumber>;
+    isVisible: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    type: AnalyticsCardType;
+    title: string;
+    metric: string;
+    position?: number | undefined;
+    filters?: Record<string, import("../../..").FirestoreValue> | undefined;
+    isVisible?: boolean | undefined;
+}, {
+    type: AnalyticsCardType;
+    title: string;
+    metric: string;
+    position?: number | undefined;
+    filters?: Record<string, import("../../..").FirestoreValue> | undefined;
+    isVisible?: boolean | undefined;
+}>;
+export type AnalyticsCardCreateValues = z.infer<typeof analyticsCardCreateSchema>;

package/dist/features/store-extensions/schemas/analytics-forms.js

@@ -0,0 +1,158 @@
+/*
+ * WHY: `POST /api/store/analytics/alerts` and `POST /api/store/analytics/cards`
+ *      both spread the raw request body into Firestore.
+ *
+ *      The alert one matters most. An analytics alert is a rule that FIRES —
+ *      `metric`, `operator`, `threshold` and `windowHours` are what a scheduled
+ *      job evaluates, and none of the four was checked. A `threshold` arriving
+ *      as the string "50" from a number input was written as a string, so the
+ *      comparison the alert exists to perform would run against a string; an
+ *      `operator` outside the real six matched nothing; and `windowHours` was
+ *      unbounded, so a rule could ask a job to look back a hundred years.
+ *
+ *      Neither failure surfaces as an error. The alert is created, listed, and
+ *      looks configured — it simply never fires, or fires wrongly.
+ *
+ * WHAT: The two create contracts.
+ *
+ * ## `scope` / `ownerId` / `isBuiltIn` are absent on purpose
+ *
+ * The routes pin all three. `scope` in particular decides whether a row is a
+ * seller's or the platform's, so accepting it from the body would let a seller
+ * file an admin-scoped card.
+ *
+ * EXPORTS:
+ *   analyticsAlertCreateSchema, analyticsCardCreateSchema,
+ *   ANALYTICS_ALERT_OPERATORS, ANALYTICS_CARD_TYPES,
+ *   type AnalyticsAlertCreateValues, type AnalyticsCardCreateValues
+ *
+ * @tag domain:store-extensions,analytics
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/store/analytics/alerts,/api/store/analytics/cards
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { firestoreValueSchema } from "../../../schemas/firestore-value";
+/*
+ * Keyed `Record<Union, true>` so BOTH mistakes are compile errors — a value
+ * added to the union and forgotten here, and a value here that is not real.
+ */
+const ALERT_OPERATOR_MAP = {
+    ">": true,
+    "<": true,
+    ">=": true,
+    "<=": true,
+    "==": true,
+    "!=": true,
+};
+export const ANALYTICS_ALERT_OPERATORS = Object.keys(ALERT_OPERATOR_MAP);
+const CARD_TYPE_MAP = {
+    metric: true,
+    line: true,
+    bar: true,
+    pie: true,
+    table: true,
+    custom: true,
+};
+export const ANALYTICS_CARD_TYPES = Object.keys(CARD_TYPE_MAP);
+/** One year. A window beyond this is a typo, not a reporting period. */
+const MAX_WINDOW_HOURS = 24 * 365;
+/**
+ * 🛑 `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 analyticsAlertCreateSchema = z
+    .object({
+    label: annotate(z.string().min(1, "Give the alert a name.").max(120), {
+        section: "alert",
+        sectionLabel: "Alert",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "full",
+    }),
+    metric: annotate(z.string().min(1, "Choose a metric to watch."), {
+        section: "rule",
+        sectionLabel: "When to fire",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "pair",
+    }),
+    operator: annotate(z.enum(ANALYTICS_ALERT_OPERATORS), {
+        section: "rule",
+        quick: true,
+        order: 2,
+        row: "pair",
+    }),
+    // Coerced. A number input sends a string, and an uncoerced threshold is
+    // compared as a string by whatever evaluates the rule — "9" > "10".
+    threshold: annotate(z.coerce.number({ invalid_type_error: "Set a numeric threshold." }), {
+        section: "rule",
+        quick: true,
+        order: 3,
+        row: "pair",
+        kind: "number",
+    }),
+    windowHours: annotate(z.coerce
+        .number()
+        .int("The window must be a whole number of hours.")
+        .min(1, "The window must be at least an hour.")
+        .max(MAX_WINDOW_HOURS, "That window is longer than a year."), { section: "rule", quick: true, order: 4, row: "pair", kind: "number" }),
+    isActive: annotate(z.boolean().optional(), {
+        section: "delivery",
+        sectionLabel: "Delivery",
+        order: 1,
+        row: "quarter",
+    }),
+    notifyChannels: annotate(z.array(z.enum(["in-app", "email", "whatsapp"])).min(1).optional(), { section: "delivery", order: 2, row: "full", kind: "list" }),
+})
+    .strict();
+export const analyticsCardCreateSchema = z
+    .object({
+    title: annotate(z.string().min(1, "Give the card a title.").max(120), {
+        section: "card",
+        sectionLabel: "Card",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "full",
+    }),
+    type: annotate(z.enum(ANALYTICS_CARD_TYPES), {
+        section: "card",
+        quick: true,
+        order: 2,
+        row: "pair",
+    }),
+    metric: annotate(z.string().min(1, "Choose a metric."), {
+        section: "card",
+        quick: true,
+        order: 3,
+        row: "pair",
+    }),
+    // Deliberately open — filter shape varies by card type, and a closed schema
+    // would silently strip whatever the builder produced for a type it did not
+    // enumerate.
+    filters: annotate(z.record(firestoreValueSchema).optional(), {
+        section: "card",
+        order: 4,
+        row: "full",
+        kind: "list",
+    }),
+    position: annotate(z.coerce.number().int().min(0).optional(), {
+        section: "layout",
+        sectionLabel: "Layout",
+        order: 1,
+        row: "pair",
+        kind: "number",
+    }),
+    isVisible: annotate(z.boolean().optional(), {
+        section: "layout",
+        order: 2,
+        row: "quarter",
+    }),
+})
+    .strict();

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

@@ -0,0 +1,85 @@
+import { z } from "zod";
+/** Whether a string is a permission this system can actually grant. */
+export declare function isKnownPermission(value: string): boolean;
+/**
+ * 🛑 `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 customRoleFormSchema: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<["global", "store"]>;
+    permissions: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    inheritsFrom: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    scope: "store" | "global";
+    name: string;
+    slug: string;
+    isActive: boolean;
+    permissions: string[];
+    description?: string | undefined;
+    inheritsFrom?: string | undefined;
+}, {
+    scope: "store" | "global";
+    name: string;
+    slug: string;
+    isActive: boolean;
+    permissions: string[];
+    description?: string | undefined;
+    inheritsFrom?: string | undefined;
+}>;
+export type CustomRoleFormValues = z.infer<typeof customRoleFormSchema>;
+/** Create contract. `createdBy` is absent — the route sets it from the session. */
+export declare const customRoleCreateSchema: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<["global", "store"]>;
+    permissions: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    inheritsFrom: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    scope: "store" | "global";
+    name: string;
+    slug: string;
+    isActive: boolean;
+    permissions: string[];
+    description?: string | undefined;
+    inheritsFrom?: string | undefined;
+}, {
+    scope: "store" | "global";
+    name: string;
+    slug: string;
+    isActive: boolean;
+    permissions: string[];
+    description?: string | undefined;
+    inheritsFrom?: string | undefined;
+}>;
+/**
+ * Update contract — partial and `.strict()`, so an unknown key is a 400 rather
+ * than a silent write into a document the permission system reads.
+ */
+export declare const customRoleUpdateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<["global", "store"]>>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    inheritsFrom: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    scope?: "store" | "global" | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    permissions?: string[] | undefined;
+    inheritsFrom?: string | undefined;
+}, {
+    scope?: "store" | "global" | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    isActive?: boolean | undefined;
+    permissions?: string[] | undefined;
+    inheritsFrom?: string | undefined;
+}>;