@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/addresses/schemas/address-form.js

@@ -0,0 +1,212 @@
+/*
+ * WHY: There were **eleven** address field shapes in the tree and three
+ *      separate naming schisms across them — `postalCode` vs `pincode`,
+ *      `phone` vs `phoneNumber`, `addressLine1` vs `line1` — plus **fifteen**
+ *      postal rules that disagreed with each other, two of them server-side
+ *      rules on the same entity. The client said `.min(1)` and the server said
+ *      `/^\d{6}$/`, so `abc` passed every check the user could see and came
+ *      back a 400 with nothing on the field.
+ * WHAT: One address shape, one postal rule, used by every form and every
+ *       route that writes an address.
+ *
+ * ## The shape is `AddressDocument`, not a new one
+ *
+ * `postalCode` / `phone` / `addressLine1` — the stored names win, because the
+ * alternative is a mapping layer at every boundary and that is precisely how
+ * eleven shapes happened.
+ *
+ * ## The postal rule is per COUNTRY, and that was the real defect
+ *
+ * `country` is free text, so an India-only `/^\d{6}$/` was being applied to
+ * Canadian addresses. `isValidPostalCode` resolves the rule from the country
+ * on the same record, and falls back to a permissive length bound when the
+ * country is one we do not enumerate — an unknown country must never block a
+ * save.
+ *
+ * EXPORTS:
+ *   refineAddressPostal, addressFormSchema, addressUpdateSchema,
+ *   adminAddressCreateSchema, adminAddressUpdateSchema, and their value types
+ *
+ * @tag domain:addresses
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AddressForm,AdminAddressEditorView,UserAddressesClient,address routes
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { DEFAULT_COUNTRY, countryFor, isValidPostalCode, postalLabelFor, } from "../../../constants/geo/countries";
+/**
+ * The ONE postal rule.
+ *
+ * Fifteen used to disagree — two of them server-side rules on the same
+ * entity — and this is the only one now, shared by every form and every route
+ * that writes an address.
+ *
+ * The message names what the country itself calls the field, so a Canadian
+ * address is never told to enter a "PIN code". An unknown country falls back
+ * to a length bound inside `isValidPostalCode`, because a postal rule exists
+ * to catch a typo and must never block a save.
+ */
+export function refineAddressPostal(v, ctx) {
+    if (!v.postalCode)
+        return;
+    const country = v.country ?? DEFAULT_COUNTRY;
+    if (isValidPostalCode(country, v.postalCode))
+        return;
+    const known = countryFor(country);
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["postalCode"],
+        message: known
+            ? `That is not a valid ${postalLabelFor(country)} for ${known.name}.`
+            : "That does not look like a postal code.",
+    });
+}
+/**
+ * 🛑 `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 addressFormSchema = z
+    .object({
+    /*
+     * Required, because `AddressDocument.label` is `string` and not
+     * `string | undefined` — four of the six server schemas already had
+     * `.min(1)` and the buyer form had it optional, which is one of the eleven
+     * shapes this collapses.
+     */
+    label: annotate(z.string().trim().min(1, "Give the address a label.").max(60), {
+        section: "address", sectionLabel: "Address", sectionRequired: true,
+        quick: true, order: 1, row: "pair", label: "Label",
+        help: "Home, Work, Warehouse — whatever helps you pick it at checkout.",
+    }),
+    fullName: annotate(z.string().trim().min(2, "Enter the recipient's full name.").max(120), {
+        section: "address", quick: true, order: 2, row: "pair",
+        label: "Full name",
+    }),
+    /*
+     * Digits, spaces and the usual separators, 7–15 long — E.164's own bound.
+     * It was `.min(1)` on one surface and unchecked on two others, so a phone
+     * number of "x" reached the courier.
+     */
+    phone: annotate(z
+        .string()
+        .trim()
+        .regex(/^[+\d][\d\s\-()]{6,19}$/, "Enter a phone number the courier can call."), {
+        section: "address", quick: true, order: 3, row: "pair",
+        label: "Phone", inputType: "tel",
+    }),
+    addressLine1: annotate(z.string().trim().min(3, "Enter the street address.").max(200), {
+        section: "location", sectionLabel: "Where", sectionRequired: true,
+        order: 1, row: "full", label: "Address line 1",
+    }),
+    addressLine2: annotate(z.string().trim().max(200).optional().or(z.literal("")), {
+        section: "location", order: 2, row: "full", label: "Address line 2",
+    }),
+    landmark: annotate(z.string().trim().max(120).optional().or(z.literal("")), {
+        section: "location", order: 3, row: "pair", label: "Landmark",
+    }),
+    city: annotate(z.string().trim().min(2, "Enter the city.").max(120), {
+        section: "location", order: 4, row: "pair", label: "City",
+    }),
+    /*
+     * A picker where the country enumerates its subdivisions, free text where
+     * it does not — the form decides that from `hasStates`. It was free text
+     * on two surfaces and a 36-option `INDIAN_STATES` select on a third, all
+     * writing the same field.
+     */
+    state: annotate(z.string().trim().min(2, "Enter the state or region.").max(120), {
+        section: "location", order: 5, row: "pair", label: "State / region",
+    }),
+    /*
+     * Only checked for emptiness HERE; the real rule is the country-aware one
+     * in the `superRefine`, because a per-field rule cannot see `country`.
+     */
+    postalCode: annotate(z.string().trim().min(1, "Enter the postal code."), {
+        section: "location", order: 6, row: "pair", label: "Postal code",
+    }),
+    country: annotate(z.string().trim().min(2, "Choose a country.").default(DEFAULT_COUNTRY), {
+        section: "location", order: 7, row: "pair", kind: "select", label: "Country",
+    }),
+    /*
+     * `.default(false)` rather than `.optional()`: `AddressDocument.isDefault`
+     * is `boolean`, so a create that omits it has to mean "not default"
+     * somewhere — and four of the six server schemas were supplying that
+     * default themselves, each in its own way.
+     */
+    isDefault: annotate(z.boolean().default(false), {
+        section: "visibility", sectionLabel: "Preferences", order: 1, row: "full",
+        label: "Use as my default address",
+    }),
+})
+    .superRefine(refineAddressPostal);
+/**
+ * A partial update.
+ *
+ * `.partial()` on the inner object, then the same refinement — an edit that
+ * changes only the label must not be told its postal code is missing, but an
+ * edit that changes the postal code must still be checked against the country.
+ */
+export const addressUpdateSchema = addressFormSchema.innerType()
+    .partial()
+    .superRefine(refineAddressPostal);
+/**
+ * An address as an ADMIN writes it — the shared shape plus the owner it
+ * belongs to, which only an admin may choose.
+ *
+ * Extended from the same base rather than restated. It was restated: the admin
+ * route declared its own eleven fields with `postalCode: z.string().min(6).max(6)`
+ * — a LENGTH check with no character class, so `"abcdef"` was a valid Indian
+ * PIN code as far as that route was concerned.
+ */
+export const adminAddressCreateSchema = addressFormSchema.innerType()
+    .extend({
+    ownerType: z.enum(["user", "store"]),
+    ownerId: z.string().trim().min(1, "Choose who this address belongs to."),
+})
+    .superRefine(refineAddressPostal);
+export const adminAddressUpdateSchema = adminAddressCreateSchema.innerType()
+    .partial()
+    .superRefine(refineAddressPostal);
+/**
+ * The admin PATCH body — an address edit OR a moderation verb.
+ *
+ * 🛑 Declared HERE rather than `.extend()`-ed at the route, because the
+ * consumer is on zod 4 and appkit compiles against zod 3 (the two-zod split
+ * documented in `field-ui-meta.ts`). Extending an appkit schema with
+ * consumer-side `z` produces a type error at best and two incompatible
+ * validator instances at worst.
+ *
+ * `action` and `banReason` are not address FIELDS — an admin banning an
+ * address is not editing it — which is why they sit alongside the shape
+ * rather than inside it.
+ */
+export const adminAddressPatchSchema = adminAddressCreateSchema.innerType()
+    .partial()
+    .extend({
+    action: z.enum(["ban", "approve_unban", "reject_unban"]).optional(),
+    banReason: z.string().trim().max(500).optional(),
+})
+    .superRefine(refineAddressPostal);
+/**
+ * A buyer's request that a banned address be restored.
+ *
+ * 🛑 Lives in appkit, not beside its drawer in the consumer: appkit compiles
+ * against zod 3 and the app is on zod 4, so a consumer-built schema handed to
+ * `useFormShellState` is a type error and two incompatible validator
+ * instances. Every schema a form primitive parses has to be declared on this
+ * side of that split.
+ *
+ * A floor of 20 characters, higher than the 10 an admin ban REASON carries.
+ * The asymmetry is deliberate: a ban is written by staff who also have the
+ * audit log and the flagged order in front of them, while this note is the
+ * only thing a reviewer has. "please unban" costs them a round trip.
+ */
+export const addressUnbanRequestSchema = z.object({
+    note: z
+        .string()
+        .trim()
+        .min(20, "Explain what happened — at least 20 characters. This is all the reviewer sees.")
+        .max(1000, "Keep it under 1000 characters."),
+});

package/dist/features/addresses/schemas/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./firestore";
+export * from "./address-form";
 import { z } from "zod";
 export declare const addressOwnerTypeSchema: z.ZodEnum<["user", "store"]>;
 export declare const addressFirestoreSchema: z.ZodObject<{

package/dist/features/addresses/schemas/index.js

@@ -1,9 +1,17 @@
 export * from "./firestore";
+export * from "./address-form";
 // ─── Firestore document schema (W2) ───────────────────────────────────────────
 // Mirrors AddressDocument in ./firestore.ts. Registered into SCHEMAS.firestore.addresses.
 import { z } from "zod";
 import { auditTimestampsShape } from "../../../schemas/firestore-helpers";
 export const addressOwnerTypeSchema = z.enum(["user", "store"]);
+/*
+ * The stored DOCUMENT, not a form. It carries `id`, `ownerType`, `ownerId` and
+ * the audit timestamps that no form collects, and it is what
+ * `SCHEMAS.firestore.addresses` validates a read against — a different job
+ * from `addressFormSchema`, which validates what a human typed.
+ */
+// audit-address-shape-ok: the Firestore document mirror, registered in SCHEMAS.firestore
 export const addressFirestoreSchema = z.object({
     id: z.string(),
     ownerType: addressOwnerTypeSchema,

package/dist/features/admin/actions/admin-read-actions.d.ts

@@ -114,4 +114,4 @@ export declare function listAdminContactSubmissions(params?: {
     sorts?: string;
     page?: number;
     pageSize?: number;
-}): Promise<import("../../..").PagedResult<import("../server").ContactSubmissionDocument>>;
+}): Promise<import("../../..").PagedResult<import("../../..").ContactSubmissionDocument>>;

package/dist/features/admin/actions/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./notification-actions";
-export * from "./chat-actions";
 export * from "./site-settings-actions";
 export * from "./admin-actions";
 export * from "./admin-read-actions";

package/dist/features/admin/actions/index.js

@@ -1,5 +1,4 @@
 export * from "./notification-actions";
-export * from "./chat-actions";
 export * from "./site-settings-actions";
 export * from "./admin-actions";
 export * from "./admin-read-actions";

package/dist/features/admin/actions/notification-actions.js

@@ -7,7 +7,7 @@ import { isChannelHealthy, withChannelRetry } from "../../../_internal/server/no
 import { enqueueJob } from "../../jobs/actions/enqueue-job";
 import { serverLogger } from "../../../monitoring";
 import { decryptPii } from "../../../security/index";
-import { resolveNotificationActionUrl, } from "../../../_internal/shared/features/notifications/action-url";
+import { resolveNotificationActionUrl, TYPE_AUDIENCE, } from "../../../_internal/shared/features/notifications/action-url";
 import { renderNotificationEmail } from "../../email/notification-templates";
 /**
  * A notification's `actionUrl` is a site-relative path — correct for the
@@ -100,46 +100,6 @@ export async function listNotifications(userId, limit = 20) {
 export async function getUnreadNotificationCount(userId) {
     return notificationRepository.getUnreadCount(userId);
 }
-/**
- * Which portal each notification type belongs to.
- *
- * `Record<NotificationType, …>`, so a new type cannot compile without an
- * answer — the same discipline `typeToPrefsKey` needed after it silently
- * omitted three types and ignored those users' opt-outs.
- */
-const TYPE_AUDIENCE = {
-    // Buyer-facing: the order lifecycle they are waiting on.
-    order_placed: "buyer",
-    order_confirmed: "buyer",
-    order_shipped: "buyer",
-    order_delivered: "buyer",
-    order_cancelled: "buyer",
-    refund_initiated: "buyer",
-    payment_review: "buyer",
-    emi_installment_due_soon: "buyer",
-    emi_installment_overdue: "buyer",
-    prize_won: "buyer",
-    prize_reveal_expired: "buyer",
-    product_available: "buyer",
-    bid_placed: "buyer",
-    bid_outbid: "buyer",
-    bid_won: "buyer",
-    bid_lost: "buyer",
-    offer_responded: "buyer",
-    offer_counter_accepted: "buyer",
-    offer_expired: "buyer",
-    review_replied: "buyer",
-    catalogue_images_stale: "buyer",
-    // Seller-facing.
-    auction_ended: "seller", // "your auction closed with no winner"
-    offer_received: "seller",
-    review_approved: "seller",
-    // Account-level, which lives in the user portal for everyone.
-    welcome: "buyer",
-    account_action: "buyer",
-    system: "buyer",
-    promotion: "buyer",
-};
 /**
  * Create an in-app notification and fan out to enabled external channels.
  *

package/dist/features/admin/components/AdminActionIndexView.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AdminActionIndexView — the one control plane for "what can a user do here,
+ * and where is it" (D7).
+ *
+ * ## It absorbs two editors that reached nothing
+ *
+ * `/admin/navigation` (CRUD over a Firestore collection) and
+ * `/admin/settings/navigation` (toggles over `siteSettings.navConfig`, seeded
+ * from an 11-item hardcoded array) both existed, and **neither one's data
+ * reached any sidebar** — because `filterNavItems` short-circuits on a missing
+ * `id` and no nav item had one until W6. Two admin screens editing settings
+ * nothing read.
+ *
+ * This screen lists every entry with its kind, portal, route, deep link and
+ * required permission, and the toggle here does reach the sidebar.
+ *
+ * ## What an admin may change, and what they may not
+ *
+ * Label, description, keywords, weight and enabled — content. Not `href`, not
+ * `kind`, not any permission field: repointing a built-in route is routing,
+ * and relaxing a permission is access control. An admin-authored entry brings
+ * its own href and is validated at SAVE time, because the audit runs on CI and
+ * a runtime-written bad link would 404 until the next run.
+ */
+import React from "react";
+import type { StackedViewShellProps } from "../../../ui";
+export interface AdminActionIndexViewProps extends Omit<StackedViewShellProps, "sections"> {
+    labels?: {
+        title?: string;
+    };
+}
+export declare function AdminActionIndexView({ labels }: AdminActionIndexViewProps): React.JSX.Element;

package/dist/features/admin/components/AdminActionIndexView.js

@@ -0,0 +1,128 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AdminActionIndexView — the one control plane for "what can a user do here,
+ * and where is it" (D7).
+ *
+ * ## It absorbs two editors that reached nothing
+ *
+ * `/admin/navigation` (CRUD over a Firestore collection) and
+ * `/admin/settings/navigation` (toggles over `siteSettings.navConfig`, seeded
+ * from an 11-item hardcoded array) both existed, and **neither one's data
+ * reached any sidebar** — because `filterNavItems` short-circuits on a missing
+ * `id` and no nav item had one until W6. Two admin screens editing settings
+ * nothing read.
+ *
+ * This screen lists every entry with its kind, portal, route, deep link and
+ * required permission, and the toggle here does reach the sidebar.
+ *
+ * ## What an admin may change, and what they may not
+ *
+ * Label, description, keywords, weight and enabled — content. Not `href`, not
+ * `kind`, not any permission field: repointing a built-in route is routing,
+ * and relaxing a permission is access control. An admin-authored entry brings
+ * its own href and is validated at SAVE time, because the audit runs on CI and
+ * a runtime-written bad link would 404 until the next run.
+ */
+import React from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useApiMutation } from "@mohasinac/appkit/client";
+import { Alert, Badge, Row, Span, Stack, Text, Toggle, useToast } from "../../../ui";
+import { apiClient } from "../../../http";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { DataListingView } from "./DataListingView";
+const ENDPOINT = ADMIN_ENDPOINTS.ACTION_INDEX;
+export function AdminActionIndexView({ labels = {} }) {
+    const queryClient = useQueryClient();
+    const { showToast } = useToast();
+    const query = useQuery({
+        queryKey: ["admin", "action-index"],
+        queryFn: () => apiClient.get(ENDPOINT),
+        staleTime: 60000,
+    });
+    const payload = query.data?.data;
+    const overrides = payload?.control?.entries ?? {};
+    const toggleMutation = useApiMutation({
+        errorMessage: "Could not update that entry.",
+        mutationFn: async (vars) => apiClient.patch(ENDPOINT, {
+            entryId: vars.entryId,
+            override: { ...overrides[vars.entryId], enabled: vars.enabled },
+        }),
+        onSuccess: () => {
+            showToast("Saved.", "success");
+            void queryClient.invalidateQueries({ queryKey: ["admin", "action-index"] });
+        },
+    });
+    /*
+     * Ordered by weight, then label — the same ranking `matchesNavQuery` gives
+     * the search, so the admin reading this list sees entries in the order a
+     * user would meet them.
+     */
+    const rows = React.useMemo(() => [...(payload?.entries ?? [])]
+        .sort((a, b) => (b.weight ?? 0) - (a.weight ?? 0) || a.label.localeCompare(b.label))
+        .map((entry) => ({
+        id: entry.id,
+        primary: entry.label,
+        secondary: entry.description ?? entry.sectionPath ?? "",
+        kind: entry.kind,
+        portal: entry.portal,
+        href: `${entry.href}${entry.deepLink ?? ""}`,
+        permission: entry.requiredPermission ?? "—",
+        enabled: overrides[entry.id]?.enabled !== false,
+    })), [payload?.entries, overrides]);
+    const sync = payload?.sync;
+    return (_jsxs(Stack, { gap: "md", children: [sync && sync.orphanedOverrides.length > 0 && (_jsxs(Alert, { variant: "warning", title: "Overrides with no entry", children: [sync.orphanedOverrides.length, " saved override", sync.orphanedOverrides.length === 1 ? "" : "s", " point at entries the code no longer has (", sync.orphanedOverrides.slice(0, 4).join(", "), sync.orphanedOverrides.length > 4 ? "…" : "", "). They are ignored \u2014 clear them when convenient."] })), _jsx(DataListingView, { config: {
+                    portal: "admin",
+                    title: labels.title ?? "Action index",
+                    subtitle: "Every page, setting and toggle a user can reach — and what the search finds them by.",
+                    search: {
+                        placeholder: "Search by label, description or keyword…",
+                        mode: "partial",
+                        fields: ["label", "description", "keywords"],
+                        commit: "debounce",
+                    },
+                    emptyLabel: "No entries match.",
+                    queryKey: ["admin", "action-index", "listing"],
+                    endpoint: ENDPOINT,
+                    filterKeys: ["portal", "kind"],
+                    defaultSort: "",
+                    /*
+                     * 🛑 No sort dropdown, on purpose.
+                     *
+                     * This endpoint returns ONE document — the whole index, ~380 entries
+                     * — and does not sort. Offering a dropdown here would be Root Cause
+                     * #63 exactly: an option whose field the query never applies, so the
+                     * control reorders nothing and says nothing about it. The rows are
+                     * ordered by weight then label below, which is the ranking the
+                     * search itself uses.
+                     */
+                    sortOptions: [],
+                    mapRows: () => rows,
+                    getTotal: () => rows.length,
+                    buildFilters: () => undefined,
+                    columns: [
+                        { key: "primary", header: "Entry" },
+                        {
+                            key: "kind",
+                            header: "Kind",
+                            render: (row) => _jsx(Badge, { variant: "default", children: row.kind }),
+                        },
+                        { key: "portal", header: "Portal" },
+                        {
+                            key: "href",
+                            header: "Goes to",
+                            render: (row) => (_jsx(Span, { size: "xs", family: "mono", color: "muted", children: row.href })),
+                        },
+                        {
+                            key: "permission",
+                            header: "Needs",
+                            render: (row) => (_jsx(Span, { size: "xs", color: "muted", children: row.permission })),
+                        },
+                        {
+                            key: "enabled",
+                            header: "Shown",
+                            render: (row) => (_jsx(Row, { align: "center", gap: "sm", children: _jsx(Toggle, { checked: row.enabled, size: "sm", "aria-label": `Show ${row.primary}`, onChange: (next) => toggleMutation.mutate({ entryId: row.id, enabled: next }) }) })),
+                        },
+                    ],
+                } }), _jsx(Text, { size: "xs", color: "muted", children: "Hiding an entry removes it from the sidebar, the header search and the command palette at once. Labels, descriptions and keywords can be edited here; a route and its required permission belong to the code." })] }));
+}