@mohasinac/appkit 4.70.0 → 4.71.0

package/dist/utils/date.formatter.js

@@ -192,3 +192,28 @@ export function formatCustomDate(date, format = "medium") {
     const options = formatOptions[format] || formatOptions.medium;
     return dateObj.toLocaleDateString(getDefaultLocale(), options);
 }
+/**
+ * Render a `YYYY-MM` period as "October 2026".
+ *
+ * Lifted from the consumer's `src/lib/format/inr.ts` (A7), where five
+ * ad-booking surfaces shared it.
+ *
+ * 🛑 `timeZone: "UTC"` is load-bearing and is NOT a default worth overriding.
+ * The period is a calendar month with no time in it, so constructing it as UTC
+ * midnight and formatting in the viewer's zone renders the PREVIOUS month for
+ * anyone west of UTC. India is UTC+5:30, so the bug is invisible to everyone
+ * testing it there — which is why the original carried this same note.
+ *
+ * 🛑 The locale was a hardcoded `"en-IN"` in the consumer copy. It now comes
+ * from the market profile, which is the one thing about that helper that was
+ * genuinely consumer-specific.
+ *
+ * Returns the input unchanged when it is not a parseable `YYYY-MM`, rather than
+ * rendering "Invalid Date" into a billing table.
+ */
+export function formatMonthLabel(period, locale) {
+    const [y, m] = period.split("-").map(Number);
+    if (!Number.isFinite(y) || !Number.isFinite(m) || m < 1 || m > 12)
+        return period;
+    return new Date(Date.UTC(y, m - 1, 1)).toLocaleDateString(locale ?? getDefaultLocale(), { month: "long", year: "numeric", timeZone: "UTC" });
+}

package/dist/utils/number.formatter.d.ts

@@ -1,6 +1,31 @@
 /**
  * Number Formatting Utilities
  */
+/**
+ * Money for PROSE — notification bodies, error messages, log lines, chips.
+ *
+ * ## Why this exists beside `formatCurrency`
+ *
+ * 71 call sites interpolated a hardcoded symbol next to a bare number —
+ * `` `Minimum offer is ₹${bounds.min}` `` — which is wrong three ways at once:
+ * the symbol is baked in, the grouping is absent (`₹1000`, not `₹1,000`), and
+ * ~20 more files reached for `toLocaleString("en-IN")` with the locale
+ * hardcoded too. All three read from the market profile now, which the consumer
+ * already configures via `configureMarketDefaults()`.
+ *
+ * ## 🛑 Why not just use `formatCurrency`
+ *
+ * `Intl.NumberFormat` with `style: "currency"` forces the currency's standard
+ * fraction digits, so every whole amount becomes `₹1,000.00`. Rewriting 71
+ * strings to add `.00` to prices, offers and refunds that are whole amounts is
+ * a user-visible copy change dressed up as a refactor. This shows the
+ * fractional part only when there is one: `₹1,000` and `₹1,000.50`.
+ *
+ * `formatCurrency` keeps its job — the ISO-correct, locale-placed rendering for
+ * tabular and formal surfaces (invoices, statements). Use that where the form
+ * matters and this where the sentence does.
+ */
+export declare function formatMoney(amount: number, locale?: string): string;
 export declare function formatCurrency(amount: number, currency?: string, locale?: string): string;
 export declare function formatNumber(num: number, locale?: string, options?: {
     decimals?: number;
@@ -13,3 +38,25 @@ export declare function formatCompactNumber(num: number): string;
 export declare function formatDecimal(num: number, decimals?: number): string;
 export declare function formatOrdinal(num: number): string;
 export declare function parseFormattedNumber(str: string): number;
+/**
+ * Whole currency units — no fractional digits — with locale grouping.
+ *
+ * `₹1,500` for 1499.50. Lifted from the consumer's `src/lib/format/inr.ts`
+ * (A5b/A7), where six `/user/*` and ad-booking pages had carried byte-identical
+ * private copies before it was consolidated there.
+ *
+ * ## 🛑 This is NOT `formatMoney`, and must not be collapsed into it
+ *
+ * `maximumFractionDigits: 0` is the whole point: this ROUNDS, so 1499.50
+ * renders `₹1,500`. `formatMoney` keeps the fractional part when there is one.
+ * Both are
+ * correct for their own surfaces — this one is for figures where the fraction
+ * is noise (a monthly ad spend, an order total in a summary row), and the
+ * surfaces using it show booking and order totals, so a change in rounding is
+ * a change in a number a buyer reads.
+ *
+ * Converging the two is a product decision about displayed money, not a
+ * de-duplication. The consumer's copy carried that warning for exactly this
+ * reason and it travels with the function.
+ */
+export declare function formatWholeMoney(amount: number, locale?: string): string;

package/dist/utils/number.formatter.js

@@ -1,7 +1,57 @@
 /**
  * Number Formatting Utilities
  */
-import { getDefaultCurrency, getDefaultLocale, } from "../core/baseline-resolver.js";
+import { getDefaultCurrency, getDefaultCurrencySymbol, getDefaultLocale, } from "../core/baseline-resolver.js";
+/**
+ * Money for PROSE — notification bodies, error messages, log lines, chips.
+ *
+ * ## Why this exists beside `formatCurrency`
+ *
+ * 71 call sites interpolated a hardcoded symbol next to a bare number —
+ * `` `Minimum offer is ₹${bounds.min}` `` — which is wrong three ways at once:
+ * the symbol is baked in, the grouping is absent (`₹1000`, not `₹1,000`), and
+ * ~20 more files reached for `toLocaleString("en-IN")` with the locale
+ * hardcoded too. All three read from the market profile now, which the consumer
+ * already configures via `configureMarketDefaults()`.
+ *
+ * ## 🛑 Why not just use `formatCurrency`
+ *
+ * `Intl.NumberFormat` with `style: "currency"` forces the currency's standard
+ * fraction digits, so every whole amount becomes `₹1,000.00`. Rewriting 71
+ * strings to add `.00` to prices, offers and refunds that are whole amounts is
+ * a user-visible copy change dressed up as a refactor. This shows the
+ * fractional part only when there is one: `₹1,000` and `₹1,000.50`.
+ *
+ * `formatCurrency` keeps its job — the ISO-correct, locale-placed rendering for
+ * tabular and formal surfaces (invoices, statements). Use that where the form
+ * matters and this where the sentence does.
+ */
+export function formatMoney(amount, locale) {
+    const resolvedLocale = locale ?? getDefaultLocale();
+    /*
+     * 🛑 0 decimals if integral, otherwise exactly 2 — NOT `min: 0, max: 2`.
+     *
+     * That first draft was wrong and `published-values.ts` caught it: with a
+     * floor of 0, `1499.5` renders "₹1,499.5", a money figure with one decimal
+     * place. The rule money actually wants is "no trailing .00 on a whole
+     * amount, but always both places when there is a fractional part" — exactly
+     * what the `formatRupees` this replaced encoded as
+     * `minimumFractionDigits: Number.isInteger(amount) ? 0 : 2`, and what its own
+     * docstring stated as `₹10`, `₹1,499.50`.
+     */
+    const fractionDigits = Number.isInteger(amount) ? 0 : 2;
+    const grouped = new Intl.NumberFormat(resolvedLocale, {
+        minimumFractionDigits: fractionDigits,
+        maximumFractionDigits: fractionDigits,
+    }).format(amount);
+    /*
+     * Symbol then number, not `Intl`'s currency placement. These strings are
+     * assembled into sentences that already read "₹500" in copy the team wrote,
+     * and a locale whose convention is "1 000,00 ₹" would reorder mid-sentence.
+     * A market that needs the symbol elsewhere overrides `currencySymbol`.
+     */
+    return `${getDefaultCurrencySymbol()}${grouped}`;
+}
 export function formatCurrency(amount, currency, locale) {
     const resolvedCurrency = currency ?? getDefaultCurrency();
     const resolvedLocale = locale ?? getDefaultLocale();
@@ -107,3 +157,31 @@ export function parseFormattedNumber(str) {
     const num = parseFloat(result);
     return isNegative ? -Math.abs(num) : num;
 }
+/**
+ * Whole currency units — no fractional digits — with locale grouping.
+ *
+ * `₹1,500` for 1499.50. Lifted from the consumer's `src/lib/format/inr.ts`
+ * (A5b/A7), where six `/user/*` and ad-booking pages had carried byte-identical
+ * private copies before it was consolidated there.
+ *
+ * ## 🛑 This is NOT `formatMoney`, and must not be collapsed into it
+ *
+ * `maximumFractionDigits: 0` is the whole point: this ROUNDS, so 1499.50
+ * renders `₹1,500`. `formatMoney` keeps the fractional part when there is one.
+ * Both are
+ * correct for their own surfaces — this one is for figures where the fraction
+ * is noise (a monthly ad spend, an order total in a summary row), and the
+ * surfaces using it show booking and order totals, so a change in rounding is
+ * a change in a number a buyer reads.
+ *
+ * Converging the two is a product decision about displayed money, not a
+ * de-duplication. The consumer's copy carried that warning for exactly this
+ * reason and it travels with the function.
+ */
+export function formatWholeMoney(amount, locale) {
+    return new Intl.NumberFormat(locale ?? getDefaultLocale(), {
+        style: "currency",
+        currency: getDefaultCurrency(),
+        maximumFractionDigits: 0,
+    }).format(amount);
+}

package/dist/validation/phone.validator.d.ts

@@ -6,4 +6,3 @@ export declare function normalizePhone(phone: string): string;
 export declare function formatPhone(phone: string, countryCode?: string): string;
 export declare function extractCountryCode(phone: string): string | null;
 export declare function isValidMobile(phone: string, phonePrefix?: string): boolean;
-export declare function isValidIndianPincode(pincode: string): boolean;

package/dist/validation/phone.validator.js

@@ -36,6 +36,20 @@ export function isValidMobile(phone, phonePrefix) {
     // Generic: 10-15 digit number
     return cleaned.length >= 10 && cleaned.length <= 15;
 }
-export function isValidIndianPincode(pincode) {
-    return /^\d{6}$/.test(pincode.trim());
-}
+/*
+ * 🛑 `isValidIndianPincode` was REMOVED in A6c. It hardcoded `/^\d{6}$/` — one
+ * country's postcode shape in a library meant to be jurisdiction-neutral — and
+ * had **zero callers**: the only reference anywhere was its own re-export from
+ * `index.ts`, so it was dead code on appkit's public surface.
+ *
+ * `constants/geo/countries.ts` is the live answer and a better one: 26 countries
+ * as DATA (`postalPattern`, `postalLabel`, `hasStates`, `dialCode`) behind
+ * `isValidPostalCode` / `postalPatternFor` / `postalLabelFor`, with 17 reader
+ * files. Its own header records the bug this function's shape causes —
+ * "a Canadian address was being held to `/^\d{6}$/`".
+ *
+ * That table is also why A6's proposed `IAddressValidationProvider` was not
+ * built: the AK2 row describing appkit as doing "pincode-only India validation"
+ * predates `countries.ts` and is stale. Postcode rules are a 26-row table, not
+ * 26 provider implementations.
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.70.0",
+  "version": "4.71.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -67,7 +67,12 @@
       "types": "./dist/contracts/registry.d.ts",
       "import": "./dist/contracts/registry.js"
     },
-    "./core/baseline-resolver": {
+    "./cli": {
+   "types": "./dist/cli/index.d.ts",
+   "import": "./dist/cli/index.js",
+   "require": "./dist/cli/index.js"
+  },
+  "./core/baseline-resolver": {
       "types": "./dist/core/baseline-resolver.d.ts",
       "import": "./dist/core/baseline-resolver.js"
     },
@@ -83,7 +88,15 @@
       "types": "./dist/providers/email-resend/index.d.ts",
       "import": "./dist/providers/email-resend/index.js"
     },
-    "./providers/storage-firebase": {
+    "./providers/tax-india-gst": {
+   "types": "./dist/providers/tax-india-gst/index.d.ts",
+   "import": "./dist/providers/tax-india-gst/index.js"
+  },
+  "./providers/shipping-shiprocket": {
+   "types": "./dist/providers/shipping-shiprocket/index.d.ts",
+   "import": "./dist/providers/shipping-shiprocket/index.js"
+  },
+  "./providers/storage-firebase": {
       "types": "./dist/providers/storage-firebase/index.d.ts",
       "import": "./dist/providers/storage-firebase/index.js"
     },
@@ -317,6 +330,7 @@
   },
   "files": [
     "dist",
+    "PROVIDERS.md",
     "tsconfig.base.json",
     "scripts/sieve-audit.mjs",
     "scripts/audit-violations.mjs",