@mohasinac/appkit 4.14.0 → 4.15.0

package/dist/features/status-history/components/StatusTimeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * StatusTimeline — the one rail that renders any entity's status history.
+ *
+ * Both the order timeline and the offer timeline were about to be written
+ * separately, against the same `StatusChangeEntry[]` shape, with the same
+ * dot-and-connector rail and the same two load-bearing rules. That is the
+ * duplication the Rule of Three exists to prevent, so this is the single
+ * implementation and each feature supplies only its own phase vocabulary.
+ *
+ * ## Two rules this component must never break
+ *
+ * **1. Never fabricate a timestamp.** A step with no recorded date renders an
+ * em-dash. Not `new Date()`, and not a proxy field: `updatedAt` means "last
+ * write of any kind" and `expiresAt` is a deadline, not an event. An offer
+ * that expired has no timestamp at all because `expireMany` never wrote one
+ * before this wave, and inventing one would make the record lie.
+ *
+ * **2. It never fetches.** A client component that loaded its own chain would
+ * fire one request per opened modal per portal. The API returns the chain;
+ * this renders it.
+ */
+import type { ReactNode } from "react";
+import type { FieldChange } from "../../../_internal/shared/history/index";
+/** The client-facing entry shape — dates already serialised to ISO. */
+export interface TimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    trigger: string;
+}
+export interface TimelineStep {
+    key: string;
+    label: string;
+    /** ISO string, or absent — absent renders an em-dash, never a guess. */
+    date?: string;
+    /** Terminal-negative: cancelled, declined, rejected. Renders in error tone. */
+    negative?: boolean;
+    /**
+     * Neutral-but-ended, e.g. a superseded offer round. Deliberately distinct
+     * from `negative`: the buyer did not walk away, they countered, and the
+     * negotiation continued.
+     */
+    muted?: boolean;
+    actorRole?: TimelineEntry["actorRole"];
+    reason?: string;
+    note?: string;
+    /** Round divider text for multi-round chains ("Round 2"). */
+    roundLabel?: string;
+}
+export interface StatusTimelineProps {
+    title?: string;
+    steps: TimelineStep[];
+    /** Entries trimmed off the front of the capped history, if any. */
+    truncatedCount?: number;
+    /** Rendered below the rail — tracking details, chain summary, etc. */
+    footer?: ReactNode;
+    /** Suppress `footer` when the last step is terminal-negative. */
+    hideFooterWhenNegative?: boolean;
+    emptyLabel?: string;
+    className?: string;
+}
+export declare function StatusTimeline({ title, steps, truncatedCount, footer, hideFooterWhenNegative, emptyLabel, className, }: StatusTimelineProps): import("react").JSX.Element;
+/**
+ * Turn recorded history entries into steps.
+ *
+ * Only entries that actually changed `status` become steps — an entry
+ * recording a tracking number or a payment-review outcome is real history but
+ * is not a phase, and putting every entry on the rail would bury the five
+ * transitions anyone reads.
+ */
+export declare function stepsFromEntries(entries: TimelineEntry[] | undefined, labelFor: (status: string) => string, isNegative: (status: string) => boolean): TimelineStep[];

package/dist/features/status-history/components/StatusTimeline.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, Div, Heading, Row, Stack, Text } from "../../../ui";
+const ACTOR_LABEL = {
+    buyer: "Buyer",
+    seller: "Store",
+    admin: "Admin",
+    system: "System",
+};
+export function StatusTimeline({ title = "Timeline", steps, truncatedCount, footer, hideFooterWhenNegative = true, emptyLabel = "No history yet", className = "", }) {
+    const isTerminalNegative = steps[steps.length - 1]?.negative === true;
+    const showFooter = footer && !(hideFooterWhenNegative && isTerminalNegative);
+    return (_jsxs(Div, { className: className, rounded: "xl", padding: "md", surface: "muted", border: "default", children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", className: "mb-3", children: title }), truncatedCount && truncatedCount > 0 ? (
+            // Say what is not being shown. Silent truncation reads as "this is all
+            // of it", which is the same lie as a silently dropped field.
+            _jsxs(Text, { size: "xs", color: "muted", className: "mb-2", children: [truncatedCount, " earlier ", truncatedCount === 1 ? "entry" : "entries", " trimmed"] })) : null, steps.length === 0 ? (_jsx(Badge, { variant: "default", children: emptyLabel })) : (_jsx(Stack, { gap: "none", children: steps.map((step, i) => {
+                    const isLast = i === steps.length - 1;
+                    return (_jsxs(Stack, { gap: "none", children: [step.roundLabel && (_jsx(Text, { size: "xs", weight: "semibold", color: "muted", className: "mb-1 mt-2", children: step.roundLabel })), _jsxs(Row, { gap: "sm", padding: isLast ? "none" : "b-md", children: [_jsxs(Stack, { gap: "none", align: "center", className: "shrink-0", children: [_jsx(Div, { className: `h-2.5 w-2.5 ${step.negative || step.muted ? "" : "bg-[var(--appkit-color-primary)]"}`, rounded: "full", surface: step.negative ? "danger-surface" : step.muted ? "subtle" : "none" }), !isLast && _jsx(Div, { className: "w-px flex-1 min-h-[24px]", surface: "subtle" })] }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, children: [_jsx(Text, { size: "sm", weight: "medium", className: step.negative ? "text-error" : undefined, color: step.muted ? "muted" : undefined, children: step.label }), step.actorRole && step.actorRole !== "system" && (_jsx(Badge, { variant: "default", size: "xs", children: ACTOR_LABEL[step.actorRole] }))] }), _jsx(Text, { size: "xs", color: "muted", children: step.date ? new Date(step.date).toLocaleString() : "—" }), step.reason && (_jsx(Text, { size: "xs", color: "muted", className: "mt-0.5", children: step.reason })), step.note && (_jsxs(Text, { size: "xs", color: "muted", italic: true, className: "mt-0.5", children: ["\u201C", step.note, "\u201D"] }))] })] })] }, `${step.key}-${i}`));
+                }) })), showFooter ? (_jsx(Div, { className: "mt-3 border-t border-[var(--appkit-color-border)]", padding: "t-sm", children: footer })) : null] }));
+}
+/**
+ * Turn recorded history entries into steps.
+ *
+ * Only entries that actually changed `status` become steps — an entry
+ * recording a tracking number or a payment-review outcome is real history but
+ * is not a phase, and putting every entry on the rail would bury the five
+ * transitions anyone reads.
+ */
+export function stepsFromEntries(entries, labelFor, isNegative) {
+    if (!entries?.length)
+        return [];
+    return entries
+        .filter((e) => "status" in e.changes)
+        .map((e) => {
+        const to = String(e.changes.status?.to ?? "");
+        return {
+            key: to,
+            label: labelFor(to),
+            date: e.at,
+            negative: isNegative(to),
+            actorRole: e.actorRole,
+            reason: e.reason,
+            note: e.note,
+        };
+    });
+}

package/dist/features/status-history/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Status history — the shared timeline rail for any entity that records how
+ * it reached its current state (orders, offers, and the 8 more adopting the
+ * primitive in W15).
+ *
+ * Deliberately NOT `features/history/` — that name was already taken by the
+ * buyer's browsing-history feature (`useHistory`, guest-history utils), which
+ * is an entirely unrelated concept.
+ */
+export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
+export type { StatusTimelineProps, TimelineEntry, TimelineStep } from "./components/StatusTimeline";

package/dist/features/status-history/index.js

@@ -0,0 +1,10 @@
+/**
+ * Status history — the shared timeline rail for any entity that records how
+ * it reached its current state (orders, offers, and the 8 more adopting the
+ * primitive in W15).
+ *
+ * Deliberately NOT `features/history/` — that name was already taken by the
+ * buyer's browsing-history feature (`useHistory`, guest-history utils), which
+ * is an entirely unrelated concept.
+ */
+export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";

package/dist/features/store-extensions/components/ReviewDecisionModal.d.ts

@@ -0,0 +1,27 @@
+import type { ZodType } from "zod";
+/**
+ * Generic over the schema's OUTPUT type, so a caller's `onConfirm` receives
+ * `ModerationReviewFormValues` / `ReportReviewFormValues` rather than an
+ * untyped bag. A `Record<string, unknown>` here would put the very seam this
+ * component exists to close straight back into the callback signature.
+ */
+export interface ReviewDecisionModalProps<TValues> {
+    isOpen: boolean;
+    onClose: () => void;
+    /** Modal heading, e.g. "Reject media". */
+    title: string;
+    /** The schema BOTH this modal and its route validate against. */
+    schema: ZodType<TValues>;
+    /** The status this decision sets — parsed as part of the payload. */
+    status: string;
+    /** Which key carries the note: `reason` for moderation, `resolution` for reports. */
+    noteField: string;
+    noteLabel: string;
+    noteHelp?: string;
+    notePlaceholder?: string;
+    confirmLabel: string;
+    confirmVariant?: "primary" | "danger";
+    /** Called only once the payload has parsed cleanly, with the PARSED value. */
+    onConfirm: (values: TValues) => Promise<void>;
+}
+export declare function ReviewDecisionModal<TValues>({ isOpen, onClose, title, schema, status, noteField, noteLabel, noteHelp, notePlaceholder, confirmLabel, confirmVariant, onConfirm, }: ReviewDecisionModalProps<TValues>): import("react").JSX.Element;

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();