@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/providers/payment-manual/index.d.ts

@@ -25,6 +25,17 @@ export declare class ManualPaymentProvider extends IPaymentProvider {
     createOrder(amount: number, currency: string, metadata?: Record<string, JsonValue>): Promise<PaymentOrder>;
     /** Manual payments have no webhook source — always false. */
     verifyWebhook(_payload: string, _signature: string): boolean;
+    /**
+     * Manual payment has no gateway callback to verify, so there is nothing that
+     * could make this true.
+     *
+     * 🛑 `false`, never `true`. This is the check that decides whether a payment
+     * is genuine; a provider that cannot verify must REJECT, not wave through.
+     * Returning `true` here would mean a forged gateway callback is accepted on
+     * any install where the gateway flag is off — which is exactly the install
+     * where nobody is watching for one.
+     */
+    verifyCheckoutSignature(_payload: Record<string, string>, _secret: string): boolean;
     /**
      * Manual payments are considered captured the moment the buyer's
      * reference/proof is recorded — there is no separate auth+capture step.

package/dist/providers/payment-manual/index.js

@@ -40,6 +40,19 @@ export class ManualPaymentProvider extends IPaymentProvider {
     verifyWebhook(_payload, _signature) {
         return false;
     }
+    /**
+     * Manual payment has no gateway callback to verify, so there is nothing that
+     * could make this true.
+     *
+     * 🛑 `false`, never `true`. This is the check that decides whether a payment
+     * is genuine; a provider that cannot verify must REJECT, not wave through.
+     * Returning `true` here would mean a forged gateway callback is accepted on
+     * any install where the gateway flag is off — which is exactly the install
+     * where nobody is watching for one.
+     */
+    verifyCheckoutSignature(_payload, _secret) {
+        return false;
+    }
     /**
      * Manual payments are considered captured the moment the buyer's
      * reference/proof is recorded — there is no separate auth+capture step.

package/dist/providers/payment-phonepe/index.d.ts

@@ -36,9 +36,9 @@
  * });
  * ```
  */
-import type { JsonValue } from "@mohasinac/appkit";
+import type { JsonValue } from "../../schemas/types";
 import { IPaymentProvider } from "../../contracts";
-import type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord } from "../../contracts";
+import type { CheckoutIntentMetadata, PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord } from "../../contracts";
 /**
  * PhonePe's `metaInfo` (udf1-udf5, ≤256 chars each) is the only channel that
  * survives from `createOrder()` through to BOTH the Order Status API AND the
@@ -48,12 +48,15 @@ import type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecor
  * the tab mid-payment. See `confirmAndPlacePhonePeOrderAction` in
  * `_internal/server/features/checkout/actions.ts`.
  */
-export interface PhonePeCheckoutIntent {
-    uid: string;
-    addressId?: string;
-    outOfStockPolicy?: string;
-    notes?: string;
-}
+/**
+ * @deprecated Use `CheckoutIntentMetadata` from `contracts/payment`.
+ *
+ * Kept as an alias so existing imports keep compiling. Every field is ours —
+ * the only PhonePe-specific thing was the name, and it forced generic checkout
+ * code to import this provider for a TYPE (A4). PhonePe carries it in
+ * `udf1..udf4`; that is a packing detail, not a definition.
+ */
+export type PhonePeCheckoutIntent = CheckoutIntentMetadata;
 export interface PhonePeConfig {
     clientId: string;
     clientSecret: string;
@@ -97,6 +100,19 @@ export declare class PhonePeProvider extends IPaymentProvider {
      * the existing webhook route already does.
      */
     verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * PhonePe has no buyer-present SIGNED callback of this shape.
+     *
+     * Its redirect carries no signature — confirmation comes from the Order
+     * Status API or the webhook (`verifyWebhook` above, which does the real
+     * `validateCallback`). So there is nothing here to verify, and the honest
+     * answer is rejection.
+     *
+     * 🛑 `false`, never `true`. "No signature to check" and "the signature is
+     * good" must never collapse into the same return value on the call that
+     * decides whether a payment is genuine.
+     */
+    verifyCheckoutSignature(_payload: Record<string, string>, _secret: string): boolean;
     /** Wraps the Order Status API. `orderId` here is our `merchantOrderId`. */
     capturePayment(orderId: string): Promise<PaymentCapture>;
     /**

package/dist/providers/payment-phonepe/index.js

@@ -47,7 +47,19 @@ function packMetaInfo(intent) {
         .udf2(intent.addressId ?? "")
         .udf3(intent.outOfStockPolicy ?? "")
         .udf4((intent.notes ?? "").slice(0, 256))
-        .udf5("")
+        /*
+         * Item 1.39 — the buyer-policy consent record id.
+         *
+         * 🛑 PhonePe's metaInfo is FIVE named slots, not an open map, so unlike
+         * Razorpay's generic `notes` flattening a new intent field is invisible
+         * here until it is named. udf5 was the one spare slot and this is what it
+         * is now for. The webhook path has no session, so without this the
+         * consent taken before the capture could not be found after it — and the
+         * placement would have to either refuse a paid order or write one with no
+         * consent record. Both are unacceptable; a 36-byte id in a spare slot is
+         * neither.
+         */
+        .udf5(intent.policyConsentId ?? "")
         .build();
 }
 function unpackMetaInfo(meta) {
@@ -58,6 +70,7 @@ function unpackMetaInfo(meta) {
         addressId: meta.udf2 || undefined,
         outOfStockPolicy: meta.udf3 || undefined,
         notes: meta.udf4 || undefined,
+        policyConsentId: meta.udf5 || undefined,
     };
 }
 /** merchantOrderId / merchantRefundId — ≤63 chars, `_`/`-` only (PhonePe constraint). */
@@ -158,6 +171,21 @@ export class PhonePeProvider extends IPaymentProvider {
             return false;
         }
     }
+    /**
+     * PhonePe has no buyer-present SIGNED callback of this shape.
+     *
+     * Its redirect carries no signature — confirmation comes from the Order
+     * Status API or the webhook (`verifyWebhook` above, which does the real
+     * `validateCallback`). So there is nothing here to verify, and the honest
+     * answer is rejection.
+     *
+     * 🛑 `false`, never `true`. "No signature to check" and "the signature is
+     * good" must never collapse into the same return value on the call that
+     * decides whether a payment is genuine.
+     */
+    verifyCheckoutSignature(_payload, _secret) {
+        return false;
+    }
     /** Wraps the Order Status API. `orderId` here is our `merchantOrderId`. */
     async capturePayment(orderId) {
         const status = await this.client.getOrderStatus(orderId, true);

package/dist/providers/payment-razorpay/index.d.ts

@@ -50,7 +50,7 @@
  * });
  * ```
  */
-import type { JsonValue } from "@mohasinac/appkit";
+import type { JsonValue } from "../../schemas/types";
 import { IPaymentProvider } from "../../contracts";
 import type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord } from "../../contracts";
 export { verifyPaymentSignature, verifyWebhookSignature, type RazorpayPaymentResult, } from "./signature";
@@ -89,6 +89,19 @@ export declare class RazorpayProvider extends IPaymentProvider {
      * is not guaranteed to reproduce the bytes that were signed.
      */
     verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * The buyer-present callback from `checkout.js`.
+     *
+     * 🛑 Delegates to the SAME `verifyPaymentSignature` the checkout action
+     * called directly before A4b — identical HMAC, identical `hexEqual`
+     * comparison, identical `if (!keySecret) return false`. The dispatch moved
+     * behind the contract; the arithmetic did not move at all. That is what let
+     * this be proven equivalent rather than argued about.
+     *
+     * The three fields are checked before the cast: a callback missing any of
+     * them cannot be verified, and "cannot verify" is rejection.
+     */
+    verifyCheckoutSignature(payload: Record<string, string>, secret: string): boolean;
     /**
      * Resolves a `pay_…` id for either id shape.
      *

package/dist/providers/payment-razorpay/index.js

@@ -54,7 +54,9 @@ import Razorpay from "razorpay";
 import { IPaymentProvider } from "../../contracts/index.js";
 import { getDefaultCurrency } from "../../core/baseline-resolver.js";
 import { paiseToRupees } from "../../core/money.js";
-import { verifyWebhookSignature } from "./signature.js";
+// `verifyPaymentSignature` is re-exported below, but a re-export does not bring
+// it into THIS module's scope — `verifyCheckoutSignature` calls it directly.
+import { verifyPaymentSignature, verifyWebhookSignature } from "./signature.js";
 export { verifyPaymentSignature, verifyWebhookSignature, } from "./signature.js";
 /** Razorpay's own order status vocabulary → the contract's. */
 function mapOrderStatus(status) {
@@ -144,6 +146,24 @@ export class RazorpayProvider extends IPaymentProvider {
             return false;
         return verifyWebhookSignature(payload, signature, this.webhookSecret);
     }
+    /**
+     * The buyer-present callback from `checkout.js`.
+     *
+     * 🛑 Delegates to the SAME `verifyPaymentSignature` the checkout action
+     * called directly before A4b — identical HMAC, identical `hexEqual`
+     * comparison, identical `if (!keySecret) return false`. The dispatch moved
+     * behind the contract; the arithmetic did not move at all. That is what let
+     * this be proven equivalent rather than argued about.
+     *
+     * The three fields are checked before the cast: a callback missing any of
+     * them cannot be verified, and "cannot verify" is rejection.
+     */
+    verifyCheckoutSignature(payload, secret) {
+        const { razorpay_order_id, razorpay_payment_id, razorpay_signature } = payload;
+        if (!razorpay_order_id || !razorpay_payment_id || !razorpay_signature)
+            return false;
+        return verifyPaymentSignature({ razorpay_order_id, razorpay_payment_id, razorpay_signature }, secret);
+    }
     /**
      * Resolves a `pay_…` id for either id shape.
      *

package/dist/providers/shipping-shiprocket/index.d.ts

@@ -54,12 +54,18 @@
  *
  * ── What is deliberately NOT here ────────────────────────────────────────
  *
- * Inbound webhooks. Shiprocket pushes status updates to a URL configured in
+ * The webhook ROUTE. Shiprocket pushes status updates to a URL configured in
  * its dashboard and authenticates them with an `x-api-key` header whose value
- * you set there — a THIRD secret, and an inbound route rather than a provider
- * method. `trackShipment` below polls instead, which is correct for a provider
- * contract and wasteful as a status mechanism; the webhook is the better
- * answer and belongs in its own route with its own verification.
+ * you set there — an inbound route rather than a provider method, so the route
+ * lives at `/api/shipping/webhook` (item 1.38) and not on this class.
+ * `trackShipment` below polls instead, which is correct for a provider contract
+ * and wasteful as a status mechanism.
+ *
+ * What DOES live here is the credential check itself —
+ * `verifyShiprocketWebhookToken` below — for the same reason
+ * `packCashfreeWebhookSignature` lives in the Cashfree adapter: the encoding of
+ * a provider's authentication belongs to that provider, so no route invents its
+ * own comparison.
  *
  * @tag domain:shipping
  * @tag layer:providers
@@ -67,6 +73,35 @@
  */
 import { IShippingProvider } from "../../contracts";
 import type { CreateShipmentInput, Shipment, TrackingInfo, ServiceabilityResult, WalletBalance } from "../../contracts";
+/**
+ * The header Shiprocket echoes its configured webhook token back on.
+ *
+ * Named here rather than inline at the route, so the route cannot drift from
+ * the provider's actual contract — the mistake that makes a webhook endpoint
+ * 401 everything in production while reading as correct.
+ */
+export declare const SHIPROCKET_WEBHOOK_TOKEN_HEADER = "x-api-key";
+/**
+ * Authenticate an inbound Shiprocket delivery.
+ *
+ * 🛑 BE HONEST ABOUT WHAT THIS IS. Shiprocket offers a SHARED SECRET echoed in
+ * a header, not an HMAC over the body — you choose the value in its dashboard
+ * and it sends that same value on every delivery. So unlike Razorpay or
+ * Cashfree, this proves the CALLER knows the secret; it does **not** prove the
+ * body was not altered in transit, and no amount of care here can make it do
+ * so. That is the strongest check the provider offers. It is written down
+ * rather than glossed over because the difference matters for what the route
+ * is allowed to do with the payload: authenticated-but-unsigned data is good
+ * enough to RECORD, which is what the route does with it.
+ *
+ * 🛑 FAILS CLOSED on every path, and `timingSafeEqual` rather than `===`. A
+ * plain comparison on a secret returns after the first differing byte, which
+ * leaks the secret one character at a time to anyone who can measure the
+ * response. The length guard is there because `timingSafeEqual` THROWS on
+ * differing lengths — and the throw would itself be a side channel, besides
+ * turning a rejection into a 500 (the one status a sender retries).
+ */
+export declare function verifyShiprocketWebhookToken(received: string | null | undefined, expected: string | undefined): boolean;
 export interface ShiprocketConfig {
     /** The API user's email. See the header on why this is not a "login id". */
     email: string;

package/dist/providers/shipping-shiprocket/index.js

@@ -54,23 +54,67 @@
  *
  * ── What is deliberately NOT here ────────────────────────────────────────
  *
- * Inbound webhooks. Shiprocket pushes status updates to a URL configured in
+ * The webhook ROUTE. Shiprocket pushes status updates to a URL configured in
  * its dashboard and authenticates them with an `x-api-key` header whose value
- * you set there — a THIRD secret, and an inbound route rather than a provider
- * method. `trackShipment` below polls instead, which is correct for a provider
- * contract and wasteful as a status mechanism; the webhook is the better
- * answer and belongs in its own route with its own verification.
+ * you set there — an inbound route rather than a provider method, so the route
+ * lives at `/api/shipping/webhook` (item 1.38) and not on this class.
+ * `trackShipment` below polls instead, which is correct for a provider contract
+ * and wasteful as a status mechanism.
+ *
+ * What DOES live here is the credential check itself —
+ * `verifyShiprocketWebhookToken` below — for the same reason
+ * `packCashfreeWebhookSignature` lives in the Cashfree adapter: the encoding of
+ * a provider's authentication belongs to that provider, so no route invents its
+ * own comparison.
  *
  * @tag domain:shipping
  * @tag layer:providers
  * @tag access:server-only
  */
+import { timingSafeEqual } from "node:crypto";
 import { z } from "zod";
 import { IShippingProvider } from "../../contracts/index.js";
 import { ApiError } from "../../errors/index.js";
 import { normalizeError } from "../../errors/normalize.js";
 import { serverLogger } from "../../monitoring/server-logger.js";
 const API_BASE = "https://apiv2.shiprocket.in/v1/external";
+/**
+ * The header Shiprocket echoes its configured webhook token back on.
+ *
+ * Named here rather than inline at the route, so the route cannot drift from
+ * the provider's actual contract — the mistake that makes a webhook endpoint
+ * 401 everything in production while reading as correct.
+ */
+export const SHIPROCKET_WEBHOOK_TOKEN_HEADER = "x-api-key";
+/**
+ * Authenticate an inbound Shiprocket delivery.
+ *
+ * 🛑 BE HONEST ABOUT WHAT THIS IS. Shiprocket offers a SHARED SECRET echoed in
+ * a header, not an HMAC over the body — you choose the value in its dashboard
+ * and it sends that same value on every delivery. So unlike Razorpay or
+ * Cashfree, this proves the CALLER knows the secret; it does **not** prove the
+ * body was not altered in transit, and no amount of care here can make it do
+ * so. That is the strongest check the provider offers. It is written down
+ * rather than glossed over because the difference matters for what the route
+ * is allowed to do with the payload: authenticated-but-unsigned data is good
+ * enough to RECORD, which is what the route does with it.
+ *
+ * 🛑 FAILS CLOSED on every path, and `timingSafeEqual` rather than `===`. A
+ * plain comparison on a secret returns after the first differing byte, which
+ * leaks the secret one character at a time to anyone who can measure the
+ * response. The length guard is there because `timingSafeEqual` THROWS on
+ * differing lengths — and the throw would itself be a side channel, besides
+ * turning a rejection into a 500 (the one status a sender retries).
+ */
+export function verifyShiprocketWebhookToken(received, expected) {
+    if (!expected || !received)
+        return false;
+    const a = Buffer.from(received, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 // ── Response contracts ──────────────────────────────────────────────────────
 //
 // Every one of these is a CLAIM about a payload nobody here has seen. Parsing

package/dist/providers/tax-india-gst/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * India GST — the default `ITaxProvider`.
+ *
+ * ## 🛑 This DELEGATES. Every figure still comes from `calculateGst` /
+ * `calculateGstInclusive`.
+ *
+ * Not a rewrite, on purpose. Those two functions split the intra-state half
+ * differently and the difference is load-bearing:
+ *
+ *   calculateGst           cgst = sgst = round(gst / 2); gst RE-DERIVED as half*2
+ *   calculateGstInclusive  cgst = round(gst / 2); sgst = round(gst - cgst)
+ *
+ * Measured on ₹66.67 at 18% inclusive: cgst 5.09, sgst 5.08 — the remainder
+ * lands in sgst so the parts still sum to 10.17. Reimplementing the maths here
+ * to make the two agree would move a paisa on figures GST is filed on. The
+ * seam's whole value is that it adds an abstraction WITHOUT touching arithmetic.
+ *
+ * Verified by `.build-memory/tax-roundtrip.mjs` — 397 breakdowns across every
+ * slab, both supply directions and the rounding edges, byte-identical.
+ *
+ * @tag domain:tax
+ * @tag layer:provider
+ * @tag access:isomorphic
+ */
+import { ITaxProvider, type TaxBreakdown, type TaxJurisdiction, type TaxableItem } from "../../contracts/tax";
+export declare class IndiaGstTaxProvider extends ITaxProvider {
+    readonly id = "india-gst";
+    /**
+     * Intra-state when origin and destination states match.
+     *
+     * 🛑 Absent information is treated as INTRA-state, which preserves the
+     * existing behaviour exactly rather than improving on it. Every current
+     * caller passes an `intraState` boolean it computed itself, and the defaults
+     * across those call sites resolve to intra-state when a place of supply is
+     * unknown — changing that here would alter tax on orders with an incomplete
+     * delivery snapshot, which is precisely the class of row most likely to
+     * exist. A stricter rule is a product decision, not a side effect of adding
+     * an interface.
+     */
+    isSameRegion(jurisdiction: TaxJurisdiction): boolean;
+    onExclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, taxableAmount: number): TaxBreakdown;
+    onInclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, gross: number): TaxBreakdown;
+}
+/** The default instance. A consumer in another jurisdiction registers its own. */
+export declare const indiaGstTaxProvider: IndiaGstTaxProvider;

package/dist/providers/tax-india-gst/index.js

@@ -0,0 +1,78 @@
+/**
+ * India GST — the default `ITaxProvider`.
+ *
+ * ## 🛑 This DELEGATES. Every figure still comes from `calculateGst` /
+ * `calculateGstInclusive`.
+ *
+ * Not a rewrite, on purpose. Those two functions split the intra-state half
+ * differently and the difference is load-bearing:
+ *
+ *   calculateGst           cgst = sgst = round(gst / 2); gst RE-DERIVED as half*2
+ *   calculateGstInclusive  cgst = round(gst / 2); sgst = round(gst - cgst)
+ *
+ * Measured on ₹66.67 at 18% inclusive: cgst 5.09, sgst 5.08 — the remainder
+ * lands in sgst so the parts still sum to 10.17. Reimplementing the maths here
+ * to make the two agree would move a paisa on figures GST is filed on. The
+ * seam's whole value is that it adds an abstraction WITHOUT touching arithmetic.
+ *
+ * Verified by `.build-memory/tax-roundtrip.mjs` — 397 breakdowns across every
+ * slab, both supply directions and the rounding edges, byte-identical.
+ *
+ * @tag domain:tax
+ * @tag layer:provider
+ * @tag access:isomorphic
+ */
+import { ITaxProvider, } from "../../contracts/tax.js";
+import { calculateGst, calculateGstInclusive, } from "../../_internal/shared/fees/calculator.js";
+/** CGST and SGST are each HALF the headline rate; IGST carries all of it. */
+function componentsFrom(breakdown, rate) {
+    const half = rate / 2;
+    if (breakdown.igst > 0 || (breakdown.cgst === 0 && breakdown.sgst === 0 && breakdown.gstAmount > 0)) {
+        return [{ code: "igst", label: "IGST", rate, amount: breakdown.igst }];
+    }
+    if (breakdown.gstAmount === 0)
+        return [];
+    return [
+        { code: "cgst", label: "CGST", rate: half, amount: breakdown.cgst },
+        { code: "sgst", label: "SGST", rate: half, amount: breakdown.sgst },
+    ];
+}
+function toBreakdown(breakdown, rate) {
+    return {
+        taxableAmount: breakdown.taxableAmount,
+        taxAmount: breakdown.gstAmount,
+        components: componentsFrom(breakdown, rate),
+    };
+}
+export class IndiaGstTaxProvider extends ITaxProvider {
+    constructor() {
+        super(...arguments);
+        this.id = "india-gst";
+    }
+    /**
+     * Intra-state when origin and destination states match.
+     *
+     * 🛑 Absent information is treated as INTRA-state, which preserves the
+     * existing behaviour exactly rather than improving on it. Every current
+     * caller passes an `intraState` boolean it computed itself, and the defaults
+     * across those call sites resolve to intra-state when a place of supply is
+     * unknown — changing that here would alter tax on orders with an incomplete
+     * delivery snapshot, which is precisely the class of row most likely to
+     * exist. A stricter rule is a product decision, not a side effect of adding
+     * an interface.
+     */
+    isSameRegion(jurisdiction) {
+        const { origin, destination } = jurisdiction;
+        if (!origin || !destination)
+            return true;
+        return origin.trim().toUpperCase() === destination.trim().toUpperCase();
+    }
+    onExclusive(item, jurisdiction, taxableAmount) {
+        return toBreakdown(calculateGst(item.rate, this.isSameRegion(jurisdiction), taxableAmount), item.rate);
+    }
+    onInclusive(item, jurisdiction, gross) {
+        return toBreakdown(calculateGstInclusive(item.rate, this.isSameRegion(jurisdiction), gross), item.rate);
+    }
+}
+/** The default instance. A consumer in another jurisdiction registers its own. */
+export const indiaGstTaxProvider = new IndiaGstTaxProvider();

package/dist/providers.d.ts

@@ -22,6 +22,9 @@ export type { RazorpayConfig } from "./providers/payment-razorpay/index";
 export { verifyPaymentSignature as verifyRazorpayPaymentSignature, verifyWebhookSignature as verifyRazorpayWebhookSignature, type RazorpayPaymentResult, } from "./providers/payment-razorpay/signature";
 export { PhonePeProvider } from "./providers/payment-phonepe/index";
 export type { PhonePeConfig } from "./providers/payment-phonepe/index";
+export { CashfreeProvider } from "./providers/payment-cashfree/index";
+export type { CashfreeConfig } from "./providers/payment-cashfree/index";
+export { packCashfreeWebhookSignature, verifyCashfreeWebhookSignature, CASHFREE_WEBHOOK_SIGNATURE_HEADER, CASHFREE_WEBHOOK_TIMESTAMP_HEADER, CASHFREE_SESSION_METADATA_KEY, } from "./providers/payment-cashfree/index";
 export { rupeesToPaise, paiseToRupees } from "./core/money";
 export { ManualPaymentProvider } from "./providers/payment-manual/index";
 export { ManualShippingProvider } from "./providers/shipping-manual/index";

package/dist/providers.js

@@ -25,6 +25,11 @@ export { RazorpayProvider } from "./providers/payment-razorpay/index.js";
 export { verifyPaymentSignature as verifyRazorpayPaymentSignature, verifyWebhookSignature as verifyRazorpayWebhookSignature, } from "./providers/payment-razorpay/signature.js";
 // Payment (PhonePe) — disabled by default; siteSettings.payment.phonepeEnabled turns it on
 export { PhonePeProvider } from "./providers/payment-phonepe/index.js";
+// Payment (Cashfree) — disabled by default; siteSettings.payment.cashfreeEnabled turns it on.
+// Bare `fetch`, no SDK, no npm dependency. `order_amount` is decimal rupees, so the
+// adapter converts at its own boundary and keeps the contract in the smallest unit.
+export { CashfreeProvider } from "./providers/payment-cashfree/index.js";
+export { packCashfreeWebhookSignature, verifyCashfreeWebhookSignature, CASHFREE_WEBHOOK_SIGNATURE_HEADER, CASHFREE_WEBHOOK_TIMESTAMP_HEADER, CASHFREE_SESSION_METADATA_KEY, } from "./providers/payment-cashfree/index.js";
 export { rupeesToPaise, paiseToRupees } from "./core/money.js";
 // Payment (manual) — the default provider
 export { ManualPaymentProvider } from "./providers/payment-manual/index.js";

package/dist/react/contexts/SessionContext.d.ts

@@ -26,7 +26,23 @@ export interface SessionUser {
      * before slugs existed have none, and `/profile/{uid}` still resolves.
      */
     slug?: string;
+    /**
+     * Legacy scalar — the HIGHEST-RANKED role this user holds, derived by
+     * `UserRepository.mapDoc`.
+     *
+     * 🛑 Do not gate on it. `roles` is the authority; a scalar cannot answer
+     * "is this seller also an employee" and answering it wrong is silent.
+     */
     role: string;
+    /**
+     * THE role authority — every role this account holds (up to
+     * `getMaxRolesPerUser()`, 3 today). Read it through `rolesOf(user)` so the
+     * `moderator` → `employee` fold applies and the legacy scalar is the
+     * fallback for a session hydrated before this field existed.
+     */
+    roles?: string[];
+    /** 🛑 DISPLAY ONLY — a badge or a default tab. Never an authorization input. */
+    primaryRole?: string;
     disabled?: boolean;
     createdAt?: Date;
     updatedAt?: Date;
@@ -42,7 +58,7 @@ export interface SessionUser {
     publicProfile?: FirestoreDocument;
     /**
      * Buyer activity counts, DERIVED by `/api/user/profile` — orders placed,
-     * auctions won, reviews written. Each is optional and `undefined` means the
+     * collector drops won, reviews written. Each is optional and `undefined` means the
      * count could not be taken, which is NOT the same as zero: render nothing.
      *
      * 🛑 Not the `users/{uid}.stats` document field, which has no writer at all
@@ -54,7 +70,7 @@ export interface SessionUser {
      */
     stats?: {
         totalOrders?: number;
-        auctionsWon?: number;
+        collectorDropsWon?: number;
         reviewsCount?: number;
     };
     metadata?: FirestoreDocument;

package/dist/react/contexts/SessionContext.js

@@ -67,7 +67,15 @@ function buildSessionUser(authUser, serverData) {
         displayName: serverData.displayName || authUser.displayName,
         photoURL: serverData.photoURL || authUser.photoURL,
         phoneNumber: serverData.phoneNumber || authUser.phoneNumber,
+        /*
+         * The role SET carried through client hydration (1.43). Forwarding only
+         * `role` here meant every client-side gate fell back to the scalar even
+         * when the server had sent the array — the dual-read reached the API
+         * response and was then dropped one layer short of the consumer.
+         */
         role: serverData.role || "user",
+        roles: serverData.roles,
+        primaryRole: serverData.primaryRole,
         disabled: serverData.disabled,
         createdAt: serverData.createdAt
             ? new Date(serverData.createdAt)
@@ -144,6 +152,8 @@ export function SessionProvider({ children, initialUser, endpoints: endpointOver
                 photoURL: data.photoURL || null,
                 phoneNumber: data.phoneNumber || null,
                 role: data.role || "user",
+                roles: data.roles,
+                primaryRole: data.primaryRole,
                 disabled: data.disabled,
                 createdAt: data.createdAt ? new Date(data.createdAt) : undefined,
                 updatedAt: data.updatedAt ? new Date(data.updatedAt) : undefined,
@@ -210,7 +220,19 @@ export function SessionProvider({ children, initialUser, endpoints: endpointOver
             const fresh = await fetchUserProfileFromServer();
             if (!fresh || fresh.uid !== user.uid)
                 return;
-            const rbacFieldsChanged = fresh.role !== user.role ||
+            /*
+             * 🛑 The role SET is compared, not just the scalar. An admin ADDING a
+             * role to someone (the owner's actual requirement — upgrading is adding,
+             * not replacing) leaves the highest-ranked scalar unchanged in most
+             * cases: granting `seller` to an `admin` does not move `role` at all. So
+             * the scalar comparison alone saw "nothing changed" and the open tab
+             * never picked up the new access — the same class of bug as the
+             * canTestAdmin one this block was written for.
+             */
+            const rolesChanged = (fresh.roles ?? []).length !== (user.roles ?? []).length ||
+                (fresh.roles ?? []).some((r) => !(user.roles ?? []).includes(r));
+            const rbacFieldsChanged = rolesChanged ||
+                fresh.role !== user.role ||
                 fresh.isTester !== user.isTester ||
                 fresh.canTestAdmin !== user.canTestAdmin ||
                 fresh.disabled !== user.disabled ||

package/dist/react/hooks/useBrowsePageFlags.d.ts

@@ -1,4 +1,4 @@
-import { type BrowsePageKey } from "../../_internal/shared/listing-types/feature-flags";
+import { type BrowsePageKey, type FlagValue } from "../../_internal/shared/listing-types/feature-flags";
 /**
  * Which public browse sections are open, as configured in
  * `siteSettings.listings.browsePages`.
@@ -13,7 +13,7 @@ import { type BrowsePageKey } from "../../_internal/shared/listing-types/feature
  * blank the navbar on every cold load until the settings request resolved —
  * visible flicker on every page of the site rather than one empty browse tab.
  */
-export type BrowsePageFlagsShape = Partial<Record<BrowsePageKey, boolean>>;
+export type BrowsePageFlagsShape = Partial<Record<BrowsePageKey, FlagValue>>;
 export type BrowsePageFlags = Record<BrowsePageKey, boolean> & {
     /** True when the section is open (or the setting has not loaded yet). */
     isEnabled: (page: BrowsePageKey) => boolean;

package/dist/react/hooks/useBrowsePageFlags.js

@@ -1,12 +1,18 @@
 "use client";
 import { useSiteSettings } from "../../core/hooks/useSiteSettings.js";
-import { ALL_BROWSE_PAGES, browsePageForPath, } from "../../_internal/shared/listing-types/feature-flags.js";
+import { ALL_BROWSE_PAGES, browsePageForPath, isBrowsePageListed, } from "../../_internal/shared/listing-types/feature-flags.js";
 export function useBrowsePageFlags() {
     const { data } = useSiteSettings();
-    const bp = data?.listings?.browsePages;
-    // Closed only when EXPLICITLY false — a missing flag, or settings that have
-    // not loaded, means open.
-    const flags = Object.fromEntries(ALL_BROWSE_PAGES.map((page) => [page, bp?.[page] !== false]));
+    const settings = { listings: { browsePages: data?.listings?.browsePages } };
+    /*
+     * 🛑 `"unlisted"` also withdraws the nav link, not just `false` — the
+     * section's own page keeps serving at 200 either way (that's the 404 gate
+     * in `closedSurfacePrefixes`, unaffected by this). `isBrowsePageListed`
+     * already encodes "missing or settings-not-loaded-yet means open", so the
+     * permissive-default behaviour this hook's docstring describes is
+     * unchanged.
+     */
+    const flags = Object.fromEntries(ALL_BROWSE_PAGES.map((page) => [page, isBrowsePageListed(page, settings)]));
     return {
         ...flags,
         isEnabled: (page) => flags[page],

package/dist/react/hooks/useCanSeePrices.js

@@ -40,7 +40,7 @@ import { useOptionalSession } from "../contexts/SessionContext.js";
  * than ripped out, because that is what makes this one boolean a real switch
  * instead of a rewrite. Two things outside this file move with it, and must
  * move back if it is ever flipped:
- *   · `gatedPriceWebPageJsonLd()` — dropped from the product and auction
+ *   · `gatedPriceWebPageJsonLd()` — dropped from the product and collector drop
  *     pages. `isAccessibleForFree: false` over a price anyone can read is a
  *     false declaration to a crawler, which is the exact mismatch the node was
  *     added to prevent, pointed the other way.

package/dist/react/hooks/useCountdown.d.ts

@@ -18,7 +18,7 @@ export interface CountdownRemaining {
 /**
  * @example
  * ```tsx
- * const remaining = useCountdown(auction.endsAt);
+ * const remaining = useCountdown(collectorDrop.endsAt);
  * if (!remaining) return <span>Ended</span>;
  * return <span>{remaining.hours}h {remaining.minutes}m {remaining.seconds}s</span>;
  * ```