@mohasinac/appkit 4.10.0 → 4.11.1

package/dist/_internal/server/jobs/core/dailyStatusDigest.js

@@ -0,0 +1,164 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Core: daily status digest email.
+ *
+ * Emails the previous 24h of order activity to the team every morning. The
+ * digest's arrival is itself the platform health signal — if it stops
+ * landing, something in the Firestore → Functions → Resend chain needs a
+ * look. Deliberately no separate error/exception tracking: there is no
+ * structured error-log collection to query, and building one just to fill
+ * this email would be scope no one asked for.
+ *
+ * Runs from a scheduled Firebase Function (not a Vercel route), so the
+ * unbounded-ish order scan below is safe against CLAUDE.md Rule #6's 10s
+ * sync ceiling — it has the Function's much larger budget.
+ */
+import { renderToStaticMarkup } from "react-dom/server";
+import { getAdminDb } from "../../../../providers/db-firebase";
+import { sendEmail } from "../../../../features/contact/email";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository";
+import { ORDER_COLLECTION, OrderStatusValues } from "../../../../features/orders/schemas/firestore";
+import { PRODUCT_COLLECTION, ProductStatusValues } from "../../../../features/products/schemas/firestore";
+import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names";
+import { EmailBold, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailRow, } from "../../../../features/email/primitives";
+import { normalizeError } from "../../../../errors/normalize";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Statuses that shouldn't count toward revenue for the day. */
+const NON_REVENUE_STATUSES = new Set([
+    OrderStatusValues.CANCELLED,
+    OrderStatusValues.REFUNDED,
+]);
+function currency(amount) {
+    return `₹${amount.toLocaleString("en-IN", { maximumFractionDigits: 2 })}`;
+}
+/** One "Label: value" line. Uses only email primitives — email clients need
+ *  inline-styled, table-based markup, which the Email* components provide. */
+function StatLine({ label, value }) {
+    return (_jsxs(_Fragment, { children: [label, ": ", _jsx(EmailBold, { children: String(value) }), _jsx("br", {})] }));
+}
+/** Gathers the last-24h numbers. Exported so the admin manual-trigger route can reuse it. */
+export async function collectDailyStatusSummary() {
+    const db = getAdminDb();
+    const since = new Date(Date.now() - DAY_MS);
+    const recentSnap = await db
+        .collection(ORDER_COLLECTION)
+        .where(ORDER_FIELDS.CREATED_AT, ">=", since)
+        .get();
+    let revenue = 0;
+    const statusBreakdown = {};
+    for (const doc of recentSnap.docs) {
+        const data = doc.data();
+        const status = data.status ?? "unknown";
+        statusBreakdown[status] = (statusBreakdown[status] ?? 0) + 1;
+        if (!NON_REVENUE_STATUSES.has(status)) {
+            revenue += Number(data.totalPrice ?? 0) || 0;
+        }
+    }
+    // Orders still sitting in PENDING beyond the 24h window — the one number
+    // here that signals something needs attention rather than just reporting
+    // volume.
+    const stuckSnap = await db
+        .collection(ORDER_COLLECTION)
+        .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.PENDING)
+        .where(ORDER_FIELDS.CREATED_AT, "<", since)
+        .count()
+        .get();
+    const activeSnap = await db
+        .collection(PRODUCT_COLLECTION)
+        .where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
+        .count()
+        .get();
+    return {
+        orderCount: recentSnap.size,
+        revenue,
+        statusBreakdown,
+        stuckPendingCount: stuckSnap.data().count,
+        activeListingCount: activeSnap.data().count,
+    };
+}
+function renderDigestHtml(summary, siteName, version) {
+    const statusRows = Object.entries(summary.statusBreakdown).sort(([a], [b]) => a.localeCompare(b));
+    const title = siteName ? `${siteName} — Daily Status` : "Daily Status";
+    return `<!DOCTYPE html>${renderToStaticMarkup(_jsx(EmailDoc, { title: title, children: _jsxs(EmailContainer, { children: [_jsx(EmailHeader, { brandName: siteName }), _jsxs(EmailRow, { children: [version
+                            ? `Deployment ${version} is live. Activity for the last 24 hours.`
+                            : "Activity for the last 24 hours.", _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Orders placed", value: summary.orderCount }), _jsx(StatLine, { label: "Revenue (excl. cancelled/refunded)", value: currency(summary.revenue) }), _jsx(StatLine, { label: "Active listings", value: summary.activeListingCount }), _jsx(StatLine, { label: "Pending > 24h (needs attention)", value: summary.stuckPendingCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Orders by status" }), _jsx("br", {}), _jsx("br", {}), statusRows.length === 0 ? ("No orders in this window.") : (statusRows.map(([status, count]) => (_jsx(StatLine, { label: status, value: count }, status))))] }), _jsx(EmailFooter, { copyright: `© ${new Date().getFullYear()}${siteName ? ` ${siteName}` : ""}. All rights reserved.` })] }) }))}`;
+}
+const DEPLOY_MARKER_COLLECTION = "system";
+const DEPLOY_MARKER_DOC = "deployDigest";
+/**
+ * Sends the digest once per deployment version.
+ *
+ * Called from server startup. On Vercel that means EVERY lambda cold start,
+ * not once per deploy — so the version marker below is what makes this a
+ * per-deployment event rather than a per-cold-start email storm. The claim
+ * runs in a transaction because several cold starts can race on the first
+ * request after a deploy; exactly one wins and sends.
+ */
+export async function runDeploymentDigest(ctx, version) {
+    if (!version)
+        return { sent: false, reason: "no_version" };
+    const markerRef = getAdminDb().collection(DEPLOY_MARKER_COLLECTION).doc(DEPLOY_MARKER_DOC);
+    let claimed = false;
+    try {
+        await getAdminDb().runTransaction(async (tx) => {
+            const snap = await tx.get(markerRef);
+            const lastVersion = snap.data()?.lastVersion;
+            if (lastVersion === version)
+                return;
+            tx.set(markerRef, { lastVersion: version, sentAt: new Date() }, { merge: true });
+            claimed = true;
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.warn("deploymentDigest: could not claim version marker — skipping", { version });
+        return { sent: false, reason: "claim_failed" };
+    }
+    if (!claimed)
+        return { sent: false, reason: "already_sent_for_version" };
+    ctx.logger.info("deploymentDigest: claimed version, sending", { version });
+    return runDailyStatusDigest(ctx, version);
+}
+export async function runDailyStatusDigest(ctx, version) {
+    const settings = await siteSettingsRepository.getSingleton().catch((err) => {
+        void normalizeError(err);
+        return null;
+    });
+    const digestConfig = settings?.emailSettings?.dailyDigest;
+    if (digestConfig?.enabled !== true) {
+        ctx.logger.info("dailyStatusDigest: disabled in site settings — skipping");
+        return { sent: false, reason: "disabled" };
+    }
+    const recipients = (digestConfig.recipients ?? []).filter((r) => r.trim().length > 0);
+    if (recipients.length === 0) {
+        ctx.logger.warn("dailyStatusDigest: enabled but no recipients configured — skipping");
+        return { sent: false, reason: "no_recipients" };
+    }
+    const ccRecipients = (digestConfig.ccRecipients ?? []).filter((r) => r.trim().length > 0);
+    const summary = await collectDailyStatusSummary();
+    // No hardcoded brand fallback — appkit is consumer-agnostic; the site name
+    // comes from settings or the consumer's own env var.
+    const siteName = settings?.siteName?.trim() || process.env.NEXT_PUBLIC_SITE_NAME?.trim() || "";
+    const { error } = await sendEmail({
+        to: recipients,
+        // Spread rather than `cc: undefined` — SendEmailOptions has a
+        // Record<string, JsonValue> index signature that rejects undefined.
+        ...(ccRecipients.length > 0 ? { cc: ccRecipients } : {}),
+        subject: "Daily Status",
+        html: renderDigestHtml(summary, siteName, version),
+        text: (version ? `Deployment ${version} is live.\n\n` : "") +
+            `Orders placed: ${summary.orderCount}\n` +
+            `Revenue: ${currency(summary.revenue)}\n` +
+            `Active listings: ${summary.activeListingCount}\n` +
+            `Pending > 24h: ${summary.stuckPendingCount}`,
+    });
+    if (error) {
+        ctx.logger.error("dailyStatusDigest: send failed", { error: String(error) });
+        throw new Error(`Daily status digest send failed: ${String(error)}`);
+    }
+    ctx.logger.info("dailyStatusDigest: sent", {
+        recipients: recipients.length,
+        orderCount: summary.orderCount,
+    });
+    return { sent: true, summary };
+}

package/dist/_internal/server/jobs/core/hardBanCascade.js

@@ -21,6 +21,8 @@ import { userRepository, sessionRepository, storeRepository, productRepository,
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { isSellerUser } from "../../../../features/auth/role-predicates";
 import { getAdminAuth } from "../../../../providers/db-firebase";
+import { recordAdminAction } from "../../features/audit-log/actions";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore";
 async function cascadeAddressClusterBan(uid, banData) {
     const userAddresses = await addressesRepository.listByOwner("user", uid);
     const uniqueHashes = [...new Set(userAddresses.map((a) => a.addressHash).filter(Boolean))];
@@ -84,6 +86,15 @@ export async function runHardBanCascade(input, ctx) {
         hardBanExpiresAt: expiresAt ?? null,
         ...(fraudOrderId ? { hardBanFraudOrderId: fraudOrderId } : {}),
     });
+    void recordAdminAction({
+        actorUid: bannedBy,
+        action: AdminAuditActionValues.USER_HARD_BAN,
+        targetType: "user",
+        targetId: uid,
+        targetLabel: target.displayName ?? uid,
+        reason,
+        metadata: { expiresAt: expiresAt?.toISOString() ?? null, fraudOrderId: fraudOrderId ?? null },
+    });
     // 3. Delete active sessions
     try {
         const sessions = await sessionRepository.findActiveByUser(uid);

package/dist/_internal/server/jobs/core/testerSandboxCleanup.d.ts

@@ -1,4 +1,5 @@
 import type { JobContext } from "../runtime/types";
+export declare const SANDBOX_COLLECTIONS: readonly ["categories", "stores", "products", "blogPosts", "events"];
 export interface TesterSandboxCleanupOptions {
     /** true = wipe every isTestData:true doc regardless of testDataExpiresAt (manual force-purge). */
     force?: boolean;

package/dist/_internal/server/jobs/core/testerSandboxCleanup.js

@@ -1,6 +1,9 @@
 import { batchDelete, getTestDataRefs } from "../handlers/_helpers";
 import { BID_FIELDS } from "../../../../constants/field-names";
-const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events"];
+// Exported so testerSandboxRefresh.ts (the every-4h revert+prune job) reuses
+// the exact same collection scope instead of redefining it — one source of
+// truth for "what counts as sandbox scope."
+export const SANDBOX_COLLECTIONS = ["categories", "stores", "products", "blogPosts", "events"];
 const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
 export async function runTesterSandboxCleanup(ctx, opts = {}) {
     const cutoff = opts.force ? null : new Date();

package/dist/_internal/server/jobs/core/testerSandboxRefresh.d.ts

@@ -0,0 +1,12 @@
+import type { JobContext } from "../runtime/types";
+/**
+ * Reverts every live tester-sandbox fixture back to its canonical seeded
+ * shape (undoing edits made through admin/seller forms) and prunes any
+ * isTestData doc that isn't one of the known fixtures (something a tester
+ * created during QA, e.g. a cloned product). Runs every 4 hours — distinct
+ * from `runTesterSandboxCleanup`, which only deletes docs whose 7-day
+ * `testDataExpiresAt` TTL has actually lapsed and never touches still-live
+ * docs' fields. Scoped to the tester sandbox only (`isTestData: true`) —
+ * the permanent Beyblade catalog real visitors browse is never touched.
+ */
+export declare function runTesterSandboxRefresh(ctx: JobContext): Promise<void>;

package/dist/_internal/server/jobs/core/testerSandboxRefresh.js

@@ -0,0 +1,85 @@
+import { batchDelete, getTestDataRefs } from "../handlers/_helpers";
+import { BID_FIELDS } from "../../../../constants/field-names";
+import { SANDBOX_COLLECTIONS } from "./testerSandboxCleanup";
+// Direct imports from each defining module (not the seed-data barrel) —
+// this is internal appkit code, not part of the package's public API surface.
+import { categoriesTesterSeedData } from "../../../../features/tester/seed-data/categories-tester-seed-data";
+import { storesTesterSeedData } from "../../../../features/tester/seed-data/stores-tester-seed-data";
+import { productsTesterSeedData } from "../../../../features/tester/seed-data/products-tester-seed-data";
+import { blogTesterSeedData } from "../../../../features/tester/seed-data/blog-tester-seed-data";
+import { eventsTesterSeedData } from "../../../../features/tester/seed-data/events-tester-seed-data";
+import { bidsTesterSeedData } from "../../../../features/tester/seed-data/bids-tester-seed-data";
+const SEED_BY_COLLECTION = {
+    categories: categoriesTesterSeedData,
+    stores: storesTesterSeedData,
+    products: productsTesterSeedData,
+    blogPosts: blogTesterSeedData,
+    events: eventsTesterSeedData,
+};
+const BID_CHUNK_SIZE = 30; // Firestore `in` query cap
+/**
+ * Reverts every live tester-sandbox fixture back to its canonical seeded
+ * shape (undoing edits made through admin/seller forms) and prunes any
+ * isTestData doc that isn't one of the known fixtures (something a tester
+ * created during QA, e.g. a cloned product). Runs every 4 hours — distinct
+ * from `runTesterSandboxCleanup`, which only deletes docs whose 7-day
+ * `testDataExpiresAt` TTL has actually lapsed and never touches still-live
+ * docs' fields. Scoped to the tester sandbox only (`isTestData: true`) —
+ * the permanent Beyblade catalog real visitors browse is never touched.
+ */
+export async function runTesterSandboxRefresh(ctx) {
+    let reverted = 0;
+    let deletedExtras = 0;
+    for (const collection of SANDBOX_COLLECTIONS) {
+        const seedDocs = SEED_BY_COLLECTION[collection] ?? [];
+        const validIds = new Set(seedDocs.map((d) => d.id).filter((id) => Boolean(id)));
+        if (seedDocs.length > 0) {
+            const batch = ctx.db.batch();
+            for (const doc of seedDocs) {
+                const { id, ...data } = doc;
+                if (!id)
+                    continue;
+                // merge:true mirrors seed-cli.mjs's loadGeneric — the seed payload
+                // carries every canonical field, so this fully overwrites anything
+                // a tester edited through the UI.
+                batch.set(ctx.db.collection(collection).doc(id), data, { merge: true });
+                reverted++;
+            }
+            await batch.commit();
+        }
+        const testDataRefs = await getTestDataRefs(ctx.db, collection, null);
+        const extraRefs = testDataRefs.filter((ref) => !validIds.has(ref.id));
+        deletedExtras += await batchDelete(ctx, extraRefs);
+    }
+    // Bids aren't isTestData-flagged themselves — scoped by productId
+    // referencing a sandbox product instead, mirroring runTesterSandboxCleanup's
+    // cascade convention.
+    const sandboxProductIds = (SEED_BY_COLLECTION.products ?? [])
+        .map((d) => d.id)
+        .filter((id) => Boolean(id));
+    const validBidIds = new Set(bidsTesterSeedData.map((d) => d.id).filter((id) => Boolean(id)));
+    if (bidsTesterSeedData.length > 0) {
+        const bidBatch = ctx.db.batch();
+        for (const bid of bidsTesterSeedData) {
+            const { id, ...data } = bid;
+            if (!id)
+                continue;
+            bidBatch.set(ctx.db.collection("bids").doc(id), data, { merge: true });
+            reverted++;
+        }
+        await bidBatch.commit();
+    }
+    const extraBidRefs = [];
+    for (let i = 0; i < sandboxProductIds.length; i += BID_CHUNK_SIZE) {
+        const chunk = sandboxProductIds.slice(i, i + BID_CHUNK_SIZE);
+        if (chunk.length === 0)
+            continue;
+        const snap = await ctx.db.collection("bids").where(BID_FIELDS.PRODUCT_ID, "in", chunk).get();
+        for (const doc of snap.docs) {
+            if (!validBidIds.has(doc.id))
+                extraBidRefs.push(doc.ref);
+        }
+    }
+    deletedExtras += await batchDelete(ctx, extraBidRefs);
+    ctx.logger.info("Tester sandbox refresh complete", { reverted, deletedExtras });
+}

package/dist/_internal/server/jobs/core/whatsappNotify.js

@@ -20,6 +20,7 @@
 import { normalizeError } from "../../../../errors/normalize";
 import { notificationRepository } from "../../../../features/admin/repository/notification.repository";
 import { sendWhatsAppTemplateMessage, sendWhatsAppBusinessMessage, } from "../../../../features/whatsapp-bot/helpers/whatsapp";
+import { isChannelHealthy, recordChannelOutcome } from "../../notifications/channel-health";
 const MAX_ATTEMPTS = 3;
 const RETRY_DELAY_MS = 1500;
 function delay(ms) {
@@ -27,6 +28,20 @@ function delay(ms) {
 }
 export async function runWhatsAppNotify(payload, ctx) {
     const { toPhone, title, message, templateName, templateLanguage, notificationId, phoneNumberId, accessToken } = payload;
+    if (!(await isChannelHealthy("whatsapp"))) {
+        ctx.logger.warn("whatsappNotify: WhatsApp channel circuit is open — skipping send", { notificationId });
+        await notificationRepository
+            .update(notificationId, { whatsappStatus: "skipped" })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+            succeeded: [],
+            skipped: [notificationId],
+            failed: [],
+        };
+    }
     let sent = false;
     let lastError;
     for (let attempt = 1; attempt <= MAX_ATTEMPTS && !sent; attempt++) {
@@ -61,6 +76,7 @@ export async function runWhatsAppNotify(payload, ctx) {
     if (!templateName) {
         ctx.logger.warn("whatsappNotify: no approved template configured for this notification type — sent as free-form text, which Meta rejects outside the 24h customer-service window", { notificationId });
     }
+    await recordChannelOutcome("whatsapp", sent);
     await notificationRepository
         .update(notificationId, { whatsappStatus: sent ? "sent" : "failed" })
         .catch((err) => {

package/dist/_internal/server/jobs/handlers/dailyStatusDigest.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const dailyStatusDigestHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/dailyStatusDigest.js

@@ -0,0 +1,4 @@
+import { runDailyStatusDigest } from "../core/dailyStatusDigest";
+export const dailyStatusDigestHandler = async (ctx) => {
+    await runDailyStatusDigest(ctx);
+};

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -29,6 +29,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { dailyStatusDigestHandler } from "./dailyStatusDigest";
 export { positionsReconcileHandler } from "./positionsReconcile";
 export { payoutBatchHandler } from "./payoutBatch";
 export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility";
@@ -52,6 +53,7 @@ export { onScamReportCreateHandler } from "./onScamReportCreate";
 export { onScamReportUpdateHandler } from "./onScamReportUpdate";
 export { draftPruneHandler } from "./draftPrune";
 export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
+export { testerSandboxRefreshHandler } from "./testerSandboxRefresh";
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";
 export { onShipmentItemWriteHandler } from "./onShipmentItemWrite";
 export { onShipmentLotWriteHandler, onShipmentHeaderWriteHandler } from "./onShipmentAllocationSync";

package/dist/_internal/server/jobs/handlers/index.js

@@ -29,6 +29,7 @@ export { hardBanReinstatementHandler } from "./hardBanReinstatement";
 export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
+export { dailyStatusDigestHandler } from "./dailyStatusDigest";
 export { positionsReconcileHandler } from "./positionsReconcile";
 export { payoutBatchHandler } from "./payoutBatch";
 export { weeklyPayoutEligibilityHandler } from "./weeklyPayoutEligibility";
@@ -64,6 +65,8 @@ export { onScamReportUpdateHandler } from "./onScamReportUpdate";
 export { draftPruneHandler } from "./draftPrune";
 // Tester program — 7-day auto-expiry sweep for the shared admin-seeded test sandbox
 export { testerSandboxCleanupHandler } from "./testerSandboxCleanup";
+// Tester program — every-4h revert-live-edits + prune-extras refresh (faster than the 7-day sweep above)
+export { testerSandboxRefreshHandler } from "./testerSandboxRefresh";
 // EMI — installment reminder + overdue-flagging sweep
 export { emiInstallmentReminderHandler } from "./emiInstallmentReminder";
 // Procurement Shipments — 3-function recompute cascade (item→lot, lot/header→shipment allocation, cascade-delete)

package/dist/_internal/server/jobs/handlers/testerSandboxRefresh.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const testerSandboxRefreshHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/testerSandboxRefresh.js

@@ -0,0 +1,2 @@
+import { runTesterSandboxRefresh } from "../core/testerSandboxRefresh";
+export const testerSandboxRefreshHandler = (ctx) => runTesterSandboxRefresh(ctx);

package/dist/_internal/server/notifications/channel-health.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Circuit breaker for outbound notification channels (email, WhatsApp).
+ *
+ * Persisted as a singleton Firestore doc `system/channelHealth` so the
+ * "is this channel currently known-bad" state survives across requests and
+ * Firebase Function invocations — a channel that just failed 3 times in a
+ * row is treated as down for a 15-minute cooldown instead of being retried
+ * on every subsequent send attempt (wasted latency + hammering a dead
+ * provider). After the cooldown, the next attempt is a half-open probe:
+ * its own outcome decides whether the circuit re-closes or re-opens.
+ */
+export type NotificationChannel = "email" | "whatsapp";
+/**
+ * Returns false only when the circuit is open and still within its cooldown
+ * window. Any other state (closed, or open-but-cooldown-elapsed) is treated
+ * as healthy — the latter lets the next call through as a half-open probe.
+ */
+export declare function isChannelHealthy(channel: NotificationChannel): Promise<boolean>;
+export declare function recordChannelOutcome(channel: NotificationChannel, success: boolean): Promise<void>;
+/**
+ * Runs `fn` up to 3 times (500ms then 1.5s between attempts) and records the
+ * final outcome against the channel's health state. `fn` must throw on
+ * failure — for a helper that returns a boolean instead (e.g. the WhatsApp
+ * Cloud API helpers), convert `false` into a thrown error at the call site
+ * before passing it in.
+ */
+export declare function withChannelRetry<T>(channel: NotificationChannel, fn: () => Promise<T>): Promise<T>;

package/dist/_internal/server/notifications/channel-health.js

@@ -0,0 +1,101 @@
+/**
+ * Circuit breaker for outbound notification channels (email, WhatsApp).
+ *
+ * Persisted as a singleton Firestore doc `system/channelHealth` so the
+ * "is this channel currently known-bad" state survives across requests and
+ * Firebase Function invocations — a channel that just failed 3 times in a
+ * row is treated as down for a 15-minute cooldown instead of being retried
+ * on every subsequent send attempt (wasted latency + hammering a dead
+ * provider). After the cooldown, the next attempt is a half-open probe:
+ * its own outcome decides whether the circuit re-closes or re-opens.
+ */
+import { getAdminDb } from "../../../providers/db-firebase";
+import { normalizeError } from "../../../errors/normalize";
+import { serverLogger } from "../../../monitoring";
+const HEALTH_COLLECTION = "system";
+const HEALTH_DOC = "channelHealth";
+const FAILURE_THRESHOLD = 3;
+const COOLDOWN_MS = 15 * 60 * 1000;
+const RETRY_DELAYS_MS = [500, 1500];
+function defaultState() {
+    return { consecutiveFailures: 0, state: "closed" };
+}
+async function readHealthDoc() {
+    try {
+        const snap = await getAdminDb().collection(HEALTH_COLLECTION).doc(HEALTH_DOC).get();
+        return snap.data() ?? {};
+    }
+    catch (err) {
+        void normalizeError(err);
+        return {};
+    }
+}
+/**
+ * Returns false only when the circuit is open and still within its cooldown
+ * window. Any other state (closed, or open-but-cooldown-elapsed) is treated
+ * as healthy — the latter lets the next call through as a half-open probe.
+ */
+export async function isChannelHealthy(channel) {
+    const doc = await readHealthDoc();
+    const state = doc[channel];
+    if (!state || state.state !== "open")
+        return true;
+    if (state.openedAt && Date.now() - state.openedAt >= COOLDOWN_MS)
+        return true;
+    return false;
+}
+export async function recordChannelOutcome(channel, success) {
+    try {
+        const doc = await readHealthDoc();
+        const prev = doc[channel] ?? defaultState();
+        const next = success
+            ? defaultState()
+            : (() => {
+                const consecutiveFailures = prev.consecutiveFailures + 1;
+                return consecutiveFailures >= FAILURE_THRESHOLD
+                    ? { consecutiveFailures, state: "open", openedAt: Date.now() }
+                    : { consecutiveFailures, state: "closed" };
+            })();
+        await getAdminDb()
+            .collection(HEALTH_COLLECTION)
+            .doc(HEALTH_DOC)
+            .set({ [channel]: next }, { merge: true });
+    }
+    catch (err) {
+        void normalizeError(err);
+        serverLogger.warn("channel-health: failed to record outcome", { channel, success });
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Runs `fn` up to 3 times (500ms then 1.5s between attempts) and records the
+ * final outcome against the channel's health state. `fn` must throw on
+ * failure — for a helper that returns a boolean instead (e.g. the WhatsApp
+ * Cloud API helpers), convert `false` into a thrown error at the call site
+ * before passing it in.
+ */
+export async function withChannelRetry(channel, fn) {
+    const maxAttempts = RETRY_DELAYS_MS.length + 1;
+    // Narrowed to Error at catch time rather than held as `unknown` — same
+    // conversion the throw below used to do, just done once at the source so
+    // `unknown` never escapes the catch clause (CLAUDE.md Root Cause #31).
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            await recordChannelOutcome(channel, true);
+            return result;
+        }
+        catch (err) {
+            void normalizeError(err);
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < maxAttempts) {
+                await delay(RETRY_DELAYS_MS[attempt - 1]);
+            }
+        }
+    }
+    await recordChannelOutcome(channel, false);
+    throw lastError ?? new Error(`${channel} channel failed after ${maxAttempts} attempts`);
+}

package/dist/_internal/shared/features/brands/schema.d.ts

@@ -4,7 +4,6 @@ export declare const brandInputSchema: z.ZodObject<{
     slug: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     logoURL: z.ZodOptional<z.ZodString>;
-    bannerURL: z.ZodOptional<z.ZodString>;
     website: z.ZodOptional<z.ZodString>;
     country: z.ZodOptional<z.ZodString>;
     founded: z.ZodOptional<z.ZodNumber>;
@@ -18,7 +17,6 @@ export declare const brandInputSchema: z.ZodObject<{
     country?: string | undefined;
     description?: string | undefined;
     logoURL?: string | undefined;
-    bannerURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
 }, {
@@ -29,7 +27,6 @@ export declare const brandInputSchema: z.ZodObject<{
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
-    bannerURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
 }>;
@@ -38,7 +35,6 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     logoURL: z.ZodOptional<z.ZodOptional<z.ZodString>>;
-    bannerURL: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     website: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     country: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     founded: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
@@ -51,7 +47,6 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
-    bannerURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
 }, {
@@ -61,7 +56,6 @@ export declare const brandUpdateSchema: z.ZodObject<Omit<{
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
-    bannerURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
 }>;

package/dist/_internal/shared/features/brands/schema.js

@@ -5,7 +5,6 @@ export const brandInputSchema = z.object({
     slug: z.string().min(1).regex(/^brand-[a-z0-9-]+$/, "Slug must start with 'brand-' and contain only lowercase letters, numbers, and hyphens"),
     description: z.string().max(BRAND_DESCRIPTION_MAX_LENGTH).optional(),
     logoURL: z.string().url().optional(),
-    bannerURL: z.string().url().optional(),
     website: z.string().url().optional(),
     country: z.string().optional(),
     founded: z.number().int().min(1800).max(new Date().getFullYear()).optional(),

package/dist/_internal/shared/features/categories/bundle-schemas.d.ts

@@ -81,6 +81,8 @@ export declare const bundleCreateSchema: z.ZodObject<{
      * "brand" — brand discovery collection; does not touch product reverse pointers.
      */
     bundleKind: z.ZodEnum<["special", "brand"]>;
+    /** Which brand this bundle belongs to, for the brand page's bundle tab — distinct from bundleQueryRule.filter.brandSlug (a dynamic-rule query filter). */
+    brandSlug: z.ZodOptional<z.ZodString>;
     bundlePrice: z.ZodNumber;
     bundleQueryRule: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"static">;
@@ -185,6 +187,7 @@ export declare const bundleCreateSchema: z.ZodObject<{
     } | undefined;
     description?: string | undefined;
     slug?: string | undefined;
+    brandSlug?: string | undefined;
     isActive?: boolean | undefined;
     bundleItemDetails?: {
         productId: string;
@@ -216,6 +219,7 @@ export declare const bundleCreateSchema: z.ZodObject<{
     } | undefined;
     description?: string | undefined;
     slug?: string | undefined;
+    brandSlug?: string | undefined;
     isActive?: boolean | undefined;
     bundleItemDetails?: {
         productId: string;
@@ -226,6 +230,7 @@ export declare const bundleUpdateSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     bundleKind: z.ZodOptional<z.ZodEnum<["special", "brand"]>>;
+    brandSlug: z.ZodOptional<z.ZodString>;
     bundlePrice: z.ZodOptional<z.ZodNumber>;
     bundleQueryRule: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"static">;
@@ -311,6 +316,7 @@ export declare const bundleUpdateSchema: z.ZodObject<{
     } | undefined;
     name?: string | undefined;
     description?: string | undefined;
+    brandSlug?: string | undefined;
     isActive?: boolean | undefined;
     bundleKind?: "brand" | "special" | undefined;
     bundleProductIds?: string[] | undefined;
@@ -341,6 +347,7 @@ export declare const bundleUpdateSchema: z.ZodObject<{
     } | undefined;
     name?: string | undefined;
     description?: string | undefined;
+    brandSlug?: string | undefined;
     isActive?: boolean | undefined;
     bundleKind?: "brand" | "special" | undefined;
     bundleProductIds?: string[] | undefined;

package/dist/_internal/shared/features/categories/bundle-schemas.js

@@ -52,6 +52,8 @@ export const bundleCreateSchema = z.object({
      * "brand" — brand discovery collection; does not touch product reverse pointers.
      */
     bundleKind: z.enum([BUNDLE_KIND_SPECIAL, BUNDLE_KIND_BRAND]),
+    /** Which brand this bundle belongs to, for the brand page's bundle tab — distinct from bundleQueryRule.filter.brandSlug (a dynamic-rule query filter). */
+    brandSlug: z.string().optional(),
     bundlePrice: z.number().min(1),
     bundleQueryRule: bundleQueryRuleSchema,
     bundleProductIds: productIdsSchema,
@@ -64,6 +66,7 @@ export const bundleUpdateSchema = z.object({
     name: z.string().min(2).max(120).optional(),
     description: z.string().max(2000).optional(),
     bundleKind: z.enum([BUNDLE_KIND_SPECIAL, BUNDLE_KIND_BRAND]).optional(),
+    brandSlug: z.string().optional(),
     bundlePrice: z.number().min(1).optional(),
     bundleQueryRule: bundleQueryRuleSchema.optional(),
     bundleProductIds: productIdsSchema.optional(),