@mohasinac/appkit 4.62.0 → 4.63.0

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

@@ -0,0 +1,58 @@
+/**
+ * The ONE write path for a platform rate.
+ *
+ * ## Why there is exactly one
+ *
+ * Rates live on `siteSettings`, which `PUT /api/admin/site` can already write
+ * — so this is not the only way the numbers CAN move. It is the only way they
+ * move with a recorded reason, an effective date and an `adminAuditLog` row,
+ * and that difference is the whole point of `/admin/pricing`.
+ *
+ * The general settings form stays able to write them. Locking it out would
+ * mean an admin fixing a typo in the COD ceiling gets a 400 from the page that
+ * has always owned it, and the fix would be to come here — which is a worse
+ * outcome than an occasional unlogged edit. What this buys is that the
+ * DELIBERATE act of repricing has one door with a record behind it.
+ *
+ * ## 🛑 Forward-only, enforced at the WRITE
+ *
+ * `rejectRateChange` is a pure function and lives in the registry so the form
+ * can run it too — but the form running it is a courtesy, and this is the
+ * enforcement. A backdated change here would restate figures already invoiced
+ * and already paid out; see the registry header.
+ */
+/**
+ * How many changes the log keeps, newest first.
+ *
+ * Sized so a year of ordinary repricing fits: 16 rates changed a few times
+ * each is well under this, and the page shows only the most recent per rate
+ * anyway. The cap exists because the array rides on a document every request
+ * reads, not because 200 entries is a lot of data.
+ */
+export declare const RATE_CHANGE_LOG_MAX = 200;
+export interface ApplyRateChangeInput {
+    path: string;
+    newValue: number;
+    /** Omit for "now". Never earlier than now — see `rejectRateChange`. */
+    effectiveFrom?: Date;
+    reason?: string;
+}
+export interface ApplyRateChangeResult {
+    path: string;
+    previousValue: number | null;
+    newValue: number;
+    effectiveFrom: Date;
+}
+/**
+ * Change one rate.
+ *
+ * 🛑 **One rate per call, on purpose.** A bulk form would need one reason
+ * covering a heterogeneous set, which is the same argument that removed the
+ * bulk offer-cancel: one shared reason across unlike records is worse audit
+ * data than no bulk action. Repricing three things is three decisions.
+ */
+export declare function applyRateChange(input: ApplyRateChangeInput, actor: {
+    uid: string;
+    name?: string;
+    isAdmin: boolean;
+}, now?: Date): Promise<ApplyRateChangeResult>;

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

@@ -0,0 +1,144 @@
+/**
+ * The ONE write path for a platform rate.
+ *
+ * ## Why there is exactly one
+ *
+ * Rates live on `siteSettings`, which `PUT /api/admin/site` can already write
+ * — so this is not the only way the numbers CAN move. It is the only way they
+ * move with a recorded reason, an effective date and an `adminAuditLog` row,
+ * and that difference is the whole point of `/admin/pricing`.
+ *
+ * The general settings form stays able to write them. Locking it out would
+ * mean an admin fixing a typo in the COD ceiling gets a 400 from the page that
+ * has always owned it, and the fix would be to come here — which is a worse
+ * outcome than an occasional unlogged edit. What this buys is that the
+ * DELIBERATE act of repricing has one door with a record behind it.
+ *
+ * ## 🛑 Forward-only, enforced at the WRITE
+ *
+ * `rejectRateChange` is a pure function and lives in the registry so the form
+ * can run it too — but the form running it is a courtesy, and this is the
+ * enforcement. A backdated change here would restate figures already invoiced
+ * and already paid out; see the registry header.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { siteSettingsRepository } from "../../../../features/admin/repository/site-settings.repository.js";
+import { SITE_SETTINGS_COLLECTION, } from "../../../../features/admin/schemas/firestore.js";
+import { canEditRate, rateByPath, rejectRateChange, } from "../../../shared/features/pricing/rate-registry.js";
+import { recordAdminAction } from "../audit-log/actions.js";
+import { AdminAuditActionValues } from "../../../../features/audit-log/schemas/firestore.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+const SINGLETON_ID = "global";
+/**
+ * How many changes the log keeps, newest first.
+ *
+ * Sized so a year of ordinary repricing fits: 16 rates changed a few times
+ * each is well under this, and the page shows only the most recent per rate
+ * anyway. The cap exists because the array rides on a document every request
+ * reads, not because 200 entries is a lot of data.
+ */
+export const RATE_CHANGE_LOG_MAX = 200;
+/** Read a dotted path off the settings document. `null` when absent. */
+function readRate(settings, path) {
+    const value = path
+        .split(".")
+        .reduce((acc, key) => (acc && typeof acc === "object" ? acc[key] : undefined), settings);
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Change one rate.
+ *
+ * 🛑 **One rate per call, on purpose.** A bulk form would need one reason
+ * covering a heterogeneous set, which is the same argument that removed the
+ * bulk offer-cancel: one shared reason across unlike records is worse audit
+ * data than no bulk action. Repricing three things is three decisions.
+ */
+export async function applyRateChange(input, actor, now = new Date()) {
+    const descriptor = rateByPath(input.path);
+    if (!descriptor) {
+        throw new ValidationError("That is not a rate this platform charges.", {
+            path: `Unknown rate: ${input.path}`,
+        });
+    }
+    if (!canEditRate(descriptor.tier, actor.isAdmin)) {
+        /*
+         * A statutory rate reaches this branch for EVERYONE, admins included —
+         * which is why the message names the real destination rather than
+         * implying the caller lacks a permission they could be granted.
+         */
+        throw new ValidationError(descriptor.tier === "statutory"
+            ? "Statutory rates are not set here — they are sourced per HSN code in Tax codes."
+            : "Only an administrator can change a policy ceiling.", { path: descriptor.label });
+    }
+    const settings = await siteSettingsRepository.getSingleton();
+    const previousValue = readRate(settings, descriptor.path);
+    const effectiveFrom = input.effectiveFrom ?? now;
+    const problem = rejectRateChange({ effectiveFrom, previousValue, newValue: input.newValue, reason: input.reason }, descriptor.tier, now);
+    if (problem) {
+        throw new ValidationError(problem, { newValue: problem });
+    }
+    const entry = {
+        path: descriptor.path,
+        previousValue,
+        newValue: input.newValue,
+        effectiveFrom,
+        changedByUid: actor.uid,
+        changedByName: actor.name ?? "",
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        changedAt: now,
+    };
+    /*
+     * 🛑 A DOTTED path for the rate, and a whole-array write for the log.
+     *
+     * `update()` replaces a nested map wholesale (D13, recorded at length in
+     * `updateSingleton`), so writing `{ commissions: { platformFeePercent: 2 } }`
+     * would delete every other commission. The dotted form touches one leaf.
+     *
+     * The log cannot use `arrayUnion` because that cannot enforce the cap — the
+     * same reason `withHistory`'s batch paths fold in memory. Newest first, so
+     * the slice drops the OLDEST.
+     */
+    const nextLog = [entry, ...(settings.rateChanges ?? [])].slice(0, RATE_CHANGE_LOG_MAX);
+    await getAdminDb()
+        .collection(SITE_SETTINGS_COLLECTION)
+        .doc(SINGLETON_ID)
+        .update({
+        [descriptor.path]: input.newValue,
+        rateChanges: nextLog,
+        updatedAt: now,
+    });
+    /*
+     * Best-effort, never fails the change — the same contract every other
+     * `recordAdminAction` caller has. The rate has already moved; refusing to
+     * acknowledge it because the log write failed would leave the admin
+     * believing it had not.
+     */
+    try {
+        await recordAdminAction({
+            actorUid: actor.uid,
+            actorName: actor.name,
+            action: AdminAuditActionValues.PRICING_UPDATE,
+            targetType: "siteSettings",
+            targetId: descriptor.path,
+            targetLabel: descriptor.label,
+            ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+            metadata: {
+                tier: descriptor.tier,
+                unit: descriptor.unit,
+                previousValue,
+                newValue: input.newValue,
+                effectiveFrom: effectiveFrom.toISOString(),
+            },
+        });
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("applyRateChange: audit log write failed", {
+            path: descriptor.path,
+            message: normalized.message,
+        });
+    }
+    return { path: descriptor.path, previousValue, newValue: input.newValue, effectiveFrom };
+}

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

@@ -45,6 +45,8 @@ import { serverLogger } from "../../../../monitoring/index.js";
 import { isFinalSaleExempt, RETURN_REASON_LABEL, } from "../../../shared/features/orders/return-reasons.js";
 import { REFUND_COPY } from "../../../shared/features/orders/refund-copy.js";
 import { applyRefundDeductionAction } from "../payouts/actions.js";
+/* Phase 7c — the credit note. Swallows its own failures by design: see its 🛑. */
+import { issueCreditNoteForRefund } from "../invoicing/credit-note.js";
 import { getAdminDb } from "../../../../providers/db-firebase/index.js";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION, } from "../../../../features/products/schemas/firestore.js";
 /**
@@ -362,6 +364,30 @@ export async function processRefundAction(input) {
             // the reconciler will look at it once and find it already done.
             serverLogger.warn("refund: claim not marked settled", { refundId });
         });
+        /*
+         * ── PHASE 7c: the credit note that documents this reversal ────────────
+         *
+         * 🛑 HERE, at settlement, and not at reservation. A credit note numbered
+         * when the entry was reserved would leave a numbered reversal in the
+         * series on every provider failure — for money that never moved, with a
+         * number that cannot be withdrawn.
+         *
+         * 🛑 AWAITED but never allowed to throw (the issuer swallows its own
+         * failures and says so). The money has already left the gateway by this
+         * line; raising here would report a successful refund as failed, and an
+         * operator would retry a refund that already happened. A missing credit
+         * note is a reporting gap a backfill can close; a double refund is not.
+         *
+         * No renderer is passed, so this NUMBERS the reversal without producing
+         * a PDF. That is what the GSTR-1 export needs — it reconciles numbers
+         * and amounts. The buyer's PDF follows the invoice's own lazy pattern
+         * when a surface asks for it.
+         */
+        const settledOrder = await orderRepository.findById(input.orderId);
+        const settledEvent = settledOrder?.refunds?.find((r) => r.refundId === refundId);
+        if (settledOrder && settledEvent) {
+            await issueCreditNoteForRefund(settledOrder, settledEvent);
+        }
         // SB-UNI-N — revoke any available (unclaimed) digital codes linked to this order.
         revokeAvailableDigitalCodes(input.orderId, digitalCodeItems);
         /*

package/dist/_internal/server/features/shipping/book-split.d.ts

@@ -0,0 +1,86 @@
+/**
+ * S5a — one parcel per destination on a coordinated purchase.
+ *
+ * A coordinated purchase can send each member's share to their own address
+ * (`CoordinationMember.destinationAddressId`). That is N parcels from one
+ * order, which is N bookings and N serviceability checks.
+ *
+ * ## 🛑 Serviceability is checked for EVERY destination BEFORE any booking
+ *
+ * Booking as you go and failing on the fourth leaves three parcels already
+ * accepted by the carrier and a coordinator who cannot undo them — the
+ * cancel path exists but the money and the pickup slot are gone. A
+ * pre-flight over all destinations turns that into one refusal naming the
+ * pincode that cannot be served, before anything is committed.
+ *
+ * Two-phase on purpose, and it is NOT a transaction: a carrier booking has
+ * no rollback. What the pre-flight buys is that the common failure — an
+ * unservable pincode — is caught while rolling back is still free.
+ *
+ * ## 🛑 Bounded by `SHARED_PURCHASE_MAX_MEMBERS`
+ *
+ * Five destinations is five outbound calls for serviceability and five more
+ * to book, on a path somebody is waiting on. That ceiling is why the limit
+ * exists at all; see the registry's own header.
+ */
+import { type CoordinationMember } from "../../../shared/features/offers/coordination";
+export interface DestinationCheck {
+    addressId: string;
+    pincode: string;
+    serviceable: boolean;
+}
+/**
+ * Can every named destination actually be delivered to?
+ *
+ * 🛑 Returns the FULL list, not the first failure. A coordinator fixing one
+ * unservable address only to be told about the next one is three round trips
+ * for a problem that was knowable in one — and each round trip is another
+ * chance for someone to give up with the arrangement half-built.
+ *
+ * 🛑 An UNREADABLE check is treated as serviceable. A provider timeout is not
+ * evidence that a pincode cannot be served, and refusing on it would block a
+ * legitimate purchase on an outage we caused. The booking itself will fail
+ * loudly if the address really is unservable, which is the recoverable
+ * direction — and it is the same reasoning `bookShipment` applies to a wallet
+ * balance it could not read.
+ *
+ * A MISSING pincode is the opposite case and is reported unserviceable: that
+ * is a fact about the stored address, not about the provider, and it will not
+ * fix itself on a retry.
+ */
+export declare function checkDestinations(members: readonly CoordinationMember[], 
+/**
+ * 🛑 The parcel's weight in kg, NOT an origin pincode.
+ *
+ * `IShippingProvider.checkServiceability(pincode, weight)` reads its first
+ * argument as the DESTINATION. A reasonable guess of `(origin, destination)`
+ * would pass two strings into a `(string, number)` signature — caught by
+ * `tsc` here, but worth naming because the argument ORDER is the part a
+ * reader assumes.
+ */
+weightKg: number): Promise<DestinationCheck[]>;
+/**
+ * Refuse the whole arrangement if any destination cannot be served.
+ *
+ * Names every failing pincode, for the reason above.
+ */
+export declare function assertAllServiceable(checks: readonly DestinationCheck[]): void;
+/**
+ * The parcels one coordinated order produces.
+ *
+ * 🛑 **Keyed by ADDRESS, not by member.** Two members naming the same address
+ * are one parcel, not two — that is the whole reason `destinationIds` returns
+ * a distinct set. Fanning out per member would book the courier twice to the
+ * same door and bill for both.
+ *
+ * 🛑 **A member with no `destinationAddressId` is NOT in this list.** Absent
+ * means "the coordinator's address", which is the ordinary one-parcel case
+ * and is handled by `bookShipment`'s existing single-delivery path — the
+ * order's own snapshot. Inventing a parcel for them here would duplicate it.
+ */
+export interface ParcelPlan {
+    addressId: string;
+    /** Members whose share rides in this parcel. Never empty. */
+    memberUids: string[];
+}
+export declare function planParcels(members: readonly CoordinationMember[]): ParcelPlan[];

package/dist/_internal/server/features/shipping/book-split.js

@@ -0,0 +1,130 @@
+/**
+ * S5a — one parcel per destination on a coordinated purchase.
+ *
+ * A coordinated purchase can send each member's share to their own address
+ * (`CoordinationMember.destinationAddressId`). That is N parcels from one
+ * order, which is N bookings and N serviceability checks.
+ *
+ * ## 🛑 Serviceability is checked for EVERY destination BEFORE any booking
+ *
+ * Booking as you go and failing on the fourth leaves three parcels already
+ * accepted by the carrier and a coordinator who cannot undo them — the
+ * cancel path exists but the money and the pickup slot are gone. A
+ * pre-flight over all destinations turns that into one refusal naming the
+ * pincode that cannot be served, before anything is committed.
+ *
+ * Two-phase on purpose, and it is NOT a transaction: a carrier booking has
+ * no rollback. What the pre-flight buys is that the common failure — an
+ * unservable pincode — is caught while rolling back is still free.
+ *
+ * ## 🛑 Bounded by `SHARED_PURCHASE_MAX_MEMBERS`
+ *
+ * Five destinations is five outbound calls for serviceability and five more
+ * to book, on a path somebody is waiting on. That ceiling is why the limit
+ * exists at all; see the registry's own header.
+ */
+import { getProviders } from "../../../../contracts/registry.js";
+import { addressesRepository } from "../../../../features/addresses/repository/addresses.repository.js";
+import { SHARED_PURCHASE_MAX_MEMBERS, destinationIds, } from "../../../shared/features/offers/coordination.js";
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+/**
+ * Can every named destination actually be delivered to?
+ *
+ * 🛑 Returns the FULL list, not the first failure. A coordinator fixing one
+ * unservable address only to be told about the next one is three round trips
+ * for a problem that was knowable in one — and each round trip is another
+ * chance for someone to give up with the arrangement half-built.
+ *
+ * 🛑 An UNREADABLE check is treated as serviceable. A provider timeout is not
+ * evidence that a pincode cannot be served, and refusing on it would block a
+ * legitimate purchase on an outage we caused. The booking itself will fail
+ * loudly if the address really is unservable, which is the recoverable
+ * direction — and it is the same reasoning `bookShipment` applies to a wallet
+ * balance it could not read.
+ *
+ * A MISSING pincode is the opposite case and is reported unserviceable: that
+ * is a fact about the stored address, not about the provider, and it will not
+ * fix itself on a retry.
+ */
+export async function checkDestinations(members, 
+/**
+ * 🛑 The parcel's weight in kg, NOT an origin pincode.
+ *
+ * `IShippingProvider.checkServiceability(pincode, weight)` reads its first
+ * argument as the DESTINATION. A reasonable guess of `(origin, destination)`
+ * would pass two strings into a `(string, number)` signature — caught by
+ * `tsc` here, but worth naming because the argument ORDER is the part a
+ * reader assumes.
+ */
+weightKg) {
+    const ids = destinationIds(members);
+    if (ids.length === 0)
+        return [];
+    if (ids.length > SHARED_PURCHASE_MAX_MEMBERS) {
+        throw new ValidationError(`A coordinated purchase can ship to at most ${SHARED_PURCHASE_MAX_MEMBERS} addresses.`, { destinations: `${ids.length} distinct addresses named.` });
+    }
+    /*
+     * 🛑 Optional on the registry. This is the serviceability PRE-FLIGHT, so
+     * with no provider the honest answer is "unknown", not "unserviceable":
+     * reporting every destination as unserviceable would block an accept that
+     * manual dispatch handles perfectly well.
+     */
+    const provider = getProviders().shipping;
+    if (!provider) {
+        return ids.map((addressId) => ({ addressId, pincode: "", serviceable: true }));
+    }
+    const docs = await Promise.all(ids.map((id) => addressesRepository.findById(id)));
+    return Promise.all(ids.map(async (addressId, i) => {
+        /*
+         * 🛑 `.postalCode` needs no reveal — it is not PII and
+         * `AddressRepository` deliberately leaves it unencrypted so it stays
+         * queryable (see its own `computeAddressHash` comment). Calling
+         * `revealAddress` here would decrypt a name and a phone number we have
+         * no use for, on a path that only needs six digits.
+         */
+        const pincode = docs[i]?.postalCode ?? "";
+        if (!pincode)
+            return { addressId, pincode, serviceable: false };
+        try {
+            const res = await provider.checkServiceability(pincode, weightKg);
+            return { addressId, pincode, serviceable: res.isServiceable };
+        }
+        catch (err) {
+            void normalizeError(err);
+            serverLogger.warn("checkDestinations: serviceability unreadable", { addressId, pincode });
+            return { addressId, pincode, serviceable: true };
+        }
+    }));
+}
+/**
+ * Refuse the whole arrangement if any destination cannot be served.
+ *
+ * Names every failing pincode, for the reason above.
+ */
+export function assertAllServiceable(checks) {
+    const bad = checks.filter((c) => !c.serviceable);
+    if (bad.length === 0)
+        return;
+    throw new ValidationError(bad.length === 1
+        ? "One delivery address cannot be served by the courier."
+        : `${bad.length} delivery addresses cannot be served by the courier.`, {
+        destinations: bad
+            .map((b) => (b.pincode ? `${b.pincode}: not serviceable` : "missing pincode"))
+            .join("; "),
+    });
+}
+export function planParcels(members) {
+    const byAddress = new Map();
+    for (const m of members) {
+        if (!m.destinationAddressId)
+            continue;
+        const uids = byAddress.get(m.destinationAddressId);
+        if (uids)
+            uids.push(m.uid);
+        else
+            byAddress.set(m.destinationAddressId, [m.uid]);
+    }
+    return [...byAddress].map(([addressId, memberUids]) => ({ addressId, memberUids }));
+}

package/dist/_internal/server/features/shipping/book.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Booking a parcel through the platform's own carrier account — Part 1′.
+ *
+ * ## 🛑 Why this could not be built until Part 14
+ *
+ * `CreateShipmentInput` needs a structured `{name, phone, addressLine1, city,
+ * state, pincode, country}` for BOTH ends. Until the delivery snapshot landed
+ * the order carried `shippingAddress?: string` — flat free text with no
+ * pincode and no phone — and the only way to produce a party from it was to
+ * parse prose. The `placeOfSupply` comment already refuses that for tax, and
+ * the same argument holds here: a mis-parsed pincode is a parcel that goes to
+ * the wrong city, except nothing errors and the label prints fine.
+ *
+ * `deliveryPartyFor(order)` now returns exactly that shape, or `null` when a
+ * required field is missing — which is the only honest answer for an order
+ * placed before the snapshot existed.
+ *
+ * ## 🛑 `platformBookedShipment` is the flag this writes
+ *
+ * `order-math.ts` gates shipping reimbursement on it
+ * (`if (order.platformBookedShipment === true) return 0`) and
+ * `quote.ts:241` records that it has had **ZERO writers** — so the
+ * reimbursement rule has been reading a flag nothing sets. This is its
+ * writer, which is why the booking and the dispatch form are one unit of
+ * work and why the form must not ship first: a "Book through us" button with
+ * no booking behind it is a control the server refuses.
+ */
+export interface BookShipmentInput {
+    orderId: string;
+    /** Centimetres and kilograms, from the dispatch form's box preset. */
+    dimensions: {
+        weight: number;
+        length: number;
+        width: number;
+        height: number;
+    };
+    /** The store address the courier collects from. */
+    pickupAddressId: string;
+}
+export interface BookShipmentResult {
+    trackingId: string;
+    courier?: string;
+    estimatedDelivery?: string;
+}
+/**
+ * Book one parcel.
+ *
+ * ## 🛑 The wallet is checked BEFORE the booking, and a failure is a 409
+ *
+ * A carrier account with no balance rejects the booking — but some providers
+ * accept it and then silently fail to hand over, which produces a tracking id
+ * that never moves. Checking first turns "the parcel vanished" into "top up
+ * the account", and the 409 is deliberate: the request is well-formed and the
+ * seller is not confused, the world is simply not ready.
+ *
+ * 🛑 `getWalletBalance` is NOT abstract on `IShippingProvider` — manual
+ * shipping has no wallet, so a provider that does not implement it returns
+ * undefined and the check is SKIPPED rather than failing. A missing balance
+ * must never block a manual dispatch.
+ */
+export declare function bookShipment(input: BookShipmentInput): Promise<BookShipmentResult>;