@mohasinac/appkit 4.53.1 → 4.54.0

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

@@ -0,0 +1,356 @@
+/**
+ * @mohasinac/shipping-shiprocket — IShippingProvider over Shiprocket's v1 API.
+ *
+ * ── Read this before trusting it ──────────────────────────────────────────
+ *
+ * ── What is verified, and what is not ────────────────────────────────────
+ *
+ * ✅ VERIFIED against the live API (2026-10-20, real API-user credentials):
+ *    `POST /v1/external/auth/login` returns HTTP 200 with
+ *    `{ company_id, created_at, email, first_name, id, last_name, token }`.
+ *    The `token` field is present and non-empty, which is the only field
+ *    `loginResponse` requires — the rest are ignored, as Zod ignores unknown
+ *    keys by default.
+ *
+ * 🛑 NOT VERIFIED: every other endpoint. Order creation, AWB assignment,
+ *    tracking, serviceability and label generation all MUTATE or bill against
+ *    a real carrier account, so none was called. Their field names below are
+ *    claims taken from the published docs, not facts read off a payload.
+ *
+ * That asymmetry is the reason every response is parsed through Zod rather
+ * than cast: an unverified contract that is wrong surfaces as a named error at
+ * the boundary, instead of as an `undefined` AWB written to an order and shown
+ * to a buyer as a tracking number that tracks nothing.
+ *
+ * ── Auth: why a dedicated API user, and why the token is cached ───────────
+ *
+ * Shiprocket's core v1 API has no long-lived key/secret. You POST credentials
+ * to `/v1/external/auth/login` and receive a bearer token valid for roughly
+ * ten days, then log in again.
+ *
+ * 🛑 Those credentials should be a DEDICATED API USER (Shiprocket dashboard →
+ * Settings → API → Configure), not the dashboard login. Using the dashboard
+ * account means the token dies whenever someone changes that password — a
+ * shipping integration that breaks on an unrelated admin action — and it hands
+ * full account scope to this process. The env var is named
+ * `SHIPROCKET_LOGIN_USER_EMAIL` rather than `LOGIN_ID` because the login payload
+ * field is `email`; a var called "login id" invites someone to put a username
+ * in it and get a 400 they cannot explain.
+ *
+ * 🛑 The token is cached in module state with its expiry. Logging in per
+ * request would mean two round trips for every shipment and would hit
+ * Shiprocket's auth rate limit under any real volume. A 401 mid-flight clears
+ * the cache and retries ONCE — exactly once, because a credential that is
+ * genuinely wrong must fail fast rather than loop.
+ *
+ * ── What is deliberately NOT here ────────────────────────────────────────
+ *
+ * Inbound webhooks. 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.
+ *
+ * @tag domain:shipping
+ * @tag layer:providers
+ * @tag access:server-only
+ */
+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";
+// ── Response contracts ──────────────────────────────────────────────────────
+//
+// Every one of these is a CLAIM about a payload nobody here has seen. Parsing
+// rather than casting is what turns a wrong claim into a named error.
+const loginResponse = z.object({
+    token: z.string().min(1),
+});
+const createOrderResponse = z.object({
+    order_id: z.union([z.number(), z.string()]),
+    shipment_id: z.union([z.number(), z.string()]),
+    /** Absent until an AWB is assigned — which is a separate call. */
+    awb_code: z.string().nullish(),
+    courier_name: z.string().nullish(),
+    status: z.string().nullish(),
+});
+const trackingResponse = z.object({
+    tracking_data: z.object({
+        shipment_status: z.union([z.number(), z.string()]).nullish(),
+        shipment_track: z
+            .array(z.object({
+            current_status: z.string().nullish(),
+            delivered_date: z.string().nullish(),
+            edd: z.string().nullish(),
+        }))
+            .nullish(),
+        shipment_track_activities: z
+            .array(z.object({
+            date: z.string().nullish(),
+            status: z.string().nullish(),
+            activity: z.string().nullish(),
+            location: z.string().nullish(),
+        }))
+            .nullish(),
+    }),
+});
+const serviceabilityResponse = z.object({
+    data: z.object({
+        available_courier_companies: z
+            .array(z.object({
+            courier_name: z.string(),
+            estimated_delivery_days: z.union([z.number(), z.string()]).nullish(),
+            rate: z.union([z.number(), z.string()]).nullish(),
+        }))
+            .nullish(),
+    }),
+});
+function num(v, fallback = 0) {
+    const n = typeof v === "string" ? Number.parseFloat(v) : v;
+    return typeof n === "number" && Number.isFinite(n) ? n : fallback;
+}
+/**
+ * Parse an upstream response, or throw a named contract error.
+ *
+ * 🛑 `.parse()`, not `.safeParse()`. The only branch on failure is to throw,
+ * and a `safeParse` whose `.success` is checked once and converted straight
+ * into a throw is indistinguishable — to a reader and to
+ * `audit-unvalidated-safeparse` — from a result nobody handled.
+ *
+ * 🛑 Logs the FAILING PATHS, never the payload. A Shiprocket response carries
+ * the buyer's name, phone and full address, and an error log is the wrong
+ * place for all three.
+ */
+function parseUpstream(contract, json, what) {
+    try {
+        return contract.parse(json);
+    }
+    catch (err) {
+        // Normalised first, before the value is inspected — audit-catch-normalize
+        // is strict-zero and the ZodError branch below reads `err` either way.
+        void normalizeError(err);
+        const issues = err instanceof z.ZodError
+            ? err.issues.map((i) => i.path.join("."))
+            : [];
+        serverLogger.error("shiprocket: response contract mismatch", {
+            what,
+            issues,
+        });
+        throw new ApiError(502, `Shiprocket ${what} returned an unexpected shape.`, {
+            code: "SHIPROCKET_CONTRACT_MISMATCH",
+        });
+    }
+}
+export class ShiprocketShippingProvider extends IShippingProvider {
+    constructor(config) {
+        super();
+        this.config = config;
+        this.name = "shiprocket";
+        this.token = null;
+        this.tokenExpiresAt = 0;
+        /*
+         * 🛑 Refuses at CONSTRUCTION, not at first use. `providers.config.ts`
+         * already argues this: a degraded shipping provider hands back a synthetic
+         * tracking id for a parcel no carrier was told about, so the seller sees an
+         * AWB-shaped string and a success toast while the buyer gets a number that
+         * tracks nothing. A loud failure at boot is attributable and recoverable by
+         * flipping one setting; the silent version is neither.
+         */
+        if (!config.email?.trim() || !config.password?.trim()) {
+            throw new Error("[shiprocket] SHIPROCKET_LOGIN_USER_EMAIL / SHIPROCKET_API_PASSWORD are empty. " +
+                "Create a dedicated API user in Shiprocket (Settings -> API -> Configure) " +
+                "and set both, or set siteSettings.shipping.provider back to 'manual'. " +
+                "This refuses rather than degrading because a fallback would return a " +
+                "synthetic tracking id for a parcel that was never booked.");
+        }
+    }
+    /**
+     * A bearer token, logging in only when the cached one is absent or stale.
+     *
+     * The 60-second safety margin matters: a token that expires mid-request
+     * produces a 401 the caller has to interpret, and shaving a minute off a
+     * ten-day lifetime costs nothing.
+     */
+    async getToken(force = false) {
+        if (!force && this.token && Date.now() < this.tokenExpiresAt - 60000) {
+            return this.token;
+        }
+        const res = await fetch(`${API_BASE}/auth/login`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                email: this.config.email,
+                password: this.config.password,
+            }),
+        });
+        if (!res.ok) {
+            throw new ApiError(502, `Shiprocket auth failed (${res.status}). Check the API user's credentials.`, { code: "SHIPROCKET_AUTH_FAILED" });
+        }
+        const parsed = parseUpstream(loginResponse, await res.json(), "auth/login");
+        this.token = parsed.token;
+        // Their docs say ~10 days; treated as 9 so a boundary never surprises us.
+        this.tokenExpiresAt = Date.now() + 9 * 24 * 60 * 60 * 1000;
+        return this.token;
+    }
+    /**
+     * One authenticated call, with a single re-auth on 401.
+     *
+     * 🛑 Exactly one retry. A token that expired early is worth one more attempt;
+     * a credential that is wrong must fail rather than loop, because a retry loop
+     * against an auth endpoint is how an integration gets rate-limited and then
+     * looks like an outage.
+     */
+    async call(path, init, contract) {
+        const attempt = async (force) => {
+            const token = await this.getToken(force);
+            return fetch(`${API_BASE}${path}`, {
+                ...init,
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                    ...(init.headers ?? {}),
+                },
+            });
+        };
+        let res = await attempt(false);
+        if (res.status === 401) {
+            this.token = null;
+            res = await attempt(true);
+        }
+        if (!res.ok) {
+            throw new ApiError(502, `Shiprocket ${path} failed (${res.status}).`, { code: "SHIPROCKET_REQUEST_FAILED" });
+        }
+        const json = await res.json();
+        return parseUpstream(contract, json, path);
+    }
+    /** Their order payload wants the address flattened across many keys. */
+    addressFields(prefix, a) {
+        const p = prefix === "billing" ? "billing" : "shipping";
+        return {
+            [`${p}_customer_name`]: a.name,
+            [`${p}_address`]: a.addressLine1,
+            [`${p}_address_2`]: a.addressLine2 ?? "",
+            [`${p}_city`]: a.city,
+            [`${p}_pincode`]: a.pincode,
+            [`${p}_state`]: a.state,
+            [`${p}_country`]: a.country,
+            [`${p}_phone`]: a.phone,
+        };
+    }
+    async createShipment(data) {
+        const body = {
+            order_id: data.orderId,
+            order_date: new Date().toISOString().slice(0, 10),
+            pickup_location: this.config.pickupLocation ?? "Primary",
+            ...this.addressFields("billing", data.delivery),
+            shipping_is_billing: true,
+            /*
+             * Shiprocket requires at least one order item. We do not receive the
+             * line items on this contract — `CreateShipmentInput` carries only
+             * dimensions and the two addresses — so a single synthetic line stands
+             * for the parcel. 🛑 This is a known gap, not a simplification: a real
+             * integration needs per-item HSN and value for a commercial invoice, and
+             * that means widening the shared contract rather than inventing values
+             * here.
+             */
+            order_items: [
+                {
+                    name: `Order ${data.orderId}`,
+                    sku: data.orderId,
+                    units: 1,
+                    selling_price: data.codAmount ?? 0,
+                },
+            ],
+            payment_method: data.isCod ? "COD" : "Prepaid",
+            sub_total: data.codAmount ?? 0,
+            length: data.dimensions.length,
+            breadth: data.dimensions.width,
+            height: data.dimensions.height,
+            weight: data.dimensions.weight,
+        };
+        const out = await this.call("/orders/create/adhoc", { method: "POST", body: JSON.stringify(body) }, createOrderResponse);
+        return {
+            id: String(out.shipment_id),
+            /*
+             * 🛑 Falls back to the shipment id when no AWB has been assigned yet —
+             * assignment is a separate call. It does NOT invent a `manual_…` string:
+             * a synthetic tracking number that a buyer can paste into a courier site
+             * and get nothing from is the failure mode this whole provider is
+             * supposed to avoid.
+             */
+            trackingId: out.awb_code?.trim() || String(out.shipment_id),
+            orderId: data.orderId,
+            status: out.status ?? "created",
+            courier: out.courier_name ?? undefined,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    async trackShipment(trackingId) {
+        const out = await this.call(`/courier/track/awb/${encodeURIComponent(trackingId)}`, { method: "GET" }, trackingResponse);
+        const t = out.tracking_data;
+        const head = t.shipment_track?.[0];
+        return {
+            trackingId,
+            currentStatus: head?.current_status ?? String(t.shipment_status ?? "unknown"),
+            estimatedDelivery: head?.edd ?? undefined,
+            events: (t.shipment_track_activities ?? []).map((e) => ({
+                status: e.status ?? "",
+                location: e.location ?? "",
+                timestamp: e.date ?? "",
+                description: e.activity ?? undefined,
+            })),
+        };
+    }
+    async cancelShipment(shipmentId) {
+        await this.call("/orders/cancel", { method: "POST", body: JSON.stringify({ ids: [shipmentId] }) }, 
+        // Their cancel returns a message envelope we do not read; accepting any
+        // object keeps us from asserting a shape we have not seen.
+        z.object({}).passthrough());
+    }
+    async checkServiceability(pincode, weight) {
+        /*
+         * 🛑 `pickup_postcode` is required by their API and we do not have it on
+         * this contract. Taken from the registered pickup location's name is NOT
+         * possible — it is a nickname, not a pincode — so this returns
+         * "unserviceable" rather than guessing a origin pincode, which would
+         * produce confidently wrong rates.
+         */
+        const origin = process.env.SHIPROCKET_PICKUP_PINCODE?.trim();
+        if (!origin) {
+            serverLogger.warn("shiprocket: SHIPROCKET_PICKUP_PINCODE unset — serviceability cannot be checked", { pincode });
+            return { isServiceable: false, couriers: [] };
+        }
+        try {
+            const out = await this.call(`/courier/serviceability/?pickup_postcode=${encodeURIComponent(origin)}` +
+                `&delivery_postcode=${encodeURIComponent(pincode)}` +
+                `&weight=${encodeURIComponent(String(weight))}&cod=0`, { method: "GET" }, serviceabilityResponse);
+            const couriers = (out.data.available_courier_companies ?? []).map((c) => ({
+                name: c.courier_name,
+                estimatedDays: num(c.estimated_delivery_days),
+                rate: num(c.rate),
+            }));
+            return { isServiceable: couriers.length > 0, couriers };
+        }
+        catch (err) {
+            void normalizeError(err);
+            /*
+             * Serviceability is a QUOTE, not a write. Failing closed here means the
+             * checkout says "we cannot ship there" on a transient carrier outage,
+             * which is wrong in the safe direction — the alternative is quoting a
+             * rate we cannot honour.
+             */
+            return { isServiceable: false, couriers: [] };
+        }
+    }
+    async generateLabel(shipmentId) {
+        const out = await this.call("/courier/generate/label", { method: "POST", body: JSON.stringify({ shipment_id: [shipmentId] }) }, z.object({ label_url: z.string().url() }));
+        const res = await fetch(out.label_url);
+        if (!res.ok) {
+            throw new ApiError(502, `Shiprocket label download failed (${res.status}).`, { code: "SHIPROCKET_LABEL_FAILED" });
+        }
+        return res.arrayBuffer();
+    }
+}

package/dist/providers.d.ts

@@ -17,6 +17,9 @@ export type { DocumentSnapshot } from "firebase-admin/firestore";
 export { firebaseStorageProvider } from "./providers/storage-firebase/index";
 export { createResendProvider } from "./providers/email-resend/index";
 export type { ResendProviderOptions } from "./providers/email-resend/index";
+export { RazorpayProvider } from "./providers/payment-razorpay/index";
+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 { rupeesToPaise, paiseToRupees } from "./core/money";

package/dist/providers.js

@@ -20,6 +20,9 @@ export { firebaseDbProvider, getAdminApp, getAdminAuth, getAdminDb, getAdminStor
 export { firebaseStorageProvider } from "./providers/storage-firebase/index.js";
 // Email (Resend)
 export { createResendProvider } from "./providers/email-resend/index.js";
+// Payment (Razorpay) — disabled by default; siteSettings.payment.razorpayEnabled turns it on
+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";
 export { rupeesToPaise, paiseToRupees } from "./core/money.js";

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

@@ -7,31 +7,4 @@ export interface CanSeePricesState {
      */
     isAuthResolving: boolean;
 }
-/**
- * May the current viewer be shown money amounts on a public listing surface?
- *
- * Prices, current bids, deposits and per-entry amounts are hidden from
- * signed-out visitors so the catalogue cannot be read at scale without an
- * account. Signed-in users see everything exactly as before.
- *
- * ## Why there are THREE states, not two
- *
- * `SessionProvider` is mounted `initialUser={null}` because the root locale
- * layout must stay static (Root Cause #82), so `loading` starts `true` on every
- * hard load — for signed-in users too, until Firebase persistence resolves and
- * `/api/user/profile` returns. A naive `!user` test therefore renders
- * "Sign in to see price" at an already-signed-in user for several hundred
- * milliseconds on every page load.
- *
- * So: `isAuthResolving` means "don't know yet" and must render a neutral
- * placeholder. Only `canSeePrices === false && isAuthResolving === false` is a
- * confirmed guest.
- *
- * ## Why `useOptionalSession`
- *
- * This is library code that ADJUSTS for the viewer rather than requiring one.
- * `useSession()` throws without a provider, which would turn an optional
- * refinement into a breaking contract for every consumer (Root Cause #20). With
- * no provider we fail CLOSED — no session means no prices.
- */
 export declare function useCanSeePrices(): CanSeePricesState;

package/dist/react/hooks/useCanSeePrices.js

@@ -27,8 +27,33 @@ import { useOptionalSession } from "../contexts/SessionContext.js";
  * refinement into a breaking contract for every consumer (Root Cause #20). With
  * no provider we fail CLOSED — no session means no prices.
  */
+/**
+ * 🛑 THE switch. `false` = prices are public; `true` restores the sign-in gate
+ * described above, with no other edit anywhere.
+ *
+ * Turned off 2026-10-20: a catalogue that will not show a price to a visitor
+ * who has not signed in loses the visitor, not the scraper — the price is in
+ * the RSC payload and in `GET /api/products` either way (the "accepted
+ * residue" in CLAUDE.md), so the gate only ever cost real buyers.
+ *
+ * Every call site, wrapper and three-state branch below is left INTACT rather
+ * 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
+ *     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.
+ *   · `audit-guest-price-leak` R3 — the rule that REQUIRES that pairing.
+ */
+const GUEST_PRICE_GATE_ENABLED = false;
 export function useCanSeePrices() {
+    // Called unconditionally: hook order cannot depend on a build-time flag.
     const session = useOptionalSession();
+    // Gate off — everyone sees prices, and nothing is "resolving", so no surface
+    // is left holding a neutral placeholder waiting for a session it never needs.
+    if (!GUEST_PRICE_GATE_ENABLED)
+        return { canSeePrices: true, isAuthResolving: false };
     // No provider: fail closed, and don't claim to be mid-resolution — there is
     // nothing in flight that will ever change the answer.
     if (!session)

package/dist/repositories/index.d.ts

@@ -40,7 +40,7 @@ export { shipmentItemsRepository } from "../features/shipments/repository/shipme
 export { catalogueRepository } from "../features/catalogue/repository/catalogue.repository";
 export { SavedPaymentMethodsRepository, savedPaymentMethodsRepository, } from "../features/payments/repository/saved-payment-methods.repository";
 export { GroupedListingsRepository, groupedListingsRepository, } from "../features/grouped/repository/grouped-listings.repository";
-export { payoutMethodsRepository, shippingConfigsRepository, analyticsCardsRepository, analyticsAlertsRepository, storeCategoriesRepository, listingTemplatesRepository, moderationQueueRepository, reportsRepository, itemRequestsRepository, storeWhatsAppConfigRepository, storeGoogleConfigRepository, PayoutMethodsRepository, ShippingConfigsRepository, AnalyticsCardsRepository, AnalyticsAlertsRepository, StoreCategoriesRepository, ListingTemplatesRepository, ModerationQueueRepository, ReportsRepository, ItemRequestsRepository, StoreWhatsAppConfigRepository, StoreGoogleConfigRepository, } from "../features/store-extensions/repository/store-extensions.repositories";
+export { payoutMethodsRepository, shippingConfigsRepository, analyticsCardsRepository, analyticsAlertsRepository, storeCategoriesRepository, listingTemplatesRepository, moderationQueueRepository, reportsRepository, itemRequestsRepository, storeGoogleConfigRepository, PayoutMethodsRepository, ShippingConfigsRepository, AnalyticsCardsRepository, AnalyticsAlertsRepository, StoreCategoriesRepository, ListingTemplatesRepository, ModerationQueueRepository, ReportsRepository, ItemRequestsRepository, StoreGoogleConfigRepository, } from "../features/store-extensions/repository/store-extensions.repositories";
 export { roleOverridesRepository, customRolesRepository, adminNotificationsRepository, RoleOverridesRepository, CustomRolesRepository, AdminNotificationsRepository, } from "../features/store-extensions/repository/rbac.repositories";
 export { OfferRepository, offerRepository, } from "../features/seller/repository/offer.repository";
 export { wishlistRepository, type UserWishlistItem as WishlistItem, WishlistFullError, } from "../features/wishlist/repository/user-wishlist.repository";

package/dist/repositories/index.js

@@ -56,7 +56,7 @@ export { SavedPaymentMethodsRepository, savedPaymentMethodsRepository, } from ".
 // Grouped listings repository
 export { GroupedListingsRepository, groupedListingsRepository, } from "../features/grouped/repository/grouped-listings.repository.js";
 // S-STORE-CROSS — 11 new collection repositories
-export { payoutMethodsRepository, shippingConfigsRepository, analyticsCardsRepository, analyticsAlertsRepository, storeCategoriesRepository, listingTemplatesRepository, moderationQueueRepository, reportsRepository, itemRequestsRepository, storeWhatsAppConfigRepository, storeGoogleConfigRepository, PayoutMethodsRepository, ShippingConfigsRepository, AnalyticsCardsRepository, AnalyticsAlertsRepository, StoreCategoriesRepository, ListingTemplatesRepository, ModerationQueueRepository, ReportsRepository, ItemRequestsRepository, StoreWhatsAppConfigRepository, StoreGoogleConfigRepository, } from "../features/store-extensions/repository/store-extensions.repositories.js";
+export { payoutMethodsRepository, shippingConfigsRepository, analyticsCardsRepository, analyticsAlertsRepository, storeCategoriesRepository, listingTemplatesRepository, moderationQueueRepository, reportsRepository, itemRequestsRepository, storeGoogleConfigRepository, PayoutMethodsRepository, ShippingConfigsRepository, AnalyticsCardsRepository, AnalyticsAlertsRepository, StoreCategoriesRepository, ListingTemplatesRepository, ModerationQueueRepository, ReportsRepository, ItemRequestsRepository, StoreGoogleConfigRepository, } from "../features/store-extensions/repository/store-extensions.repositories.js";
 // S-STORE RBAC + admin notifications
 export { roleOverridesRepository, customRolesRepository, adminNotificationsRepository, RoleOverridesRepository, CustomRolesRepository, AdminNotificationsRepository, } from "../features/store-extensions/repository/rbac.repositories.js";
 export { OfferRepository, offerRepository, } from "../features/seller/repository/offer.repository.js";