@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/blog/actions/blog-actions.js

@@ -6,6 +6,8 @@ import { blogRepository } from "../repository/blog.repository.js";
 import { coerceMediaField, getMediaUrl } from "../../../utils/index.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 import { finalizeStagedMediaField, finalizeStagedMediaObject, finalizeStagedMediaObjectArray, } from "../../media/finalize.js";
+// Defining module, not the `../schemas` barrel — Root Cause #18.
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 // --- Schemas --------------------------------------------------------------
 const singleImageMediaSchema = z
     .union([
@@ -33,6 +35,11 @@ export const createBlogPostSchema = z.object({
     category: z.enum(["news", "tips", "guides", "updates", "community"]),
     tags: z.array(z.string()).default([]),
     isFeatured: z.boolean().default(false),
+    // `.default(false)` is required, not cosmetic: `isPinned` is the first key of
+    // the public default sort, and Firestore excludes a document that lacks an
+    // `orderBy` field (Root Cause #100). A create that omitted it would write a
+    // post that cannot appear on its own index.
+    isPinned: z.boolean().default(false),
     status: z.enum(["draft", "published", "archived"]).default("draft"),
     coverImage: singleImageMediaSchema,
     contentImages: z.array(mediaFieldSchema).max(10).optional().default([]),
@@ -108,8 +115,16 @@ export async function getFeaturedBlogPosts(count = 3) {
     return hidePublicTestData(result.items);
 }
 export async function getLatestBlogPosts(count = 5) {
-    const result = await blogRepository.listPublished({}, { sorts: sortBy("publishedAt", "DESC"), page: 1, pageSize: count });
-    return result.items;
+    const result = await blogRepository.listPublished({}, { sorts: BLOG_DEFAULT_PUBLIC_SORT, page: 1, pageSize: count });
+    /*
+     * 🛑 `hidePublicTestData` was MISSING here while its sibling
+     * `getFeaturedBlogPosts` has always had it. This function feeds the homepage
+     * `blog-articles` section, so the seeded sandbox post was reaching the
+     * busiest public page on the site — the exact shape
+     * `audit-public-test-data-leak` exists to block, in the one blog path it
+     * does not scan.
+     */
+    return hidePublicTestData(result.items);
 }
 export async function getBlogPostById(id) {
     return blogRepository.findById(id);

package/dist/features/blog/api/route.js

@@ -9,6 +9,7 @@
  * ```
  */
 import { blogRepository } from "../repository/blog.repository.js";
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 import { NextResponse } from "next/server.js";
 import { getProviders } from "../../../contracts/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
@@ -34,7 +35,9 @@ export async function GET(request) {
         const pageSize = url.searchParams.has("perPage")
             ? numParam(url, "perPage", 20)
             : numParam(url, "pageSize", 20);
-        const sort = param(url, "sort") ?? "-publishedAt";
+        // Must be the SAME constant the SSR view uses — the view's result becomes
+        // this route's `initialData` under `staleTime: Infinity` (Root Cause #30).
+        const sort = param(url, "sort") ?? BLOG_DEFAULT_PUBLIC_SORT;
         const parts = [];
         const category = param(url, "category");
         if (category)

package/dist/features/blog/columns/index.js

@@ -25,6 +25,11 @@ export const blogAdminColumns = [
         header: "Featured",
         render: (p) => (p.isFeatured ? "Yes" : "No"),
     },
+    {
+        key: "isPinned",
+        header: "Pinned",
+        render: (p) => (p.isPinned ? "Yes" : "No"),
+    },
     {
         key: "readTimeMinutes",
         header: "Read Time",

package/dist/features/blog/components/BlogIndexPageView.js

@@ -3,6 +3,7 @@ import { blogRepository } from "../../../repositories/index.js";
 import { Container, Heading, Main, Section } from "../../../ui/index.js";
 import { AdSlot } from "../../homepage/components/AdSlot.js";
 import { BlogIndexListing } from "./BlogIndexListing.js";
+import { BLOG_DEFAULT_PUBLIC_SORT } from "../schemas/firestore.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
 function sp(params, key) {
@@ -10,7 +11,7 @@ function sp(params, key) {
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
 }
 export async function BlogIndexPageView({ searchParams = {} }) {
-    const sort = sp(searchParams, "sort") || "-publishedAt";
+    const sort = sp(searchParams, "sort") || BLOG_DEFAULT_PUBLIC_SORT;
     const page = Number(sp(searchParams, "page")) || 1;
     const pageSize = Number(sp(searchParams, "pageSize")) || 24;
     const category = sp(searchParams, "category");

package/dist/features/blog/repository/blog.repository.d.ts

@@ -55,6 +55,10 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        isPinned: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         readTimeMinutes: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/blog/repository/blog.repository.js

@@ -223,6 +223,11 @@ BlogRepository.SIEVE_FIELDS = {
     authorName: { canFilter: true, canSort: true },
     authorId: { canFilter: true, canSort: false },
     isFeatured: { canFilter: true, canSort: false },
+    // canSort because it is the FIRST key of the default sort
+    // `-isPinned,-publishedAt`. A `canSort: false` field is silently dropped by
+    // sievejs (Root Cause #63), which would leave the index ordered by date
+    // alone and the pin doing nothing, with no error anywhere.
+    isPinned: { canFilter: true, canSort: true },
     readTimeMinutes: { canFilter: true, canSort: true },
     views: { canFilter: true, canSort: true },
     publishedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },

package/dist/features/blog/schemas/blog-form.d.ts

@@ -47,6 +47,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     publishedAt: z.ZodString;
     authorName: z.ZodString;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
 }, "strip", z.ZodTypeAny, {
     status: "published" | "draft" | "archived";
     title: string;
@@ -60,6 +61,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }, {
@@ -75,6 +77,7 @@ export declare const blogDraftSchema: z.ZodObject<{
     excerpt: string;
     coverImage: string;
     authorName: string;
+    isPinned: boolean;
     metaTitle: string;
     metaDescription: string;
 }>;

package/dist/features/blog/schemas/blog-form.js

@@ -97,4 +97,5 @@ export const blogDraftSchema = z.object({
     }),
     authorName: annotate(z.string(), { section: "publish", order: 3, row: "pair" }),
     isFeatured: annotate(z.boolean(), { section: "publish", order: 4, row: "quarter" }),
+    isPinned: annotate(z.boolean(), { section: "publish", order: 5, row: "quarter" }),
 });

package/dist/features/blog/schemas/firestore.d.ts

@@ -29,6 +29,23 @@ export interface BlogPostDocument extends BaseDocument {
     category: BlogPostCategory;
     tags: string[];
     isFeatured: boolean;
+    /**
+     * Keeps the post at the top of the blog index and the homepage
+     * `blog-articles` section, above newer posts.
+     *
+     * 🛑 REQUIRED, not optional, and that is load-bearing. The default sort is
+     * `-isPinned,-publishedAt`, and Firestore EXCLUDES a document that lacks an
+     * `orderBy` field (Root Cause #100) — so an optional `isPinned` would drop
+     * every pre-existing post out of its own index, silently, with a 200.
+     * A `mapDoc` default cannot rescue it either: that is a read-side fixup and
+     * a query never sees it (Root Cause #101). Every row needs a real `false`
+     * written, which is why the seed carries it explicitly.
+     *
+     * Distinct from `isFeatured` on purpose: featured drives the badge and the
+     * featured-card treatment, and there are several featured posts. Overloading
+     * it would make "featured" and "first" the same decision.
+     */
+    isPinned: boolean;
     status: BlogPostStatus;
     publishedAt?: Date;
     authorId: string;
@@ -40,7 +57,25 @@ export interface BlogPostDocument extends BaseDocument {
     metaDescription?: string;
 }
 export declare const BLOG_POSTS_COLLECTION: "blogPosts";
-export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "category", "slug"];
+export declare const BLOG_POSTS_INDEXED_FIELDS: readonly ["searchTxt", "status", "publishedAt", "isFeatured", "isPinned", "category", "slug"];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export declare const BLOG_DEFAULT_PUBLIC_SORT: "-isPinned,-publishedAt";
 export declare const BLOG_POST_FIELDS: {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     readonly SEARCH_TXT: "searchTxt";
@@ -56,6 +91,7 @@ export declare const BLOG_POST_FIELDS: {
     readonly CATEGORY: "category";
     readonly TAGS: "tags";
     readonly IS_FEATURED: "isFeatured";
+    readonly IS_PINNED: "isPinned";
     readonly STATUS: "status";
     readonly PUBLISHED_AT: "publishedAt";
     readonly AUTHOR_ID: "authorId";
@@ -89,6 +125,7 @@ export type BlogPostUpdateInput = Partial<Omit<BlogPostDocument, "id" | "created
 export declare const blogPostQueryHelpers: {
     readonly published: () => readonly ["status", "==", BlogPostStatus];
     readonly featured: () => readonly ["isFeatured", "==", true];
+    readonly pinned: () => readonly ["isPinned", "==", true];
     readonly byCategory: (category: BlogPostCategory) => readonly ["category", "==", BlogPostCategory];
     readonly bySlug: (slug: string) => readonly ["slug", "==", string];
     readonly byAuthor: (authorId: string) => readonly ["authorId", "==", string];

package/dist/features/blog/schemas/firestore.js

@@ -14,9 +14,28 @@ export const BLOG_POSTS_INDEXED_FIELDS = [
     "status",
     "publishedAt",
     "isFeatured",
+    "isPinned",
     "category",
     "slug",
 ];
+/**
+ * The default ordering for every PUBLIC blog surface — the `/blog` index, the
+ * `/api/blog` route that refetches it, and the homepage `blog-articles` feed.
+ *
+ * 🛑 ONE constant, three consumers, deliberately. The SSR view hands its result
+ * to the listing hook as `initialData`, and that hook sets `staleTime: Infinity`
+ * when given SSR data — so if the route's default sort differed from the view's
+ * by even a character, the first paint would be frozen in one order while the
+ * query key described another (Root Cause #30). Three literals is how that
+ * drift happens; one import is how it cannot.
+ *
+ * `isPinned` leads so pinned posts sit above newer ones. Needs the composite
+ * indexes on (status, isPinned DESC, publishedAt DESC) and its category /
+ * isFeatured / searchTxt variants — a multi-field sieve sort becomes two
+ * `orderBy` calls, and a missing index is a silent FAILED_PRECONDITION that
+ * every caller swallows into an empty page (Root Cause #2 / #59).
+ */
+export const BLOG_DEFAULT_PUBLIC_SORT = "-isPinned,-publishedAt";
 export const BLOG_POST_FIELDS = {
     /** Word-prefix search tokens. Derived on write by `buildSearchTxtFor`. */
     SEARCH_TXT: "searchTxt",
@@ -32,6 +51,7 @@ export const BLOG_POST_FIELDS = {
     CATEGORY: "category",
     TAGS: "tags",
     IS_FEATURED: "isFeatured",
+    IS_PINNED: "isPinned",
     STATUS: "status",
     PUBLISHED_AT: "publishedAt",
     AUTHOR_ID: "authorId",
@@ -64,6 +84,7 @@ export const DEFAULT_BLOG_POST_DATA = {
     category: "news",
     tags: [],
     isFeatured: false,
+    isPinned: false,
     status: "draft",
     authorId: "",
     authorName: "",
@@ -80,6 +101,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
     "category",
     "tags",
     "isFeatured",
+    "isPinned",
     "status",
     "publishedAt",
     "authorName",
@@ -94,6 +116,7 @@ export const BLOG_POST_PUBLIC_FIELDS = [
 export const blogPostQueryHelpers = {
     published: () => ["status", "==", "published"],
     featured: () => ["isFeatured", "==", true],
+    pinned: () => ["isPinned", "==", true],
     byCategory: (category) => ["category", "==", category],
     bySlug: (slug) => ["slug", "==", slug],
     byAuthor: (authorId) => ["authorId", "==", authorId],

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

@@ -99,6 +99,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     category: z.ZodString;
     tags: z.ZodArray<z.ZodString, "many">;
     isFeatured: z.ZodBoolean;
+    isPinned: z.ZodBoolean;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodString, z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -134,6 +135,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -187,6 +189,7 @@ export declare const blogPostFirestoreSchema: z.ZodObject<{
     authorId: string;
     authorName: string;
     readTimeMinutes: number;
+    isPinned: boolean;
     publishedAt?: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -343,6 +346,7 @@ export declare const blogPostSchema: z.ZodObject<{
     category: z.ZodEnum<["news", "tips", "guides", "updates", "community"]>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     isFeatured: z.ZodOptional<z.ZodBoolean>;
+    isPinned: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodEnum<["draft", "published", "archived"]>;
     publishedAt: z.ZodOptional<z.ZodString>;
     authorId: z.ZodOptional<z.ZodString>;
@@ -401,6 +405,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     authorAvatar?: string | undefined;
     metaTitle?: string | undefined;
     metaDescription?: string | undefined;
@@ -430,6 +435,7 @@ export declare const blogPostSchema: z.ZodObject<{
     authorId?: string | undefined;
     authorName?: string | undefined;
     readTimeMinutes?: number | undefined;
+    isPinned?: boolean | undefined;
     additionalImages?: {
         type: "video" | "image" | "file";
         url: string;

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

@@ -18,6 +18,7 @@ export const blogPostFirestoreSchema = z.object({
     category: z.string(),
     tags: z.array(z.string()),
     isFeatured: z.boolean(),
+    isPinned: z.boolean(),
     status: blogPostStatusEnumSchema,
     publishedAt: firestoreDateSchema.optional(),
     authorId: z.string(),
@@ -72,6 +73,7 @@ export const blogPostSchema = z.object({
     category: blogPostCategorySchema,
     tags: z.array(z.string()).optional(),
     isFeatured: z.boolean().optional(),
+    isPinned: z.boolean().optional(),
     status: blogPostStatusSchema,
     publishedAt: z.string().optional(),
     authorId: z.string().optional(),

package/dist/features/blog/types/index.d.ts

@@ -15,6 +15,8 @@ export interface BlogPost {
     category: BlogPostCategory;
     tags?: string[];
     isFeatured?: boolean;
+    /** Keeps the post above newer ones on the blog index and homepage. */
+    isPinned?: boolean;
     status: BlogPostStatus;
     publishedAt?: string;
     authorId?: string;

package/dist/features/cart/components/CartPriceBreakdown.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { FeeDerivations } from "../../../_internal/shared/fees/explain";
 /**
  * The aggregate price breakdown shown in the cart's expandable preview and in
  * the checkout Order Summary.
@@ -32,6 +33,11 @@ export interface CartPriceBreakdownStore {
     supportsShippingProtection: boolean;
     supportsSaleProtection: boolean;
     hasFinalSaleItem: boolean;
+    /** D46/D47 + decision 22 — whether this seller accepts points, and how many. */
+    acceptsPoints: boolean;
+    pointsApplied: number;
+    /** S5a — handling + extra shipping legs for this store's order. */
+    sharedPurchaseFee: number;
 }
 /** Mirrors `CheckoutPricingPreview` without importing server code. */
 export interface CartPriceBreakdownData {
@@ -46,7 +52,15 @@ export interface CartPriceBreakdownData {
     couponDiscount: number;
     platformFee: number;
     gstOnFee: number;
+    /** S5a — handling + extra shipping legs across the cart. */
+    sharedPurchaseFee: number;
     total: number;
+    /** D46/D47 — points applied across every accepting store. */
+    pointsApplied: number;
+    /** What the buyer actually pays: `total − pointsApplied`. */
+    amountDue: number;
+    /** Their remaining balance, for the toggle's own label. */
+    pointsBalance: number;
     stores: CartPriceBreakdownStore[];
 }
 export interface CartPriceBreakdownProps {
@@ -73,5 +87,15 @@ export interface CartPriceBreakdownProps {
     errorNote?: React.ReactNode;
     isLoading?: boolean;
     className?: string;
+    /**
+     * Per-line "why am I paying this" disclosures, built by the
+     * `explain*` helpers in `_internal/shared/fees/explain`.
+     *
+     * 🛑 Optional, and an absent entry renders no disclosure rather than a
+     * placeholder. The cart renders this breakdown for a signed-out guest with
+     * no server preview at all — a line that cannot be explained must say
+     * nothing, never "we could not work this out", which reads as a fault.
+     */
+    derivations?: FeeDerivations;
 }
-export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, }: CartPriceBreakdownProps): React.JSX.Element;
+export declare function CartPriceBreakdown({ preview, itemCount, currency, unavailableNote, fallbackSubtotal, errorNote, isLoading, className, derivations, }: CartPriceBreakdownProps): React.JSX.Element;

package/dist/features/cart/components/CartPriceBreakdown.js

@@ -1,15 +1,34 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Details, Div, Row, Stack, Summary, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
-function Line({ label, amount, tone = "muted", strong = false, }) {
-    return (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+/**
+ * The "how is this calculated?" disclosure under a fee line.
+ *
+ * 🛑 Collapsed by default, and that is the whole design. An unexplained charge
+ * is untrustworthy, but five expanded derivations turn the Order Summary into
+ * a wall of arithmetic at the moment a buyer is deciding to pay. The
+ * obligation is that the answer is *available at the point of the charge* —
+ * not that it is shouted.
+ *
+ * A native `<details>` rather than a tooltip or a modal: it works before
+ * hydration, it is keyboard-reachable for free, and it does not cover the
+ * number it is explaining.
+ */
+function Derivation({ derivation }) {
+    return (_jsxs(Details, { tone: "muted", padding: "sm", rounded: "md", children: [_jsx(Summary, { size: "xs", color: "muted", children: "How is this calculated?" }), _jsxs(Stack, { gap: "xs", className: "pt-[var(--appkit-space-2)]", children: [_jsx(Text, { size: "xs", color: "muted", children: derivation.summary }), derivation.steps.map((step, i) => (_jsx(Text, { size: "xs", color: "faint", className: "tabular-nums", children: step }, i)))] })] }));
+}
+function Line({ label, amount, tone = "muted", strong = false, derivation, }) {
+    const row = (_jsxs(Row, { align: "center", justify: "between", gap: "sm", className: "min-w-0", children: [_jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "min-w-0", truncate: 1, children: label }), _jsx(Text, { size: "sm", color: tone, weight: strong ? "semibold" : undefined, className: "flex-shrink-0 tabular-nums", children: amount })] }));
+    if (!derivation)
+        return row;
+    return (_jsxs(Stack, { gap: "xs", children: [row, _jsx(Derivation, { derivation: derivation })] }));
 }
 /** "Shipping (2 stores)" — only qualifies when more than one store contributes. */
 function withStoreCount(label, count) {
     return count > 1 ? `${label} (${count} stores)` : label;
 }
-export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", }) {
+export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unavailableNote, fallbackSubtotal = 0, errorNote, isLoading = false, className = "", derivations, }) {
     const money = (value) => formatCurrency(value, currency);
     if (!preview) {
         return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: itemCount !== undefined ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""})` : "Subtotal", amount: money(fallbackSubtotal) }), (errorNote ?? unavailableNote) && (_jsx(Text, { size: "xs", color: errorNote ? "error" : "muted", children: errorNote ?? unavailableNote }))] }));
@@ -21,5 +40,9 @@ export function CartPriceBreakdown({ preview, itemCount, currency = "INR", unava
     const subtotalLabel = itemCount !== undefined
         ? `Subtotal (${itemCount} item${itemCount !== 1 ? "s" : ""}${storeCount > 1 ? `, ${storeCount} stores` : ""})`
         : "Subtotal";
-    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee) })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge) })), preview.platformFee > 0 && _jsx(Line, { label: "Platform fee", amount: money(preview.platformFee) }), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee) })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: true }) }), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
+    return (_jsxs(Stack, { gap: "xs", className: className, children: [_jsx(Line, { label: subtotalLabel, amount: money(preview.subtotal) }), preview.shippingFee > 0 && (_jsx(Line, { label: withStoreCount("Shipping", storeCount), amount: money(preview.shippingFee) })), preview.codHandlingFee > 0 && (_jsx(Line, { label: "COD handling fee", amount: money(preview.codHandlingFee), derivation: derivations?.codHandlingFee })), preview.giftWrapFee > 0 && (_jsx(Line, { label: withStoreCount("Gift wrap", countCharged((s) => s.giftWrapFee)), amount: money(preview.giftWrapFee) })), preview.shipmentProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Shipment protection", countCharged((s) => s.shipmentProtectionFee)), amount: money(preview.shipmentProtectionFee) })), preview.saleProtectionFee > 0 && (_jsx(Line, { label: withStoreCount("Sale protection", countCharged((s) => s.saleProtectionFee)), amount: money(preview.saleProtectionFee) })), preview.emiSurcharge > 0 && (_jsx(Line, { label: "EMI surcharge", amount: money(preview.emiSurcharge), derivation: derivations?.emiSurcharge })), preview.sharedPurchaseFee > 0 && (_jsx(Line, { label: withStoreCount("Split delivery", countCharged((s) => s.sharedPurchaseFee)), amount: money(preview.sharedPurchaseFee) })), preview.platformFee > 0 && (_jsx(Line, { label: "Platform fee", amount: money(preview.platformFee), derivation: derivations?.platformFee })), preview.gstOnFee > 0 && (_jsx(Line, { label: "GST on platform fee", amount: money(preview.gstOnFee), derivation: derivations?.gstOnFee })), preview.couponDiscount > 0 && (_jsx(Line, { label: "Coupon discount", amount: `−${money(preview.couponDiscount)}`, tone: "success" })), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Total", amount: money(preview.total), tone: "primary", strong: preview.pointsApplied <= 0 }) }), preview.pointsApplied > 0 && (_jsxs(_Fragment, { children: [_jsx(Line, { label: `Points applied (${preview.pointsApplied.toLocaleString("en-IN")} pts)`, amount: `−${money(preview.pointsApplied)}`, tone: "success" }), _jsx(Div, { border: "top-subtle", paddingY: "t-sm", children: _jsx(Line, { label: "Amount due", amount: money(preview.amountDue), tone: "primary", strong: true }) })] })), preview.pointsApplied > 0 && preview.pointsBalance > preview.pointsApplied && (_jsxs(Text, { size: "xs", color: "muted", children: [(preview.pointsBalance - preview.pointsApplied).toLocaleString("en-IN"), " points stay in your balance \u2014 up to half of an order can be paid with points."] })), preview.pointsApplied === 0 && preview.pointsBalance > 0 && (_jsx(Text, { size: "xs", color: "muted", children: preview.stores.some((s) => s.acceptsPoints)
+                    ? "Your points could not be applied to this order."
+                    : storeCount > 1
+                        ? "None of these sellers accepts points."
+                        : "This seller does not accept points." })), preview.gstAmount > 0 && (_jsxs(Text, { size: "xs", color: "muted", children: ["Includes GST of ", money(preview.gstAmount)] })), errorNote ? (_jsx(Text, { size: "xs", color: "error", children: errorNote })) : (isLoading && (_jsx(Text, { size: "xs", color: "muted", children: "Updating\u2026" })))] }));
 }

package/dist/features/cart/components/PointsTenderPicker.d.ts

@@ -0,0 +1,61 @@
+import React from "react";
+/**
+ * "Pay with my points" — one checkbox for the whole cart (D46/D47).
+ *
+ * ## Why ONE control for the cart, where add-ons get one per store
+ *
+ * An add-on is a thing the buyer buys from a particular seller, so choosing it
+ * per seller is the only coherent shape. Points are the buyer's own balance:
+ * they do not belong to a seller, and asking "how many of your points would you
+ * like to spend at each of these three shops" is a question nobody wants to
+ * answer. So the buyer opts in once and the server spends what it can, in group
+ * order, at the sellers who accept them (decision 22).
+ *
+ * ## 🛑 A checkbox and NOT a number input, deliberately
+ *
+ * Decision 24: tick it and as many points as the 50% cap allows are applied;
+ * whatever cannot be applied stays in the balance for a later order. Nothing is
+ * forfeited, so there is no amount worth agonising over — and more importantly,
+ * an amount the client can send is an amount the client can lie about. The
+ * figure is always derived server-side from the live balance.
+ *
+ * ## It renders nothing when there is nothing to offer
+ *
+ * A zero balance gets no control at all rather than a disabled one. A disabled
+ * checkbox beside "0 points" is an advertisement, and the place to advertise
+ * the programme is the points page, not the cart of somebody who cannot use it.
+ */
+export interface PointsTenderPickerProps {
+    /** Current cart flag. */
+    value: boolean;
+    onChange: (next: boolean) => void;
+    /**
+     * The buyer's live balance, in points (1 point = ₹1).
+     *
+     * 🛑 Zero when the cart has not opted in, because the server only reads a
+     * balance it is going to use — so this cannot be relied on to decide whether
+     * to RENDER. `hasBalance` below exists for that.
+     */
+    balance: number;
+    /**
+     * Points actually applied to this cart, from the server preview. Undefined
+     * while the preview is in flight.
+     */
+    applied?: number;
+    /**
+     * Whether the buyer has ANY points, independent of the opt-in state.
+     *
+     * Separate from `balance` for the reason above: with the toggle off the
+     * preview returns `pointsBalance: 0`, so a control gated on `balance > 0`
+     * could never be switched back on once switched off — a one-way door, the
+     * `BackToTop` failure in Root Cause #41.
+     */
+    hasBalance: boolean;
+    /** No store in the cart accepts points — the control says so instead of hiding. */
+    noAcceptingStore?: boolean;
+    currency?: string;
+    disabled?: boolean;
+    disabledReason?: string;
+    className?: string;
+}
+export declare function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore, currency, disabled, disabledReason, className, }: PointsTenderPickerProps): React.JSX.Element | null;

package/dist/features/cart/components/PointsTenderPicker.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { IconBox } from "../../../ui/components/IconBox.js";
+import { Icon } from "../../../ui/components/Icon.js";
+import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+export function PointsTenderPicker({ value, onChange, balance, applied, hasBalance, noAcceptingStore = false, currency = "INR", disabled = false, disabledReason, className = "", }) {
+    if (!hasBalance)
+        return null;
+    const shownBalance = value ? balance : 0;
+    return (_jsx(Div, { surface: "muted", rounded: "lg", padding: "sm", className: className, children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Row, { align: "center", gap: "sm", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "brand", rounded: "lg", children: _jsx(Icon, { name: "points", size: "sm" }) }), _jsx(Div, { className: "min-w-0 flex-1", children: _jsx(FieldCheckbox, { name: "useAllPoints", label: "Pay with my points", checked: value, onChange: onChange, disabled: disabled || noAcceptingStore }) })] }), noAcceptingStore ? (_jsx(Text, { size: "xs", color: "muted", children: "Points cannot be used with the seller(s) in this cart." })) : disabled && disabledReason ? (_jsx(Text, { size: "xs", color: "muted", children: disabledReason })) : value && applied !== undefined ? (applied > 0 ? (_jsxs(Text, { size: "xs", color: "muted", children: [applied.toLocaleString("en-IN"), " points applied (", formatCurrency(applied, currency), ")", shownBalance > applied
+                            ? ` · ${(shownBalance - applied).toLocaleString("en-IN")} left over`
+                            : ""] })) : (_jsx(Text, { size: "xs", color: "muted", children: "No points could be applied to this order." }))) : (_jsx(Text, { size: "xs", color: "muted", children: "Up to half of an order can be paid with points." }))] }) }));
+}

package/dist/features/cart/components/StoreAddonsPicker.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Gift, ShieldAlert, ShieldCheck, ShieldOff } from "lucide-react";
 import { Div, Row, Stack, Text } from "../../../ui/index.js";
+import { Disclaimer } from "../../../ui/components/Disclaimer.js";
 import { IconBox } from "../../../ui/components/IconBox.js";
 import { FieldCheckbox } from "../../../ui/forms/FieldCheckbox.js";
 import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
@@ -54,5 +55,5 @@ export function StoreAddonsPicker({ storeId, storeSubtotal, value, onChange, rat
                             ? "This seller does not offer shipment or sale protection."
                             : shippingDeclined
                                 ? "This seller does not offer shipment protection."
-                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] }))] }));
+                                : "This seller does not offer sale protection." })] })), saleBlockedByFinalSale && (_jsxs(Row, { gap: "sm", align: "start", className: "min-w-0", children: [_jsx(IconBox, { size: "sm", tone: "muted", children: _jsx(ShieldOff, { size: 14 }) }), _jsx(Text, { size: "xs", color: "muted", className: "flex-1 min-w-0", children: "Sale protection is not available \u2014 this basket contains a final-sale item. Shipment protection is unaffected." })] })), (shippingOffered || saleOffered) && _jsx(Disclaimer, { id: "protection-cover", inline: true })] }));
 }

package/dist/features/cart/components/index.d.ts

@@ -7,6 +7,8 @@ export { CartSummary } from "./CartSummary";
 export type { CartSummaryProps } from "./CartSummary";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker";
 export type { StoreAddonsPickerProps, StoreAddonsValue, StoreAddonsRates, } from "./StoreAddonsPicker";
+export { PointsTenderPicker } from "./PointsTenderPicker";
+export type { PointsTenderPickerProps } from "./PointsTenderPicker";
 export { CartPriceBreakdown } from "./CartPriceBreakdown";
 export type { CartPriceBreakdownProps, CartPriceBreakdownData, CartPriceBreakdownStore, } from "./CartPriceBreakdown";
 export { CheckoutView } from "./CheckoutView";

package/dist/features/cart/components/index.js

@@ -3,6 +3,7 @@ export { CartGroupLineRow } from "./CartGroupLineRow.js";
 export { CartView } from "./CartView.js";
 export { CartSummary } from "./CartSummary.js";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./StoreAddonsPicker.js";
+export { PointsTenderPicker } from "./PointsTenderPicker.js";
 export { CartPriceBreakdown } from "./CartPriceBreakdown.js";
 export { CheckoutView } from "./CheckoutView.js";
 export { CheckoutAddressStep } from "./CheckoutAddressStep.js";

package/dist/features/cart/repository/cart.repository.d.ts

@@ -129,6 +129,39 @@ export declare class CartRepository extends BaseRepository<CartDocument> {
      * and keeping both shapes around invites readers that handle only one.
      */
     setStoreAddons(userId: string, storeId: string, addons: CartStoreAddons | null): Promise<void>;
+    /**
+     * Opt the cart in or out of paying with points (D46/D47, decision 24).
+     *
+     * 🛑 A BOOLEAN, and the schema deliberately has no numeric sibling. Opt in
+     * and the server applies as many points as the 50% cap allows; whatever
+     * cannot be applied stays in the balance for a later order. A client-supplied
+     * amount is a client-supplied discount, which is the whole reason
+     * `storeAddons` is the source of truth for add-on fees rather than a request
+     * body.
+     *
+     * Written with the same `set(..., { merge: true })` as its neighbours so a
+     * concurrent add-on or selection write is not clobbered.
+     *
+     * 🛑 Opting OUT deletes the field rather than writing `false` — absent and
+     * `false` mean the same thing to every reader (`cart.useAllPoints === true`),
+     * and keeping both shapes invites a reader that handles only one. Same
+     * reasoning as `setStoreAddons` directly above.
+     */
+    /**
+     * Set or clear the instalment plan.
+     *
+     * 🛑 `null` DELETES the field rather than storing `{ optIn: false }`. The
+     * schema's rule is that absent means "no instalments", so a second
+     * representation of the same state is one more thing every reader has to
+     * get right (Root Cause #42's shape). `tenureMonths` is stored verbatim and
+     * validated against the live `emi.tenureOptions` at order time — the admin
+     * can change those options after a cart was saved, so validating here would
+     * freeze a tenure that is no longer offered.
+     */
+    setEmiPlan(userId: string, plan: {
+        tenureMonths: number;
+    } | null): Promise<void>;
+    setUseAllPoints(userId: string, useAllPoints: boolean): Promise<void>;
     /**
      * Cloud Functions: return refs of stale carts not updated within TTL.
      */