@mohasinac/appkit 2.6.3 → 2.6.5

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

@@ -1,9 +1,2 @@
-/**
- * scheduledPrizeRevealReminder — daily 10am IST (SB8-E).
- *
- * Notifies users whose prize-draw reveals expire in the next 24 hours and
- * haven't been claimed yet. Triggered once a day so users get exactly one
- * nudge before the auto-refund kicks in.
- */
 import type { ScheduleHandler } from "../runtime/types";
 export declare const prizeRevealReminderHandler: ScheduleHandler;

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

@@ -1,45 +1,2 @@
-/**
- * scheduledPrizeRevealReminder — daily 10am IST (SB8-E).
- *
- * Notifies users whose prize-draw reveals expire in the next 24 hours and
- * haven't been claimed yet. Triggered once a day so users get exactly one
- * nudge before the auto-refund kicks in.
- */
-import { notificationRepository } from "../../../../repositories";
-const ORDER_COLLECTION = "orders";
-const ONE_DAY_MS = 86400000;
-export const prizeRevealReminderHandler = async (ctx) => {
-    ctx.logger.info("Prize reveal reminder sweep starting");
-    const cutoff = new Date(ctx.now.getTime() + ONE_DAY_MS);
-    const snap = await ctx.db
-        .collection(ORDER_COLLECTION)
-        .where("paymentStatus", "==", "paid")
-        .where("status", "in", ["pending", "confirmed", "processing"])
-        .where("prizeRevealDeadline", "<=", cutoff)
-        .where("prizeRevealDeadline", ">", ctx.now)
-        .limit(500)
-        .get();
-    let notified = 0;
-    for (const doc of snap.docs) {
-        const order = doc.data();
-        if (!order.userId || order.prizeWon || !order.prizeDrawProductId)
-            continue;
-        try {
-            await notificationRepository.create({
-                userId: order.userId,
-                type: "prize_reveal_reminder",
-                priority: "normal",
-                title: "Reveal expires within 24h",
-                message: `Reveal your prize for "${order.productTitle ?? "the draw"}" today — unclaimed reveals are auto-refunded after the deadline.`,
-                relatedId: doc.id,
-                relatedType: "order",
-                actionUrl: `/user/orders/view/${doc.id}`,
-            });
-            notified++;
-        }
-        catch (err) {
-            ctx.logger.warn("Reveal reminder notification failed", { err });
-        }
-    }
-    ctx.logger.info("Prize reveal reminder sweep complete", { notified });
-};
+import { runPrizeRevealReminder } from "../core/prizeRevealReminder";
+export const prizeRevealReminderHandler = runPrizeRevealReminder;

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

@@ -1,8 +1,2 @@
-/**
- * Job handler: recompute avgRating + reviewCount on every published product
- * from approved reviews. Heals drift from partial writes / moderation changes.
- *
- * Concurrency capped at 5 to avoid Firestore read-rate spikes.
- */
 import type { ScheduleHandler } from "../runtime/types";
 export declare const productStatsSyncHandler: ScheduleHandler;

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

@@ -1,36 +1,2 @@
-/**
- * Job handler: recompute avgRating + reviewCount on every published product
- * from approved reviews. Heals drift from partial writes / moderation changes.
- *
- * Concurrency capped at 5 to avoid Firestore read-rate spikes.
- */
-import { productRepository, reviewRepository } from "../../../../repositories";
-const CONCURRENCY = 5;
-async function syncOne(productId) {
-    const { count, avgRating } = await reviewRepository.getApprovedRatingAggregate(productId);
-    await productRepository.update(productId, { avgRating, reviewCount: count });
-}
-export const productStatsSyncHandler = async (ctx) => {
-    ctx.logger.info("Starting product stats sync");
-    const productIds = await productRepository.getPublishedIds();
-    if (productIds.length === 0) {
-        ctx.logger.info("No published products found");
-        return;
-    }
-    ctx.logger.info(`Syncing stats for ${productIds.length} product(s)`);
-    let succeeded = 0;
-    let failed = 0;
-    for (let i = 0; i < productIds.length; i += CONCURRENCY) {
-        const slice = productIds.slice(i, i + CONCURRENCY);
-        const results = await Promise.allSettled(slice.map(syncOne));
-        for (const r of results) {
-            if (r.status === "fulfilled")
-                succeeded++;
-            else {
-                failed++;
-                ctx.logger.error("Failed to sync product stats", r.reason);
-            }
-        }
-    }
-    ctx.logger.info("Product stats sync complete", { succeeded, failed });
-};
+import { runProductStatsSync } from "../core/productStatsSync";
+export const productStatsSyncHandler = runProductStatsSync;

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

@@ -1,12 +1,4 @@
 import type { CallableHandler } from "../runtime/types";
-export interface PromotionsCallableResult {
-    promotedProducts: unknown[];
-    featuredProducts: unknown[];
-    activeCoupons: unknown[];
-}
-/**
- * Callable handler for promotions data — promoted + featured products and
- * active coupons. Wraps the listing query that needs an OR-shaped
- * (coupon.startDate IS NULL OR <= now) filter Firestore can't express.
- */
+import { type PromotionsCallableResult } from "../core/promotions";
+export type { PromotionsCallableResult };
 export declare const promotionsHandler: CallableHandler<void, PromotionsCallableResult>;

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

@@ -1,43 +1,2 @@
-import { productRepository, couponsRepository } from "../../../../repositories";
-import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
-/**
- * Callable handler for promotions data — promoted + featured products and
- * active coupons. Wraps the listing query that needs an OR-shaped
- * (coupon.startDate IS NULL OR <= now) filter Firestore can't express.
- */
-export const promotionsHandler = async (_input, ctx) => {
-    ctx.logger.info("Promotions data requested");
-    const now = new Date();
-    const nowIso = now.toISOString();
-    const [promotedResult, featuredResult, activeCouponsResult] = await Promise.all([
-        productRepository.list({
-            filters: `status==${ProductStatusValues.PUBLISHED},isPromoted==true`,
-            sorts: "-createdAt",
-            page: "1",
-            pageSize: "12",
-        }, { status: ProductStatusValues.PUBLISHED }),
-        productRepository.list({
-            filters: `status==${ProductStatusValues.PUBLISHED},featured==true`,
-            sorts: "-createdAt",
-            page: "1",
-            pageSize: "8",
-        }, { status: ProductStatusValues.PUBLISHED }),
-        couponsRepository.list({
-            filters: `validity.isActive==true,validity.endDate>=${nowIso}`,
-            sorts: "validity.endDate",
-            page: "1",
-            pageSize: "50",
-        }),
-    ]);
-    const activeCoupons = activeCouponsResult.items.filter((c) => !c.validity?.startDate || new Date(c.validity.startDate) <= now);
-    ctx.logger.info("Promotions loaded", {
-        promoted: promotedResult.items.length,
-        featured: featuredResult.items.length,
-        coupons: activeCoupons.length,
-    });
-    return {
-        promotedProducts: promotedResult.items,
-        featuredProducts: featuredResult.items,
-        activeCoupons,
-    };
-};
+import { runPromotions } from "../core/promotions";
+export const promotionsHandler = runPromotions;

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

@@ -1,30 +1,4 @@
-/**
- * HTTPS callable handler: aggregate seller (store) analytics for the past
- * 6 months. Input: `{ sellerId }` (the Firebase Auth UID); store slug is
- * resolved server-side via `storeRepository.findByOwnerId`.
- */
 import type { CallableHandler } from "../runtime/types";
-export interface StoreAnalyticsInput {
-    sellerId: string;
-}
-export interface StoreAnalyticsResult {
-    summary: {
-        totalOrders: number;
-        totalRevenue: number;
-        totalProducts: number;
-        publishedProducts: number;
-    };
-    revenueByMonth: Array<{
-        month: string;
-        orders: number;
-        revenue: number;
-    }>;
-    topProducts: Array<{
-        productId: string;
-        title: string;
-        revenue: number;
-        orders: number;
-        mainImage: string;
-    }>;
-}
+import { type StoreAnalyticsInput, type StoreAnalyticsResult } from "../core/storeAnalytics";
+export type { StoreAnalyticsInput, StoreAnalyticsResult };
 export declare const storeAnalyticsHandler: CallableHandler<StoreAnalyticsInput, StoreAnalyticsResult>;

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

@@ -1,109 +1,2 @@
-/**
- * HTTPS callable handler: aggregate seller (store) analytics for the past
- * 6 months. Input: `{ sellerId }` (the Firebase Auth UID); store slug is
- * resolved server-side via `storeRepository.findByOwnerId`.
- */
-import { orderRepository, productRepository, storeRepository, } from "../../../../repositories";
-import { formatMonthYear } from "../../../../utils/date.formatter";
-import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
-class StoreAnalyticsError extends Error {
-    constructor(status, message) {
-        super(message);
-        this.name = "StoreAnalyticsError";
-        this.httpStatus = status;
-    }
-}
-function normalizeDate(raw) {
-    return raw instanceof Date ? raw : new Date(raw);
-}
-async function loadStore6MonthOrders(storeId) {
-    const now = new Date();
-    const isoStart = new Date(now.getFullYear(), now.getMonth() - 5, 1).toISOString();
-    const out = [];
-    let page = 1;
-    let hasMore = true;
-    while (hasMore && page <= 5) {
-        const result = await orderRepository.listAll({
-            filters: `storeId==${storeId},createdAt>=${isoStart}`,
-            sorts: "-createdAt",
-            page: String(page),
-            pageSize: "300",
-        });
-        out.push(...result.items);
-        hasMore = result.hasMore;
-        page += 1;
-    }
-    return out;
-}
-export const storeAnalyticsHandler = async (input, ctx) => {
-    const sellerId = input?.sellerId;
-    if (!sellerId || typeof sellerId !== "string") {
-        throw new StoreAnalyticsError(400, "sellerId is required");
-    }
-    ctx.logger.info("Store analytics requested", { sellerId });
-    const store = await storeRepository.findByOwnerId(sellerId);
-    if (!store)
-        throw new StoreAnalyticsError(404, "Store not found for this seller");
-    const storeId = store.id;
-    const [past6, totalProductsResult, publishedProductsResult] = await Promise.all([
-        loadStore6MonthOrders(storeId),
-        productRepository.list({ page: "1", pageSize: "1" }, { storeId }),
-        productRepository.list({
-            filters: `status==${ProductStatusValues.PUBLISHED}`,
-            page: "1",
-            pageSize: "1",
-        }, { storeId, status: ProductStatusValues.PUBLISHED }),
-    ]);
-    const productIds = Array.from(new Set(past6.map((o) => o.productId)));
-    const products = await Promise.all(productIds.map((id) => productRepository.findById(id)));
-    const productMap = new Map(products.filter(Boolean).map((p) => [p.id, p]));
-    const totalOrders = past6.length;
-    const totalRevenue = past6.reduce((sum, o) => sum + (o.totalPrice ?? 0), 0);
-    const now = new Date();
-    const monthMap = new Map();
-    for (let i = 5; i >= 0; i--) {
-        const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
-        const key = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
-        monthMap.set(key, { month: formatMonthYear(d), orders: 0, revenue: 0 });
-    }
-    for (const order of past6) {
-        const d = normalizeDate(order.createdAt);
-        const key = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
-        const entry = monthMap.get(key);
-        if (entry) {
-            entry.orders += 1;
-            entry.revenue += order.totalPrice ?? 0;
-        }
-    }
-    const revenueByProduct = new Map();
-    for (const order of past6) {
-        const existing = revenueByProduct.get(order.productId);
-        if (existing) {
-            existing.revenue += order.totalPrice ?? 0;
-            existing.orders += 1;
-        }
-        else {
-            const product = productMap.get(order.productId);
-            revenueByProduct.set(order.productId, {
-                productId: order.productId,
-                title: order.productTitle,
-                revenue: order.totalPrice ?? 0,
-                orders: 1,
-                mainImage: product?.mainImage ?? "",
-            });
-        }
-    }
-    const topProducts = Array.from(revenueByProduct.values())
-        .sort((a, b) => b.revenue - a.revenue)
-        .slice(0, 5);
-    return {
-        summary: {
-            totalOrders,
-            totalRevenue,
-            totalProducts: totalProductsResult.total,
-            publishedProducts: publishedProductsResult.total,
-        },
-        revenueByMonth: Array.from(monthMap.values()),
-        topProducts,
-    };
-};
+import { runStoreAnalytics, } from "../core/storeAnalytics";
+export const storeAnalyticsHandler = runStoreAnalytics;

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

@@ -1,30 +1,3 @@
-/**
- * triggerEventRaffle — HTTP callable (SB9-D).
- *
- * Selects a raffle winner for an event using `crypto.randomInt()`. Pool logic
- * keys off the event's `raffleType`:
- *   - "top_n_scorers"      → sort entries by `points DESC` take top N
- *   - "top_n_participants" → sort entries by `createdAt ASC` take first N
- *   - "open_raffle"        → all CONFIRMED entries are eligible
- *
- * On success the function stamps the winner fields onto the event doc and
- * sets the GitHub permalink for proof-of-fairness.
- */
 import type { CallableHandler } from "../runtime/types";
-interface TriggerEventRaffleInput {
-    eventId: string;
-    /** Optional override; otherwise read from event.raffleType. */
-    raffleType?: "top_n_scorers" | "top_n_participants" | "open_raffle";
-    /** Optional N override; otherwise read from event.raffleTopN. */
-    topN?: number;
-}
-interface TriggerEventRaffleResult {
-    eventId: string;
-    raffleWinnerUserId?: string;
-    raffleWinnerDisplayName?: string;
-    raffleEntryCount: number;
-    alreadyTriggered?: boolean;
-    reason?: string;
-}
+import { type TriggerEventRaffleInput, type TriggerEventRaffleResult } from "../core/triggerEventRaffle";
 export declare const triggerEventRaffleHandler: CallableHandler<TriggerEventRaffleInput, TriggerEventRaffleResult>;
-export {};

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

@@ -1,94 +1,2 @@
-/**
- * triggerEventRaffle — HTTP callable (SB9-D).
- *
- * Selects a raffle winner for an event using `crypto.randomInt()`. Pool logic
- * keys off the event's `raffleType`:
- *   - "top_n_scorers"      → sort entries by `points DESC` take top N
- *   - "top_n_participants" → sort entries by `createdAt ASC` take first N
- *   - "open_raffle"        → all CONFIRMED entries are eligible
- *
- * On success the function stamps the winner fields onto the event doc and
- * sets the GitHub permalink for proof-of-fairness.
- */
-import crypto from "node:crypto";
-const EVENTS_COLLECTION = "events";
-const EVENT_ENTRIES_COLLECTION = "eventEntries";
-export const triggerEventRaffleHandler = async (input, ctx) => {
-    const eventRef = ctx.db.collection(EVENTS_COLLECTION).doc(input.eventId);
-    const eventSnap = await eventRef.get();
-    if (!eventSnap.exists) {
-        return {
-            eventId: input.eventId,
-            raffleEntryCount: 0,
-            reason: "event_not_found",
-        };
-    }
-    const event = eventSnap.data();
-    if (event.raffleWinnerUserId) {
-        return {
-            eventId: input.eventId,
-            raffleEntryCount: 0,
-            alreadyTriggered: true,
-            raffleWinnerUserId: event.raffleWinnerUserId,
-        };
-    }
-    const raffleType = input.raffleType ?? event.raffleType ?? "open_raffle";
-    const topN = input.topN ?? event.raffleTopN ?? 0;
-    const entriesSnap = await ctx.db
-        .collection(EVENT_ENTRIES_COLLECTION)
-        .where("eventId", "==", input.eventId)
-        .where("status", "==", "CONFIRMED")
-        .get();
-    let pool = entriesSnap.docs.map((d) => ({
-        id: d.id,
-        data: d.data(),
-    }));
-    if (raffleType === "top_n_scorers" && topN > 0) {
-        pool = pool
-            .sort((a, b) => (b.data.points ?? 0) - (a.data.points ?? 0))
-            .slice(0, topN);
-    }
-    else if (raffleType === "top_n_participants" && topN > 0) {
-        pool = pool
-            .sort((a, b) => {
-            const aT = a.data.createdAt instanceof Date
-                ? a.data.createdAt.getTime()
-                : (a.data.createdAt?.toDate?.()?.getTime() ?? 0);
-            const bT = b.data.createdAt instanceof Date
-                ? b.data.createdAt.getTime()
-                : (b.data.createdAt?.toDate?.()?.getTime() ?? 0);
-            return aT - bT;
-        })
-            .slice(0, topN);
-    }
-    if (pool.length === 0) {
-        return {
-            eventId: input.eventId,
-            raffleEntryCount: 0,
-            reason: "no_eligible_entries",
-        };
-    }
-    const winnerIdx = crypto.randomInt(0, pool.length);
-    const winner = pool[winnerIdx];
-    await eventRef.update({
-        raffleWinnerUserId: winner.data.userId,
-        raffleWinnerDisplayName: winner.data.userDisplayName ?? "",
-        raffleWinnerEntryId: winner.id,
-        raffleTriggeredAt: ctx.now,
-        raffleEntryCount: entriesSnap.size,
-        raffleGithubFunctionUrl: `${ctx.env("PROOF_OF_FAIRNESS_BASE_URL") ?? ""}/raffles/${input.eventId}.json`,
-        updatedAt: ctx.now,
-    });
-    ctx.logger.info("Event raffle triggered", {
-        eventId: input.eventId,
-        raffleType,
-        poolSize: pool.length,
-        winnerId: winner.id,
-    });
-    return {
-        eventId: input.eventId,
-        raffleWinnerUserId: winner.data.userId,
-        raffleWinnerDisplayName: winner.data.userDisplayName,
-        raffleEntryCount: entriesSnap.size,
-    };
-};
+import { runTriggerEventRaffle, } from "../core/triggerEventRaffle";
+export const triggerEventRaffleHandler = runTriggerEventRaffle;

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

@@ -1,8 +1,2 @@
-/**
- * Job handler: weekly Saturday sweep — converts delivered Shiprocket orders
- * with `payoutStatus=eligible` into pending payout documents grouped by seller.
- * Net amount = gross − 5% platform fee. Idempotent: orders already requested
- * are filtered out by the repository.
- */
 import type { ScheduleHandler } from "../runtime/types";
 export declare const weeklyPayoutEligibilityHandler: ScheduleHandler;

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

@@ -1,87 +1,2 @@
-/**
- * Job handler: weekly Saturday sweep — converts delivered Shiprocket orders
- * with `payoutStatus=eligible` into pending payout documents grouped by seller.
- * Net amount = gross − 5% platform fee. Idempotent: orders already requested
- * are filtered out by the repository.
- */
-import { storeRepository, userRepository, orderRepository, payoutRepository, } from "../../../../repositories";
-import { BATCH_LIMIT } from "./messages";
-import { getDefaultCurrency } from "../../../../core";
-const PLATFORM_COMMISSION_RATE = 0.05;
-export const weeklyPayoutEligibilityHandler = async (ctx) => {
-    ctx.logger.info("Starting weekly payout eligibility sweep");
-    const eligible = await orderRepository.getEligibleShiprocket();
-    if (eligible.length === 0) {
-        ctx.logger.info("No eligible Shiprocket-delivered orders found");
-        return;
-    }
-    ctx.logger.info(`Found ${eligible.length} eligible order(s) — grouping by seller`);
-    const byStore = new Map();
-    for (const entry of eligible) {
-        const storeId = entry.data.storeId;
-        if (!storeId) {
-            ctx.logger.warn(`Order ${entry.id} has no storeId — skipping`);
-            continue;
-        }
-        if (!byStore.has(storeId))
-            byStore.set(storeId, []);
-        byStore.get(storeId).push(entry);
-    }
-    let payoutsCreated = 0;
-    let ordersProcessed = 0;
-    const defaultCurrency = getDefaultCurrency();
-    for (const [storeId, orders] of byStore.entries()) {
-        const store = await storeRepository.findBySlug(storeId);
-        const seller = store ? await userRepository.findById(store.ownerId) : null;
-        if (!store || !seller) {
-            ctx.logger.warn(`Store/seller ${storeId} not found — skipping ${orders.length} order(s)`);
-            continue;
-        }
-        const grossAmount = orders.reduce((sum, o) => sum + (o.data.totalPrice ?? 0), 0);
-        const platformFee = Math.round(grossAmount * PLATFORM_COMMISSION_RATE * 100) / 100;
-        const netAmount = Math.round((grossAmount - platformFee) * 100) / 100;
-        const payoutInput = {
-            storeId,
-            sellerName: (seller.displayName ?? seller.email ?? store.ownerId),
-            sellerEmail: (seller.email ?? ""),
-            orderIds: orders.map((o) => o.id),
-            amount: netAmount,
-            grossAmount,
-            platformFee,
-            platformFeeRate: PLATFORM_COMMISSION_RATE,
-            currency: defaultCurrency,
-            status: "pending",
-            paymentMethod: seller.payoutDetails?.method === "upi" ? "upi" : "bank_transfer",
-            upiId: seller.payoutDetails?.method === "upi" ? seller.payoutDetails.upiId : undefined,
-            bankAccount: seller.payoutDetails?.method === "bank_transfer" && seller.payoutDetails.bankAccount
-                ? {
-                    accountHolderName: seller.payoutDetails.bankAccount.accountHolderName,
-                    accountNumberMasked: seller.payoutDetails.bankAccount.accountNumberMasked,
-                    ifscCode: seller.payoutDetails.bankAccount.ifscCode,
-                    bankName: seller.payoutDetails.bankAccount.bankName,
-                }
-                : undefined,
-            notes: `Automated weekly payout — ${orders.length} Shiprocket delivered order(s)`,
-            requestedAt: new Date(),
-        };
-        const { id: payoutId } = await payoutRepository.create(payoutInput);
-        for (let i = 0; i < orders.length; i += BATCH_LIMIT) {
-            const slice = orders.slice(i, i + BATCH_LIMIT);
-            const batch = ctx.db.batch();
-            for (const entry of slice) {
-                orderRepository.markPayoutRequested(batch, entry.ref, payoutId);
-            }
-            await batch.commit();
-        }
-        payoutsCreated++;
-        ordersProcessed += orders.length;
-        ctx.logger.info(`Payout created for store ${storeId}`, {
-            payoutId,
-            orderCount: orders.length,
-            netAmount,
-            grossAmount,
-            platformFee,
-        });
-    }
-    ctx.logger.info("Weekly payout eligibility sweep complete", { payoutsCreated, ordersProcessed });
-};
+import { runWeeklyPayoutEligibility } from "../core/weeklyPayoutEligibility";
+export const weeklyPayoutEligibilityHandler = runWeeklyPayoutEligibility;

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

@@ -1,4 +1,5 @@
 export * from "./handlers/index";
+export * from "./core/index";
 export * from "./runtime/types";
 export { bindSchedule, bindDocumentWritten, bindDocumentCreated, bindDocumentUpdated, bindCallable, bindHttps, bindToFirebase, } from "./runtime/adapters/firebase";
 export type { BindHttpsOptions } from "./runtime/adapters/firebase";

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

@@ -1,3 +1,4 @@
 export * from "./handlers/index";
+export * from "./core/index";
 export * from "./runtime/types";
 export { bindSchedule, bindDocumentWritten, bindDocumentCreated, bindDocumentUpdated, bindCallable, bindHttps, bindToFirebase, } from "./runtime/adapters/firebase";

package/dist/_internal/server/jobs/runtime/adapters/firebase.js

@@ -13,6 +13,13 @@
 import { onSchedule } from "firebase-functions/v2/scheduler";
 import { onDocumentWritten, onDocumentCreated, onDocumentUpdated, } from "firebase-functions/v2/firestore";
 import { onCall, onRequest, } from "firebase-functions/v2/https";
+// Note: we intentionally pass secret NAMES (as strings) — not `defineSecret`
+// Param refs — to `onRequest({ secrets: [...] })`. firebase-functions v2
+// accepts both forms; the string form skips the firebase-tools Param-value
+// preflight that requires either an interactive prompt or a
+// functions/.env.<project> file (which would defeat the purpose of using
+// Secret Manager for the value). At runtime the SDK resolves the secret name
+// from Cloud Secret Manager directly and injects it into process.env.
 import { getAdminDb } from "../../../../../providers/db-firebase";
 import { serverLogger } from "../../../../../monitoring";
 function buildContext(job) {
@@ -120,6 +127,20 @@ export function bindCallable(job, handler, options) {
  */
 export function bindHttps(job, handler, options) {
     const { secretEnvVar, methods = ["POST"], ...httpsOptions } = options;
+    // Firebase Functions v2 requires secrets to be DECLARED via `secrets: [...]`
+    // in the `onRequest` options for the runtime to inject them into
+    // `process.env`. Just *reading* `process.env[secretEnvVar]` returns
+    // undefined unless the secret is bound here. Declare it via `defineSecret`
+    // so the deploy step provisions the binding (and developers see the secret
+    // listed in `firebase deploy` output).
+    if (secretEnvVar) {
+        const existing = Array.isArray(httpsOptions.secrets)
+            ? httpsOptions.secrets
+            : [];
+        if (!existing.includes(secretEnvVar)) {
+            httpsOptions.secrets = [...existing, secretEnvVar];
+        }
+    }
     return onRequest(httpsOptions, async (req, res) => {
         const ctx = buildContext(job);
         if (secretEnvVar) {