@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/_internal/server/functions/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Firebase Functions registry types.
+ *
+ * Every appkit-owned function is declared as a `FunctionDefinition` value via
+ * `defineFunction({...})` in `appkit/src/_internal/server/functions/<category>/<name>.ts`.
+ * Definitions are collected into `APPKIT_FUNCTIONS` (manifest.ts) and bound to
+ * Firebase via `bindAllFromRegistry(...)` (bind-all.ts).
+ *
+ * Consumer extension contract: a consumer may declare its own `FunctionDefinition[]`
+ * and pass it as a second registry to `mergeFunctionRegistries(...)`. Name
+ * collisions are an error unless the later definition declares
+ * `options.overrides` referencing the shadowed name.
+ *
+ * Handler signatures are inherited from the existing job runtime types
+ * (ScheduleHandler / FirestoreTriggerHandler / CallableHandler).
+ */
+import type { CallableHandler, FirestoreTriggerHandler, ScheduleHandler } from "../jobs/runtime/types";
+export type FunctionMemory = "128MiB" | "256MiB" | "512MiB" | "1GiB" | "2GiB";
+export interface FunctionOptions {
+    readonly region?: string;
+    readonly timeoutSeconds?: number;
+    readonly memory?: FunctionMemory;
+    readonly maxInstances?: number;
+    readonly minInstances?: number;
+    /**
+     * CORS configuration for HTTPS functions only. `false` (the default for
+     * server-to-server calls) rejects browser preflights.
+     */
+    readonly cors?: boolean | string | readonly string[];
+    /**
+     * Names of Secret Manager secrets bound to the runtime. Required by audit
+     * for every HTTPS definition; ignored by Firebase for other trigger kinds.
+     */
+    readonly secrets?: readonly string[];
+    /**
+     * Env var name whose value the request's `x-internal-secret` header must
+     * equal. Required by audit for every HTTPS definition.
+     */
+    readonly secretEnvVar?: string;
+    /**
+     * If the consumer registry intentionally shadows an appkit definition, this
+     * field MUST hold the name being overridden. Any other collision is an
+     * error in `mergeFunctionRegistries`.
+     */
+    readonly overrides?: string;
+}
+export interface ScheduleTrigger {
+    readonly kind: "schedule";
+    readonly cron: string;
+    readonly timeZone?: string;
+}
+export interface DocumentCreatedTrigger {
+    readonly kind: "documentCreated";
+    readonly pathPattern: string;
+}
+export interface DocumentUpdatedTrigger {
+    readonly kind: "documentUpdated";
+    readonly pathPattern: string;
+}
+export interface DocumentWrittenTrigger {
+    readonly kind: "documentWritten";
+    readonly pathPattern: string;
+}
+export interface HttpsTrigger {
+    readonly kind: "https";
+    readonly methods?: readonly string[];
+}
+export type FunctionTrigger = ScheduleTrigger | DocumentCreatedTrigger | DocumentUpdatedTrigger | DocumentWrittenTrigger | HttpsTrigger;
+interface FunctionDefinitionBase {
+    readonly name: string;
+    readonly description: string;
+    readonly options?: FunctionOptions;
+}
+export interface ScheduledFunctionDefinition extends FunctionDefinitionBase {
+    readonly trigger: ScheduleTrigger;
+    readonly handler: ScheduleHandler;
+}
+export interface DocumentTriggerFunctionDefinition<TBefore = unknown, TAfter = unknown> extends FunctionDefinitionBase {
+    readonly trigger: DocumentCreatedTrigger | DocumentUpdatedTrigger | DocumentWrittenTrigger;
+    readonly handler: FirestoreTriggerHandler<TBefore, TAfter>;
+}
+/**
+ * HTTPS definitions are typed to require both `secretEnvVar` and `secrets`
+ * on `options`. The audit duplicates the rule for runtime confirmation;
+ * the type makes accidental omission a compile error.
+ */
+export interface HttpsFunctionDefinition<TInput = unknown, TOutput = unknown> extends FunctionDefinitionBase {
+    readonly trigger: HttpsTrigger;
+    readonly handler: CallableHandler<TInput, TOutput>;
+    readonly options: FunctionOptions & {
+        readonly secretEnvVar: string;
+        readonly secrets?: readonly string[];
+    };
+}
+export type FunctionDefinition = ScheduledFunctionDefinition | DocumentTriggerFunctionDefinition | HttpsFunctionDefinition;
+export {};

package/dist/_internal/server/functions/types.js

@@ -0,0 +1,17 @@
+/**
+ * Firebase Functions registry types.
+ *
+ * Every appkit-owned function is declared as a `FunctionDefinition` value via
+ * `defineFunction({...})` in `appkit/src/_internal/server/functions/<category>/<name>.ts`.
+ * Definitions are collected into `APPKIT_FUNCTIONS` (manifest.ts) and bound to
+ * Firebase via `bindAllFromRegistry(...)` (bind-all.ts).
+ *
+ * Consumer extension contract: a consumer may declare its own `FunctionDefinition[]`
+ * and pass it as a second registry to `mergeFunctionRegistries(...)`. Name
+ * collisions are an error unless the later definition declares
+ * `options.overrides` referencing the shadowed name.
+ *
+ * Handler signatures are inherited from the existing job runtime types
+ * (ScheduleHandler / FirestoreTriggerHandler / CallableHandler).
+ */
+export {};

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { getAdminAuth, getAdminRealtimeDb } from "../../../../providers/db-firebase";
 const AUTH_STALE_MS = 3 * 60 * 1000;
 const PAYMENT_STALE_MS = 15 * 60 * 1000;
@@ -23,6 +24,7 @@ export async function runCleanupRtdbEvents(ctx) {
         }
     }
     catch (authErr) {
+        void normalizeError(authErr);
         ctx.logger.error("Auth events cleanup failed (non-fatal)", authErr);
     }
     try {
@@ -39,6 +41,7 @@ export async function runCleanupRtdbEvents(ctx) {
         }
     }
     catch (payErr) {
+        void normalizeError(payErr);
         ctx.logger.error("Payment events cleanup failed (non-fatal)", payErr);
     }
     ctx.logger.info("RTDB events cleanup complete");

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { categoriesRepository, reviewRepository, storeRepository, } from "../../../../repositories";
 import { ProductStatusValues, PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names";
@@ -79,6 +80,7 @@ async function reconcileStores(ctx) {
             processed++;
         }
         catch (storeErr) {
+            void normalizeError(storeErr);
             errors++;
             ctx.logger.error(`[stores] failed for store ${storeId}`, storeErr);
         }
@@ -94,7 +96,7 @@ export async function runCountersReconcile(ctx) {
     try {
         await reconcileCategories(ctx);
     }
-    catch (err) {
+    catch (err) { // audit-catch-raw-ok: pre-existing-handler-intentional
         ctx.logger.error("Category reconciliation failed", err);
     }
     try {

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

@@ -7,6 +7,7 @@
  * (`p` directly) or infinite-mode (forward `cursor` from previous response).
  */
 import type { JobContext } from "../runtime/types";
+import type { JsonValue } from "../../../../schemas/types";
 export interface ListingRequestBody {
     collection: string;
     q?: string;
@@ -15,7 +16,7 @@ export interface ListingRequestBody {
     p?: number | string;
     ps?: number | string;
     cursor?: string;
-    baseOpts?: Record<string, unknown>;
+    baseOpts?: Record<string, JsonValue>;
 }
 export interface ListingResponseBody {
     items: unknown[];

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

@@ -1,14 +1,2 @@
-/**
- * Core: media tmp cleanup.
- *
- * Sweeps Firebase Storage for stale objects under the tmp/ prefix. Layer 2 of
- * the dual-layer scheme — Layer 1 is the form-level onAbort() DELETE call;
- * this job mops up anything that escaped (crashes, expired sessions).
- *
- * Safety invariants:
- *  - Only touches objects whose name starts with `tmp/`.
- *  - Only deletes objects older than `ttlHours` (default 24).
- *  - Idempotent: 404s on delete are swallowed (Layer 1 already removed it).
- */
 import type { JobContext } from "../runtime/types";
 export declare function runMediaTmpCleanup(ctx: JobContext): Promise<void>;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 /**
  * Core: media tmp cleanup.
  *
@@ -51,6 +52,7 @@ export async function runMediaTmpCleanup(ctx) {
                 deleted++;
             }
             catch (fileError) {
+                void normalizeError(fileError);
                 errors++;
                 const code = fileError?.code;
                 if (code === 404) {

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { offerRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 export async function runOfferExpiry(ctx) {
@@ -30,6 +31,7 @@ export async function runOfferExpiry(ctx) {
             });
         }
         catch (err) {
+            void normalizeError(err);
             ctx.logger.warn(`Failed to process expiry for offer ${offer.id}`, {
                 error: err instanceof Error ? err.message : String(err),
             });

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { bidRepository, productRepository, } from "../../../../repositories";
 import { decryptPii } from "../../../../security/index";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
@@ -42,6 +43,7 @@ export async function handleBidPlaced(input, ctx) {
                 });
             }
             catch (rtdbError) {
+                void normalizeError(rtdbError);
                 ctx.logger.error("Realtime DB push failed (non-fatal)", rtdbError);
             }
         }

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

@@ -1,11 +1,6 @@
-/**
- * Core: maintain DFS `position` + `subtreeSize` on every category write.
- * CREATE → insert into parent's subtree + shift later siblings;
- * DELETE → shift back; MOVE → mark `positionDirty` so the nightly reconcile
- * job rebuilds.
- */
+import type { JsonValue } from "@mohasinac/appkit";
 import type { JobContext } from "../runtime/types";
-export type CategoryDoc = Record<string, unknown>;
+export type CategoryDoc = Record<string, JsonValue>;
 export interface HandleCategoryWriteInput {
     categoryId: string;
     before: CategoryDoc | null;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 /**
  * Core: maintain DFS `position` + `subtreeSize` on every category write.
  * CREATE → insert into parent's subtree + shift later siblings;
@@ -127,6 +128,7 @@ export async function handleCategoryWrite(input, ctx) {
         }
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Position update failed (non-fatal — will heal on next reconcile)", err, {
             categoryId,
         });

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { storeRepository, userRepository } from "../../../../repositories";
 import { decryptPii } from "../../../../security/index";
 import { sendWhatsAppBusinessMessage, buildPurchaseAnnouncementMessage, } from "../../../../features/whatsapp-bot/server";
@@ -20,6 +21,7 @@ async function sendAnnouncement(ctx, toPhone, message, phoneNumberId, accessToke
         }
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error(`Announcement send threw for ${label} (non-fatal)`, err, { orderId });
     }
 }
@@ -38,6 +40,7 @@ async function notifyStoreOwner(ctx, storeId, message, phoneNumberId, accessToke
         }
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Store owner lookup failed (non-fatal)", err, { orderId, storeId });
     }
 }

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { getAdminRealtimeDb } from "../../../../providers/db-firebase";
 import { decryptPii } from "../../../../security/index";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
@@ -66,6 +67,7 @@ export async function handleOrderStatusChange(input, ctx) {
             });
         }
         catch (rtdbError) {
+            void normalizeError(rtdbError);
             ctx.logger.error("Realtime DB push failed (non-fatal)", rtdbError);
         }
         ctx.logger.info(`Order ${orderId} status → ${newStatus}`, { userId: after.userId });

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

@@ -1,15 +1,4 @@
-/**
- * Core: SB-UNI-V product stock-change reaction.
- *
- * Looks up every bundle category (categoryType:"bundle") that lists the
- * product in `bundleProductIds[]` and recomputes its `bundleStockStatus`.
- * Also updates every grouped listing that lists the product in `productIds[]`
- * — bumps `activeMemberCount` and `visibilityStatus`.
- *
- * Cheap: each affected bundle/group reads its `bundleProductIds.length`
- * member products (≤16 typically). Caller should skip when the product's
- * status didn't transition between "available" and "unavailable".
- */
+import { normalizeError } from "../../../../errors/normalize";
 import { CATEGORY_FIELDS, PRODUCT_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names";
 const CATEGORIES_COLLECTION = "categories";
 const GROUPED_LISTINGS_COLLECTION = "groupedListings";
@@ -122,6 +111,7 @@ export async function handleProductStockChange(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("onProductStockChange sync failed (non-fatal)", err, { productId });
     }
 }

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

@@ -1,9 +1,6 @@
-/**
- * Core: keep category metrics + store stats in sync when a product document
- * is written. Only published products count.
- */
+import type { JsonValue } from "@mohasinac/appkit";
 import type { JobContext } from "../runtime/types";
-export type ProductDoc = Record<string, unknown>;
+export type ProductDoc = Record<string, JsonValue>;
 export interface HandleProductWriteInput {
     productId: string;
     before: ProductDoc | null;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 /**
  * Core: keep category metrics + store stats in sync when a product document
  * is written. Only published products count.
@@ -78,6 +79,7 @@ export async function handleProductWrite(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Counter update failed (non-fatal)", err, { productId });
     }
 }

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

@@ -1,7 +1,8 @@
 import type { JobContext } from "../runtime/types";
+import type { FirestoreDocument } from "@mohasinac/appkit";
 export interface HandleReviewWriteInput {
     reviewId: string;
-    before: Record<string, unknown> | null;
-    after: Record<string, unknown> | null;
+    before: FirestoreDocument | null;
+    after: FirestoreDocument | null;
 }
 export declare function handleReviewWrite(input: HandleReviewWriteInput, ctx: JobContext): Promise<void>;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { userRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { SCAM_TYPE_LABELS } from "../../../../features/scams/constants/scam-types";
@@ -22,6 +23,7 @@ export async function handleScamReportCreate(input, ctx) {
             });
         }
         catch (err) {
+            void normalizeError(err);
             ctx.logger.error("Failed to notify reporter (non-fatal)", err, { scammerId, reportedBy });
         }
     }
@@ -45,10 +47,11 @@ export async function handleScamReportCreate(input, ctx) {
             relatedType: "scammer",
             userEmail: employee.email ?? undefined,
             userPhone: employee.phoneNumber ?? undefined,
-        }).catch((err) => ctx.logger.error("Failed to notify employee (non-fatal)", err, { scammerId, employeeId: employee.id }))));
+        }).catch((err) => ctx.logger.error("Failed to notify employee (non-fatal)", err, { scammerId, employeeId: employee.id ?? null }))));
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Failed to query employees for scam notification (non-fatal)", err, { scammerId });
     }
-    ctx.logger.info("onScamReportCreate complete", { scammerId, reportedBy });
+    ctx.logger.info("onScamReportCreate complete", { scammerId, reportedBy: reportedBy ?? null });
 }

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { userRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 export async function handleScamReportRejected(input, ctx) {
@@ -25,6 +26,7 @@ export async function handleScamReportRejected(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Failed to notify reporter of rejection (non-fatal)", err, { scammerId, reportedBy });
     }
     ctx.logger.info("onScamReportRejected complete", { scammerId, reportedBy });

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { userRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 export async function handleScamReportVerified(input, ctx) {
@@ -25,6 +26,7 @@ export async function handleScamReportVerified(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Failed to notify reporter of verification (non-fatal)", err, { scammerId, reportedBy });
     }
     ctx.logger.info("onScamReportVerified complete", { scammerId, reportedBy });

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

@@ -3,7 +3,8 @@
  * synced an external search index that has since been removed.
  */
 import type { JobContext } from "../runtime/types";
-export type StoreDoc = Record<string, unknown>;
+import type { JsonValue } from "@mohasinac/appkit";
+export type StoreDoc = Record<string, JsonValue>;
 export interface HandleStoreWriteInput {
     storeId: string;
     before: StoreDoc | null;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 export async function handleSupportTicketCreate(input, ctx) {
     const { ticketId, ticket } = input;
@@ -18,6 +19,7 @@ export async function handleSupportTicketCreate(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Failed to send ticket confirmation notification (non-fatal)", err, { ticketId, userId });
     }
     ctx.logger.info("onSupportTicketCreate complete", { ticketId, userId });

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 const USER_NOTIFY_STATUSES = new Set(["resolved", "closed", "waiting_on_user", "in_progress"]);
 const STATUS_MESSAGES = {
@@ -43,7 +44,8 @@ export async function handleSupportTicketUpdate(input, ctx) {
         });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("Failed to notify user of ticket status change (non-fatal)", err, { ticketId, userId, nextStatus });
     }
-    ctx.logger.info("onSupportTicketUpdate complete", { ticketId, userId, prevStatus, nextStatus });
+    ctx.logger.info("onSupportTicketUpdate complete", { ticketId, userId, prevStatus: prevStatus ?? null, nextStatus });
 }

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 export async function handleUserBanChange(input, ctx) {
     const { uid, before, after } = input;
     if (!after)
@@ -54,6 +55,7 @@ export async function handleUserBanChange(input, ctx) {
         ctx.logger.info("onUserBanChange: ban history entries written", { uid, count: entries.length });
     }
     catch (err) {
+        void normalizeError(err);
         ctx.logger.error("onUserBanChange: failed to write ban history (non-fatal)", err, { uid });
     }
 }

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

@@ -1,8 +1,2 @@
-/**
- * Core: 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.
- */
 import type { JobContext } from "../runtime/types";
 export declare function runPayoutBatch(ctx: JobContext): Promise<void>;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 /**
  * Core: dispatch pending payouts via Razorpay Payouts API.
  *
@@ -70,6 +71,7 @@ async function dispatch(ctx, entry) {
         ctx.logger.info(`Payout ${payout.id} dispatched`, { razorpayId: result.id, razorpayStatus: result.status });
     }
     catch (error) {
+        void normalizeError(error);
         const failureCount = (payout.failureCount ?? 0) + 1;
         const isFinal = failureCount >= MAX_FAILURES;
         const reason = error instanceof Error ? error.message : String(error);

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { ORDER_FIELDS, PRODUCT_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names";
 const ORDER_COLLECTION = "orders";
@@ -46,7 +47,8 @@ export async function runPrizeRevealExpiry(ctx) {
                 });
             }
             catch (err) {
-                ctx.logger.warn("Reveal-expired notification failed", { err });
+                void normalizeError(err);
+                ctx.logger.warn("Reveal-expired notification failed", { err: err instanceof Error ? err.message : String(err) });
             }
         }
         refunded++;

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { PRODUCT_FIELDS, ORDER_FIELDS, COMMON_FIELDS } from "../../../../constants/field-names";
 const PRODUCT_COLLECTION = "products";
@@ -51,7 +52,8 @@ export async function runPrizeRevealOpen(ctx) {
                 notified++;
             }
             catch (err) {
-                ctx.logger.warn("Reveal-ready notification failed", { err });
+                void normalizeError(err);
+                ctx.logger.warn("Reveal-ready notification failed", { err: err instanceof Error ? err.message : String(err) });
             }
         }
         ctx.logger.info("Opened prize draw", {

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

@@ -1,3 +1,4 @@
+import { normalizeError } from "../../../../errors/normalize";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { ORDER_FIELDS, PRODUCT_FIELDS } from "../../../../constants/field-names";
 const ORDER_COLLECTION = "orders";
@@ -36,7 +37,8 @@ export async function runPrizeRevealReminder(ctx) {
             notified++;
         }
         catch (err) {
-            ctx.logger.warn("Reveal reminder notification failed", { err });
+            void normalizeError(err);
+            ctx.logger.warn("Reveal reminder notification failed", { err: err instanceof Error ? err.message : String(err) });
         }
     }
     ctx.logger.info("Prize reveal reminder sweep complete", { notified });

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

@@ -0,0 +1,25 @@
+/**
+ * wrapJobHandler — turn any pure job handler into one whose exceptions are
+ * persisted to `serverErrors` (source: "function") before being re-thrown so
+ * the runtime's retry semantics are preserved.
+ *
+ * Apply to every handler in the consumer's runtime adapter so the maintenance
+ * UI sees a row for every Cloud Function failure.
+ */
+import type { CallableHandler, FirestoreTriggerHandler, ScheduleHandler } from "../runtime/types";
+interface WrapOptions {
+    /** Function/handler name — used as the route field on serverErrors rows. */
+    name: string;
+    /** Optional payload-size cap when stringifying the input as bodyDigest seed. */
+    payloadMaxBytes?: number;
+}
+export declare function wrapScheduleHandler(name: string, handler: ScheduleHandler): ScheduleHandler;
+export declare function wrapTriggerHandler<TBefore = unknown, TAfter = unknown>(name: string, handler: FirestoreTriggerHandler<TBefore, TAfter>): FirestoreTriggerHandler<TBefore, TAfter>;
+export declare function wrapCallableHandler<TInput = unknown, TOutput = unknown>(name: string, handler: CallableHandler<TInput, TOutput>): CallableHandler<TInput, TOutput>;
+/**
+ * Generic wrap-by-name helper. The kind is inferred from the handler arity.
+ * Use this only when bundling JobHandlers — prefer the typed wrappers above
+ * in adapter code.
+ */
+export declare function wrapJobHandler<F extends (...args: never[]) => Promise<unknown>>(name: string, handler: F): F;
+export type { WrapOptions };

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

@@ -0,0 +1,79 @@
+/**
+ * wrapJobHandler — turn any pure job handler into one whose exceptions are
+ * persisted to `serverErrors` (source: "function") before being re-thrown so
+ * the runtime's retry semantics are preserved.
+ *
+ * Apply to every handler in the consumer's runtime adapter so the maintenance
+ * UI sees a row for every Cloud Function failure.
+ */
+import { mapToHttpError } from "../../../../errors/error-mapping";
+import { serverErrorsRepository } from "../../../../features/server-errors/repository/server-errors.repository";
+// audit-unknown-ok: error-handler entry point — accepts thrown values of any shape
+async function persist(name, err, ctxLike) {
+    const mapped = mapToHttpError(err);
+    try {
+        await serverErrorsRepository().record({
+            source: "function",
+            route: name,
+            code: mapped.code,
+            message: mapped.message,
+            stack: err instanceof Error ? err.stack : undefined,
+            requestId: `fn-${name}-${(ctxLike?.now ?? new Date()).getTime()}`,
+            occurredAt: (ctxLike?.now ?? new Date()).getTime(),
+        });
+    }
+    catch {
+        /* logging-the-logging-failure is forbidden */
+    }
+}
+export function wrapScheduleHandler(name, handler) {
+    return async (ctx) => {
+        try {
+            return await handler(ctx);
+        }
+        catch (err) {
+            await persist(name, err, ctx);
+            throw err;
+        }
+    };
+}
+export function wrapTriggerHandler(name, handler) {
+    return async (event, ctx) => {
+        try {
+            return await handler(event, ctx);
+        }
+        catch (err) {
+            await persist(name, err, ctx);
+            throw err;
+        }
+    };
+}
+export function wrapCallableHandler(name, handler) {
+    return async (input, ctx) => {
+        try {
+            return await handler(input, ctx);
+        }
+        catch (err) {
+            await persist(name, err, ctx);
+            throw err;
+        }
+    };
+}
+/**
+ * Generic wrap-by-name helper. The kind is inferred from the handler arity.
+ * Use this only when bundling JobHandlers — prefer the typed wrappers above
+ * in adapter code.
+ */
+export function wrapJobHandler(name, handler) {
+    return (async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (err) {
+            // Best-effort: pull the last arg as JobContext if it has a `.now`
+            const maybeCtx = args[args.length - 1];
+            await persist(name, err, maybeCtx);
+            throw err;
+        }
+    });
+}