@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/shared/fees/explain.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Plain-language derivations for every fee line a buyer is shown.
+ *
+ * 🛑 The problem this solves is not presentation. The Order Summary listed
+ * `EMI surcharge ₹2,133.00`, `Platform fee ₹10.00` and `GST on platform fee
+ * ₹1.80` beside a `₹39,500.00` subtotal, and **none of the three could be
+ * checked by the person paying them.** ₹2,133 on ₹39,500 is 5.4% — a buyer has
+ * no way to tell whether that is a rate, a tenure, a rounding error or a bug,
+ * and the only honest response to an unexplained charge is to distrust it.
+ *
+ * ── Why the STRINGS live here and not in the component ────────────────────
+ *
+ * Each sentence is a claim about how a number was computed, and the number is
+ * computed in `calculator.ts` / `emi/schedule.ts`. Putting the sentence beside
+ * a `<Line>` would make it a second, prose implementation of the same rule —
+ * free to drift the moment a cap moves (Root Cause #75: a rule reachable by
+ * copy-paste gets copied, and the copy never learns about the branch added
+ * later). These functions read the SAME rate fields the calculators read.
+ *
+ * ── Why they take the CHARGED amount as an argument ───────────────────────
+ *
+ * They explain the figure actually on screen; they do not recompute it. If a
+ * derivation and the rendered amount ever disagree, the explanation must say
+ * so rather than quietly print a second, prettier number — so each function
+ * ends at the charged value and describes the route to it.
+ *
+ * 🛑 NOTHING HERE MAY NAME A SELLER-SIDE RATE. `surchargeSellerSharePercent`
+ * (the platform/seller split of the EMI surcharge), `gatewayFeePercent`,
+ * `payoutHoldDays` and `minPayoutAmount` are `PRIVATE_*_FIELDS`
+ * (Root Cause #70). The EMI functions below are typed against
+ * `BuyerEmiSettings`, which excludes the split structurally — so the omission
+ * is enforced by `tsc`, not by this paragraph.
+ */
+import type { BuyerEmiSettings, BuyerFacingFees } from "../features/site-settings/fees";
+import type { BuyerEmiQuote } from "../features/emi/schedule";
+/** One rendered explanation: a short claim plus the steps behind it. */
+export interface FeeDerivation {
+    /** One sentence answering "why am I paying this". */
+    summary: string;
+    /** The arithmetic, one step per line, in the order it is applied. */
+    steps: string[];
+}
+/**
+ * The platform commission.
+ *
+ * The cap is the interesting half and the reason this needed explaining at
+ * all: on a ₹39,500 order the uncapped commission is large and the charge is
+ * ₹10, so the number on screen bears no visible relation to the subtotal.
+ */
+export declare function explainPlatformFee(subtotal: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * GST on the commission.
+ *
+ * 🛑 Levied on the commission ACTUALLY CHARGED, never on the uncapped figure —
+ * which is the one thing a buyer checking ₹1.80 against a ₹39,500 subtotal
+ * would get wrong.
+ */
+export declare function explainGstOnPlatformFee(platformFee: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * The EMI surcharge — the cost of credit, stated as a cost of credit.
+ *
+ * 🛑 Takes a `BuyerEmiQuote`, which is `computeBuyerEmiQuote`'s return type and
+ * carries no surcharge split. `computeEmiSchedule`'s richer result is
+ * assignable to it, so the type does not stop a server caller passing the
+ * wrong one — but nothing here reads a field that only exists on the wider
+ * shape, so no split can be printed either.
+ */
+export declare function explainEmiSurcharge(sellerSubtotal: number, tenureMonths: number, quote: BuyerEmiQuote, emi: BuyerEmiSettings | null, currency?: string): FeeDerivation | null;
+/** COD handling — a cap that bites on most carts, same shape as the commission. */
+export declare function explainCodHandlingFee(subtotal: number, charged: number, fees: BuyerFacingFees | null, currency?: string): FeeDerivation | null;
+/**
+ * Every derivation a price breakdown can render, keyed by the line it belongs
+ * to. A key with no entry simply renders no disclosure — a line we cannot
+ * explain says nothing rather than guessing.
+ */
+export interface FeeDerivations {
+    platformFee?: FeeDerivation | null;
+    gstOnFee?: FeeDerivation | null;
+    emiSurcharge?: FeeDerivation | null;
+    codHandlingFee?: FeeDerivation | null;
+}

package/dist/_internal/shared/fees/explain.js

@@ -0,0 +1,101 @@
+import { formatCurrency } from "../../../utils/number.formatter.js";
+/** `2` → `"2%"`, `2.5` → `"2.5%"` — no trailing `.0`. */
+function pct(value) {
+    return `${Number(value.toFixed(2))}%`;
+}
+/**
+ * The platform commission.
+ *
+ * The cap is the interesting half and the reason this needed explaining at
+ * all: on a ₹39,500 order the uncapped commission is large and the charge is
+ * ₹10, so the number on screen bears no visible relation to the subtotal.
+ */
+export function explainPlatformFee(subtotal, charged, fees, currency = "INR") {
+    if (!fees || fees.platformFeePercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const uncapped = (subtotal * fees.platformFeePercent) / 100;
+    const steps = [
+        `${pct(fees.platformFeePercent)} of ${money(subtotal)} = ${money(uncapped)}`,
+    ];
+    if (fees.platformFeeMax !== undefined && uncapped > fees.platformFeeMax) {
+        steps.push(`Capped at ${money(fees.platformFeeMax)} — you pay the cap, not the percentage`);
+    }
+    /*
+     * The floor is defined on `platformFee + gstOnFee` COMBINED and is applied
+     * once, inside `allocateCheckoutFees`, as extra platform fee with no GST of
+     * its own. So it is mentioned here and never on the GST line — see the D41
+     * note in `calculator.ts`.
+     */
+    if (fees.minimumTransactionFee !== undefined && charged > Math.min(uncapped, fees.platformFeeMax ?? uncapped)) {
+        steps.push(`Raised to meet the ${money(fees.minimumTransactionFee)} minimum transaction fee, which covers the commission and its GST together`);
+    }
+    steps.push(`You pay ${money(charged)}`);
+    return {
+        summary: fees.platformFeeMax !== undefined && uncapped > fees.platformFeeMax
+            ? `Our commission is ${pct(fees.platformFeePercent)}, capped at ${money(fees.platformFeeMax)} per order.`
+            : `Our commission is ${pct(fees.platformFeePercent)} of the order.`,
+        steps,
+    };
+}
+/**
+ * GST on the commission.
+ *
+ * 🛑 Levied on the commission ACTUALLY CHARGED, never on the uncapped figure —
+ * which is the one thing a buyer checking ₹1.80 against a ₹39,500 subtotal
+ * would get wrong.
+ */
+export function explainGstOnPlatformFee(platformFee, charged, fees, currency = "INR") {
+    if (!fees || fees.gstPercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    return {
+        summary: `GST at ${pct(fees.gstPercent)}, charged on our commission — not on the price of the items.`,
+        steps: [
+            `${pct(fees.gstPercent)} of the ${money(platformFee)} commission = ${money(charged)}`,
+            "Item prices already include their own GST, shown below the total",
+        ],
+    };
+}
+/**
+ * The EMI surcharge — the cost of credit, stated as a cost of credit.
+ *
+ * 🛑 Takes a `BuyerEmiQuote`, which is `computeBuyerEmiQuote`'s return type and
+ * carries no surcharge split. `computeEmiSchedule`'s richer result is
+ * assignable to it, so the type does not stop a server caller passing the
+ * wrong one — but nothing here reads a field that only exists on the wider
+ * shape, so no split can be printed either.
+ */
+export function explainEmiSurcharge(sellerSubtotal, tenureMonths, quote, emi, currency = "INR") {
+    if (!emi)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const principal = sellerSubtotal - quote.tokenAmount;
+    const perMonth = quote.installments[0]?.amount ?? 0;
+    return {
+        summary: `Spreading ${money(sellerSubtotal)} over ${tenureMonths} months costs ${money(quote.surchargeAmount)} — that is the total cost of credit.`,
+        steps: [
+            `Token paid today: ${pct(emi.tokenPercent)} of ${money(sellerSubtotal)} = ${money(quote.tokenAmount)}`,
+            `Financed amount: ${money(sellerSubtotal)} − ${money(quote.tokenAmount)} = ${money(principal)}`,
+            `Surcharge: ${pct(emi.surchargePercentPerMonth)} of ${money(principal)} per month × ${tenureMonths} months = ${money(quote.surchargeAmount)}`,
+            `Repaid over ${tenureMonths} instalments of about ${money(perMonth)}, due on day ${emi.billingDay} of each month`,
+            `Total you will pay: ${money(quote.tokenAmount)} + ${money(quote.remainingBalance)} = ${money(quote.tokenAmount + quote.remainingBalance)}`,
+        ],
+    };
+}
+/** COD handling — a cap that bites on most carts, same shape as the commission. */
+export function explainCodHandlingFee(subtotal, charged, fees, currency = "INR") {
+    if (!fees || fees.codHandlingFeePercent === undefined)
+        return null;
+    const money = (v) => formatCurrency(v, currency);
+    const uncapped = (subtotal * fees.codHandlingFeePercent) / 100;
+    const steps = [`${pct(fees.codHandlingFeePercent)} of ${money(subtotal)} = ${money(uncapped)}`];
+    if (fees.codHandlingFeeCap !== undefined && uncapped > fees.codHandlingFeeCap) {
+        steps.push(`Capped at ${money(fees.codHandlingFeeCap)}`);
+    }
+    steps.push(`You pay ${money(charged)}`);
+    return {
+        summary: "What it costs us to collect cash at your door and bank it.",
+        steps,
+    };
+}

package/dist/_internal/shared/history/index.d.ts

@@ -1,4 +1,4 @@
 export type { HistoryActorRole, HistoryActor, FieldChange, StatusChangeEntry, AppendHistoryResult, SerialisedStatusChangeEntry, } from "./types";
-export { STATUS_HISTORY_MAX } from "./types";
+export { STATUS_HISTORY_MAX, HISTORY_ACTOR_ROLE } from "./types";
 export type { BuildHistoryEntryInput } from "./history";
 export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history";

package/dist/_internal/shared/history/index.js

@@ -1,2 +1,2 @@
-export { STATUS_HISTORY_MAX } from "./types.js";
+export { STATUS_HISTORY_MAX, HISTORY_ACTOR_ROLE } from "./types.js";
 export { diffTrackedFields, buildHistoryEntry, appendHistoryEntry, withHistory, } from "./history.js";

package/dist/_internal/shared/history/types.d.ts

@@ -9,7 +9,13 @@ import type { FirestoreValue } from "../../../schemas/types";
  * entities had any history at all — `ads`, built inline in a route handler
  * with no type and no reuse.
  */
-export type HistoryActorRole = "buyer" | "seller" | "admin" | "system";
+export declare const HISTORY_ACTOR_ROLE: {
+    readonly BUYER: "buyer";
+    readonly SELLER: "seller";
+    readonly ADMIN: "admin";
+    readonly SYSTEM: "system";
+};
+export type HistoryActorRole = (typeof HISTORY_ACTOR_ROLE)[keyof typeof HISTORY_ACTOR_ROLE];
 export interface HistoryActor {
     /** Firebase Auth uid. Absent for `system` (cron jobs, Firestore triggers). */
     uid?: string;

package/dist/_internal/shared/history/types.js

@@ -1,3 +1,28 @@
+/**
+ * Generic entity status history — the shape shared by every entity that
+ * records how it got to its current state.
+ *
+ * Built for orders first (W2) and adopted by stores, payouts, offers, bids,
+ * support tickets, scammer profiles, catalogue approvals, shipments and
+ * returns in W15. Before this existed, exactly ONE of ~40 status-bearing
+ * entities had any history at all — `ads`, built inline in a route handler
+ * with no type and no reuse.
+ */
+/*
+ * 🛑 This is an ACTOR KIND, not a `UserDocument.role`. No user has the role
+ * "buyer" — a buyer's stored role is "user" — so the two namespaces must never
+ * be compared, and `audit-phantom-buyer-role` exists to catch exactly that
+ * mistake in a runtime auth gate.
+ *
+ * The constant below is what a gate should compare against: it names the
+ * namespace at the call site, where a bare `"buyer"` literal cannot.
+ */
+export const HISTORY_ACTOR_ROLE = {
+    BUYER: "buyer",
+    SELLER: "seller",
+    ADMIN: "admin",
+    SYSTEM: "system",
+};
 /**
  * Cap for any history array. Matches `HISTORY_MAX`'s reasoning: an unbounded
  * array on a hot document inflates every read of that document (Rule #6), and

package/dist/client.d.ts

@@ -283,6 +283,8 @@ export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister,
 export type { LoginCredentials, RegisterData, ForgotPasswordData, ResetPasswordData, VerifyEmailData, ChangeEmailData } from "./features/auth/index";
 export { CartView, CartItemRow, CartGroupLineRow, CartSummary, CartPriceBreakdown, CartDrawer, CheckoutView, CheckoutSuccessView, CheckoutAddressStep, useGuestCart, useCartCount, useAddToCart, useCart, useGuestCartMerge, useCartQuery } from "./features/cart/index";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./features/cart/index";
+export { PointsTenderPicker } from "./features/cart/index";
+export type { PointsTenderPickerProps } from "./features/cart/index";
 export { clientLineTotal } from "./features/cart/utils/line-total";
 export type { PricedCartLine } from "./features/cart/utils/line-total";
 export type { CartPriceBreakdownData, CartPriceBreakdownStore, StoreAddonsValue, StoreAddonsRates } from "./features/cart/index";
@@ -389,12 +391,20 @@ export type { UserAccountHubViewProps, UserAccountHubViewLabels, UserOrdersViewP
 export { useOrders, useOrder, OrdersList } from "./features/orders/index";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline";
 export type { OrderStatusTimelineProps } from "./features/orders/components/OrderStatusTimeline";
+export { OrderProvenanceCard } from "./features/orders/components/OrderProvenanceCard";
+export type { OrderProvenanceCardProps } from "./features/orders/components/OrderProvenanceCard";
+export { RaiseDisputeForm } from "./features/orders/components/RaiseDisputeForm";
+export type { RaiseDisputeFormProps } from "./features/orders/components/RaiseDisputeForm";
+export type { OrderSourceContext } from "./features/orders/schemas/firestore";
 export { PROTECTION_CLAIM_REASON_LABEL } from "./features/protection-claims/schemas/firestore";
 export type { ProtectionClaimReason } from "./features/protection-claims/schemas/firestore";
 export { OrderCompletionPanel } from "./features/orders/components/OrderCompletionPanel";
 export type { OrderCompletionPanelProps, RateableLine } from "./features/orders/components/OrderCompletionPanel";
 export { EmiInstallmentsPanel } from "./features/orders/components/EmiInstallmentsPanel";
 export type { EmiInstallmentsPanelProps } from "./features/orders/components/EmiInstallmentsPanel";
+export { BalancePaymentPanel } from "./features/orders/components/BalancePaymentPanel";
+export type { BalancePaymentPanelProps } from "./features/orders/components/BalancePaymentPanel";
+export { balanceProofSchema, balanceReviewSchema, type BalanceProofInput, type BalanceReviewInput, } from "./features/orders/schemas/balance";
 export { CountdownDisplay } from "./ui/components/CountdownDisplay";
 export type { CountdownDisplayProps } from "./ui/components/CountdownDisplay";
 export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges";
@@ -506,6 +516,7 @@ export { CommandPalette, useCommandPaletteHotkey } from "./features/shell/index"
 export type { CommandPaletteGroup } from "./features/shell/index";
 export { AdminBlogEditorView, AdminBundleEditorView, AdminCarouselEditorView, AdminCategoryEditorView, AdminCouponEditorView, AdminFaqEditorView, AdminFeatureEditorView, AdminOrderEditorView, AdminPayoutMarkPaidModal, AdminAuditLogView, AdminMoneyCasesView, AdminGatewayEventsView, ViewAuditLogEntryModal, AdminProductEditorView, AdminScammerEditorView, AdminEmployeeEditorView, AdminNavEditorView, AdminUserEditorView, AdminStoreEditorView, AdminSublistingCategoryEditorView, AdminSupportTicketDetailView, } from "./features/admin/index";
 export type { AdminStoreEditorViewProps, AdminPayoutMarkPaidModalProps, AdminAuditLogViewProps, AdminMoneyCasesViewProps, AuditLogEntryDetail, ViewAuditLogEntryModalProps } from "./features/admin/index";
+export type { AdminOrderEditorViewProps } from "./features/admin/components/AdminOrderEditorView";
 export type { NavItemData } from "./features/admin/index";
 export { PageLoader } from "./ui/index";
 export { ADMIN_CHECKOUT_BYPASS_FLAG_KEY } from "./features/admin/schemas/firestore";
@@ -527,6 +538,10 @@ export { BUNDLE_COPY } from "./_internal/shared/features/categories/bundle-copy"
 export { useSiteSettings } from "./core/index";
 export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "./_internal/shared/features/emi/schedule";
 export type { EmiSettings, BuyerEmiQuote } from "./_internal/shared/features/emi/schedule";
+export { emiTenderBlockReason, isTenderCompatibleWithEmi } from "./_internal/shared/features/emi/choice";
+export type { EmiTender } from "./_internal/shared/features/emi/choice";
+export { explainCodHandlingFee, explainEmiSurcharge, explainGstOnPlatformFee, explainPlatformFee, } from "./_internal/shared/fees/explain";
+export type { FeeDerivation, FeeDerivations } from "./_internal/shared/fees/explain";
 export type { BuyerFacingFees, BuyerEmiSettings, } from "./_internal/shared/features/site-settings/fees";
 export type { PublicSiteSettings } from "./_internal/shared/features/site-settings/types";
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator";
@@ -551,6 +566,8 @@ export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms";
 export { orderCancelSchema, paymentProofSchema, } from "./features/orders/schemas/buyer-forms";
 export { scamReportFormSchema } from "./features/scams/schemas/report-form";
 export { sublistingCategoryFormSchema } from "./features/store-extensions/schemas/sublisting-category-form";
+export { adCreativeFormSchema } from "./features/ads/schemas/creative-form";
+export type { AdCreativeFormValues } from "./features/ads/schemas/creative-form";
 export { adminStoreUpdateSchema, announcementBarSchema, } from "./features/admin/schemas/admin-editor-forms";
 export { adminOrderUpdateSchema, employeeInviteSchema, hardBanReasonSchema, featureFlagsUpdateSchema, adminAdFormSchema, } from "./features/admin/schemas/admin-ops-forms";
 export { changeEmailSchema } from "./features/account/schemas/index";
@@ -586,6 +603,10 @@ export type { SellerSupportViewProps } from "./features/seller/components/Seller
 export { REFUND_COPY } from "./_internal/shared/features/orders/refund-copy";
 export { RETURN_REASON, FINAL_SALE_EXEMPT_REASONS, RETURN_REASON_LABEL, RETURN_REASON_GROUP_LABEL, isFinalSaleExempt, isReturnReason, selectableReturnReasons, } from "./_internal/shared/features/orders/return-reasons";
 export type { ReturnReason } from "./_internal/shared/features/orders/return-reasons";
+export { DISPUTE_KIND, DISPUTE_KIND_LABEL, DISPUTE_GATE, DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, isDisputeKind, checkDisputeGate, resolveDisputeEtd, disputeNotReachedFilableFrom, } from "./_internal/shared/features/orders/dispute-reasons";
+export type { DisputeKind, DisputeGateOrder, DisputeGateResult, } from "./_internal/shared/features/orders/dispute-reasons";
+export { INTEGRATIONS, INTEGRATION_ORDER, readIntegrationStates, integrationPatch, allIntegrationsPatch, } from "./_internal/shared/features/admin/integrations";
+export type { IntegrationId, IntegrationDescriptor, IntegrationPatch, IntegrationState, } from "./_internal/shared/features/admin/integrations";
 export { RefundRequestView } from "./features/orders/components/RefundRequestView";
 export type { RefundRequestViewProps, RefundRequestSubmission, } from "./features/orders/components/RefundRequestView";
 export { ORDER_RETURN_WINDOW_DAYS, ORDER_RETURN_WINDOW_MS, ORDER_CANCELLABLE_STATUSES, } from "./_internal/shared/features/orders/config";

package/dist/client.js

@@ -335,6 +335,10 @@ export { ProtectedRoute, ForgotPasswordView, LoginForm, RegisterForm, ResetPassw
 export { useLogout, useLogin, useGoogleLogin, useLinkGoogleAccount, useRegister, useForgotPassword, useResetPassword, useVerifyEmail, useChangeEmail } from "./features/auth/index.js";
 export { CartView, CartItemRow, CartGroupLineRow, CartSummary, CartPriceBreakdown, CartDrawer, CheckoutView, CheckoutSuccessView, CheckoutAddressStep, useGuestCart, useCartCount, useAddToCart, useCart, useGuestCartMerge, useCartQuery } from "./features/cart/index.js";
 export { StoreAddonsPicker, hasAnyStoreAddon } from "./features/cart/index.js";
+// D46/D47 — the cart's single "pay with my points" control. One per CART, not
+// per store, unlike the add-ons picker above it: points are the buyer's balance
+// rather than something bought from a seller.
+export { PointsTenderPicker } from "./features/cart/index.js";
 export { clientLineTotal } from "./features/cart/utils/line-total.js";
 // `clearCartOps` / `removeCartOpsFor` are exported because the cart page has to
 // drain the queue after a removal succeeds server-side — without them a cleared
@@ -416,6 +420,9 @@ export { couponDraftToPayload } from "./features/seller/schemas/coupon-form.js";
 export { UserAccountHubView, UserOrdersView, UserBidsView, OrderDetailView, UserReturnsView, useNotifications } from "./features/account/index.js";
 export { useOrders, useOrder, OrdersList } from "./features/orders/index.js";
 export { OrderStatusTimeline } from "./features/orders/components/OrderStatusTimeline.js";
+export { OrderProvenanceCard } from "./features/orders/components/OrderProvenanceCard.js";
+// The buyer's dispute form: pick a kind, pick a reason, say what happened.
+export { RaiseDisputeForm } from "./features/orders/components/RaiseDisputeForm.js";
 /*
  * The buyer's completion surface. Client entry only — it fetches and posts.
  */
@@ -433,6 +440,9 @@ export { PROTECTION_CLAIM_REASON_LABEL } from "./features/protection-claims/sche
 export { OrderCompletionPanel } from "./features/orders/components/OrderCompletionPanel.js";
 // Buyer-facing EMI schedule with a pay-any-instalment action.
 export { EmiInstallmentsPanel } from "./features/orders/components/EmiInstallmentsPanel.js";
+// D55 — the pre-order balance collector's buyer panel and its write shapes.
+export { BalancePaymentPanel } from "./features/orders/components/BalancePaymentPanel.js";
+export { balanceProofSchema, balanceReviewSchema, } from "./features/orders/schemas/balance.js";
 export { CountdownDisplay } from "./ui/components/CountdownDisplay.js";
 export { OrderAddonBadges } from "./features/orders/components/OrderAddonBadges.js";
 // Manual-payment (cash / UPI / EMI) shared constants — pure data + predicates,
@@ -560,6 +570,15 @@ export { useProduct } from "./features/products/index.js";
 export { BUNDLE_COPY } from "./_internal/shared/features/categories/bundle-copy.js";
 export { useSiteSettings } from "./core/index.js";
 export { checkEmiEligibility, computeEmiSchedule, computeBuyerEmiQuote, } from "./_internal/shared/features/emi/schedule.js";
+/*
+ * 0f — the checkout client needs to know which tenders can carry instalments
+ * so it can DISABLE an incompatible one with a reason rather than let the
+ * buyer pick it and be refused at submit. Same map the server refuses from, so
+ * the affordance and the rule cannot disagree.
+ */
+export { emiTenderBlockReason, isTenderCompatibleWithEmi } from "./_internal/shared/features/emi/choice.js";
+/* The derivation strings for the fee breakdown — pure, no I/O. */
+export { explainCodHandlingFee, explainEmiSurcharge, explainGstOnPlatformFee, explainPlatformFee, } from "./_internal/shared/fees/explain.js";
 export { computeCodHandlingFee } from "./_internal/shared/fees/calculator.js"; // reexport-from-internal-ok: pure fee-calc utility consumed directly by public checkout UI (CheckoutRouteClient.tsx), same category as the sibling computeEmiSchedule/checkEmiEligibility re-export two lines above
 export { FAQPageContent } from "./features/faq/index.js";
 export { CategoryInlineSelect } from "./features/seller/components/CategoryInlineSelect.js";
@@ -596,6 +615,7 @@ export { raffleEntrySchema } from "./features/contact/schemas/inquiry-forms.js";
 export { orderCancelSchema, paymentProofSchema, } from "./features/orders/schemas/buyer-forms.js";
 export { scamReportFormSchema } from "./features/scams/schemas/report-form.js";
 export { sublistingCategoryFormSchema } from "./features/store-extensions/schemas/sublisting-category-form.js";
+export { adCreativeFormSchema } from "./features/ads/schemas/creative-form.js";
 export { adminStoreUpdateSchema, announcementBarSchema, } from "./features/admin/schemas/admin-editor-forms.js";
 export { adminOrderUpdateSchema, employeeInviteSchema, hardBanReasonSchema, featureFlagsUpdateSchema, adminAdFormSchema, } from "./features/admin/schemas/admin-ops-forms.js";
 export { changeEmailSchema } from "./features/account/schemas/index.js";
@@ -634,6 +654,29 @@ export { REFUND_COPY } from "./_internal/shared/features/orders/refund-copy.js";
 // See the module docstring for why the exempt set is "seller or carrier fault"
 // rather than "serious reasons".
 export { RETURN_REASON, FINAL_SALE_EXEMPT_REASONS, RETURN_REASON_LABEL, RETURN_REASON_GROUP_LABEL, isFinalSaleExempt, isReturnReason, selectableReturnReasons, } from "./_internal/shared/features/orders/return-reasons.js";
+// Dispute KINDS and their gates. Exported for the same reason the return
+// reasons above are: the buyer's form renders the labels and needs to show the
+// date a `not_reached` dispute becomes filable from, and
+// `@mohasinac/appkit/_internal/*` is NOT a subpath export — `_internal` is
+// reachable only through a barrel.
+export { DISPUTE_KIND, DISPUTE_KIND_LABEL, DISPUTE_GATE, DISPUTE_TRANSIT_WINDOW_DAYS, DISPUTE_NOT_REACHED_GRACE_DAYS, isDisputeKind, checkDisputeGate, resolveDisputeEtd, disputeNotReachedFilableFrom, } from "./_internal/shared/features/orders/dispute-reasons.js";
+/*
+ * The integration switches. Exported from the CLIENT entry because the admin
+ * integrations page is a "use client" surface — it renders each row's label and
+ * `offConsequence` and needs `readIntegrationStates` to show the current
+ * position.
+ *
+ * 🛑 The SAME module is re-exported from `server.ts`, deliberately, because the
+ * route guards resolve their answer through `readIntegrationStates` too. One
+ * expression, two entries — which is the point: a hand-written copy of "is this
+ * integration on" in a guard is how the page and the enforcement drift apart,
+ * and that had already happened once inside the module itself (the payments OR
+ * across both gateways).
+ *
+ * Safe in a client bundle: the file's only import is `import type`, so its
+ * runtime graph is empty and it cannot reach firebase-admin.
+ */
+export { INTEGRATIONS, INTEGRATION_ORDER, readIntegrationStates, integrationPatch, allIntegrationsPatch, } from "./_internal/shared/features/admin/integrations.js";
 // Buyer-facing return/refund request form and the window it is gated on.
 // Exported from the CLIENT entry because the page that renders it is a
 // "use client" route — importing it from the main entry there would drag the

package/dist/constants/api-endpoints.d.ts

@@ -98,6 +98,10 @@ export declare const ADMIN_ENDPOINTS: {
     /** The action-index control plane (W7 / D7) — GET the whole index, PATCH one override. */
     readonly ACTION_INDEX: "/api/admin/action-index";
     readonly AD_BY_ID: (id: string) => string;
+    /** D56 — the self-serve creative moderation queue. */
+    readonly AD_BOOKINGS: "/api/admin/ads/bookings";
+    /** D56 — approve or reject one creative. A rejection REQUIRES a note. */
+    readonly AD_BOOKING_MODERATE: (id: string) => string;
     readonly PAYMENTS_SETTINGS: "/api/admin/payments/settings";
     readonly PRODUCTS: "/api/admin/products";
     readonly PRODUCT_BY_ID: (id: string) => string;
@@ -110,6 +114,7 @@ export declare const ADMIN_ENDPOINTS: {
     readonly ORDER_PAYMENT_VERIFY: (id: string) => string;
     readonly ORDER_PAYMENT_REUPLOAD: (id: string) => string;
     readonly ORDER_PAYMENT_REJECT_FRAUD: (id: string) => string;
+    readonly ORDER_BALANCE_REVIEW: (id: string) => string;
     readonly USERS: "/api/admin/users";
     readonly USERS_BULK: "/api/admin/users/bulk";
     readonly USER_BY_ID: (uid: string) => string;
@@ -150,6 +155,14 @@ export declare const ADMIN_ENDPOINTS: {
     readonly PAYOUTS_EXPORT: "/api/admin/payouts/export";
     readonly AUDIT_LOG: "/api/admin/audit-log";
     readonly AUDIT_LOG_BY_ID: (id: string) => string;
+    /**
+     * Phase 7 — the GSTR-1 DRAFT export. Takes `?from=&to=` as YYYY-MM-DD and
+     * returns a CSV.
+     *
+     * 🛑 "draft" is in the filename for a reason: nothing in this codebase talks
+     * to the GST portal, and the file is the input to a human filing.
+     */
+    readonly INVOICING_GSTR1: "/api/admin/invoicing/gstr1";
     readonly PAYMENT_CASES: "/api/admin/payment-cases";
     readonly PAYMENT_CASE_BY_ID: (id: string) => string;
     readonly PROTECTION_CLAIMS: "/api/admin/protection-claims";
@@ -272,6 +285,19 @@ export declare const CART_ENDPOINTS: {
     readonly SELECTION: "/api/cart/selection";
     /** Per-store paid add-on selections — the source of truth for what's charged. */
     readonly ADDONS: "/api/cart/addons";
+    /**
+     * Pay with points, on or off (D46/D47). A boolean and nothing else — the
+     * AMOUNT is derived server-side from the live balance and the 50% cap, which
+     * is why there is no `/api/cart/points/amount`.
+     */
+    readonly POINTS: "/api/cart/points";
+    /**
+     * The instalment plan — a TENURE and nothing else. It lives on the cart,
+     * not in a checkout body, because the online path needs the same answer in
+     * two requests (`/api/payment/create-order` captures, `/api/payment/verify`
+     * writes the order). Same reasoning as `POINTS` and `ADDONS` above.
+     */
+    readonly EMI: "/api/cart/emi";
     readonly COUPON: "/api/cart/coupon";
     /**
      * Add a buyer-assembled group selection as ONE line. Separate from `GET`'s
@@ -447,6 +473,7 @@ export declare const ORDER_ENDPOINTS: {
     readonly BY_ID: (id: string) => string;
     readonly TRACK: (trackingId: string) => string;
     readonly PAYMENT_PROOF: (id: string) => string;
+    readonly BALANCE_PROOF: (id: string) => string;
     readonly DISPUTE: (id: string) => string;
 };
 export declare const PREORDER_ENDPOINTS: {
@@ -488,6 +515,17 @@ export declare const SELLER_ENDPOINTS: {
     readonly PRODUCTS: "/api/store/products";
     readonly ORDERS: "/api/store/orders";
     readonly ORDERS_BY_ID: (orderId: string) => string;
+    /**
+     * Dispatch — BOTH branches of `shipOrderSchema`'s discriminated union.
+     *
+     * `method: "custom"` records a carrier the seller posted themselves;
+     * `method: "platform"` enqueues a booking through our own account. One
+     * route, because they are one decision — a second endpoint for the
+     * platform branch would be the same handler behind two ceilings, which is
+     * Root Cause #85.
+     */
+    readonly ORDER_SHIP: (orderId: string) => string;
+    readonly ORDER_OPEN_BALANCE: (orderId: string) => string;
     readonly AUCTIONS: "/api/store/products";
     readonly COUPONS: "/api/store/coupons";
     readonly COUPON_BY_ID: (id: string) => string;
@@ -681,6 +719,10 @@ export declare const API_ENDPOINTS: {
         /** The action-index control plane (W7 / D7) — GET the whole index, PATCH one override. */
         readonly ACTION_INDEX: "/api/admin/action-index";
         readonly AD_BY_ID: (id: string) => string;
+        /** D56 — the self-serve creative moderation queue. */
+        readonly AD_BOOKINGS: "/api/admin/ads/bookings";
+        /** D56 — approve or reject one creative. A rejection REQUIRES a note. */
+        readonly AD_BOOKING_MODERATE: (id: string) => string;
         readonly PAYMENTS_SETTINGS: "/api/admin/payments/settings";
         readonly PRODUCTS: "/api/admin/products";
         readonly PRODUCT_BY_ID: (id: string) => string;
@@ -693,6 +735,7 @@ export declare const API_ENDPOINTS: {
         readonly ORDER_PAYMENT_VERIFY: (id: string) => string;
         readonly ORDER_PAYMENT_REUPLOAD: (id: string) => string;
         readonly ORDER_PAYMENT_REJECT_FRAUD: (id: string) => string;
+        readonly ORDER_BALANCE_REVIEW: (id: string) => string;
         readonly USERS: "/api/admin/users";
         readonly USERS_BULK: "/api/admin/users/bulk";
         readonly USER_BY_ID: (uid: string) => string;
@@ -733,6 +776,14 @@ export declare const API_ENDPOINTS: {
         readonly PAYOUTS_EXPORT: "/api/admin/payouts/export";
         readonly AUDIT_LOG: "/api/admin/audit-log";
         readonly AUDIT_LOG_BY_ID: (id: string) => string;
+        /**
+         * Phase 7 — the GSTR-1 DRAFT export. Takes `?from=&to=` as YYYY-MM-DD and
+         * returns a CSV.
+         *
+         * 🛑 "draft" is in the filename for a reason: nothing in this codebase talks
+         * to the GST portal, and the file is the input to a human filing.
+         */
+        readonly INVOICING_GSTR1: "/api/admin/invoicing/gstr1";
         readonly PAYMENT_CASES: "/api/admin/payment-cases";
         readonly PAYMENT_CASE_BY_ID: (id: string) => string;
         readonly PROTECTION_CLAIMS: "/api/admin/protection-claims";
@@ -855,6 +906,19 @@ export declare const API_ENDPOINTS: {
         readonly SELECTION: "/api/cart/selection";
         /** Per-store paid add-on selections — the source of truth for what's charged. */
         readonly ADDONS: "/api/cart/addons";
+        /**
+         * Pay with points, on or off (D46/D47). A boolean and nothing else — the
+         * AMOUNT is derived server-side from the live balance and the 50% cap, which
+         * is why there is no `/api/cart/points/amount`.
+         */
+        readonly POINTS: "/api/cart/points";
+        /**
+         * The instalment plan — a TENURE and nothing else. It lives on the cart,
+         * not in a checkout body, because the online path needs the same answer in
+         * two requests (`/api/payment/create-order` captures, `/api/payment/verify`
+         * writes the order). Same reasoning as `POINTS` and `ADDONS` above.
+         */
+        readonly EMI: "/api/cart/emi";
         readonly COUPON: "/api/cart/coupon";
         /**
          * Add a buyer-assembled group selection as ONE line. Separate from `GET`'s
@@ -977,6 +1041,7 @@ export declare const API_ENDPOINTS: {
         readonly BY_ID: (id: string) => string;
         readonly TRACK: (trackingId: string) => string;
         readonly PAYMENT_PROOF: (id: string) => string;
+        readonly BALANCE_PROOF: (id: string) => string;
         readonly DISPUTE: (id: string) => string;
     };
     readonly PREORDERS: {
@@ -1015,6 +1080,17 @@ export declare const API_ENDPOINTS: {
         readonly PRODUCTS: "/api/store/products";
         readonly ORDERS: "/api/store/orders";
         readonly ORDERS_BY_ID: (orderId: string) => string;
+        /**
+         * Dispatch — BOTH branches of `shipOrderSchema`'s discriminated union.
+         *
+         * `method: "custom"` records a carrier the seller posted themselves;
+         * `method: "platform"` enqueues a booking through our own account. One
+         * route, because they are one decision — a second endpoint for the
+         * platform branch would be the same handler behind two ceilings, which is
+         * Root Cause #85.
+         */
+        readonly ORDER_SHIP: (orderId: string) => string;
+        readonly ORDER_OPEN_BALANCE: (orderId: string) => string;
         readonly AUCTIONS: "/api/store/products";
         readonly COUPONS: "/api/store/coupons";
         readonly COUPON_BY_ID: (id: string) => string;
@@ -1229,6 +1305,10 @@ export declare const API_ROUTES: {
         /** The action-index control plane (W7 / D7) — GET the whole index, PATCH one override. */
         readonly ACTION_INDEX: "/api/admin/action-index";
         readonly AD_BY_ID: (id: string) => string;
+        /** D56 — the self-serve creative moderation queue. */
+        readonly AD_BOOKINGS: "/api/admin/ads/bookings";
+        /** D56 — approve or reject one creative. A rejection REQUIRES a note. */
+        readonly AD_BOOKING_MODERATE: (id: string) => string;
         readonly PAYMENTS_SETTINGS: "/api/admin/payments/settings";
         readonly PRODUCTS: "/api/admin/products";
         readonly PRODUCT_BY_ID: (id: string) => string;
@@ -1241,6 +1321,7 @@ export declare const API_ROUTES: {
         readonly ORDER_PAYMENT_VERIFY: (id: string) => string;
         readonly ORDER_PAYMENT_REUPLOAD: (id: string) => string;
         readonly ORDER_PAYMENT_REJECT_FRAUD: (id: string) => string;
+        readonly ORDER_BALANCE_REVIEW: (id: string) => string;
         readonly USERS: "/api/admin/users";
         readonly USERS_BULK: "/api/admin/users/bulk";
         readonly USER_BY_ID: (uid: string) => string;
@@ -1281,6 +1362,14 @@ export declare const API_ROUTES: {
         readonly PAYOUTS_EXPORT: "/api/admin/payouts/export";
         readonly AUDIT_LOG: "/api/admin/audit-log";
         readonly AUDIT_LOG_BY_ID: (id: string) => string;
+        /**
+         * Phase 7 — the GSTR-1 DRAFT export. Takes `?from=&to=` as YYYY-MM-DD and
+         * returns a CSV.
+         *
+         * 🛑 "draft" is in the filename for a reason: nothing in this codebase talks
+         * to the GST portal, and the file is the input to a human filing.
+         */
+        readonly INVOICING_GSTR1: "/api/admin/invoicing/gstr1";
         readonly PAYMENT_CASES: "/api/admin/payment-cases";
         readonly PAYMENT_CASE_BY_ID: (id: string) => string;
         readonly PROTECTION_CLAIMS: "/api/admin/protection-claims";
@@ -1403,6 +1492,19 @@ export declare const API_ROUTES: {
         readonly SELECTION: "/api/cart/selection";
         /** Per-store paid add-on selections — the source of truth for what's charged. */
         readonly ADDONS: "/api/cart/addons";
+        /**
+         * Pay with points, on or off (D46/D47). A boolean and nothing else — the
+         * AMOUNT is derived server-side from the live balance and the 50% cap, which
+         * is why there is no `/api/cart/points/amount`.
+         */
+        readonly POINTS: "/api/cart/points";
+        /**
+         * The instalment plan — a TENURE and nothing else. It lives on the cart,
+         * not in a checkout body, because the online path needs the same answer in
+         * two requests (`/api/payment/create-order` captures, `/api/payment/verify`
+         * writes the order). Same reasoning as `POINTS` and `ADDONS` above.
+         */
+        readonly EMI: "/api/cart/emi";
         readonly COUPON: "/api/cart/coupon";
         /**
          * Add a buyer-assembled group selection as ONE line. Separate from `GET`'s
@@ -1525,6 +1627,7 @@ export declare const API_ROUTES: {
         readonly BY_ID: (id: string) => string;
         readonly TRACK: (trackingId: string) => string;
         readonly PAYMENT_PROOF: (id: string) => string;
+        readonly BALANCE_PROOF: (id: string) => string;
         readonly DISPUTE: (id: string) => string;
     };
     readonly PREORDERS: {
@@ -1563,6 +1666,17 @@ export declare const API_ROUTES: {
         readonly PRODUCTS: "/api/store/products";
         readonly ORDERS: "/api/store/orders";
         readonly ORDERS_BY_ID: (orderId: string) => string;
+        /**
+         * Dispatch — BOTH branches of `shipOrderSchema`'s discriminated union.
+         *
+         * `method: "custom"` records a carrier the seller posted themselves;
+         * `method: "platform"` enqueues a booking through our own account. One
+         * route, because they are one decision — a second endpoint for the
+         * platform branch would be the same handler behind two ceilings, which is
+         * Root Cause #85.
+         */
+        readonly ORDER_SHIP: (orderId: string) => string;
+        readonly ORDER_OPEN_BALANCE: (orderId: string) => string;
         readonly AUCTIONS: "/api/store/products";
         readonly COUPONS: "/api/store/coupons";
         readonly COUPON_BY_ID: (id: string) => string;