@temboplus/frontend-core 1.0.2 → 1.0.3-beta.1

package/dist/utilities/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./timezone/index.js";
+export * from "./text/index.js";

package/dist/utilities/text/index.d.ts

@@ -0,0 +1 @@
+export * from "./text.js";

package/dist/{utils → utilities/text}/text.d.ts

@@ -32,62 +32,16 @@ declare function getInitialsFrom(fullName: string): string;
 /**
  * Validates a personal name (account holder name, wallet owner name, etc.)
  * Used across bank accounts and mobile-money wallets for consistent validation.
- *
- * @param {string} name - The name to validate
- * @returns {boolean} True if the name meets all validation criteria, false otherwise
- *
- * @example
- * // Returns true
- * validatePersonalName("John Smith");
- *
- * @example
- * // Returns false (too short)
- * validatePersonalName("Jo");
- *
- * @example
- * // Returns false (invalid characters)
- * validatePersonalName("User123");
  */
 declare function validatePersonalName(name: string): boolean;
 /**
  * Validates a business name (company, organization, etc.)
  * More lenient than personal name validation.
- *
- * @param {string} name - The business name to validate
- * @returns {boolean} True if the name meets business name criteria, false otherwise
- *
- * @example
- * // Returns true
- * validateBusinessName("ABC Corporation Ltd");
- *
- * @example
- * // Returns true
- * validateBusinessName("Smith & Sons Inc.");
- *
- * @example
- * // Returns true
- * validateBusinessName("M-Pesa");
  */
 declare function validateBusinessName(name: string): boolean;
 /**
  * Validates any name (personal or business) with automatic detection.
- * First tries to detect if it's a business name, then validates accordingly.
- * If detection fails, tries both validation methods.
- *
- * @param {string} name - The name to validate (personal or business)
- * @returns {boolean} True if the name is valid as either personal or business name
- *
- * @example
- * // Returns true (personal name)
- * validateName("John Smith");
- *
- * @example
- * // Returns true (business name)
- * validateName("CRDB Bank PLC");
- *
- * @example
- * // Returns true (could be either)
- * validateName("Smith Solutions");
+ * First tries personal name validation; if that fails, falls back to business name validation.
  */
 declare function validateName(name: string): boolean;
 export declare const TextUtils: {

package/dist/utilities/timezone/boundaries.d.ts

@@ -0,0 +1,49 @@
+import { TZDate } from "@date-fns/tz";
+/**
+ * Timezone-aware day-boundary helpers.
+ *
+ * `react-day-picker` and most form widgets hand us `Date` objects whose
+ * year/month/day come from the **browser's** local clock. When the user
+ * has chosen a different timezone in Settings, that's wrong: picking
+ * "May 25" from London should map to "midnight 25 May in Africa/Nairobi"
+ * (i.e. 21:00 UTC on the 24th), not "midnight 25 May BST" (23:00 UTC).
+ *
+ * Two distinct directions:
+ *
+ * - **Picker → API**: `startOfDayInTimezone` / `endOfDayInTimezone` take
+ *   a picker `Date` and return a plain `Date` anchored at the right UTC
+ *   instant for the wall-clock day boundary in `tz`. We deliberately
+ *   return a plain `Date` (not `TZDate`) so `.toISOString()` produces
+ *   UTC-`Z` format — every value reaching the server / SDK must be
+ *   UTC-`Z`, never the `+HH:MM` offset form that `TZDate.toISOString()`
+ *   emits by default.
+ *
+ * - **API → Picker**: `parseInTimezone` parses a server ISO string into
+ *   a `TZDate` so `getDate()`/`getMonth()`/`getFullYear()` report the
+ *   wall-clock day in `tz` — which is what react-day-picker uses to
+ *   highlight a cell. Do NOT `.toISOString()` the result without going
+ *   through `toUtcInstant` first.
+ */
+/**
+ * Strip timezone identity from any `Date` subclass, returning the bare
+ * UTC instant. `.toISOString()` on the result is guaranteed `Z` form.
+ */
+export declare function toUtcInstant(date: Date): Date;
+/**
+ * UTC instant of midnight on `date`'s wall-clock day in `tz`.
+ */
+export declare function startOfDayInTimezone(date: Date, tz: string): Date;
+/**
+ * UTC instant of 23:59:59.999 on `date`'s wall-clock day in `tz`.
+ */
+export declare function endOfDayInTimezone(date: Date, tz: string): Date;
+/**
+ * Parse an ISO string as a `TZDate` so its Y/M/D/h getters report the
+ * wall-clock value in `tz`.
+ */
+export declare function parseInTimezone(iso: string, tz: string): TZDate;
+/**
+ * True when two dates fall on the same wall-clock day in `tz`. Accepts
+ * either a real `Date` or a `TZDate`.
+ */
+export declare function sameDayInTimezone(a: Date, b: Date, tz: string): boolean;

package/dist/utilities/timezone/format.d.ts

@@ -0,0 +1,8 @@
+/** `25 MAY 2026` */
+export declare function formatDate(date: Date, tz?: string): string;
+/** `25 MAY 2026, 02:30 PM` */
+export declare function formatDateTime(date: Date, tz?: string): string;
+/** `25 MAY 2026, 02:30:45 PM` — audit rows where seconds matter. */
+export declare function formatDateTimeWithSeconds(date: Date, tz?: string): string;
+/** `02:30 PM` */
+export declare function formatTime(date: Date, tz?: string): string;

package/dist/utilities/timezone/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./markets.js";
+export * from "./options.js";
+export * from "./validate.js";
+export * from "./format.js";
+export * from "./boundaries.js";
+export * from "./plain-date.js";

package/dist/utilities/timezone/markets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Zones for the markets TemboPlus operates in. Always visible at the top
+ * of a timezone picker. Each entry pairs the canonical IANA id with the
+ * market-oriented label shown in that group (e.g. "Tanzania & Kenya"
+ * rather than "Africa / Nairobi") — operating rows read as markets, not
+ * zones. Editorial order, not alphabetical.
+ */
+export declare const OPERATING_TIMEZONES: ReadonlyArray<{
+    value: string;
+    market: string;
+}>;
+/**
+ * Reference / anchor zones that are useful even when you don't operate
+ * there — UTC is universal, GMT/London/NY/Paris are how the rest of the
+ * world spells time. Kept deliberately short.
+ */
+export declare const ANCHOR_TIMEZONES: ReadonlyArray<string>;

package/dist/utilities/timezone/options.d.ts

@@ -0,0 +1,36 @@
+export type TimezoneGroup = "operating" | "anchors" | "others";
+export interface TimezoneOption {
+    /**
+     * IANA id, e.g. `"Africa/Nairobi"`. This is what's persisted and what
+     * `Intl.DateTimeFormat` consumes.
+     */
+    value: string;
+    /**
+     * Friendly label for a dropdown, e.g. `"Africa / Nairobi (GMT+03:00)"`.
+     * The offset reflects the current moment — it shifts across DST
+     * boundaries for affected zones, which is acceptable for a picker.
+     */
+    label: string;
+    /**
+     * Market-oriented label rendered only for operating zones, e.g.
+     * `"Tanzania & Kenya (GMT+03:00)"`. Other groups render `label`.
+     */
+    marketLabel?: string;
+    /**
+     * Which dropdown section this option belongs to. Pickers typically hide
+     * the `others` section until the user starts typing.
+     */
+    group: TimezoneGroup;
+}
+/**
+ * Returns the current offset for `timeZone` as a `GMT±HH:MM` string, or
+ * an empty string if `Intl` can't resolve it.
+ */
+export declare function formatOffset(timeZone: string): string;
+/**
+ * Friendly dropdown label for an IANA id, e.g.
+ * `"Africa / Nairobi (GMT+03:00)"`.
+ */
+export declare function formatLabel(timeZone: string): string;
+/** Frozen list of every selectable timezone option, in display order. */
+export declare const TIMEZONE_OPTIONS: ReadonlyArray<TimezoneOption>;

package/dist/utilities/timezone/plain-date.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/**
+ * A calendar day expressed as `YYYY-MM-DD`. No time, no timezone — just
+ * the digits a date picker hands you. Use this for any "what calendar
+ * day did the user pick?" boundary; convert to a `Date` only when you
+ * need to do timezone-aware arithmetic.
+ */
+export type PlainDate = string;
+/** Regex matching a valid `YYYY-MM-DD` string. */
+export declare const PLAIN_DATE_PATTERN: RegExp;
+/** Zod schema validating a {@link PlainDate}. */
+export declare const plainDateSchema: z.ZodString;
+/**
+ * Add or subtract whole calendar days from a `YYYY-MM-DD` string. Pure
+ * string-in/string-out, no dependency on the JS runtime's local
+ * timezone — we pin to UTC noon so DST cliffs and ±1s rounding can't
+ * tip the result onto an adjacent day.
+ *
+ * @example
+ * shiftPlainDate("2026-05-15", 1);   // → "2026-05-16"
+ * shiftPlainDate("2026-05-15", -1);  // → "2026-05-14"
+ * shiftPlainDate("2026-05-31", 1);   // → "2026-06-01"   (month wrap)
+ * shiftPlainDate("2026-01-01", -1);  // → "2025-12-31"   (year wrap)
+ * shiftPlainDate("2026-03-08", 1);   // → "2026-03-09"   (DST-safe; US "spring forward" day)
+ */
+export declare function shiftPlainDate(date: PlainDate, days: number): PlainDate;
+/**
+ * Pad an EAT date range by ±1 day on each side. Used to ensure that an
+ * upstream EAT-anchored query returns every transaction that falls on
+ * the caller's local-zone window, regardless of timezone offset (±1 is
+ * sufficient because the maximum delta from EAT (UTC+3) to any timezone
+ * on earth is 15 hours, comfortably under 24h).
+ *
+ * @example
+ * padEatRange({ startDate: "2026-05-15", endDate: "2026-05-16" });
+ * // → { startDate: "2026-05-14", endDate: "2026-05-17" }
+ */
+export declare function padEatRange(range: {
+    startDate: PlainDate;
+    endDate: PlainDate;
+}): {
+    startDate: PlainDate;
+    endDate: PlainDate;
+};
+/**
+ * Format an absolute instant as a `YYYY-MM-DD` string in the given IANA
+ * timezone. Uses `en-CA` locale because that's the one major locale
+ * whose default date format is already ISO-like — no stitching parts.
+ *
+ * @example
+ * const instant = new Date("2026-05-15T01:30:00+03:00");
+ * localDateInZone(instant, "Africa/Nairobi");    // → "2026-05-15"
+ * localDateInZone(instant, "UTC");               // → "2026-05-14"
+ * localDateInZone(instant, "America/New_York");  // → "2026-05-14"
+ * localDateInZone(instant, "Pacific/Auckland");  // → "2026-05-15"
+ */
+export declare function localDateInZone(instant: Date, timezone: string): PlainDate;

package/dist/utilities/timezone/validate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * IANA id for East Africa Time. The TemboPlus database is anchored to
+ * this zone, so it's the natural default for any report or statement
+ * whose data originates there.
+ */
+export declare const EAT_TIMEZONE = "Africa/Nairobi";
+/**
+ * Default for callers that don't pin a specific timezone. Currently EAT;
+ * may change if/when TemboPlus operates in more markets.
+ */
+export declare const DEFAULT_TIMEZONE = "Africa/Nairobi";
+/**
+ * Validate that a value is a known IANA timezone. The known set comes
+ * from `Intl.supportedValuesOf("timeZone")` plus pinned operating and
+ * anchor zones.
+ */
+export declare function isValidTimezone(value: unknown): value is string;
+/**
+ * True when the caller's selected timezone is effectively EAT. Useful
+ * for short-circuiting EAT-anchored padding / post-filtering so callers
+ * who haven't migrated see byte-identical behaviour.
+ *
+ * @example
+ * isEatTimezone(undefined);          // → true   (no zone = legacy EAT behaviour)
+ * isEatTimezone("Africa/Nairobi");   // → true   (canonical EAT id)
+ * isEatTimezone("UTC");              // → false
+ */
+export declare function isEatTimezone(timezone: string | undefined): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/frontend-core",
-  "version": "1.0.2",
+  "version": "1.0.3-beta.1",
   "description": "A JavaScript/TypeScript package providing common utilities and logic shared across front-end TemboPlus projects.",
   "author": "Okello Gerald",
   "license": "MIT",
@@ -37,10 +37,10 @@
   },
   "homepage": "https://github.com/TemboPlus-Frontend/frontend-core-js#readme",
   "dependencies": {
+    "@date-fns/tz": "^1.4.1",
+    "date-fns": "^4.2.1",
     "libphonenumber-js": "^1.12.6",
-    "pino": "^9.13.1",
     "tslib": "^2.8.1",
-    "uuid": "^11.1.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {
@@ -50,7 +50,6 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
-    "pino-pretty": "^13.1.1",
     "rollup": "^4.39.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",

package/dist/utils/id.d.ts

@@ -1,16 +0,0 @@
-/**
- * Generates a unique UUID (version 4).
- * @returns {string} - A randomly generated UUID string.
- */
-declare function generateUniqueUUID(): string;
-/**
- * Generates a UUID (version 5) based on the input string and a predefined namespace.
- * @param {string} data - The input string to generate the UUID from.
- * @returns {string} - A UUID string generated from the input string.
- */
-declare function generateUuidBasedOn(data: string): string;
-export declare const IdUtils: {
-    generateUniqueUUID: typeof generateUniqueUUID;
-    generateUuidBasedOn: typeof generateUuidBasedOn;
-};
-export {};

package/dist/utils/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./id.js";
-export * from "./time.js";
-export * from "./text.js";
-export * from "./logger.js";

package/dist/utils/logger.d.ts

@@ -1,2 +0,0 @@
-import pino from "pino";
-export declare const logger: pino.Logger<never, boolean>;

package/dist/utils/time.d.ts

@@ -1,26 +0,0 @@
-/**
- * Compares two dates (years, months, and days only) without considering the time.
- * @param {Date} a - The first Date object.
- * @param {Date} b - The second Date object.
- * @returns {boolean} - Returns true if the dates are equal in terms of year, month, and day; otherwise, false.
- */
-declare function compareDates(a: Date, b: Date): boolean;
-/**
- * Sorts two dates in descending order (latest date first).
- * @param {Date} a - The first Date object.
- * @param {Date} b - The second Date object.
- * @returns {number} - Returns a positive value if `b` is after `a`, a negative value if `a` is after `b`, and 0 if they are equal.
- */
-declare function sortDates(a: Date, b: Date): number;
-/**
- * Creates a delay for a given number of milliseconds.
- * @param {number} milliseconds - The delay duration in milliseconds.
- * @returns {Promise<void>} - A promise that resolves after the specified delay.
- */
-declare function delay(milliseconds: number): Promise<void>;
-export declare const TimeUtils: {
-    compareDates: typeof compareDates;
-    sortDates: typeof sortDates;
-    delay: typeof delay;
-};
-export {};