@mohasinac/appkit 4.2.0 → 4.3.1

package/dist/features/auctions/components/PlaceBidFormClient.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useTransition } from "react";
+import { useRouter } from "next/navigation";
 import { formatCurrency } from "../../../utils/number.formatter";
 import { isAuthError } from "../../../utils/auth-error";
 import { Button, Div, LoginRequiredModal, Modal, Row, Span, Stack, Text } from "../../../ui";
@@ -8,6 +9,7 @@ import { Form } from "../../../ui/components/Form";
 import { FieldInput } from "../../../ui/forms/FieldInput";
 import { applyZodIssues } from "../../../ui/forms/FormShell";
 import { placeBidSchema } from "../schemas/bid-input";
+import { useLiveAuctionBid } from "../hooks/useLiveAuctionBid";
 import { normalizeError } from "../../../errors/normalize";
 const __P = {
     p5: "p-[var(--appkit-space-5)]",
@@ -19,7 +21,13 @@ const BID_ERROR_DISPLAY = {
     BID_SELF_BID: "You cannot bid on your own listing.",
     BID_USER_BANNED: "Your account is currently restricted from bidding. Contact support.",
 };
-export function PlaceBidFormClient({ productId, currentBid, startingBid, minBidIncrement, currency, isEnded, buyNowPrice, bidsHaveStarted = false, bidCount, tags = [], onPlaceBid, onBuyNow, }) {
+export function PlaceBidFormClient({ productId, currentBid: ssrCurrentBid, startingBid, minBidIncrement, currency, isEnded, buyNowPrice, bidsHaveStarted = false, bidCount: ssrBidCount, tags = [], onPlaceBid, onBuyNow, }) {
+    const router = useRouter();
+    // Live-updates while the bid card is open — reflects other bidders'
+    // activity on this auction, not just the bidder's own submission.
+    const live = useLiveAuctionBid(productId, ssrCurrentBid, ssrBidCount, { enabled: !isEnded });
+    const currentBid = live.currentBid;
+    const bidCount = live.bidCount;
     const minBid = currentBid + minBidIncrement;
     const [bidAmount, setBidAmount] = useState(String(minBid));
     const [stepMul, setStepMul] = useState(1);
@@ -44,6 +52,12 @@ export function PlaceBidFormClient({ productId, currentBid, startingBid, minBidI
             setSuccess(true);
             setBidAmount(String(amount + minBidIncrement));
             setStepMul(1);
+            // The bid history list and any duplicated static current-bid/bid-count
+            // text elsewhere on this SSR'd page (info panel, page-level summary
+            // cards) are frozen server props — refresh so they reflect this bid
+            // immediately instead of waiting for the page's ISR window to roll
+            // over. The live price shown above already updated via SSE regardless.
+            router.refresh();
         }
         catch (err) {
             void normalizeError(err);
@@ -78,6 +92,7 @@ export function PlaceBidFormClient({ productId, currentBid, startingBid, minBidI
                     return;
                 }
                 setSuccess(true);
+                router.refresh();
             }
             catch (err) {
                 void normalizeError(err);

package/dist/features/auctions/hooks/useBids.d.ts

@@ -0,0 +1,33 @@
+import type { BidDocument } from "../schemas/firestore";
+export interface BidListResponse {
+    items: Omit<BidDocument, "userEmail">[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+export interface UseBidsParams {
+    productId: string;
+    page?: number;
+    pageSize?: number;
+}
+export interface UseBidsOptions {
+    initialData?: BidListResponse;
+    enabled?: boolean;
+}
+/**
+ * useBids
+ *
+ * Paginated, newest-first bid history for a single auction — backs the
+ * auction detail page's "Bid History" section. `/api/bids` already sorts
+ * `bidDate DESC` server-side (see `listBidsByProduct`), so no client sort
+ * is needed here.
+ */
+export declare function useBids(params: UseBidsParams, opts?: UseBidsOptions): {
+    bids: Omit<BidDocument, "userEmail">[];
+    total: number;
+    totalPages: number;
+    isLoading: boolean;
+    error: Error | null;
+};

package/dist/features/auctions/hooks/useBids.js

@@ -0,0 +1,32 @@
+import { useQuery } from "@tanstack/react-query";
+import { apiClient } from "../../../http";
+import { BID_ENDPOINTS } from "../../../constants/api-endpoints";
+/**
+ * useBids
+ *
+ * Paginated, newest-first bid history for a single auction — backs the
+ * auction detail page's "Bid History" section. `/api/bids` already sorts
+ * `bidDate DESC` server-side (see `listBidsByProduct`), so no client sort
+ * is needed here.
+ */
+export function useBids(params, opts) {
+    const { productId, page = 1, pageSize = 5 } = params;
+    const sp = new URLSearchParams();
+    sp.set("productId", productId);
+    sp.set("page", String(page));
+    sp.set("pageSize", String(pageSize));
+    const endpoint = `${BID_ENDPOINTS.LIST}?${sp.toString()}`;
+    const query = useQuery({
+        queryKey: ["bids", productId, page, pageSize],
+        queryFn: () => apiClient.get(endpoint),
+        initialData: page === 1 ? opts?.initialData : undefined,
+        enabled: opts?.enabled !== false && !!productId,
+    });
+    return {
+        bids: query.data?.items ?? [],
+        total: query.data?.total ?? 0,
+        totalPages: query.data?.totalPages ?? 1,
+        isLoading: query.isLoading,
+        error: query.error,
+    };
+}

package/dist/features/auctions/hooks/useLiveAuctionBid.d.ts

@@ -0,0 +1,20 @@
+export interface UseLiveAuctionBidResult {
+    currentBid: number;
+    bidCount: number;
+    /** True once the SSE channel has delivered at least one live update. */
+    isLive: boolean;
+}
+/**
+ * useLiveAuctionBid
+ *
+ * Layers the SSE-driven `useRealtimeBids` channel on top of the auction
+ * detail page's SSR-rendered `currentBid`/`bidCount` (server props, frozen
+ * at request time / the page's ISR window). Falls back to those SSR values
+ * until the live channel connects and pushes its first update — this is
+ * what lets any viewer watching an auction see a new bid the instant
+ * another user places it, mirroring how the cart/wishlist badges layer a
+ * live delta on top of the last known server count.
+ */
+export declare function useLiveAuctionBid(productId: string, ssrCurrentBid: number, ssrBidCount: number, opts?: {
+    enabled?: boolean;
+}): UseLiveAuctionBidResult;

package/dist/features/auctions/hooks/useLiveAuctionBid.js

@@ -0,0 +1,23 @@
+"use client";
+import { useRealtimeBids } from "./useRealtimeBids";
+/**
+ * useLiveAuctionBid
+ *
+ * Layers the SSE-driven `useRealtimeBids` channel on top of the auction
+ * detail page's SSR-rendered `currentBid`/`bidCount` (server props, frozen
+ * at request time / the page's ISR window). Falls back to those SSR values
+ * until the live channel connects and pushes its first update — this is
+ * what lets any viewer watching an auction see a new bid the instant
+ * another user places it, mirroring how the cart/wishlist badges layer a
+ * live delta on top of the last known server count.
+ */
+export function useLiveAuctionBid(productId, ssrCurrentBid, ssrBidCount, opts) {
+    const enabled = opts?.enabled !== false;
+    const live = useRealtimeBids(enabled ? productId : null);
+    const isLive = live.connected && live.currentBid !== null;
+    return {
+        currentBid: isLive ? live.currentBid : ssrCurrentBid,
+        bidCount: isLive && live.bidCount !== null ? live.bidCount : ssrBidCount,
+        isLive,
+    };
+}

package/dist/features/auth/checkout-value-otp.d.ts

@@ -1,17 +1,13 @@
 /**
  * Checkout Value OTP — Tier PP.
  *
- * A distinct OTP purpose from `consent-otp.ts` (which gates third-party
- * shipping consent): this one gates placing a checkout ≥ the site's
- * `payment.otpCheckoutThreshold` (skipped for COD — see
- * `createCheckoutOrderAction`). Deliberately a SEPARATE Firestore namespace
- * (`checkoutValueOtps` vs `consentOtps`) rather than reusing the shipping-
- * consent one — different purpose, different copy, independently tunable
- * rate limits. Reuses `generateOtpCode()`/`hashOtp()` from `consent-otp.ts`
- * rather than duplicating the crypto.
+ * Gates placing a checkout ≥ the site's `payment.otpCheckoutThreshold`
+ * (skipped for COD — see `createCheckoutOrderAction`).
  */
-import { generateOtpCode, hashOtp } from "./consent-otp";
-export { generateOtpCode, hashOtp };
+/** HMAC-SHA256 hash of an OTP code. */
+export declare function hashOtp(code: string): string;
+/** Generate a cryptographically-secure random 6-digit OTP string. */
+export declare function generateOtpCode(): string;
 /** OTP validity window (10 minutes) — matches consent-OTP's window; independently tunable if policy diverges later. */
 export declare const CHECKOUT_VALUE_OTP_EXPIRY_MS: number;
 export declare const CHECKOUT_VALUE_OTP_EXPIRY_MINUTES = 10;
@@ -44,3 +40,4 @@ export interface CheckoutValueOtpDoc {
 export declare function enforceCheckoutValueOtpRateLimit(db: Db, uid: string): Promise<void>;
 /** Build the checkout-value OTP WhatsApp/SMS message body. */
 export declare function buildCheckoutValueOtpMessage(code: string, siteName: string): string;
+export {};

package/dist/features/auth/checkout-value-otp.js

@@ -1,20 +1,24 @@
 /**
  * Checkout Value OTP — Tier PP.
  *
- * A distinct OTP purpose from `consent-otp.ts` (which gates third-party
- * shipping consent): this one gates placing a checkout ≥ the site's
- * `payment.otpCheckoutThreshold` (skipped for COD — see
- * `createCheckoutOrderAction`). Deliberately a SEPARATE Firestore namespace
- * (`checkoutValueOtps` vs `consentOtps`) rather than reusing the shipping-
- * consent one — different purpose, different copy, independently tunable
- * rate limits. Reuses `generateOtpCode()`/`hashOtp()` from `consent-otp.ts`
- * rather than duplicating the crypto.
+ * Gates placing a checkout ≥ the site's `payment.otpCheckoutThreshold`
+ * (skipped for COD — see `createCheckoutOrderAction`).
  */
+import { createHmac, randomInt } from "crypto";
 import { AuthorizationError } from "../../errors";
 import { resolveDate } from "../../utils";
 import { USER_COLLECTION } from "./schemas";
-import { generateOtpCode, hashOtp } from "./consent-otp";
-export { generateOtpCode, hashOtp };
+const HMAC_KEY = process.env.CONSENT_OTP_HMAC_KEY ||
+    process.env.HMAC_SECRET ||
+    "consent-otp-secret";
+/** HMAC-SHA256 hash of an OTP code. */
+export function hashOtp(code) {
+    return createHmac("sha256", HMAC_KEY).update(code).digest("hex");
+}
+/** Generate a cryptographically-secure random 6-digit OTP string. */
+export function generateOtpCode() {
+    return String(randomInt(100000, 1000000));
+}
 /** OTP validity window (10 minutes) — matches consent-OTP's window; independently tunable if policy diverges later. */
 export const CHECKOUT_VALUE_OTP_EXPIRY_MS = 10 * 60 * 1000;
 export const CHECKOUT_VALUE_OTP_EXPIRY_MINUTES = 10;

package/dist/features/auth/server.d.ts

@@ -14,7 +14,6 @@
  * ```
  */
 export * from "./token-store";
-export * from "./consent-otp";
 export * from "./repository";
 export * from "./actions";
 export { authMeGET } from "./api/route";

package/dist/features/auth/server.js

@@ -14,7 +14,6 @@
  * ```
  */
 export * from "./token-store";
-export * from "./consent-otp";
 export * from "./repository";
 export * from "./actions";
 export { authMeGET } from "./api/route";

package/dist/features/blog/api/[slug]/route.d.ts

@@ -17,7 +17,12 @@ type RouteContext = {
 };
 export interface BlogPostDetailResponse {
     post: BlogPost;
+    /** Same category — the original single "related" signal. */
     related: BlogPost[];
+    /** Posts sharing at least one tag. */
+    relatedByTags: BlogPost[];
+    /** Other posts by the same author. */
+    relatedByAuthor: BlogPost[];
 }
 export declare function GET(_request: Request, context: RouteContext): Promise<NextResponse>;
 export {};

package/dist/features/blog/api/[slug]/route.js

@@ -30,9 +30,18 @@ export async function GET(_request, context) {
         }
         // Increment view count fire-and-forget — must not block response
         safeFireAndForget(blogRepository.incrementViews(post.id), "blog: incrementViews");
-        // Related posts: same category, latest 3, excluding current
-        const related = (await blogRepository.findRelated(post.category, post.id, 3)).map(toBlogPost);
-        const body = { post: toBlogPost(post), related };
+        // Related posts: same category / tag overlap / same author — latest 3 each, excluding current
+        const [related, relatedByTags, relatedByAuthor] = await Promise.all([
+            blogRepository.findRelated(post.category, post.id, 3),
+            blogRepository.findByTagsOverlap(post.tags ?? [], post.id, 3),
+            blogRepository.findByAuthor(post.authorId, post.id, 3),
+        ]);
+        const body = {
+            post: toBlogPost(post),
+            related: related.map(toBlogPost),
+            relatedByTags: relatedByTags.map(toBlogPost),
+            relatedByAuthor: relatedByAuthor.map(toBlogPost),
+        };
         return NextResponse.json({ success: true, data: body });
     }
     catch (error) {

package/dist/features/blog/components/BlogPostView.d.ts

@@ -14,6 +14,8 @@ export interface BlogPostViewProps {
         viewsLabel?: string;
         featured?: string;
         relatedTitle?: string;
+        relatedByTagsTitle?: string;
+        relatedByAuthorTitle?: string;
     };
     /** Render the cover image */
     renderImage?: (post: BlogPost) => React.ReactNode;

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

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import React from "react";
 import Link from "next/link";
 import { Div, Heading, RichText, Row, Scrim, Span, Stack, Text } from "../../../ui";
+import { Iframe } from "../../../ui/components/Iframe";
 import { MediaImage } from "../../media/MediaImage";
 import { useBlogPost } from "../hooks/useBlog";
 import { BlogCard } from "./BlogListView";
@@ -27,13 +28,13 @@ const CLS_FEATURED_BADGE = "bg-warning-surface text-warning dark:bg-warning-surf
 function renderBlogPostHeader(post, date, labels) {
     return (_jsxs(Div, { className: "mb-8", children: [_jsxs(Row, { className: "mb-4", gap: "sm", children: [_jsx(Span, { size: "xs", weight: "medium", className: `inline-block capitalize ${CATEGORY_BADGE[post.category] ?? ""}`, rounded: "full", padding: "pill-xs", children: post.category }), post.isFeatured && _jsx(Span, { size: "xs", weight: "medium", className: CLS_FEATURED_BADGE, children: labels?.featured ?? "Featured" })] }), _jsx(Heading, { level: 1, className: "mb-4", size: "3xl", weight: "bold", children: post.title }), post.excerpt && _jsx(Text, { className: "mb-6", color: "muted", size: "lg", children: post.excerpt }), _jsxs(Row, { color: "muted", textSize: "sm", wrap: true, gap: "md", children: [post.authorName && _jsxs(Span, { children: [labels?.author ?? "By", " ", _jsx(Span, { weight: "medium", color: "muted", children: post.authorName })] }), post.readTimeMinutes != null && _jsxs(Span, { children: [post.readTimeMinutes, " ", labels?.readTime ?? "min read"] }), date && _jsxs(Span, { children: [labels?.publishedOn ?? "Published", " ", date] }), post.views != null && _jsxs(Span, { children: [post.views, " ", labels?.viewsLabel ?? "views"] })] })] }));
 }
-function renderBlogPostRelated(related, labels, renderRelatedCard) {
+function renderBlogPostRelated(related, title, renderRelatedCard) {
     if (related.length === 0)
         return null;
-    return (_jsxs(Div, { children: [_jsx(Heading, { level: 2, className: "mb-6", size: "xl", weight: "semibold", children: labels?.relatedTitle ?? "Related Posts" }), _jsx(Div, { layout: "grid", gap: "6", className: "sm:grid-cols-3", children: related.map((rel, i) => renderRelatedCard ? (_jsx(React.Fragment, { children: renderRelatedCard(rel, i) }, rel.id)) : (_jsx(BlogCard, { post: rel, href: String(ROUTES.BLOG.ARTICLE(rel.slug)) }, rel.id))) })] }));
+    return (_jsxs(Div, { children: [_jsx(Heading, { level: 2, className: "mb-6", size: "xl", weight: "semibold", children: title }), _jsx(Div, { layout: "grid", gap: "6", className: "sm:grid-cols-3", children: related.map((rel, i) => renderRelatedCard ? (_jsx(React.Fragment, { children: renderRelatedCard(rel, i) }, rel.id)) : (_jsx(BlogCard, { post: rel, href: String(ROUTES.BLOG.ARTICLE(rel.slug)) }, rel.id))) })] }));
 }
 export function BlogPostView({ slug, initialData, labels = {}, renderImage, renderContent, renderBackButton, renderLoading, renderError, renderRelatedCard, renderAuthorBio, className = "", }) {
-    const { post, related, isLoading, error } = useBlogPost(slug, {
+    const { post, related, relatedByTags, relatedByAuthor, isLoading, error } = useBlogPost(slug, {
         initialData,
     });
     if (isLoading) {
@@ -54,5 +55,5 @@ export function BlogPostView({ slug, initialData, labels = {}, renderImage, rend
         })
         : "";
     const coverImageUrl = getMediaUrl(post.coverImage);
-    return (_jsxs(Div, { className: `min-h-screen ${className}`, children: [coverImageUrl && (_jsxs(Div, { className: `relative h-72 md:h-96 ${__O.hidden}`, children: [renderImage ? (renderImage(post)) : (_jsx(MediaImage, { src: coverImageUrl, alt: post.title, size: "hero" })), _jsx(Scrim, { direction: "bottom-up", intensity: "subtle", className: "absolute inset-0" })] })), _jsxs(Div, { className: "max-w-3xl mx-auto", paddingY: "y-3xl", paddingX: "x-md", children: [renderBlogPostHeader(post, date, labels), post.tags && post.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-8", children: post.tags.map((tag) => (_jsxs(Link, { href: `${String(ROUTES.PUBLIC.BLOG)}?tags=${encodeURIComponent(tag)}`, className: "inline-block px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] rounded-full bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] hover:bg-primary/10 text-[var(--appkit-color-text-muted)] hover:text-primary text-[length:var(--appkit-text-xs)] font-medium transition-colors", children: ["#", tag] }, tag))) })), renderAuthorBio && _jsx(Div, { className: "mb-6", children: renderAuthorBio(post) }), _jsx(Div, { surface: "card", padding: "xl", className: "mb-12", children: renderContent ? renderContent(post) : (_jsx(RichText, { html: normalizeRichTextHtml(post.content ?? ""), proseClass: "prose max-w-none dark:prose-invert" })) }), renderBlogPostRelated(related, labels, renderRelatedCard), renderBackButton && _jsx(Div, { border: "default", className: "mt-10 border-t", padding: "t-xl", children: renderBackButton() })] })] }));
+    return (_jsxs(Div, { className: `min-h-screen ${className}`, children: [coverImageUrl && (_jsxs(Div, { className: `relative h-72 md:h-96 ${__O.hidden}`, children: [renderImage ? (renderImage(post)) : (_jsx(MediaImage, { src: coverImageUrl, alt: post.title, size: "hero" })), _jsx(Scrim, { direction: "bottom-up", intensity: "subtle", className: "absolute inset-0" })] })), _jsxs(Div, { className: "max-w-3xl mx-auto", paddingY: "y-3xl", paddingX: "x-md", children: [renderBlogPostHeader(post, date, labels), post.youtubeId && /^[A-Za-z0-9_-]{6,20}$/.test(post.youtubeId) && (_jsx(Div, { className: "mb-8", children: _jsx(Iframe, { src: `https://www.youtube-nocookie.com/embed/${post.youtubeId}`, title: `${post.title} — video`, aspect: "video", rounded: "lg" }) })), post.tags && post.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-8", children: post.tags.map((tag) => (_jsxs(Link, { href: `${String(ROUTES.PUBLIC.BLOG)}?tags=${encodeURIComponent(tag)}`, className: "inline-block px-[var(--appkit-space-3)] py-[var(--appkit-space-1)] rounded-full bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] hover:bg-primary/10 text-[var(--appkit-color-text-muted)] hover:text-primary text-[length:var(--appkit-text-xs)] font-medium transition-colors", children: ["#", tag] }, tag))) })), renderAuthorBio && _jsx(Div, { className: "mb-6", children: renderAuthorBio(post) }), _jsx(Div, { surface: "card", padding: "xl", className: "mb-12", children: renderContent ? renderContent(post) : (_jsx(RichText, { html: normalizeRichTextHtml(post.content ?? ""), proseClass: "prose max-w-none dark:prose-invert" })) }), _jsxs(Stack, { gap: "xl", children: [renderBlogPostRelated(related, labels?.relatedTitle ?? "Related Posts", renderRelatedCard), renderBlogPostRelated(relatedByTags, labels?.relatedByTagsTitle ?? "You might also like", renderRelatedCard), renderBlogPostRelated(relatedByAuthor, labels?.relatedByAuthorTitle ?? `More from ${post.authorName}`, renderRelatedCard)] }), renderBackButton && _jsx(Div, { border: "default", className: "mt-10 border-t", padding: "t-xl", children: renderBackButton() })] })] }));
 }

package/dist/features/blog/hooks/useBlog.d.ts

@@ -24,6 +24,8 @@ interface UseBlogPostOptions {
 export declare function useBlogPost(slug: string, opts?: UseBlogPostOptions): {
     post: import("..").BlogPost | null;
     related: import("..").BlogPost[];
+    relatedByTags: import("..").BlogPost[];
+    relatedByAuthor: import("..").BlogPost[];
     isLoading: boolean;
     error: Error | null;
 };

package/dist/features/blog/hooks/useBlog.js

@@ -46,6 +46,8 @@ export function useBlogPost(slug, opts) {
     return {
         post: query.data?.post ?? null,
         related: query.data?.related ?? [],
+        relatedByTags: query.data?.relatedByTags ?? [],
+        relatedByAuthor: query.data?.relatedByAuthor ?? [],
         isLoading: query.isLoading,
         error: query.error,
     };

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

@@ -10,6 +10,13 @@ declare class BlogRepository extends BaseRepository<BlogPostDocument> {
     delete(id: string): Promise<void>;
     incrementViews(id: string): Promise<void>;
     findRelated(category: BlogPostCategory, excludeId: string, limit?: number): Promise<BlogPostDocument[]>;
+    /**
+     * Published posts sharing at least one tag with the given list.
+     * `array-contains-any` caps at 10 values, so only the first 10 tags are used.
+     */
+    findByTagsOverlap(tags: string[], excludeId: string, limit?: number): Promise<BlogPostDocument[]>;
+    /** Other published posts by the same author. */
+    findByAuthor(authorId: string, excludeId: string, limit?: number): Promise<BlogPostDocument[]>;
     static readonly SIEVE_FIELDS: {
         id: {
             canFilter: boolean;

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

@@ -95,6 +95,50 @@ class BlogRepository extends BaseRepository {
             throw new DatabaseError(`Failed to find related posts: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Published posts sharing at least one tag with the given list.
+     * `array-contains-any` caps at 10 values, so only the first 10 tags are used.
+     */
+    async findByTagsOverlap(tags, excludeId, limit = 3) {
+        if (tags.length === 0)
+            return [];
+        try {
+            const snapshot = await this.db
+                .collection(this.collection)
+                .where(BLOG_POST_FIELDS.STATUS, "==", "published")
+                .where(BLOG_POST_FIELDS.TAGS, "array-contains-any", tags.slice(0, 10))
+                .limit(limit + 1)
+                .get();
+            return snapshot.docs
+                .map((doc) => this.mapDoc(doc))
+                .filter((post) => post.id !== excludeId)
+                .slice(0, limit);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to find posts by tag overlap: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
+    /** Other published posts by the same author. */
+    async findByAuthor(authorId, excludeId, limit = 3) {
+        try {
+            const snapshot = await this.db
+                .collection(this.collection)
+                .where(BLOG_POST_FIELDS.STATUS, "==", "published")
+                .where(BLOG_POST_FIELDS.AUTHOR_ID, "==", authorId)
+                .orderBy(BLOG_POST_FIELDS.PUBLISHED_AT, "desc")
+                .limit(limit + 1)
+                .get();
+            return snapshot.docs
+                .map((doc) => this.mapDoc(doc))
+                .filter((post) => post.id !== excludeId)
+                .slice(0, limit);
+        }
+        catch (error) {
+            void normalizeError(error);
+            throw new DatabaseError(`Failed to find posts by author: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
     async listPublished(opts, model) {
         let baseQuery = this.getCollection().where(BLOG_POST_FIELDS.STATUS, "==", "published");
         if (opts?.category) {

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

@@ -22,6 +22,8 @@ export interface BlogPostDocument extends BaseDocument {
     coverImage?: MediaFieldInput;
     contentImages?: MediaField[];
     additionalImages?: MediaField[];
+    /** YouTube video ID (11 chars, e.g. "dQw4w9WgXcQ") embedded above the article content. */
+    youtubeId?: string;
     category: BlogPostCategory;
     tags: string[];
     isFeatured: boolean;
@@ -46,6 +48,7 @@ export declare const BLOG_POST_FIELDS: {
     readonly COVER_IMAGE: "coverImage";
     readonly CONTENT_IMAGES: "contentImages";
     readonly ADDITIONAL_IMAGES: "additionalImages";
+    readonly YOUTUBE_ID: "youtubeId";
     readonly CATEGORY: "category";
     readonly TAGS: "tags";
     readonly IS_FEATURED: "isFeatured";

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

@@ -25,6 +25,7 @@ export const BLOG_POST_FIELDS = {
     COVER_IMAGE: "coverImage",
     CONTENT_IMAGES: "contentImages",
     ADDITIONAL_IMAGES: "additionalImages",
+    YOUTUBE_ID: "youtubeId",
     CATEGORY: "category",
     TAGS: "tags",
     IS_FEATURED: "isFeatured",

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

@@ -10,6 +10,8 @@ export interface BlogPost {
     coverImage?: MediaFieldInput;
     contentImages?: MediaField[];
     additionalImages?: MediaField[];
+    /** YouTube video ID (11 chars, e.g. "dQw4w9WgXcQ") embedded above the article content. */
+    youtubeId?: string;
     category: BlogPostCategory;
     tags?: string[];
     isFeatured?: boolean;

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

@@ -7,8 +7,6 @@ export { CheckoutView } from "./CheckoutView";
 export type { CheckoutViewProps } from "./CheckoutView";
 export { CheckoutAddressStep } from "./CheckoutAddressStep";
 export type { CheckoutAddressStepProps, CheckoutAddressStepLabels, } from "./CheckoutAddressStep";
-export { CheckoutOtpModal } from "./CheckoutOtpModal";
-export type { CheckoutOtpModalProps } from "./CheckoutOtpModal";
 export { CheckoutSuccessView } from "./CheckoutSuccessView";
 export type { CheckoutSuccessViewProps } from "./CheckoutSuccessView";
 export { ShippingPicker } from "./ShippingPicker";

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

@@ -3,6 +3,5 @@ export { CartView } from "./CartView";
 export { CartSummary } from "./CartSummary";
 export { CheckoutView } from "./CheckoutView";
 export { CheckoutAddressStep } from "./CheckoutAddressStep";
-export { CheckoutOtpModal } from "./CheckoutOtpModal";
 export { CheckoutSuccessView } from "./CheckoutSuccessView";
 export { ShippingPicker } from "./ShippingPicker";

package/dist/features/cart/hooks/useCartCount.js

@@ -1,7 +1,10 @@
+"use client";
+import { useEffect, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { useGuestCart } from "./useGuestCart";
 import { CART_ENDPOINTS } from "../../../constants/api-endpoints";
+import { CART_OPS_CHANGE_EVENT, getCartOpsDelta } from "../utils/pending-ops";
 /**
  * useCartCount
  *
@@ -16,11 +19,25 @@ export function useCartCount(enabled = false) {
         queryFn: () => apiClient.get(CART_ENDPOINTS.GET),
         enabled,
     });
-    // When authenticated, the server is authoritative — never mix in the guest
-    // count, otherwise stale localStorage entries leak into the badge after
-    // login (the cart-merge clears the local store but `useGuestCart`'s React
-    // state holds the pre-clear snapshot until remount).
+    // "Add to cart" quick actions (listing grid, product cards) write local-
+    // first — see useSyncManager — and queue an unsynced op that only reaches
+    // the server on the next ~30s background sync. Layer that pending delta on
+    // top of the server count so the badge updates the instant the op is
+    // queued instead of lagging up to 30s behind the toast.
+    const [pendingDelta, setPendingDelta] = useState(0);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const recompute = () => setPendingDelta(getCartOpsDelta());
+        recompute();
+        window.addEventListener(CART_OPS_CHANGE_EVENT, recompute);
+        return () => window.removeEventListener(CART_OPS_CHANGE_EVENT, recompute);
+    }, [enabled]);
+    // When authenticated, the server + pending-ops delta is authoritative —
+    // never mix in the guest count, otherwise stale localStorage entries leak
+    // into the badge after login (the cart-merge clears the local store but
+    // `useGuestCart`'s React state holds the pre-clear snapshot until remount).
     if (enabled)
-        return data?.itemCount ?? 0;
+        return (data?.itemCount ?? 0) + pendingDelta;
     return guestCount;
 }

package/dist/features/cart/hooks/useGuestCart.js

@@ -1,6 +1,6 @@
 "use client";
 import { useState, useEffect, useCallback } from "react";
-import { getGuestCartItems, addToGuestCart, clearGuestCart, removeFromGuestCart, updateGuestCartQuantity, } from "../utils/guest-cart";
+import { getGuestCartItems, addToGuestCart, clearGuestCart, removeFromGuestCart, updateGuestCartQuantity, GUEST_CART_CHANGE_EVENT, } from "../utils/guest-cart";
 /**
  * useGuestCart
  *
@@ -10,6 +10,16 @@ export function useGuestCart() {
     const [items, setItems] = useState([]);
     useEffect(() => {
         setItems(getGuestCartItems());
+        // Cross-instance sync within the same tab (e.g. a listing-page "Add to
+        // cart" quick action writing storage while the header badge's own
+        // useGuestCart() instance is mounted elsewhere) + cross-tab via "storage".
+        const onChange = () => setItems(getGuestCartItems());
+        window.addEventListener(GUEST_CART_CHANGE_EVENT, onChange);
+        window.addEventListener("storage", onChange);
+        return () => {
+            window.removeEventListener(GUEST_CART_CHANGE_EVENT, onChange);
+            window.removeEventListener("storage", onChange);
+        };
     }, []);
     const add = useCallback((productId, quantity, snapshot) => {
         const updated = addToGuestCart(productId, quantity, snapshot);

package/dist/features/cart/utils/guest-cart.d.ts

@@ -1,3 +1,7 @@
+/** Fired whenever guest cart storage is written, so every `useGuestCart()`
+ *  instance in the tab (header badge, listing quick-add, cart page) can
+ *  re-read storage and stay in sync without waiting for a remount. */
+export declare const GUEST_CART_CHANGE_EVENT = "appkit/cart/guest-changed";
 export declare class CartFullError extends Error {
     readonly code: "CART_FULL";
     readonly limit = 50;

package/dist/features/cart/utils/guest-cart.js

@@ -6,6 +6,15 @@ const DEFAULT_GUEST_CART_KEY = process.env.NEXT_PUBLIC_APP_ID
 const DEFAULT_GUEST_RETURN_TO_KEY = process.env.NEXT_PUBLIC_APP_ID
     ? `${process.env.NEXT_PUBLIC_APP_ID}_guest_return_to`
     : "guest_return_to";
+/** Fired whenever guest cart storage is written, so every `useGuestCart()`
+ *  instance in the tab (header badge, listing quick-add, cart page) can
+ *  re-read storage and stay in sync without waiting for a remount. */
+export const GUEST_CART_CHANGE_EVENT = "appkit/cart/guest-changed";
+function dispatchGuestCartChange() {
+    if (typeof window === "undefined")
+        return;
+    window.dispatchEvent(new Event(GUEST_CART_CHANGE_EVENT));
+}
 export class CartFullError extends Error {
     constructor(current) {
         super(`Cart full (${current}/${CART_MAX_ITEMS})`);
@@ -39,6 +48,7 @@ function writeItems(storage, key, items) {
     if (!storage)
         return;
     storage.setItem(key, JSON.stringify(items));
+    dispatchGuestCartChange();
 }
 export function getGuestCartItems(storage = getDefaultStorage(), key = DEFAULT_GUEST_CART_KEY) {
     return readItems(storage, key);

package/dist/features/cart/utils/pending-ops.d.ts

@@ -5,6 +5,12 @@
  * Written to localStorage so they survive page refreshes.
  * The sync manager replays these and clears them after a successful push.
  */
+/** Fired whenever the pending cart/wishlist op queue changes, so a badge
+ *  reading server-authoritative counts (authenticated users) can layer the
+ *  not-yet-synced local delta on top instead of waiting for the next
+ *  useSyncManager interval (up to 30s) to reflect a just-added item. */
+export declare const CART_OPS_CHANGE_EVENT = "appkit/cart/ops-changed";
+export declare const WISHLIST_OPS_CHANGE_EVENT = "appkit/wishlist/ops-changed";
 export type CartOpKind = "add" | "remove";
 export type WishlistOpKind = "add" | "remove";
 export interface CartOp {
@@ -34,6 +40,17 @@ export interface WishlistOp {
 export declare function getCartOps(): CartOp[];
 export declare function pushCartOp(op: Omit<CartOp, "ts">): void;
 export declare function clearCartOps(): void;
+/** Net quantity of unsynced "add" ops — layered on top of the server's
+ *  authoritative itemCount so the header badge updates immediately instead
+ *  of waiting for the next useSyncManager interval. Cart never queues
+ *  "remove" ops (removal from an authenticated cart is always a synchronous
+ *  API call), so summing "add" quantities is exact, not an approximation. */
+export declare function getCartOpsDelta(): number;
 export declare function getWishlistOps(): WishlistOp[];
 export declare function pushWishlistOp(op: Omit<WishlistOp, "ts">): void;
+/** Net count of unsynced wishlist ops — add/remove pairs for the same item
+ *  are already collapsed by `pushWishlistOp`, so this is exact: +1 per
+ *  queued "add", -1 per queued "remove" (an item already on the server
+ *  being removed before the next sync). */
+export declare function getWishlistOpsDelta(): number;
 export declare function clearWishlistOps(): void;