@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/schemas/registry.js

@@ -0,0 +1,174 @@
+// [SCHEMA] Central schema registry.
+//
+// SCHEMAS is the single source of truth for every Zod schema used at a
+// system boundary. Per-feature schema files (`features/<f>/schemas/index.ts`)
+// register into the relevant bucket here; nothing else forks the tree.
+//
+// Reading SCHEMAS:
+//   - SCHEMAS.firestore[collection] — Firestore document schema, used by
+//     `withConverter()` in the matching repository so `.data()` returns the
+//     parsed shape (not `DocumentData`).
+//   - SCHEMAS.api["POST /api/wishlist"] — { body?, query?, params?, response? }
+//     bundle, used by `createRouteHandler({ schema: { body: "POST /api/wishlist" } })`.
+//   - SCHEMAS.forms[formId] — used by FormShell / QuickFormDrawer.
+//   - SCHEMAS.sieve[collection] — filter-grammar schema per repository.
+//   - SCHEMAS.webhook[provider][event] — discriminated-union envelopes per provider.
+//   - SCHEMAS.rtdb[pathPattern] — Realtime Database channel payload.
+//   - SCHEMAS.storage[op] — signed-upload metadata.
+//
+// To register a new schema:
+//   1. Author the Zod schema in the relevant `features/<f>/schemas/index.ts`.
+//   2. Import it here (alphabetically inside its bucket) and add an entry.
+//   3. The completeness audit (`appkit/scripts/audit-schema-registry-completeness.mjs`)
+//      asserts every feature export appears in SCHEMAS, every API route in
+//      `src/app/api/**` has an entry, and every Firestore collection in the
+//      CLAUDE.md seed table has a `firestore.<collection>` entry.
+// ── W2 — Firestore document schemas ──────────────────────────────────────────
+import { addressFirestoreSchema } from "../features/addresses/schemas";
+import { blogPostFirestoreSchema } from "../features/blog/schemas";
+import { categoryFirestoreSchema } from "../features/categories/schemas";
+import { conversationFirestoreSchema } from "../features/messages/schemas";
+import { carouselFirestoreSchema, carouselSlideFirestoreSchema, homepageSectionFirestoreSchema, } from "../features/homepage/schemas";
+import { faqFirestoreSchema } from "../features/faq/schemas";
+import { groupedListingFirestoreSchema } from "../features/grouped/schemas";
+import { orderFirestoreSchema } from "../features/orders/schemas";
+import { payoutFirestoreSchema } from "../features/payments/schemas";
+import { claimedCouponFirestoreSchema, couponFirestoreSchema, couponUsageFirestoreSchema, } from "../features/promotions/schemas";
+import { reviewFirestoreSchema } from "../features/reviews/schemas";
+import { scammerCommentFirestoreSchema, scammerContestFirestoreSchema, scammerFirestoreSchema, scammerIncidentFirestoreSchema, } from "../features/scams/schemas";
+import { serverErrorFirestoreSchema } from "../features/server-errors/schemas";
+import { storeFirestoreSchema } from "../features/stores/schemas";
+import { supportTicketFirestoreSchema } from "../features/support/schemas";
+// ---------------------------------------------------------------------------
+// Firestore document schemas — populated by W2.
+//
+// Coverage of the CLAUDE.md § Seed Data Reference table. Collections marked
+// (W2) were authored as part of the W2 workstream; others rely on schemas
+// already shipped in pre-existing per-feature files. The
+// `audit-firestore-schema-coverage` audit will surface any drift between this
+// map and the live seed table.
+// ---------------------------------------------------------------------------
+const firestore = {
+    addresses: addressFirestoreSchema, // W2
+    blogPosts: blogPostFirestoreSchema, // W2
+    carousels: carouselFirestoreSchema, // W2
+    carouselSlides: carouselSlideFirestoreSchema, // W2
+    categories: categoryFirestoreSchema, // W2
+    claimedCoupons: claimedCouponFirestoreSchema, // W2
+    conversations: conversationFirestoreSchema, // W2
+    coupons: couponFirestoreSchema, // W2
+    couponUsage: couponUsageFirestoreSchema, // W2
+    faqs: faqFirestoreSchema, // W2
+    groupedListings: groupedListingFirestoreSchema, // W2
+    homepageSections: homepageSectionFirestoreSchema, // W2
+    orders: orderFirestoreSchema, // W2
+    payouts: payoutFirestoreSchema, // W2
+    reviews: reviewFirestoreSchema, // W2
+    scammerProfiles: scammerFirestoreSchema, // W2
+    scammerIncidents: scammerIncidentFirestoreSchema, // W2 (subcollection)
+    scammerComments: scammerCommentFirestoreSchema, // W2 (subcollection)
+    scammerContests: scammerContestFirestoreSchema, // W2 (subcollection)
+    serverErrors: serverErrorFirestoreSchema, // W2
+    stores: storeFirestoreSchema, // W2
+    supportTickets: supportTicketFirestoreSchema, // W2
+    // Remaining CLAUDE.md collections (users, brands, products, bids, carts,
+    // wishlists, history, events, eventEntries, notifications, sessions,
+    // siteSettings) wire in via their pre-existing Zod schemas — registered as
+    // those are touched in W5/W7.
+};
+// ---------------------------------------------------------------------------
+// API route schemas — W4 seed cohort. Each entry maps an HTTP-verb-and-path
+// key to its `{ body?, query?, params?, response? }` schema bundle. The
+// `createRouteHandler` helper accepts either a direct Zod schema or one of
+// these keys.
+// ---------------------------------------------------------------------------
+import { postApiWishlist, postApiAuthSession, postApiAdminProductsIdGroup, postApiMediaSign, postApiMediaFinalize, getApiSearchSuggestions, } from "./api-routes";
+const api = {
+    "POST /api/wishlist": postApiWishlist,
+    "POST /api/auth/session": postApiAuthSession,
+    "POST /api/admin/products/[id]/group": postApiAdminProductsIdGroup,
+    "POST /api/media/sign": postApiMediaSign,
+    "POST /api/media/finalize": postApiMediaFinalize,
+    "GET /api/search/suggestions": getApiSearchSuggestions,
+};
+// ---------------------------------------------------------------------------
+// Form schemas — keyed by form id (matches FormShell/QuickFormDrawer `formId`).
+// `audit-form-schema` already enforces presence at FormShell sites; this
+// registry centralizes the schemas for cross-route reuse.
+// ---------------------------------------------------------------------------
+const forms = {
+// Populated in W5 as section builders + admin forms are tightened.
+};
+// ---------------------------------------------------------------------------
+// Sieve filter-grammar schemas — populated by W6. Each collection registers
+// a Zod schema for its filter clauses so `listingProcessor` and per-repo
+// `parseSieveFilters` return typed clauses (not `Record<string, JsonValue>`).
+// ---------------------------------------------------------------------------
+const sieve = {
+// Populated in W6.
+};
+// ---------------------------------------------------------------------------
+// Webhook envelope schemas — W7 cohort. Each provider registers a bucket
+// of `eventName` → schema. The Razorpay envelope is a discriminated union
+// keyed on the `event` discriminator.
+// ---------------------------------------------------------------------------
+import { razorpayWebhookEnvelopeSchema } from "./webhooks/razorpay";
+import { shiprocketTrackingUpdateSchema } from "./webhooks/shiprocket";
+import { googleSignInWithIdpResponseSchema, googleTokenInfoSchema, } from "./webhooks/google-oauth";
+const webhook = {
+    razorpay: {
+        envelope: razorpayWebhookEnvelopeSchema,
+    },
+    shiprocket: {
+        trackingUpdate: shiprocketTrackingUpdateSchema,
+    },
+    googleOauth: {
+        signInWithIdp: googleSignInWithIdpResponseSchema,
+        tokenInfo: googleTokenInfoSchema,
+    },
+};
+// ---------------------------------------------------------------------------
+// RTDB channel schemas — populated by W5/W6. Path keys mirror the live RTDB
+// tree (e.g. "chats/{convId}/lastUpdate", "auth/google/{uid}").
+// ---------------------------------------------------------------------------
+const rtdb = {
+// Populated in W5/W6.
+};
+// ---------------------------------------------------------------------------
+// Storage metadata schemas — populated by W4 (mediaSign, mediaFinalize).
+// ---------------------------------------------------------------------------
+const storage = {
+// Populated in W4.
+};
+// ---------------------------------------------------------------------------
+// Composed registry. `as const satisfies SchemaRegistry` preserves the literal
+// keys at the type level so consumers get autocomplete on registered routes,
+// collections, forms, etc.
+// ---------------------------------------------------------------------------
+export const SCHEMAS = {
+    firestore,
+    api,
+    forms,
+    sieve,
+    webhook,
+    rtdb,
+    storage,
+};
+// ---------------------------------------------------------------------------
+// Lookup helpers — preferred over reaching into SCHEMAS directly so call sites
+// surface a typed error when the key isn't registered.
+// ---------------------------------------------------------------------------
+export function lookupApiSchema(key) {
+    const entry = SCHEMAS.api[key];
+    if (!entry) {
+        throw new Error(`[schemas] No API schema registered for route "${String(key)}".`);
+    }
+    return entry;
+}
+export function lookupFirestoreSchema(collection) {
+    const entry = SCHEMAS.firestore[collection];
+    if (!entry) {
+        throw new Error(`[schemas] No Firestore schema registered for "${String(collection)}".`);
+    }
+    return entry;
+}

package/dist/schemas/sieve.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const sieveGrammarSchema: z.ZodObject<{
+    filters: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    sorts: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    pageSize: number;
+    filters: string;
+    sorts: string;
+}, {
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    filters?: string | undefined;
+    sorts?: string | undefined;
+}>;
+export type SieveGrammar = z.infer<typeof sieveGrammarSchema>;
+export declare const sieveWhereOpSchema: z.ZodEnum<["==", "!=", "<", "<=", ">", ">=", "array-contains", "in", "not-in", "array-contains-any"]>;
+export declare const sieveFilterClauseSchema: z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<["==", "!=", "<", "<=", ">", ">=", "array-contains", "in", "not-in", "array-contains-any"]>;
+    value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>, "many">]>;
+}, "strip", z.ZodTypeAny, {
+    value: string | number | boolean | (string | number | boolean)[] | null;
+    field: string;
+    op: "<" | ">" | "==" | ">=" | "in" | "!=" | "<=" | "array-contains" | "not-in" | "array-contains-any";
+}, {
+    value: string | number | boolean | (string | number | boolean)[] | null;
+    field: string;
+    op: "<" | ">" | "==" | ">=" | "in" | "!=" | "<=" | "array-contains" | "not-in" | "array-contains-any";
+}>;
+export type SieveFilterClause = z.infer<typeof sieveFilterClauseSchema>;
+export type SieveWhereOp = z.infer<typeof sieveWhereOpSchema>;
+export declare const sieveSortClauseSchema: z.ZodObject<{
+    field: z.ZodString;
+    direction: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+}, "strip", z.ZodTypeAny, {
+    direction: "desc" | "asc";
+    field: string;
+}, {
+    field: string;
+    direction?: "desc" | "asc" | undefined;
+}>;
+export type SieveSortClause = z.infer<typeof sieveSortClauseSchema>;

package/dist/schemas/sieve.js

@@ -0,0 +1,55 @@
+// [SCHEMA] Sieve filter-grammar schemas (W6).
+//
+// Sieve filters are passed to repository `list()` methods and to
+// `listingProcessor` as opaque strings (e.g. "status==published,price>100").
+// This module gives them a Zod schema for the request envelope plus a typed
+// shape for a single parsed clause so per-repository `parseSieveFilters`
+// helpers stop returning `Record<string, JsonValue>`.
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// SieveGrammarSchema — the wire-level request envelope. `filters` and `sorts`
+// stay as opaque strings (parsed per-collection); page + pageSize coerce
+// from query-string numbers and clamp to sensible bounds.
+// ---------------------------------------------------------------------------
+export const sieveGrammarSchema = z.object({
+    filters: z.string().optional().default(""),
+    sorts: z.string().optional().default(""),
+    page: z.coerce.number().int().min(1).default(1),
+    pageSize: z.coerce.number().int().min(1).max(100).default(20),
+});
+// ---------------------------------------------------------------------------
+// SieveFilterClause — the parsed shape of a single `field op value` clause.
+// The repository's `parseSieveFilters` helper returns an array of these.
+// ---------------------------------------------------------------------------
+export const sieveWhereOpSchema = z.enum([
+    "==",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "array-contains",
+    "in",
+    "not-in",
+    "array-contains-any",
+]);
+export const sieveFilterClauseSchema = z.object({
+    field: z.string().min(1),
+    op: sieveWhereOpSchema,
+    // `value` is a JSON-like primitive or array. Repositories cast per-field
+    // type after parsing; the wire shape is constrained but not field-typed.
+    value: z.union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.null(),
+        z.array(z.union([z.string(), z.number(), z.boolean()])),
+    ]),
+});
+// ---------------------------------------------------------------------------
+// SieveSortClause — the parsed shape of a single sort directive.
+// ---------------------------------------------------------------------------
+export const sieveSortClauseSchema = z.object({
+    field: z.string().min(1),
+    direction: z.enum(["asc", "desc"]).default("asc"),
+});

package/dist/schemas/types.d.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = readonly JsonValue[];
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/** JsonValue + Date + undefined, recursive. Use for Firestore document boundaries
+ *  where Date is unavoidable (mapDoc return shapes, repository .data() reads) AND
+ *  nested objects may have `field?: T` optional fields. Firestore strips undefined
+ *  on write, so this matches runtime semantics. */
+export type FirestoreValue = string | number | boolean | null | undefined | Date | readonly FirestoreValue[] | {
+    readonly [key: string]: FirestoreValue;
+};
+/** Record whose values are FirestoreValue. Use as the document shape for
+ *  Firestore-backed repositories and mapDoc helpers. */
+export type FirestoreDocument = Record<string, FirestoreValue>;
+/** Recursive JSON value that admits `undefined` at every nesting level.
+ *  `JSON.stringify` drops undefined keys, so the emitted JSON is valid.
+ *  Use for builders that emit `field: value || undefined` patterns and for
+ *  JSON-LD output (matches schema.org optional-field semantics). */
+export type JsonValueWithUndefined = string | number | boolean | null | undefined | readonly JsonValueWithUndefined[] | {
+    readonly [key: string]: JsonValueWithUndefined;
+};
+/** Record alias whose values are JsonValueWithUndefined. */
+export type JsonObjectWithUndefined = Record<string, JsonValueWithUndefined>;
+/** Form state values — JsonValue + Date (date pickers) + File (uploads) +
+ *  undefined. Note `File` is browser-only at runtime, but its TYPE is provided
+ *  by `lib.dom` (included in appkit tsconfig). */
+export type FormFieldValue = JsonValue | Date | File | undefined;
+/** Record whose values are FormFieldValue. Use for form-shell state shapes. */
+export type FormValues = Record<string, FormFieldValue>;
+export type HttpVerb = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type ApiRouteKey = `${HttpVerb} ${string}`;
+export interface ApiRouteSchema<TBody extends z.ZodTypeAny = z.ZodTypeAny, TQuery extends z.ZodTypeAny = z.ZodTypeAny, TParams extends z.ZodTypeAny = z.ZodTypeAny, TResponse extends z.ZodTypeAny = z.ZodTypeAny> {
+    readonly body?: TBody;
+    readonly query?: TQuery;
+    readonly params?: TParams;
+    readonly response?: TResponse;
+}
+export type WebhookSchemaBucket = Readonly<Record<string, z.ZodTypeAny>>;
+export interface SchemaRegistry {
+    /** Per-Firestore-collection document schema. Key = collection name. */
+    readonly firestore: Readonly<Record<string, z.ZodTypeAny>>;
+    /** Per-API-route schema bundle. Key = `${verb} ${pathPattern}`. */
+    readonly api: Readonly<Partial<Record<ApiRouteKey, ApiRouteSchema>>>;
+    /** Per-form schema. Key = form id (matches FormShell/QuickFormDrawer `formId`). */
+    readonly forms: Readonly<Record<string, z.ZodTypeAny>>;
+    /** Per-sieve-collection filter-grammar schema. Key = collection name. */
+    readonly sieve: Readonly<Record<string, z.ZodTypeAny>>;
+    /** Per-provider webhook envelope buckets. */
+    readonly webhook: Readonly<Record<string, WebhookSchemaBucket>>;
+    /** Per-RTDB-path payload schema. Key = path pattern (e.g. "chats/{convId}/lastUpdate"). */
+    readonly rtdb: Readonly<Record<string, z.ZodTypeAny>>;
+    /** Signed-upload + storage metadata schemas. */
+    readonly storage: Readonly<Record<string, z.ZodTypeAny>>;
+}
+export type RegistryEntry<TSchema extends z.ZodTypeAny> = {
+    readonly schema: TSchema;
+    readonly type: z.infer<TSchema>;
+};

package/dist/schemas/types.js

@@ -0,0 +1,10 @@
+// [SCHEMA] Central schema-registry types.
+//
+// This file defines the shape of the central `SCHEMAS` registry exported from
+// `./registry`. Every value crossing a system boundary (Firestore document,
+// API route input/output, form submit, sieve query, webhook payload, RTDB
+// channel, signed-upload metadata) is parsed by a Zod schema registered into
+// SCHEMAS. Anywhere else uses concrete TS types inferred from those schemas.
+//
+// See plan: `we-have-too-many-gentle-ripple.md` § W1.
+export {};

package/dist/schemas/webhooks/google-oauth.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export declare const googleSignInWithIdpResponseSchema: z.ZodObject<{
+    federatedId: z.ZodOptional<z.ZodString>;
+    providerId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    emailVerified: z.ZodOptional<z.ZodBoolean>;
+    firstName: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    lastName: z.ZodOptional<z.ZodString>;
+    photoUrl: z.ZodOptional<z.ZodString>;
+    localId: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    idToken: z.ZodString;
+    refreshToken: z.ZodString;
+    expiresIn: z.ZodString;
+    oauthAccessToken: z.ZodOptional<z.ZodString>;
+    oauthExpireIn: z.ZodOptional<z.ZodNumber>;
+    rawUserInfo: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    refreshToken: string;
+    idToken: string;
+    localId: string;
+    expiresIn: string;
+    email?: string | undefined;
+    kind?: string | undefined;
+    displayName?: string | undefined;
+    emailVerified?: boolean | undefined;
+    fullName?: string | undefined;
+    firstName?: string | undefined;
+    lastName?: string | undefined;
+    providerId?: string | undefined;
+    federatedId?: string | undefined;
+    photoUrl?: string | undefined;
+    oauthAccessToken?: string | undefined;
+    oauthExpireIn?: number | undefined;
+    rawUserInfo?: string | undefined;
+}, {
+    refreshToken: string;
+    idToken: string;
+    localId: string;
+    expiresIn: string;
+    email?: string | undefined;
+    kind?: string | undefined;
+    displayName?: string | undefined;
+    emailVerified?: boolean | undefined;
+    fullName?: string | undefined;
+    firstName?: string | undefined;
+    lastName?: string | undefined;
+    providerId?: string | undefined;
+    federatedId?: string | undefined;
+    photoUrl?: string | undefined;
+    oauthAccessToken?: string | undefined;
+    oauthExpireIn?: number | undefined;
+    rawUserInfo?: string | undefined;
+}>;
+export type GoogleSignInWithIdpResponse = z.infer<typeof googleSignInWithIdpResponseSchema>;
+export declare const googleTokenInfoSchema: z.ZodObject<{
+    sub: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    email_verified: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodString]>>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    expiry_date: z.ZodOptional<z.ZodNumber>;
+    azp: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    email?: string | undefined;
+    sub?: string | undefined;
+    email_verified?: string | boolean | undefined;
+    scopes?: string[] | undefined;
+    expiry_date?: number | undefined;
+    azp?: string | undefined;
+    aud?: string | undefined;
+}, {
+    email?: string | undefined;
+    sub?: string | undefined;
+    email_verified?: string | boolean | undefined;
+    scopes?: string[] | undefined;
+    expiry_date?: number | undefined;
+    azp?: string | undefined;
+    aud?: string | undefined;
+}>;
+export type GoogleTokenInfo = z.infer<typeof googleTokenInfoSchema>;

package/dist/schemas/webhooks/google-oauth.js

@@ -0,0 +1,39 @@
+// [SCHEMA] Google OAuth response envelopes (W7).
+//
+// Consumed by src/app/api/auth/google/callback/route.ts. Replaces the
+// `signInData.idToken` property-existence guard with a Zod parse.
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Firebase Identity Toolkit signInWithIdp response (subset we depend on).
+// ---------------------------------------------------------------------------
+export const googleSignInWithIdpResponseSchema = z.object({
+    federatedId: z.string().optional(),
+    providerId: z.string().optional(),
+    email: z.string().optional(),
+    emailVerified: z.boolean().optional(),
+    firstName: z.string().optional(),
+    fullName: z.string().optional(),
+    lastName: z.string().optional(),
+    photoUrl: z.string().optional(),
+    localId: z.string(),
+    displayName: z.string().optional(),
+    idToken: z.string(),
+    refreshToken: z.string(),
+    expiresIn: z.string(),
+    oauthAccessToken: z.string().optional(),
+    oauthExpireIn: z.number().int().optional(),
+    rawUserInfo: z.string().optional(),
+    kind: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// google-auth-library `getTokenInfo` shape (subset).
+// ---------------------------------------------------------------------------
+export const googleTokenInfoSchema = z.object({
+    sub: z.string().optional(),
+    email: z.string().optional(),
+    email_verified: z.union([z.boolean(), z.string()]).optional(),
+    scopes: z.array(z.string()).optional(),
+    expiry_date: z.number().int().optional(),
+    azp: z.string().optional(),
+    aud: z.string().optional(),
+});