@temboplus/afloat 0.2.1-beta.11 → 0.2.1-beta.13

package/dist/modules/wallet/index.d.ts

@@ -3,4 +3,5 @@ export * from "./wallet.model.js";
 export * from "./statement-entry.model.js";
 export * from "./narration.model.js";
 export * from "./wallet.repository.js";
+export * from "./wallet.timezone.js";
 export * from "./wallet.utils.js";

package/dist/modules/wallet/wallet.repository.d.ts

@@ -147,16 +147,27 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
      * The statement endpoint filters by calendar day, evaluated against
      * the EAT-anchored database. Bounds are therefore *plain* date strings
      * (`YYYY-MM-DD`), not full timestamps — sending a datetime gets
-     * rejected upstream. If you have `Date` objects from a picker, format
-     * them with the exported `toPlainDate` helper.
+     * rejected upstream.
+     *
+     * When `timezone` is provided (and not EAT), `range` is interpreted as
+     * calendar days in that zone: the SDK pads the upstream EAT request
+     * by ±1 day and then post-filters entries whose `valueDate` (an
+     * absolute instant, parsed from the API's offset-carrying ISO string)
+     * falls outside the caller's window when rendered in `timezone`. The
+     * server's own filter is on `valueDate`, so this is consistent.
      *
      * @param props - The statement request properties
      * @param props.wallet - The wallet to get statement for (preferred method)
      * @param props.accountNo - Alternative: account number to lookup wallet and fetch statement
      * @param props.range - Required date range. Both bounds are `YYYY-MM-DD`
-     *   strings; they correspond to calendar days in EAT.
+     *   strings. Without `timezone`, they correspond to calendar days in
+     *   EAT (unchanged legacy behavior). With `timezone`, they correspond
+     *   to calendar days in that zone.
      * @param props.range.startDate - Start of statement period (inclusive), `YYYY-MM-DD`
      * @param props.range.endDate - End of statement period (inclusive), `YYYY-MM-DD`
+     * @param props.timezone - Optional IANA timezone id (e.g.
+     *   `"America/New_York"`). When omitted or set to `"Africa/Nairobi"`,
+     *   behavior is byte-identical to before this option existed.
      * @returns Promise that resolves to an array of validated WalletStatementEntry instances with Narration objects
      * @throws {Error} If neither wallet nor accountNo is provided
      * @throws {Error} If accountNo is provided but no matching wallet is found
@@ -178,15 +189,6 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
      *   range: { startDate: "2024-01-01", endDate: "2024-01-31" },
      * });
      *
-     * // From a Date picker
-     * const entries = await repo.getStatement({
-     *   wallet,
-     *   range: {
-     *     startDate: toPlainDate(pickedFromDate),
-     *     endDate: toPlainDate(pickedToDate),
-     *   },
-     * });
-     *
      * // Process payout transactions
      * const payoutEntries = entries.filter(entry => entry.isPayout);
      * payoutEntries.forEach(entry => {
@@ -201,6 +203,7 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
         };
         wallet?: Wallet;
         accountNo?: string;
+        timezone?: string;
     }): Promise<WalletStatementEntry[]>;
     /**
      * Check if a wallet exists with the given query

package/dist/modules/wallet/wallet.timezone.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Timezone helpers for the wallet statement flow.
+ *
+ * The statement endpoint accepts `YYYY-MM-DD` bounds and evaluates them
+ * against the EAT-anchored (UTC+3) database. To support a caller who
+ * wants "transactions whose `valueDate` falls on these calendar days in
+ * timezone `tz`", we:
+ *
+ *   1. Widen the EAT request by ±1 day, so the upstream window
+ *      definitely contains every instant the caller cares about. ±1 is
+ *      mathematically sufficient because the maximum delta from EAT
+ *      (UTC+3) to any timezone on earth is 15 hours, comfortably under
+ *      24h.
+ *   2. After the response comes back, filter entries by `valueDate`
+ *      rendered in the caller's zone, comparing as plain `YYYY-MM-DD`
+ *      strings (which is correct because string-comparing two ISO
+ *      calendar dates is equivalent to comparing the dates).
+ *
+ * The server's filter is on `valueDate` (verified empirically), so the
+ * client-side filter uses the same field — no risk of dropping records
+ * that were padded in.
+ */
+import type { PlainDate } from "./wallet.dtos.js";
+/** IANA id for EAT. The SDK short-circuits all timezone work for this. */
+export declare const EAT_TIMEZONE = "Africa/Nairobi";
+/**
+ * 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.
+ *
+ * @example
+ * padEatRange({ startDate: "2026-05-15", endDate: "2026-05-16" });
+ * // → { startDate: "2026-05-14", endDate: "2026-05-17" }
+ *
+ * padEatRange({ startDate: "2026-01-01", endDate: "2026-12-31" });
+ * // → { startDate: "2025-12-31", endDate: "2027-01-01" }   (year wraps on both ends)
+ */
+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 need to
+ * stitch parts back together by hand.
+ *
+ * @example
+ * // A transaction's valueDate from the API ("+03:00" is EAT)
+ * const instant = new Date("2026-05-15T01:30:00+03:00");
+ *
+ * localDateInZone(instant, "Africa/Nairobi");    // → "2026-05-15"
+ * localDateInZone(instant, "UTC");               // → "2026-05-14" (22:30 prev day in UTC)
+ * localDateInZone(instant, "America/New_York");  // → "2026-05-14" (18:30 prev day in NY)
+ * localDateInZone(instant, "Pacific/Auckland");  // → "2026-05-15" (10:30 same day in NZ)
+ */
+export declare function localDateInZone(instant: Date, timezone: string): PlainDate;
+/**
+ * True when the caller's selected timezone is effectively EAT. Used to
+ * short-circuit padding + post-filtering so existing EAT callers see
+ * byte-identical behavior.
+ *
+ * @example
+ * isEatTimezone(undefined);          // → true   (no zone = legacy EAT behavior)
+ * isEatTimezone("Africa/Nairobi");   // → true   (canonical EAT id)
+ * isEatTimezone("UTC");              // → false
+ * isEatTimezone("America/New_York"); // → false
+ */
+export declare function isEatTimezone(timezone: string | undefined): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.2.1-beta.11",
+  "version": "0.2.1-beta.13",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",