@mohasinac/appkit 4.53.1 → 4.54.0

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

@@ -0,0 +1,125 @@
+/**
+ * @mohasinac/payment-razorpay — Razorpay IPaymentProvider implementation
+ *
+ * Implements the `IPaymentProvider` contract using the official `razorpay`
+ * package. Accepts credentials via constructor — no Firestore or DB
+ * dependency (same shape as `payment-manual` and `payment-phonepe`).
+ *
+ * 🛑 This is a RESTORE, not the original file. The pre-2026-10 provider was
+ * deleted in "replace Razorpay with PhonePe Standard Checkout v2" and this
+ * one is deliberately NOT a revert of it. Three things changed, each because
+ * the old shape could not work against the current money path:
+ *
+ *   1. **`getOrder()` maps the real status.** The old implementation
+ *      hardcoded `status: "created"` on every fetch. That was survivable
+ *      when the Razorpay path verified a client-side signature and nothing
+ *      else, but the current `verifyAndPlaceGatewayOrderAction` treats
+ *      `getOrder().status === "paid"` as the authoritative proof of payment
+ *      (PhonePe hands the browser nothing verifiable, so that is the only
+ *      check it has). A provider that always answers "created" would make
+ *      every Razorpay checkout fail verification after a successful charge —
+ *      the buyer is debited and gets no order.
+ *   2. **`capturePayment()`/`refund()` are ORDER-keyed, tolerantly.** The
+ *      rest of this codebase keys gateway lookups on one id — PhonePe's
+ *      order-keyed `merchantOrderId` — and stores it as `order.paymentId`.
+ *      Razorpay's refund API is payment-keyed (`pay_…`), so rather than
+ *      forcing every caller to track a second id, both methods accept EITHER
+ *      an `order_…` or a `pay_…` id and resolve the order's captured payment
+ *      themselves. See `resolvePaymentId()`.
+ *   3. **The three `@deprecated` standalone helpers are gone.** The old file
+ *      carried a second, credential-resolving API surface
+ *      (`createRazorpayOrder`, `fetchRazorpayOrder`, `createRazorpayRefund`,
+ *      …) that bypassed the provider registry entirely. Its own JSDoc said
+ *      to use `getProviders().payment` instead, and every live caller now
+ *      does. Restoring a bypass layer nothing needs would be reviving the
+ *      exact duplication Root Cause #75 is about.
+ *
+ * Unlike PhonePe, Razorpay uses a client-side modal: `createOrder()` returns
+ * no `checkoutUrl`, and the browser opens Razorpay's `checkout.js` with the
+ * returned order id plus the PUBLISHABLE key id. The key id is handed to the
+ * client by `/api/payment/create-order`, never by this provider.
+ *
+ * @example
+ * ```ts
+ * registerProviders({
+ *   payment: new RazorpayProvider({
+ *     keyId: process.env.RAZORPAY_KEY_ID!,
+ *     keySecret: process.env.RAZORPAY_KEY_SECRET!,
+ *     webhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
+ *   }),
+ * });
+ * ```
+ */
+import type { JsonValue } from "@mohasinac/appkit";
+import { IPaymentProvider } from "../../contracts";
+import type { PaymentOrder, PaymentCapture, Refund } from "../../contracts";
+export { verifyPaymentSignature, verifyWebhookSignature, type RazorpayPaymentResult, } from "./signature";
+export interface RazorpayConfig {
+    /** Publishable key (`rzp_test_…` / `rzp_live_…`). Safe to expose to the browser. */
+    keyId: string;
+    /** Secret key. Server-only — never returned by any route. */
+    keySecret: string;
+    /** Webhook signing secret from the Razorpay dashboard's Webhooks tab. `verifyWebhook()` returns false without it. */
+    webhookSecret?: string;
+}
+export declare class RazorpayProvider extends IPaymentProvider {
+    readonly name = "razorpay";
+    private readonly razorpay;
+    private readonly webhookSecret?;
+    constructor(config: RazorpayConfig);
+    /**
+     * Creates a Razorpay order. `amount` is in PAISE — the smallest currency
+     * unit, which is what Razorpay's `amount` field means and what every
+     * caller in this codebase already passes (`rupeesToPaise(total)`).
+     *
+     * The returned `id` is Razorpay's own order id (`order_…`) and is the key
+     * every later lookup uses, so `gatewayOrderId` stays unset — the contract
+     * reserves that for gateways where the two ids differ. No `checkoutUrl`:
+     * Razorpay has no hosted page in this integration, the browser opens its
+     * modal instead.
+     */
+    createOrder(amount: number, currency?: string, metadata?: Record<string, JsonValue>): Promise<PaymentOrder>;
+    /**
+     * Verifies a Razorpay webhook: HMAC-SHA256 hex over the RAW request body,
+     * compared against the `x-razorpay-signature` header.
+     *
+     * Fails closed when no webhook secret is configured — same shape as
+     * PhonePe's missing-credential behaviour. The caller must pass the raw
+     * body string, not a re-serialised object: `JSON.stringify(JSON.parse(b))`
+     * is not guaranteed to reproduce the bytes that were signed.
+     */
+    verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * Resolves a `pay_…` id for either id shape.
+     *
+     * Given an `order_…` id, picks that order's captured payment (falling back
+     * to an authorized one, which is what a non-auto-capture flow leaves
+     * behind). Throws when the order has no such payment, because every caller
+     * — capture confirmation and refund alike — is meaningless without one.
+     */
+    private resolvePaymentId;
+    /**
+     * Reports the state of the payment behind an order. Accepts our stored
+     * order id (`order_…`) or a payment id (`pay_…`) — see the class comment.
+     *
+     * Named `capturePayment` by the contract, but it does NOT capture: this
+     * integration creates orders with Razorpay's default auto-capture, so a
+     * successful payment is already captured by the time anything here runs.
+     * Issuing a second capture would be an error, not a no-op.
+     */
+    capturePayment(orderId: string): Promise<PaymentCapture>;
+    /**
+     * Full or partial refund. `amount` is in paise; omit it to refund the whole
+     * payment. `paymentId` may be an `order_…` id — Razorpay refunds are
+     * payment-keyed but this codebase stores the order id, so it is resolved
+     * here rather than at ~6 call sites (see the class comment).
+     */
+    refund(paymentId: string, amount?: number): Promise<Refund>;
+    /**
+     * Fetches an order and reports its REAL status. This is the authoritative
+     * "was this paid" check — `verifyAndPlaceGatewayOrderAction` gates order
+     * placement on `status === "paid"`, so the mapping here is load-bearing
+     * (see point 1 of the class comment).
+     */
+    getOrder(orderId: string): Promise<PaymentOrder>;
+}

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

@@ -0,0 +1,232 @@
+/**
+ * @mohasinac/payment-razorpay — Razorpay IPaymentProvider implementation
+ *
+ * Implements the `IPaymentProvider` contract using the official `razorpay`
+ * package. Accepts credentials via constructor — no Firestore or DB
+ * dependency (same shape as `payment-manual` and `payment-phonepe`).
+ *
+ * 🛑 This is a RESTORE, not the original file. The pre-2026-10 provider was
+ * deleted in "replace Razorpay with PhonePe Standard Checkout v2" and this
+ * one is deliberately NOT a revert of it. Three things changed, each because
+ * the old shape could not work against the current money path:
+ *
+ *   1. **`getOrder()` maps the real status.** The old implementation
+ *      hardcoded `status: "created"` on every fetch. That was survivable
+ *      when the Razorpay path verified a client-side signature and nothing
+ *      else, but the current `verifyAndPlaceGatewayOrderAction` treats
+ *      `getOrder().status === "paid"` as the authoritative proof of payment
+ *      (PhonePe hands the browser nothing verifiable, so that is the only
+ *      check it has). A provider that always answers "created" would make
+ *      every Razorpay checkout fail verification after a successful charge —
+ *      the buyer is debited and gets no order.
+ *   2. **`capturePayment()`/`refund()` are ORDER-keyed, tolerantly.** The
+ *      rest of this codebase keys gateway lookups on one id — PhonePe's
+ *      order-keyed `merchantOrderId` — and stores it as `order.paymentId`.
+ *      Razorpay's refund API is payment-keyed (`pay_…`), so rather than
+ *      forcing every caller to track a second id, both methods accept EITHER
+ *      an `order_…` or a `pay_…` id and resolve the order's captured payment
+ *      themselves. See `resolvePaymentId()`.
+ *   3. **The three `@deprecated` standalone helpers are gone.** The old file
+ *      carried a second, credential-resolving API surface
+ *      (`createRazorpayOrder`, `fetchRazorpayOrder`, `createRazorpayRefund`,
+ *      …) that bypassed the provider registry entirely. Its own JSDoc said
+ *      to use `getProviders().payment` instead, and every live caller now
+ *      does. Restoring a bypass layer nothing needs would be reviving the
+ *      exact duplication Root Cause #75 is about.
+ *
+ * Unlike PhonePe, Razorpay uses a client-side modal: `createOrder()` returns
+ * no `checkoutUrl`, and the browser opens Razorpay's `checkout.js` with the
+ * returned order id plus the PUBLISHABLE key id. The key id is handed to the
+ * client by `/api/payment/create-order`, never by this provider.
+ *
+ * @example
+ * ```ts
+ * registerProviders({
+ *   payment: new RazorpayProvider({
+ *     keyId: process.env.RAZORPAY_KEY_ID!,
+ *     keySecret: process.env.RAZORPAY_KEY_SECRET!,
+ *     webhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
+ *   }),
+ * });
+ * ```
+ */
+import Razorpay from "razorpay";
+import { IPaymentProvider } from "../../contracts/index.js";
+import { getDefaultCurrency } from "../../core/baseline-resolver.js";
+import { verifyWebhookSignature } from "./signature.js";
+export { verifyPaymentSignature, verifyWebhookSignature, } from "./signature.js";
+/** Razorpay's own order status vocabulary → the contract's. */
+function mapOrderStatus(status) {
+    switch (status) {
+        case "paid":
+            return "paid";
+        case "attempted":
+            return "attempted";
+        default:
+            return "created";
+    }
+}
+/**
+ * Razorpay `notes` is a flat string map (≤15 keys, 256 chars per value), but
+ * `createOrder`'s `metadata` is `Record<string, JsonValue>` and the shared
+ * create-order route passes PhonePe-shaped keys (`uid`, `redirectUrl`) through
+ * it. Flatten what survives and drop what does not, rather than letting a
+ * nested object reach the API and 400 the whole checkout.
+ */
+function toNotes(metadata) {
+    if (!metadata)
+        return undefined;
+    const notes = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === null || value === undefined)
+            continue;
+        if (typeof value === "object")
+            continue; // arrays/objects have no representation in notes
+        if (Object.keys(notes).length >= 15)
+            break;
+        notes[key] = String(value).slice(0, 256);
+    }
+    return Object.keys(notes).length > 0 ? notes : undefined;
+}
+// --- IPaymentProvider implementation ------------------------------------------
+export class RazorpayProvider extends IPaymentProvider {
+    constructor(config) {
+        super();
+        this.name = "razorpay";
+        if (!config.keyId || !config.keySecret) {
+            throw new Error("RazorpayProvider requires keyId and keySecret. Configure them in Admin › Site Settings › Credentials, or set RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET.");
+        }
+        this.razorpay = new Razorpay({ key_id: config.keyId, key_secret: config.keySecret });
+        this.webhookSecret = config.webhookSecret;
+    }
+    /**
+     * Creates a Razorpay order. `amount` is in PAISE — the smallest currency
+     * unit, which is what Razorpay's `amount` field means and what every
+     * caller in this codebase already passes (`rupeesToPaise(total)`).
+     *
+     * The returned `id` is Razorpay's own order id (`order_…`) and is the key
+     * every later lookup uses, so `gatewayOrderId` stays unset — the contract
+     * reserves that for gateways where the two ids differ. No `checkoutUrl`:
+     * Razorpay has no hosted page in this integration, the browser opens its
+     * modal instead.
+     */
+    async createOrder(amount, currency, metadata) {
+        const resolvedCurrency = currency ?? getDefaultCurrency();
+        const receipt = typeof metadata?.receipt === "string" ? metadata.receipt : undefined;
+        const order = await this.razorpay.orders.create({
+            amount,
+            currency: resolvedCurrency,
+            receipt,
+            notes: toNotes(metadata),
+        });
+        return {
+            id: String(order.id),
+            amount: Number(order.amount),
+            currency: String(order.currency),
+            status: mapOrderStatus(String(order.status)),
+            receipt: order.receipt ?? undefined,
+            metadata,
+            createdAt: new Date(Number(order.created_at) * 1000).toISOString(),
+        };
+    }
+    /**
+     * Verifies a Razorpay webhook: HMAC-SHA256 hex over the RAW request body,
+     * compared against the `x-razorpay-signature` header.
+     *
+     * Fails closed when no webhook secret is configured — same shape as
+     * PhonePe's missing-credential behaviour. The caller must pass the raw
+     * body string, not a re-serialised object: `JSON.stringify(JSON.parse(b))`
+     * is not guaranteed to reproduce the bytes that were signed.
+     */
+    verifyWebhook(payload, signature) {
+        if (!this.webhookSecret)
+            return false;
+        return verifyWebhookSignature(payload, signature, this.webhookSecret);
+    }
+    /**
+     * Resolves a `pay_…` id for either id shape.
+     *
+     * Given an `order_…` id, picks that order's captured payment (falling back
+     * to an authorized one, which is what a non-auto-capture flow leaves
+     * behind). Throws when the order has no such payment, because every caller
+     * — capture confirmation and refund alike — is meaningless without one.
+     */
+    async resolvePaymentId(id) {
+        if (!id.startsWith("order_"))
+            return id;
+        const { items } = await this.razorpay.orders.fetchPayments(id);
+        const payment = items.find((p) => p.status === "captured") ?? items.find((p) => p.status === "authorized");
+        if (!payment) {
+            throw new Error(`Razorpay order ${id} has no captured or authorized payment`);
+        }
+        return String(payment.id);
+    }
+    /**
+     * Reports the state of the payment behind an order. Accepts our stored
+     * order id (`order_…`) or a payment id (`pay_…`) — see the class comment.
+     *
+     * Named `capturePayment` by the contract, but it does NOT capture: this
+     * integration creates orders with Razorpay's default auto-capture, so a
+     * successful payment is already captured by the time anything here runs.
+     * Issuing a second capture would be an error, not a no-op.
+     */
+    async capturePayment(orderId) {
+        const paymentId = await this.resolvePaymentId(orderId);
+        const payment = await this.razorpay.payments.fetch(paymentId);
+        return {
+            id: String(payment.id),
+            orderId: String(payment.order_id ?? orderId),
+            amount: Number(payment.amount),
+            currency: String(payment.currency),
+            status: payment.status === "captured" ? "captured" : "failed",
+            capturedAt: new Date().toISOString(),
+            transactionId: String(payment.id),
+        };
+    }
+    /**
+     * Full or partial refund. `amount` is in paise; omit it to refund the whole
+     * payment. `paymentId` may be an `order_…` id — Razorpay refunds are
+     * payment-keyed but this codebase stores the order id, so it is resolved
+     * here rather than at ~6 call sites (see the class comment).
+     */
+    async refund(paymentId, amount) {
+        const resolvedPaymentId = await this.resolvePaymentId(paymentId);
+        const result = await this.razorpay.payments.refund(resolvedPaymentId, amount === undefined ? {} : { amount });
+        return {
+            id: String(result.id),
+            paymentId: resolvedPaymentId,
+            amount: Number(result.amount),
+            currency: String(result.currency),
+            status: result.status === "processed"
+                ? "processed"
+                : result.status === "failed"
+                    ? "failed"
+                    : "pending",
+            createdAt: new Date(Number(result.created_at) * 1000).toISOString(),
+        };
+    }
+    /**
+     * Fetches an order and reports its REAL status. This is the authoritative
+     * "was this paid" check — `verifyAndPlaceGatewayOrderAction` gates order
+     * placement on `status === "paid"`, so the mapping here is load-bearing
+     * (see point 1 of the class comment).
+     */
+    async getOrder(orderId) {
+        const order = await this.razorpay.orders.fetch(orderId);
+        return {
+            id: String(order.id),
+            amount: Number(order.amount),
+            currency: String(order.currency),
+            status: mapOrderStatus(String(order.status)),
+            receipt: order.receipt ?? undefined,
+            createdAt: new Date(Number(order.created_at) * 1000).toISOString(),
+            /*
+             * `notes` round-trips whatever `createOrder` put there, which is how the
+             * WEBHOOK path (no buyer session) recovers the checkout intent — the
+             * same job PhonePe's `metaInfo` does. Without this the webhook could
+             * confirm a payment and then have no uid to place the order for.
+             */
+            metadata: order.notes,
+        };
+    }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Razorpay signature verification — pure `node:crypto`, NO SDK import.
+ *
+ * 🛑 This is a separate module from `./index.ts` on purpose, and the split is
+ * load-bearing rather than tidiness. `_internal/server/features/checkout/
+ * actions.ts` needs `verifyPaymentSignature` on the buyer-present verify path,
+ * and importing it from the provider's `index.ts` would pull a static
+ * `import Razorpay from "razorpay"` into the checkout action's import graph —
+ * the whole SDK, its transitive deps and its own `node:` requires — for one
+ * HMAC comparison. Root Cause #24 is the same shape one layer down: a static
+ * top-level import is resolved before anything is tree-shaken, so "the symbol
+ * I use is cheap" does not make the module it lives in cheap.
+ *
+ * Keep this file free of SDK imports. `./index.ts` re-exports from here so
+ * the provider still has one public surface.
+ */
+/** The three fields Razorpay's `checkout.js` hands back on a successful payment. */
+export interface RazorpayPaymentResult {
+    razorpay_order_id: string;
+    razorpay_payment_id: string;
+    razorpay_signature: string;
+}
+/**
+ * Compares two hex digests without leaking position through an early exit.
+ *
+ * `timingSafeEqual` throws on unequal buffer lengths, and a non-hex input
+ * silently produces a short buffer — both are "not equal", so both are
+ * caught rather than propagated. Returning false on malformed input is the
+ * fail-closed direction.
+ */
+export declare function hexEqual(expected: string, received: string): boolean;
+/**
+ * Verifies the signature Razorpay's modal returns to the browser:
+ * HMAC-SHA256 over `{order_id}|{payment_id}`, keyed with the SECRET.
+ *
+ * 🛑 This proves the browser's callback was not forged or tampered with. It is
+ * NOT on its own proof that money moved — the digest is computable the moment
+ * an order id and a payment id exist, and both are visible to the client.
+ * `verifyAndPlaceGatewayOrderAction` therefore checks this AND re-fetches the
+ * order from Razorpay; this is the cheap guard, the fetch is the authority.
+ * Each alone has a failure mode: signature-only trusts a client-reported
+ * outcome, fetch-only accepts a replayed order id from another session.
+ */
+export declare function verifyPaymentSignature(params: RazorpayPaymentResult, keySecret: string): boolean;
+/**
+ * Verifies a Razorpay webhook: HMAC-SHA256 hex over the RAW request body,
+ * compared against the `x-razorpay-signature` header.
+ *
+ * 🛑 The caller must pass the raw body STRING, not a re-serialised object.
+ * `JSON.stringify(JSON.parse(body))` is not guaranteed to reproduce the bytes
+ * that were signed — key order and whitespace both survive into the digest.
+ */
+export declare function verifyWebhookSignature(rawBody: string, signature: string, webhookSecret: string): boolean;

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

@@ -0,0 +1,71 @@
+/**
+ * Razorpay signature verification — pure `node:crypto`, NO SDK import.
+ *
+ * 🛑 This is a separate module from `./index.ts` on purpose, and the split is
+ * load-bearing rather than tidiness. `_internal/server/features/checkout/
+ * actions.ts` needs `verifyPaymentSignature` on the buyer-present verify path,
+ * and importing it from the provider's `index.ts` would pull a static
+ * `import Razorpay from "razorpay"` into the checkout action's import graph —
+ * the whole SDK, its transitive deps and its own `node:` requires — for one
+ * HMAC comparison. Root Cause #24 is the same shape one layer down: a static
+ * top-level import is resolved before anything is tree-shaken, so "the symbol
+ * I use is cheap" does not make the module it lives in cheap.
+ *
+ * Keep this file free of SDK imports. `./index.ts` re-exports from here so
+ * the provider still has one public surface.
+ */
+import { createHmac, timingSafeEqual } from "crypto";
+import { normalizeError } from "../../errors/normalize.js";
+/**
+ * Compares two hex digests without leaking position through an early exit.
+ *
+ * `timingSafeEqual` throws on unequal buffer lengths, and a non-hex input
+ * silently produces a short buffer — both are "not equal", so both are
+ * caught rather than propagated. Returning false on malformed input is the
+ * fail-closed direction.
+ */
+export function hexEqual(expected, received) {
+    if (expected.length !== received.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(received, "hex"));
+    }
+    catch (err) {
+        void normalizeError(err);
+        return false;
+    }
+}
+/**
+ * Verifies the signature Razorpay's modal returns to the browser:
+ * HMAC-SHA256 over `{order_id}|{payment_id}`, keyed with the SECRET.
+ *
+ * 🛑 This proves the browser's callback was not forged or tampered with. It is
+ * NOT on its own proof that money moved — the digest is computable the moment
+ * an order id and a payment id exist, and both are visible to the client.
+ * `verifyAndPlaceGatewayOrderAction` therefore checks this AND re-fetches the
+ * order from Razorpay; this is the cheap guard, the fetch is the authority.
+ * Each alone has a failure mode: signature-only trusts a client-reported
+ * outcome, fetch-only accepts a replayed order id from another session.
+ */
+export function verifyPaymentSignature(params, keySecret) {
+    if (!keySecret)
+        return false;
+    const expected = createHmac("sha256", keySecret)
+        .update(`${params.razorpay_order_id}|${params.razorpay_payment_id}`)
+        .digest("hex");
+    return hexEqual(expected, params.razorpay_signature);
+}
+/**
+ * Verifies a Razorpay webhook: HMAC-SHA256 hex over the RAW request body,
+ * compared against the `x-razorpay-signature` header.
+ *
+ * 🛑 The caller must pass the raw body STRING, not a re-serialised object.
+ * `JSON.stringify(JSON.parse(body))` is not guaranteed to reproduce the bytes
+ * that were signed — key order and whitespace both survive into the digest.
+ */
+export function verifyWebhookSignature(rawBody, signature, webhookSecret) {
+    if (!webhookSecret)
+        return false;
+    const expected = createHmac("sha256", webhookSecret).update(rawBody).digest("hex");
+    return hexEqual(expected, signature);
+}

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

@@ -0,0 +1,98 @@
+/**
+ * @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 { IShippingProvider } from "../../contracts";
+import type { CreateShipmentInput, Shipment, TrackingInfo, ServiceabilityResult } from "../../contracts";
+export interface ShiprocketConfig {
+    /** The API user's email. See the header on why this is not a "login id". */
+    email: string;
+    password: string;
+    /** Shiprocket pickup-location nickname, as registered in their dashboard. */
+    pickupLocation?: string;
+}
+export declare class ShiprocketShippingProvider extends IShippingProvider {
+    private readonly config;
+    readonly name = "shiprocket";
+    private token;
+    private tokenExpiresAt;
+    constructor(config: ShiprocketConfig);
+    /**
+     * 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.
+     */
+    private getToken;
+    /**
+     * 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.
+     */
+    private call;
+    /** Their order payload wants the address flattened across many keys. */
+    private addressFields;
+    createShipment(data: CreateShipmentInput): Promise<Shipment>;
+    trackShipment(trackingId: string): Promise<TrackingInfo>;
+    cancelShipment(shipmentId: string): Promise<void>;
+    checkServiceability(pincode: string, weight: number): Promise<ServiceabilityResult>;
+    generateLabel(shipmentId: string): Promise<ArrayBuffer>;
+}