@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/_internal/server/features/maintenance/analyze.d.ts

@@ -0,0 +1,67 @@
+/**
+ * analyze-logs core — shared by the CLI (`scripts/analyze-logs.mjs`) and the
+ * admin route (`/api/admin/maintenance/analysis`). Pure function over the
+ * `serverErrors` collection: pages through documents within a time window and
+ * computes a report.
+ *
+ * Designed to be cheap enough to run on Vercel's 10s sync-function ceiling for
+ * a 7-day window. For larger windows or denser failure rates, call from the
+ * CLI which has no ceiling and writes a markdown report to disk.
+ */
+import { type ServerErrorSource } from "../../../../features/server-errors/schemas/firestore";
+export interface AnalyzeOptions {
+    /** Look-back window in days (1..30). */
+    days: number;
+    /** Filter by source. Omit / "all" for the full union. */
+    source?: ServerErrorSource | "all";
+    /** Hard cap on documents loaded — defaults 5000. */
+    maxDocs?: number;
+}
+export interface AnalyzeReport {
+    generatedAt: string;
+    window: {
+        days: number;
+        from: number;
+        to: number;
+    };
+    source: ServerErrorSource | "all";
+    totalErrors: number;
+    uniqueUsers: number;
+    topCodes: Array<{
+        code: string;
+        count: number;
+        userImpact: number;
+    }>;
+    topRoutes: Array<{
+        route: string;
+        count: number;
+        source: string;
+    }>;
+    hourlyHistogram: Array<{
+        hour: string;
+        count: number;
+    }>;
+    dailyHistogram: Array<{
+        day: string;
+        count: number;
+    }>;
+    stackClusters: Array<{
+        signature: string;
+        count: number;
+        sampleMessage: string;
+        sampleStackHead: string[];
+    }>;
+    burstWindows: Array<{
+        start: string;
+        end: string;
+        count: number;
+        multiplier: number;
+    }>;
+    clientServerCorrelation: Array<{
+        requestId: string;
+        serverCode: string;
+        clientCode: string;
+    }>;
+    recommendations: string[];
+}
+export declare function analyzeLogs(opts: AnalyzeOptions): Promise<AnalyzeReport>;

package/dist/_internal/server/features/maintenance/analyze.js

@@ -0,0 +1,178 @@
+/**
+ * analyze-logs core — shared by the CLI (`scripts/analyze-logs.mjs`) and the
+ * admin route (`/api/admin/maintenance/analysis`). Pure function over the
+ * `serverErrors` collection: pages through documents within a time window and
+ * computes a report.
+ *
+ * Designed to be cheap enough to run on Vercel's 10s sync-function ceiling for
+ * a 7-day window. For larger windows or denser failure rates, call from the
+ * CLI which has no ceiling and writes a markdown report to disk.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/admin";
+import { SERVER_ERRORS_COLLECTION, } from "../../../../features/server-errors/schemas/firestore";
+function topFrames(stack, n) {
+    if (!stack)
+        return [];
+    return stack
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.startsWith("at "))
+        .slice(0, n);
+}
+function stackSignature(stack) {
+    return topFrames(stack, 3).join(" >> ");
+}
+export async function analyzeLogs(opts) {
+    const days = Math.max(1, Math.min(30, opts.days));
+    const maxDocs = opts.maxDocs ?? 5000;
+    const now = Date.now();
+    const from = now - days * 86400000;
+    const sourceFilter = opts.source && opts.source !== "all" ? opts.source : null;
+    const db = getAdminDb();
+    let q = db.collection(SERVER_ERRORS_COLLECTION).where("occurredAt", ">=", from);
+    if (sourceFilter)
+        q = q.where("source", "==", sourceFilter);
+    const snap = await q.orderBy("occurredAt", "desc").limit(maxDocs).get();
+    const docs = snap.docs.map((d) => d.data());
+    const totalErrors = docs.length;
+    const uniqueUsersSet = new Set();
+    const codeCounts = new Map();
+    const routeCounts = new Map();
+    const hourlyMap = new Map();
+    const dailyMap = new Map();
+    const stackMap = new Map();
+    const requestIdMap = new Map();
+    for (const d of docs) {
+        if (d.userId)
+            uniqueUsersSet.add(d.userId);
+        const cc = codeCounts.get(d.code) ?? { count: 0, users: new Set() };
+        cc.count++;
+        if (d.userId)
+            cc.users.add(d.userId);
+        codeCounts.set(d.code, cc);
+        const routeKey = `${d.source}:${d.route}`;
+        const rc = routeCounts.get(routeKey) ?? { count: 0, source: d.source };
+        rc.count++;
+        routeCounts.set(routeKey, rc);
+        const date = new Date(d.occurredAt);
+        const hourKey = `${date.toISOString().slice(0, 13)}:00`;
+        hourlyMap.set(hourKey, (hourlyMap.get(hourKey) ?? 0) + 1);
+        const dayKey = date.toISOString().slice(0, 10);
+        dailyMap.set(dayKey, (dailyMap.get(dayKey) ?? 0) + 1);
+        const sig = stackSignature(d.stack);
+        if (sig) {
+            const sm = stackMap.get(sig) ?? {
+                count: 0,
+                sampleMessage: d.message,
+                sampleStackHead: topFrames(d.stack, 3),
+            };
+            sm.count++;
+            stackMap.set(sig, sm);
+        }
+        if (d.requestId) {
+            const slot = requestIdMap.get(d.requestId) ?? {};
+            if (d.source === "client")
+                slot.client = d.code;
+            else
+                slot.server = d.code;
+            requestIdMap.set(d.requestId, slot);
+        }
+    }
+    const topCodes = [...codeCounts.entries()]
+        .map(([code, v]) => ({ code, count: v.count, userImpact: v.users.size }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 20);
+    const topRoutes = [...routeCounts.entries()]
+        .map(([key, v]) => ({ route: key.replace(/^[^:]+:/, ""), count: v.count, source: v.source }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 20);
+    const hourlyHistogram = [...hourlyMap.entries()]
+        .map(([hour, count]) => ({ hour, count }))
+        .sort((a, b) => a.hour.localeCompare(b.hour));
+    const dailyHistogram = [...dailyMap.entries()]
+        .map(([day, count]) => ({ day, count }))
+        .sort((a, b) => a.day.localeCompare(b.day));
+    const stackClusters = [...stackMap.entries()]
+        .filter(([, v]) => v.count >= 5)
+        .map(([signature, v]) => ({
+        signature,
+        count: v.count,
+        sampleMessage: v.sampleMessage,
+        sampleStackHead: v.sampleStackHead,
+    }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 20);
+    // 5xx burst detection: split hourlyHistogram into 5-min windows; flag any
+    // window > 3× the rolling 24h avg.
+    const fiveMinMap = new Map();
+    for (const d of docs) {
+        const t = new Date(d.occurredAt);
+        const slot = new Date(t);
+        slot.setUTCMinutes(Math.floor(t.getUTCMinutes() / 5) * 5, 0, 0);
+        const k = slot.toISOString();
+        fiveMinMap.set(k, (fiveMinMap.get(k) ?? 0) + 1);
+    }
+    const rolling24hAvg = totalErrors / Math.max(1, days * 24 * 12); // per 5 min slot
+    const burstWindows = [...fiveMinMap.entries()]
+        .filter(([, count]) => count > 3 * rolling24hAvg && count >= 5)
+        .map(([start, count]) => {
+        const end = new Date(new Date(start).getTime() + 5 * 60000).toISOString();
+        return {
+            start,
+            end,
+            count,
+            multiplier: Number((count / Math.max(0.001, rolling24hAvg)).toFixed(1)),
+        };
+    })
+        .sort((a, b) => b.multiplier - a.multiplier)
+        .slice(0, 10);
+    const clientServerCorrelation = [...requestIdMap.entries()]
+        .filter(([, v]) => v.server && v.client)
+        .slice(0, 20)
+        .map(([requestId, v]) => ({
+        requestId,
+        serverCode: v.server ?? "",
+        clientCode: v.client ?? "",
+    }));
+    // Heuristic recommendations
+    const recommendations = [];
+    const topCode = topCodes[0];
+    if (topCode?.code === "NOT_FOUND") {
+        recommendations.push(`NOT_FOUND is the top code (${topCode.count}× in window). Verify seed coverage of referenced collections.`);
+    }
+    if (topCodes.find((c) => c.code === "PERMISSION_DENIED" && c.count >= 5)) {
+        recommendations.push("PERMISSION_DENIED spike — check Firestore security rules deploy on the affected routes.");
+    }
+    if (topCodes.find((c) => c.code === "CONCURRENT_MODIFICATION" && c.count >= 5)) {
+        recommendations.push("CONCURRENT_MODIFICATION cluster — review transaction retry logic and consider tighter retry bounds.");
+    }
+    const validationFailures = topRoutes.filter((r) => routeCounts.get(`${r.source}:${r.route}`)?.count !== undefined && topCodes[0]?.code === "VALIDATION_FAILED");
+    if (validationFailures.length > 0) {
+        recommendations.push(`VALIDATION_FAILED concentrated on ${validationFailures[0].route} — fix client request shape or extend the route's Zod schema.`);
+    }
+    if (topCodes.find((c) => c.code.startsWith("PAYMENT_ROLLBACK"))) {
+        recommendations.push("PAYMENT_ROLLBACK_* observed — verify Razorpay webhook health and check the refund-rollback path.");
+    }
+    if (topRoutes.find((r) => r.route === "/api/client-errors" &&
+        topCodes[0]?.code === "NETWORK_ERROR")) {
+        recommendations.push("/api/client-errors itself is failing — ingestion endpoint may be down; client errors are being lost.");
+    }
+    if (recommendations.length === 0) {
+        recommendations.push("No anomaly heuristics triggered — failures are within expected distribution.");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        window: { days, from, to: now },
+        source: opts.source ?? "all",
+        totalErrors,
+        uniqueUsers: uniqueUsersSet.size,
+        topCodes,
+        topRoutes,
+        hourlyHistogram,
+        dailyHistogram,
+        stackClusters,
+        burstWindows,
+        clientServerCorrelation,
+        recommendations,
+    };
+}

package/dist/_internal/server/features/maintenance/data.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server-side data loaders for the maintenance pages. Each function reads
+ * straight from the `serverErrors` collection — bypasses the sieve framework
+ * because the workload is tiny (admin UI / a single human) and the queries
+ * are simple.
+ */
+import { type ServerErrorDocument, type ServerErrorSource } from "../../../../features/server-errors/schemas/firestore";
+interface ListOpts {
+    source?: ServerErrorSource;
+    /** Filter by one or more codes. */
+    codes?: string[];
+    limit?: number;
+    /** Look-back window in days; default 7. */
+    days?: number;
+}
+export declare const listServerErrors: (opts?: ListOpts) => Promise<ServerErrorDocument[]>;
+export declare const getServerErrorById: (id: string) => Promise<ServerErrorDocument | null>;
+export declare const findRelatedClientErrors: (requestId: string) => Promise<ServerErrorDocument[]>;
+export interface MaintenanceDashboardCounts {
+    last24h: number;
+    last7d: number;
+    last30d: number;
+    bySource: Record<ServerErrorSource, number>;
+    topCodes: Array<{
+        code: string;
+        count: number;
+    }>;
+    topRoutes: Array<{
+        route: string;
+        count: number;
+        source: string;
+    }>;
+}
+export declare const getMaintenanceDashboardCounts: () => Promise<MaintenanceDashboardCounts>;
+export {};

package/dist/_internal/server/features/maintenance/data.js

@@ -0,0 +1,86 @@
+/**
+ * Server-side data loaders for the maintenance pages. Each function reads
+ * straight from the `serverErrors` collection — bypasses the sieve framework
+ * because the workload is tiny (admin UI / a single human) and the queries
+ * are simple.
+ */
+import { cache } from "react";
+import { getAdminDb } from "../../../../providers/db-firebase/admin";
+import { SERVER_ERRORS_COLLECTION, SERVER_ERROR_FIELDS, } from "../../../../features/server-errors/schemas/firestore";
+export const listServerErrors = cache(async (opts = {}) => {
+    const days = opts.days ?? 7;
+    const since = Date.now() - days * 86400000;
+    let q = getAdminDb()
+        .collection(SERVER_ERRORS_COLLECTION)
+        .where(SERVER_ERROR_FIELDS.OCCURRED_AT, ">=", since);
+    if (opts.source)
+        q = q.where(SERVER_ERROR_FIELDS.SOURCE, "==", opts.source);
+    if (opts.codes && opts.codes.length > 0) {
+        // Firestore "in" requires ≤30 values
+        q = q.where(SERVER_ERROR_FIELDS.CODE, "in", opts.codes.slice(0, 30));
+    }
+    const snap = await q.orderBy(SERVER_ERROR_FIELDS.OCCURRED_AT, "desc").limit(opts.limit ?? 200).get();
+    return snap.docs.map((d) => d.data());
+});
+export const getServerErrorById = cache(async (id) => {
+    const doc = await getAdminDb()
+        .collection(SERVER_ERRORS_COLLECTION)
+        .doc(id)
+        .get();
+    return doc.exists ? doc.data() : null;
+});
+export const findRelatedClientErrors = cache(async (requestId) => {
+    if (!requestId || requestId === "client-self")
+        return [];
+    const snap = await getAdminDb()
+        .collection(SERVER_ERRORS_COLLECTION)
+        .where("requestId", "==", requestId)
+        .where("source", "==", "client")
+        .limit(20)
+        .get();
+    return snap.docs.map((d) => d.data());
+});
+export const getMaintenanceDashboardCounts = cache(async () => {
+    const now = Date.now();
+    const win24h = now - 24 * 3600000;
+    const win7d = now - 7 * 86400000;
+    const win30d = now - 30 * 86400000;
+    const snap = await getAdminDb()
+        .collection(SERVER_ERRORS_COLLECTION)
+        .where("occurredAt", ">=", win30d)
+        .orderBy("occurredAt", "desc")
+        .limit(5000)
+        .get();
+    const docs = snap.docs.map((d) => d.data());
+    const bySource = {
+        vercel: 0,
+        client: 0,
+        function: 0,
+    };
+    const codeMap = new Map();
+    const routeMap = new Map();
+    let last24h = 0;
+    let last7d = 0;
+    const last30d = docs.length;
+    for (const d of docs) {
+        if (d.occurredAt >= win24h)
+            last24h++;
+        if (d.occurredAt >= win7d)
+            last7d++;
+        bySource[d.source]++;
+        codeMap.set(d.code, (codeMap.get(d.code) ?? 0) + 1);
+        const rk = `${d.source}:${d.route}`;
+        const cur = routeMap.get(rk) ?? { count: 0, source: d.source };
+        cur.count++;
+        routeMap.set(rk, cur);
+    }
+    const topCodes = [...codeMap.entries()]
+        .map(([code, count]) => ({ code, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    const topRoutes = [...routeMap.entries()]
+        .map(([k, v]) => ({ route: k.replace(/^[^:]+:/, ""), count: v.count, source: v.source }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    return { last24h, last7d, last30d, bySource, topCodes, topRoutes };
+});

package/dist/_internal/server/features/media/contextGuards.d.ts

@@ -11,6 +11,7 @@
  */
 import { type AllowedMime } from "../../../shared/media/limits";
 import { type MediaFilenameContext } from "../../../../utils/id-generators";
+import type { FirestoreDocument } from "@mohasinac/appkit";
 export declare const CONTEXT_LIMITS: {
     readonly PRODUCT_IMAGE_MAX: 5;
     readonly PRODUCT_VIDEO_MAX: 1;
@@ -31,7 +32,7 @@ export interface GuardError {
     ok: false;
     error: string;
     status: number;
-    details?: Record<string, unknown>;
+    details?: FirestoreDocument;
 }
 export interface GuardSuccess {
     ok: true;

package/dist/_internal/server/features/orders/actions.d.ts

@@ -1,4 +1,5 @@
-export declare function createOrderAction(input: unknown): Promise<import("../../../..").OrderDocument>;
-export declare function cancelOrderAction(input: unknown): Promise<import("../../../..").OrderDocument>;
-export declare function requestReturnAction(input: unknown): Promise<import("../../../..").OrderDocument>;
-export declare function updateOrderStatusAction(input: unknown): Promise<import("../../../..").OrderDocument>;
+import { type ActionResult } from "@mohasinac/appkit/server";
+export declare function createOrderAction(input: unknown): Promise<ActionResult<unknown>>;
+export declare function cancelOrderAction(input: unknown): Promise<ActionResult<unknown>>;
+export declare function requestReturnAction(input: unknown): Promise<ActionResult<unknown>>;
+export declare function updateOrderStatusAction(input: unknown): Promise<ActionResult<unknown>>;

package/dist/_internal/server/features/orders/actions.js

@@ -1,50 +1,64 @@
 "use server";
+import { wrapAction } from "@mohasinac/appkit/server";
 import { orderRepository } from "../../../../repositories";
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers";
 import { createOrderSchema, updateOrderStatusSchema, cancelOrderSchema, } from "../../../shared/features/orders/schema";
 import { assertOrderCancellable, assertReturnWindowOpen } from "./service";
 import { ValidationError } from "../../../shared/errors/index";
 import { OrderNotFoundError, OrderOwnershipError } from "../../../shared/features/orders/errors";
+import { isAdminUser } from "../../../../features/auth/role-predicates";
+// audit-unknown-ok: callback entry point — accepts arbitrary payload value
 export async function createOrderAction(input) {
-    const user = await requireRoleUser(["buyer", "seller", "admin"]);
-    const parsed = createOrderSchema.safeParse(input);
-    if (!parsed.success)
-        throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid order input");
-    return orderRepository.create({
-        ...parsed.data,
-        userId: user.uid,
-        status: "pending",
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["buyer", "seller", "admin"]);
+        const parsed = createOrderSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid order input");
+        return orderRepository.create({
+            ...parsed.data,
+            userId: user.uid,
+            status: "pending",
+        });
     });
 }
+// audit-unknown-ok: callback entry point — accepts arbitrary payload value
 export async function cancelOrderAction(input) {
-    const user = await requireRoleUser(["buyer", "seller", "admin"]);
-    const parsed = cancelOrderSchema.safeParse(input);
-    if (!parsed.success)
-        throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
-    await assertOrderCancellable(parsed.data.orderId, user.uid);
-    return orderRepository.cancelOrder(parsed.data.orderId, parsed.data.reason ?? "Cancelled by user");
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["buyer", "seller", "admin"]);
+        const parsed = cancelOrderSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
+        await assertOrderCancellable(parsed.data.orderId, user.uid);
+        return orderRepository.cancelOrder(parsed.data.orderId, parsed.data.reason ?? "Cancelled by user");
+    });
 }
+// audit-unknown-ok: callback entry point — accepts arbitrary payload value
 export async function requestReturnAction(input) {
-    const user = await requireRoleUser(["buyer", "seller", "admin"]);
-    const parsed = cancelOrderSchema.safeParse(input);
-    if (!parsed.success)
-        throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
-    await assertReturnWindowOpen(parsed.data.orderId, user.uid);
-    return orderRepository.updateStatus(parsed.data.orderId, "return_requested");
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["buyer", "seller", "admin"]);
+        const parsed = cancelOrderSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
+        await assertReturnWindowOpen(parsed.data.orderId, user.uid);
+        return orderRepository.updateStatus(parsed.data.orderId, "return_requested");
+    });
 }
+// audit-unknown-ok: callback entry point — accepts arbitrary payload value
 export async function updateOrderStatusAction(input) {
-    const user = await requireRoleUser(["seller", "admin"]);
-    const parsed = updateOrderStatusSchema.safeParse(input);
-    if (!parsed.success)
-        throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
-    const order = await orderRepository.findById(parsed.data.orderId).catch(() => null);
-    if (!order)
-        throw new OrderNotFoundError(parsed.data.orderId);
-    if (user.role !== "admin" && order.storeId !== user.uid) {
-        throw new OrderOwnershipError(parsed.data.orderId);
-    }
-    return orderRepository.updateStatus(parsed.data.orderId, parsed.data.status, {
-        trackingNumber: parsed.data.trackingNumber,
-        shippingCarrier: parsed.data.carrier,
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["seller", "admin"]);
+        const parsed = updateOrderStatusSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid input");
+        const order = await orderRepository.findById(parsed.data.orderId).catch(() => null);
+        if (!order)
+            throw new OrderNotFoundError(parsed.data.orderId);
+        if (!isAdminUser(user) && order.storeId !== user.uid) {
+            throw new OrderOwnershipError(parsed.data.orderId);
+        }
+        return orderRepository.updateStatus(parsed.data.orderId, parsed.data.status, {
+            trackingNumber: parsed.data.trackingNumber,
+            shippingCarrier: parsed.data.carrier,
+        });
     });
 }

package/dist/_internal/server/features/payouts/actions.d.ts

@@ -1,3 +1,4 @@
+import { type ActionResult } from "@mohasinac/appkit/server";
 export type ApplyRefundDeductionInput = {
     storeId: string;
     orderId: string;
@@ -16,4 +17,4 @@ export type ApplyRefundDeductionResult = {
     applied: false;
     reason: string;
 };
-export declare function applyRefundDeductionAction(input: ApplyRefundDeductionInput): Promise<ApplyRefundDeductionResult>;
+export declare function applyRefundDeductionAction(input: ApplyRefundDeductionInput): Promise<ActionResult<ApplyRefundDeductionResult>>;

package/dist/_internal/server/features/payouts/actions.js

@@ -1,4 +1,5 @@
 "use server";
+import { wrapAction } from "@mohasinac/appkit/server";
 /**
  * applyRefundDeductionAction — deduct a refund from a seller's pending payout.
  *
@@ -15,24 +16,26 @@
 import { payoutRepository } from "../../../../repositories";
 import { ValidationError } from "../../../../errors";
 export async function applyRefundDeductionAction(input) {
-    if (input.refundedAmountInPaise <= 0) {
-        throw new ValidationError("Refund amount must be positive");
-    }
-    const feeRate = input.platformFeeRate ?? 0.05;
-    const deductedAmount = Math.round(input.refundedAmountInPaise * (1 - feeRate));
-    const pending = await payoutRepository.findPendingByStore(input.storeId);
-    if (!pending) {
-        return { applied: false, reason: "no_pending_payout" };
-    }
-    if (!pending.orderIds.includes(input.orderId)) {
-        return { applied: false, reason: "order_not_in_payout" };
-    }
-    const updated = await payoutRepository.applyRefundDeduction(pending.id, {
-        orderId: input.orderId,
-        refundId: input.refundId,
-        refundedAmount: input.refundedAmountInPaise,
-        deductedAmount,
-        reason: input.reason,
+    return wrapAction(async () => {
+        if (input.refundedAmountInPaise <= 0) {
+            throw new ValidationError("Refund amount must be positive");
+        }
+        const feeRate = input.platformFeeRate ?? 0.05;
+        const deductedAmount = Math.round(input.refundedAmountInPaise * (1 - feeRate));
+        const pending = await payoutRepository.findPendingByStore(input.storeId);
+        if (!pending) {
+            return { applied: false, reason: "no_pending_payout" };
+        }
+        if (!pending.orderIds.includes(input.orderId)) {
+            return { applied: false, reason: "order_not_in_payout" };
+        }
+        const updated = await payoutRepository.applyRefundDeduction(pending.id, {
+            orderId: input.orderId,
+            refundId: input.refundId,
+            refundedAmount: input.refundedAmountInPaise,
+            deductedAmount,
+            reason: input.reason,
+        });
+        return { applied: true, payoutId: updated.id, netAmount: updated.netAmount ?? updated.amount };
     });
-    return { applied: true, payoutId: updated.id, netAmount: updated.netAmount ?? updated.amount };
 }

package/dist/_internal/server/features/pre-orders/actions.d.ts

@@ -1,7 +1,2 @@
-export declare function reservePreOrderAction(input: unknown): Promise<{
-    preOrderId: string;
-    buyerId: string;
-    quantity: number;
-    depositAmount: number;
-    status: string;
-}>;
+import { type ActionResult } from "@mohasinac/appkit/server";
+export declare function reservePreOrderAction(input: unknown): Promise<ActionResult<unknown>>;

package/dist/_internal/server/features/pre-orders/actions.js

@@ -1,26 +1,30 @@
 "use server";
+import { wrapAction } from "@mohasinac/appkit/server";
 import { productRepository } from "../../../../repositories";
 import { requireRoleUser } from "../../../../providers/auth-firebase/helpers";
 import { reservePreOrderSchema } from "../../../shared/features/pre-orders/schema";
 import { assertPreOrderAvailable, computeDeposit } from "./service";
 import { ValidationError } from "../../../shared/errors/index";
+// audit-unknown-ok: callback entry point — accepts arbitrary payload value
 export async function reservePreOrderAction(input) {
-    const user = await requireRoleUser(["buyer", "seller", "admin"]);
-    const parsed = reservePreOrderSchema.safeParse(input);
-    if (!parsed.success)
-        throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid reservation input");
-    const { preOrderId, quantity } = parsed.data;
-    const product = await assertPreOrderAvailable(preOrderId, quantity);
-    const deposit = computeDeposit(product);
-    // Increment reservation count
-    await productRepository.update(preOrderId, {
-        preOrderCurrentCount: (product.preOrderCurrentCount ?? 0) + quantity,
+    return wrapAction(async () => {
+        const user = await requireRoleUser(["buyer", "seller", "admin"]);
+        const parsed = reservePreOrderSchema.safeParse(input);
+        if (!parsed.success)
+            throw new ValidationError(parsed.error.issues[0]?.message ?? "Invalid reservation input");
+        const { preOrderId, quantity } = parsed.data;
+        const product = await assertPreOrderAvailable(preOrderId, quantity);
+        const deposit = computeDeposit(product);
+        // Increment reservation count
+        await productRepository.update(preOrderId, {
+            preOrderCurrentCount: (product.preOrderCurrentCount ?? 0) + quantity,
+        });
+        return {
+            preOrderId,
+            buyerId: user.uid,
+            quantity,
+            depositAmount: deposit * quantity,
+            status: "pending_payment",
+        };
     });
-    return {
-        preOrderId,
-        buyerId: user.uid,
-        quantity,
-        depositAmount: deposit * quantity,
-        status: "pending_payment",
-    };
 }

package/dist/_internal/server/features/pre-orders/og.js

@@ -4,6 +4,7 @@ import { resolveOgImageUrl } from "../seo/og";
 export function renderPreOrderOg(doc, opts) {
     const locale = opts.locale ?? "en-IN";
     const release = doc?.preOrderReleaseDate
+        // audit-unknown-ok: TS structural escape — primitive cast
         ? new Date(doc.preOrderReleaseDate)
         : null;
     const releaseDateLabel = release

package/dist/_internal/server/features/pre-orders/service.js

@@ -12,6 +12,7 @@ export async function assertPreOrderAvailable(preOrderId, requestedQty = 1) {
     const current = product.preOrderCurrentCount ?? 0;
     if (current + requestedQty > maxQty)
         throw new PreOrderSoldOutError(preOrderId);
+    // audit-unknown-ok: TS structural escape — domain document type lacks index signature
     return product;
 }
 /** Compute deposit amount in paise. */