@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/addresses/hooks/usePostalLookup.js

@@ -0,0 +1,133 @@
+"use client";
+/*
+ * WHY: "Typing a zipcode should fill in the city" — and there was **no lookup
+ *      anywhere in the codebase**. Two dead modules carried the shape of one
+ *      that had been removed (`useAddressForm`, `address-validation`, both
+ *      with an unused `validatePostalCode` extension point and zero
+ *      consumers), which is what made it look built.
+ * WHAT: `usePostalLookup` — resolve a postal code to its place and region.
+ *
+ * ## Zippopotam, and one code path for every country
+ *
+ * `https://api.zippopotam.us/{country}/{postal}` is free, needs no key and
+ * covers ~60 countries. It returns place + state, not district — which is fine:
+ * the user writes the locality, this fills the two fields they would otherwise
+ * copy off an envelope.
+ *
+ * India Post's own API would be more complete for India, but it is one country
+ * behind a different contract; a second provider is a second failure mode and a
+ * second set of field names for a form that just spent this wave collapsing
+ * eleven shapes into one.
+ *
+ * ## 🛑 Three rules, and each one is the difference between help and damage
+ *
+ * 1. **Never overwrite what the user typed.** Autofill lands only in an EMPTY
+ *    city or state. A lookup that corrects a deliberately unusual address is a
+ *    bug the user cannot even report — they watch their own typing vanish.
+ * 2. **Fail silently and OPEN.** A network error, a 404, an unsupported
+ *    country: all leave the fields exactly as they were and never block the
+ *    submit. Zippopotam's India coverage is thinner than India Post's, so a
+ *    miss is the common case and must be a non-event.
+ * 3. **Abort in flight.** A user typing "560001" fires on every keystroke past
+ *    the debounce; without an `AbortController` the answer for "56000" can
+ *    land after the answer for "560001" and fill the wrong city.
+ *
+ * EXPORTS: usePostalLookup, type PostalLookupResult
+ *
+ * @tag domain:addresses
+ * @tag layer:hook
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:AddressForm,AdminAddressEditorView
+ * @tag sideEffects:network
+ */
+import * as React from "react";
+import { normalizeError } from "../../../errors/normalize";
+import { countryFor, isValidPostalCode } from "../../../constants/geo/countries";
+const ENDPOINT = "https://api.zippopotam.us";
+const DEBOUNCE_MS = 400;
+/**
+ * Per-session cache, keyed `{country}:{postal}`.
+ *
+ * Module scope rather than component state: the same postal code is looked up
+ * again every time the user opens the address form, and a miss is cached too —
+ * re-asking for a code Zippopotam does not have is a round trip that can only
+ * fail again.
+ */
+const CACHE = new Map();
+export function usePostalLookup({ onResolved, enabled = true, }) {
+    const [isLooking, setIsLooking] = React.useState(false);
+    const timerRef = React.useRef(null);
+    const abortRef = React.useRef(null);
+    /*
+     * The callback in a ref so `lookup` is stable across renders. Without it
+     * every keystroke re-creates the debounced function and the timer never
+     * survives long enough to fire.
+     */
+    const onResolvedRef = React.useRef(onResolved);
+    onResolvedRef.current = onResolved;
+    React.useEffect(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        abortRef.current?.abort();
+    }, []);
+    const lookup = React.useCallback((postalCode, country) => {
+        if (!enabled)
+            return;
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        abortRef.current?.abort();
+        const code = postalCode.trim();
+        const def = countryFor(country);
+        // Only ask once the code is plausibly complete for this country, so a
+        // half-typed PIN does not spend a round trip proving itself wrong.
+        if (!def || !isValidPostalCode(country, code))
+            return;
+        const key = `${def.code}:${code}`;
+        const cached = CACHE.get(key);
+        if (cached !== undefined) {
+            if (cached)
+                onResolvedRef.current(cached);
+            return;
+        }
+        timerRef.current = setTimeout(() => {
+            const controller = new AbortController();
+            abortRef.current = controller;
+            setIsLooking(true);
+            void fetch(`${ENDPOINT}/${def.code.toLowerCase()}/${encodeURIComponent(code)}`, {
+                signal: controller.signal,
+            })
+                .then((res) => (res.ok ? res.json() : null))
+                .then((json) => {
+                const place = json?.places?.[0];
+                const result = place
+                    ? {
+                        city: place["place name"] ?? "",
+                        state: place.state ?? place["state abbreviation"] ?? "",
+                    }
+                    : null;
+                CACHE.set(key, result);
+                if (result)
+                    onResolvedRef.current(result);
+            })
+                .catch((err) => {
+                const normalized = normalizeError(err);
+                /*
+                 * Deliberately silent. An abort is the expected path when the user
+                 * keeps typing, and a real failure must leave the fields editable
+                 * rather than tell the buyer their postcode is wrong when it is
+                 * our upstream that is down. Not cached, so a transient failure
+                 * does not poison the code for the session.
+                 */
+                void normalized;
+            })
+                .finally(() => {
+                if (abortRef.current === controller) {
+                    abortRef.current = null;
+                    setIsLooking(false);
+                }
+            });
+        }, DEBOUNCE_MS);
+    }, [enabled]);
+    return { lookup, isLooking };
+}

package/dist/features/addresses/schemas/address-form.d.ts

@@ -0,0 +1,423 @@
+import { z } from "zod";
+/**
+ * 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 declare function refineAddressPostal(v: {
+    postalCode?: string;
+    country?: string;
+}, ctx: z.RefinementCtx): void;
+/**
+ * 🛑 `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 addressFormSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    fullName: z.ZodString;
+    phone: z.ZodString;
+    addressLine1: z.ZodString;
+    addressLine2: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    landmark: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    city: z.ZodString;
+    state: z.ZodString;
+    postalCode: z.ZodString;
+    country: z.ZodDefault<z.ZodString>;
+    isDefault: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    country: string;
+    label: string;
+    isDefault: boolean;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    label: string;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country?: string | undefined;
+    isDefault?: boolean | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>, {
+    country: string;
+    label: string;
+    isDefault: boolean;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    label: string;
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country?: string | undefined;
+    isDefault?: boolean | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>;
+export type AddressFormValues = z.infer<typeof addressFormSchema>;
+/**
+ * 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 declare const addressUpdateSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    addressLine1: z.ZodOptional<z.ZodString>;
+    addressLine2: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    landmark: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    postalCode: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    isDefault: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>;
+export type AddressUpdateValues = z.infer<typeof addressUpdateSchema>;
+/**
+ * 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 declare const adminAddressCreateSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    fullName: z.ZodString;
+    phone: z.ZodString;
+    addressLine1: z.ZodString;
+    addressLine2: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    landmark: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    city: z.ZodString;
+    state: z.ZodString;
+    postalCode: z.ZodString;
+    country: z.ZodDefault<z.ZodString>;
+    isDefault: z.ZodDefault<z.ZodBoolean>;
+} & {
+    ownerType: z.ZodEnum<["user", "store"]>;
+    ownerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    country: string;
+    label: string;
+    isDefault: boolean;
+    ownerId: string;
+    ownerType: "user" | "store";
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    label: string;
+    ownerId: string;
+    ownerType: "user" | "store";
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country?: string | undefined;
+    isDefault?: boolean | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>, {
+    country: string;
+    label: string;
+    isDefault: boolean;
+    ownerId: string;
+    ownerType: "user" | "store";
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    label: string;
+    ownerId: string;
+    ownerType: "user" | "store";
+    fullName: string;
+    phone: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country?: string | undefined;
+    isDefault?: boolean | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>;
+export declare const adminAddressUpdateSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    addressLine1: z.ZodOptional<z.ZodString>;
+    addressLine2: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    landmark: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    postalCode: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    isDefault: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    ownerType: z.ZodOptional<z.ZodEnum<["user", "store"]>>;
+    ownerId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    isDefault?: boolean | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>;
+export type AdminAddressCreateValues = z.infer<typeof adminAddressCreateSchema>;
+/**
+ * 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 declare const adminAddressPatchSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+    addressLine1: z.ZodOptional<z.ZodString>;
+    addressLine2: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    landmark: z.ZodOptional<z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    postalCode: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    isDefault: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    ownerType: z.ZodOptional<z.ZodEnum<["user", "store"]>>;
+    ownerId: z.ZodOptional<z.ZodString>;
+} & {
+    action: z.ZodOptional<z.ZodEnum<["ban", "approve_unban", "reject_unban"]>>;
+    banReason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    country?: string | undefined;
+    label?: string | undefined;
+    action?: "ban" | "approve_unban" | "reject_unban" | undefined;
+    isDefault?: boolean | undefined;
+    banReason?: string | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    action?: "ban" | "approve_unban" | "reject_unban" | undefined;
+    isDefault?: boolean | undefined;
+    banReason?: string | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>, {
+    country?: string | undefined;
+    label?: string | undefined;
+    action?: "ban" | "approve_unban" | "reject_unban" | undefined;
+    isDefault?: boolean | undefined;
+    banReason?: string | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}, {
+    country?: string | undefined;
+    label?: string | undefined;
+    action?: "ban" | "approve_unban" | "reject_unban" | undefined;
+    isDefault?: boolean | undefined;
+    banReason?: string | undefined;
+    ownerId?: string | undefined;
+    ownerType?: "user" | "store" | undefined;
+    fullName?: string | undefined;
+    phone?: string | undefined;
+    addressLine1?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalCode?: string | undefined;
+    addressLine2?: string | undefined;
+    landmark?: string | undefined;
+}>;
+export type AdminAddressPatchValues = z.infer<typeof adminAddressPatchSchema>;
+/**
+ * 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 declare const addressUnbanRequestSchema: z.ZodObject<{
+    note: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    note: string;
+}, {
+    note: string;
+}>;
+export type AddressUnbanRequestValues = z.infer<typeof addressUnbanRequestSchema>;