@mohasinac/appkit 2.4.10 → 2.5.0

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

@@ -0,0 +1,104 @@
+/**
+ * Job handler: dispatch pending payouts via Razorpay Payouts API.
+ *
+ * Reads RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET / RAZORPAY_ACCOUNT_NUMBER from
+ * env (via `ctx.env`). On 3rd consecutive failure the record is marked failed.
+ *
+ * Brand name in the narration is taken from `ctx.env("APP_BRAND_NAME")`
+ * (default empty) so appkit stays consumer-agnostic.
+ */
+import { payoutRepository } from "../../../../repositories";
+const MAX_FAILURES = 3;
+async function dispatch(ctx, entry) {
+    const { ref, data: payout } = entry;
+    await payoutRepository.markProcessing(ref);
+    try {
+        const keyId = ctx.env("RAZORPAY_KEY_ID") ?? "";
+        const keySecret = ctx.env("RAZORPAY_KEY_SECRET") ?? "";
+        const accountNumber = ctx.env("RAZORPAY_ACCOUNT_NUMBER") ?? "";
+        const apiBaseUrl = ctx.env("RAZORPAY_API_BASE_URL") ?? "https://api.razorpay.com/v1";
+        const brandName = ctx.env("APP_BRAND_NAME") ?? "";
+        if (!keyId || !keySecret || !accountNumber) {
+            throw new Error("Razorpay credentials not configured");
+        }
+        const basicAuth = Buffer.from(`${keyId}:${keySecret}`).toString("base64");
+        let fundAccount;
+        if (payout.paymentMethod === "upi" && payout.upiId) {
+            fundAccount = { account_type: "vpa", vpa: { address: payout.upiId } };
+        }
+        else if (payout.bankAccount) {
+            fundAccount = {
+                account_type: "bank_account",
+                bank_account: {
+                    name: payout.bankAccount.accountHolderName,
+                    ifsc: payout.bankAccount.ifscCode,
+                    account_number: payout.bankAccount.accountNumberMasked,
+                },
+            };
+        }
+        else {
+            throw new Error("Payout has no fund account configured");
+        }
+        const payload = {
+            account_number: accountNumber,
+            fund_account: {
+                ...fundAccount,
+                contact: { name: payout.sellerEmail, type: "vendor", email: payout.sellerEmail },
+            },
+            amount: Math.round(payout.amount * 100),
+            currency: payout.currency.toUpperCase(),
+            mode: payout.paymentMethod === "upi" ? "UPI" : "NEFT",
+            purpose: "payout",
+            reference_id: payout.id,
+            narration: brandName
+                ? `${brandName} payout for seller ${payout.storeId}`
+                : `Payout for seller ${payout.storeId}`,
+        };
+        const response = await fetch(`${apiBaseUrl}/payouts`, {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${basicAuth}`,
+                "Content-Type": "application/json",
+                "X-Payout-Idempotency": payout.id,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const errBody = await response.text();
+            throw new Error(`Razorpay ${response.status}: ${errBody}`);
+        }
+        const result = (await response.json());
+        await payoutRepository.recordSuccess(ref, result.id, result.status);
+        ctx.logger.info(`Payout ${payout.id} dispatched`, { razorpayId: result.id, razorpayStatus: result.status });
+    }
+    catch (error) {
+        const failureCount = (payout.failureCount ?? 0) + 1;
+        const isFinal = failureCount >= MAX_FAILURES;
+        const reason = error instanceof Error ? error.message : String(error);
+        await payoutRepository.recordFailure(ref, failureCount, reason, isFinal);
+        if (isFinal) {
+            ctx.logger.error(`Payout ${payout.id} permanently failed after ${MAX_FAILURES} attempts`, error, {
+                sellerId: payout.storeId,
+            });
+        }
+        else {
+            ctx.logger.warn(`Payout ${payout.id} failed (attempt ${failureCount})`, { error: reason });
+        }
+    }
+}
+export const payoutBatchHandler = async (ctx) => {
+    ctx.logger.info("Starting payout batch sweep");
+    const pending = await payoutRepository.getPending();
+    if (pending.length === 0) {
+        ctx.logger.info("No pending payouts to process");
+        return;
+    }
+    ctx.logger.info(`Dispatching ${pending.length} payout(s)`);
+    const results = await Promise.allSettled(pending.map((entry) => dispatch(ctx, entry)));
+    const failed = results.filter((r) => r.status === "rejected").length;
+    ctx.logger.info("Payout batch complete", {
+        total: pending.length,
+        succeeded: pending.length - failed,
+        failed,
+    });
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Job handler: cancel pending orders that have not paid in time.
+ *
+ * Reads timeout-hours from `ctx.env("ORDER_TIMEOUT_HOURS")` (default 24).
+ * Writes cancellation notifications atomically in the same Firestore batch.
+ */
+import type { ScheduleHandler } from "../runtime/types";
+export declare const pendingOrderTimeoutHandler: ScheduleHandler;

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

@@ -0,0 +1,33 @@
+/**
+ * Job handler: cancel pending orders that have not paid in time.
+ *
+ * Reads timeout-hours from `ctx.env("ORDER_TIMEOUT_HOURS")` (default 24).
+ * Writes cancellation notifications atomically in the same Firestore batch.
+ */
+import { notificationRepository, orderRepository } from "../../../../repositories";
+import { ORDER_MESSAGES } from "./messages";
+const DEFAULT_TIMEOUT_HOURS = 24;
+export const pendingOrderTimeoutHandler = async (ctx) => {
+    const timeoutHours = Number(ctx.env("ORDER_TIMEOUT_HOURS") ?? DEFAULT_TIMEOUT_HOURS);
+    ctx.logger.info(`Scanning orders unpaid > ${timeoutHours}h`);
+    const timedOut = await orderRepository.getTimedOutPending(timeoutHours);
+    if (timedOut.length === 0) {
+        ctx.logger.info("No timed-out pending orders found");
+        return;
+    }
+    const batch = ctx.db.batch();
+    for (const entry of timedOut) {
+        orderRepository.cancelInBatch(batch, entry.ref);
+        notificationRepository.createInBatch(batch, {
+            userId: entry.data.userId,
+            type: "order_cancelled",
+            priority: "normal",
+            title: ORDER_MESSAGES.CANCELLED_TITLE,
+            message: ORDER_MESSAGES.CANCELLED_TIMEOUT_MESSAGE(entry.data.productTitle, timeoutHours),
+            relatedId: entry.data.id,
+            relatedType: "order",
+        });
+    }
+    await batch.commit();
+    ctx.logger.info("Pending order timeout complete", { cancelled: timedOut.length });
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Job handler: rebuild `position` + `subtreeSize` for every category via
+ * DFS pre-order from the roots. Heals drift left by the trigger's
+ * `positionDirty` flag and any failed real-time updates.
+ */
+import type { ScheduleHandler } from "../runtime/types";
+export declare const positionsReconcileHandler: ScheduleHandler;

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

@@ -0,0 +1,87 @@
+/**
+ * Job handler: rebuild `position` + `subtreeSize` for every category via
+ * DFS pre-order from the roots. Heals drift left by the trigger's
+ * `positionDirty` flag and any failed real-time updates.
+ */
+import { BATCH_LIMIT } from "./messages";
+const CATEGORIES = "categories";
+function dfsAssign(nodeId, childMap, counter, result) {
+    const position = counter;
+    counter++;
+    const children = (childMap.get(nodeId) ?? []).sort((a, b) => a.order - b.order);
+    for (const child of children) {
+        counter = dfsAssign(child.id, childMap, counter, result);
+    }
+    const subtreeSize = counter - position;
+    result.set(nodeId, { position, subtreeSize });
+    return counter;
+}
+export const positionsReconcileHandler = async (ctx) => {
+    const snap = await ctx.db.collection(CATEGORIES).get();
+    const nodes = snap.docs.map((doc) => {
+        const d = doc.data();
+        const parentIds = d.parentIds ?? [];
+        return {
+            id: doc.id,
+            parentId: parentIds.length > 0 ? parentIds[parentIds.length - 1] : null,
+            order: d.order ?? 0,
+            position: d.position ?? 0,
+            subtreeSize: d.subtreeSize ?? 1,
+            positionDirty: d.positionDirty ?? false,
+        };
+    });
+    if (nodes.length === 0) {
+        ctx.logger.info("No categories — nothing to reconcile");
+        return;
+    }
+    const childMap = new Map();
+    const roots = [];
+    for (const node of nodes) {
+        if (node.parentId === null) {
+            roots.push(node);
+        }
+        else {
+            const siblings = childMap.get(node.parentId) ?? [];
+            siblings.push(node);
+            childMap.set(node.parentId, siblings);
+        }
+    }
+    const computed = new Map();
+    let counter = 1;
+    for (const root of roots.sort((a, b) => a.order - b.order)) {
+        counter = dfsAssign(root.id, childMap, counter, computed);
+    }
+    const orphans = nodes.filter((n) => !computed.has(n.id));
+    for (const orphan of orphans) {
+        counter = dfsAssign(orphan.id, childMap, counter, computed);
+    }
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const toUpdate = [];
+    for (const [id, { position, subtreeSize }] of computed) {
+        const current = nodeMap.get(id);
+        if (!current || current.position !== position || current.subtreeSize !== subtreeSize || current.positionDirty) {
+            toUpdate.push({ id, position, subtreeSize });
+        }
+    }
+    if (toUpdate.length === 0) {
+        ctx.logger.info("Positions already correct", { scanned: nodes.length });
+        return;
+    }
+    for (let i = 0; i < toUpdate.length; i += BATCH_LIMIT) {
+        const batch = ctx.db.batch();
+        for (const { id, position, subtreeSize } of toUpdate.slice(i, i + BATCH_LIMIT)) {
+            batch.update(ctx.db.collection(CATEGORIES).doc(id), {
+                position,
+                subtreeSize,
+                positionDirty: false,
+                updatedAt: new Date(),
+            });
+        }
+        await batch.commit();
+    }
+    ctx.logger.info("Positions reconciled", {
+        scanned: nodes.length,
+        updated: toUpdate.length,
+        orphans: orphans.length,
+    });
+};

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

@@ -0,0 +1,8 @@
+/**
+ * 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

@@ -0,0 +1,36 @@
+/**
+ * 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 });
+};

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

@@ -0,0 +1,12 @@
+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.
+ */
+export declare const promotionsHandler: CallableHandler<void, PromotionsCallableResult>;

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

@@ -0,0 +1,43 @@
+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,
+    };
+};

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+    }>;
+}
+export declare const storeAnalyticsHandler: CallableHandler<StoreAnalyticsInput, StoreAnalyticsResult>;

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

@@ -0,0 +1,109 @@
+/**
+ * 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,
+    };
+};

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

@@ -0,0 +1,8 @@
+/**
+ * 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

@@ -0,0 +1,87 @@
+/**
+ * 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 });
+};

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

@@ -0,0 +1,4 @@
+export * from "./handlers/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

@@ -0,0 +1,3 @@
+export * from "./handlers/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.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Firebase runtime adapter for appkit job handlers.
+ *
+ * Wraps pure handler functions into Firebase Functions v2 triggers so the
+ * consumer's `functions/src/index.ts` becomes a thin barrel:
+ *
+ *   import { handlers } from "./_internal/server/jobs/handlers";
+ *   export const auctionSettlement = bindSchedule("auctionSettlement", handlers.auctionSettlement, { schedule: "every 15 minutes" });
+ *
+ * The adapter resolves a JobContext (db + logger + env) per invocation so the
+ * handler stays portable.
+ */
+import { type ScheduleOptions } from "firebase-functions/v2/scheduler";
+import { type DocumentOptions } from "firebase-functions/v2/firestore";
+import { type CallableOptions, type HttpsOptions } from "firebase-functions/v2/https";
+import type { CallableHandler, FirestoreTriggerHandler, ScheduleHandler } from "../types";
+export declare function bindSchedule(job: string, handler: ScheduleHandler, options: ScheduleOptions): import("firebase-functions/v2/scheduler").ScheduleFunction;
+export declare function bindDocumentWritten<TBefore = unknown, TAfter = unknown>(job: string, handler: FirestoreTriggerHandler<TBefore, TAfter>, options: DocumentOptions): import("firebase-functions/core").CloudFunction<import("firebase-functions/v2/firestore").FirestoreEvent<import("firebase-functions/core").Change<import("firebase-functions/v2/firestore").DocumentSnapshot> | undefined, Record<string, string>>>;
+export declare function bindDocumentCreated<TAfter = unknown>(job: string, handler: FirestoreTriggerHandler<null, TAfter>, options: DocumentOptions): import("firebase-functions/core").CloudFunction<import("firebase-functions/v2/firestore").FirestoreEvent<import("firebase-functions/v2/firestore").QueryDocumentSnapshot | undefined, Record<string, string>>>;
+export declare function bindDocumentUpdated<TBefore = unknown, TAfter = unknown>(job: string, handler: FirestoreTriggerHandler<TBefore, TAfter>, options: DocumentOptions): import("firebase-functions/core").CloudFunction<import("firebase-functions/v2/firestore").FirestoreEvent<import("firebase-functions/core").Change<import("firebase-functions/v2/firestore").QueryDocumentSnapshot> | undefined, Record<string, string>>>;
+export declare function bindCallable<TInput = unknown, TOutput = unknown>(job: string, handler: CallableHandler<TInput, TOutput>, options: CallableOptions): import("firebase-functions/v2/https").CallableFunction<TInput, Promise<TOutput>, unknown>;
+export interface BindHttpsOptions extends HttpsOptions {
+    /**
+     * Env var holding the shared secret. The request's `x-internal-secret`
+     * header must equal `process.env[secretEnvVar]` or the request is rejected
+     * with 401. Omit (or pass `null`) to disable secret auth — the consumer is
+     * then responsible for authenticating the request before the handler runs.
+     */
+    secretEnvVar?: string | null;
+    /** Allowed HTTP methods; defaults to POST only. */
+    methods?: string[];
+}
+/**
+ * Bind a pure callable handler to a Firebase HTTPS Cloud Function with
+ * shared-secret authentication. Translates JSON body → handler input and
+ * handler output → JSON response. Status codes:
+ *  - 401 if secret invalid
+ *  - 405 if method not allowed
+ *  - 400 if handler throws a ValidationError-shaped error
+ *  - 500 on any other thrown error
+ */
+export declare function bindHttps<TInput = unknown, TOutput = unknown>(job: string, handler: CallableHandler<TInput, TOutput>, options: BindHttpsOptions): import("firebase-functions/v2/https").HttpsFunction;
+export declare const bindToFirebase: {
+    schedule: typeof bindSchedule;
+    documentWritten: typeof bindDocumentWritten;
+    documentCreated: typeof bindDocumentCreated;
+    documentUpdated: typeof bindDocumentUpdated;
+    callable: typeof bindCallable;
+    https: typeof bindHttps;
+};