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

package/dist/lib/query/query.builder.d.ts

@@ -28,8 +28,14 @@ export declare class QueryBuilder {
     whereLessThanOrEqual(field: string, value: any): this;
     whereBetween(field: string, min: any, max: any): this;
     /**
-     * Filter by date range with support for Date objects, strings, and null
-     * Internally converts to createdAt:gte and createdAt:lte filters
+     * Filter by date range with support for Date objects, strings, and null.
+     * Internally converts to createdAt:gte and createdAt:lte filters.
+     *
+     * Date objects are normalised to UTC-`Z` ISO format on the wire,
+     * regardless of subclass. Some host-app helpers (e.g. `@date-fns/tz`'s
+     * `TZDate`) override `.toISOString()` to emit `+HH:MM` offset form;
+     * routing through `new Date(d.getTime())` strips the zone identity and
+     * forces the canonical UTC representation.
      */
     whereDateBetween(startDate?: string | Date | null, endDate?: string | Date | null): this;
     addSort(criteria: SortCriteria): this;

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.contract.d.ts

@@ -86,16 +86,16 @@ export declare const contract: {
         summary: "Get Wallet Statement";
         method: "POST";
         body: z.ZodObject<{
-            endDate: z.ZodDate;
-            startDate: z.ZodDate;
+            endDate: z.ZodString;
+            startDate: z.ZodString;
             accountNo: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            startDate: Date;
-            endDate: Date;
+            startDate: string;
+            endDate: string;
             accountNo?: string | undefined;
         }, {
-            startDate: Date;
-            endDate: Date;
+            startDate: string;
+            endDate: string;
             accountNo?: string | undefined;
         }>;
         path: "/statement";

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

@@ -102,6 +102,14 @@ declare const statementEntrySchema: z.ZodObject<{
     accountNo?: string | undefined;
     currencyCode?: string | undefined;
 }>;
+/**
+ * Plain calendar date as a `YYYY-MM-DD` string. Used by endpoints that
+ * filter against a calendar day rather than a moment in time — e.g. the
+ * statement endpoint, which the server evaluates against EAT-anchored
+ * data. Validated by regex to avoid silently sending a full ISO
+ * timestamp where a date-only string is expected.
+ */
+declare const plainDateSchema: z.ZodString;
 /**
  * Collection of wallet-related schemas for export.
  * Provides access to both wallet and statement entry validation schemas.
@@ -197,8 +205,10 @@ export declare const WalletDTOSchemas: {
         accountNo?: string | undefined;
         currencyCode?: string | undefined;
     }>;
+    plainDate: z.ZodString;
 };
 export type WalletDTO = z.infer<typeof walletSchema>;
 export type WalletQueryDTO = z.infer<typeof walletQuerySchema>;
 export type WalletStatementEntryDTO = z.infer<typeof statementEntrySchema>;
+export type PlainDate = z.infer<typeof plainDateSchema>;
 export {};

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

@@ -144,55 +144,66 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
      * 1. Direct wallet object (preferred for performance and currency context)
      * 2. Account number lookup (requires additional API call to determine currency)
      *
-     * If no date range is provided, defaults to the current month.
-     * Returns statement entries with enhanced narration objects containing payout detection
-     * and parsing capabilities.
+     * 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.
+     *
+     * 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 - Optional date range (defaults to current month)
-     * @param props.range.startDate - Start date for statement period
-     * @param props.range.endDate - End date for statement period
+     * @param props.range - Required date range. Both bounds are `YYYY-MM-DD`
+     *   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
+     * @throws {Error} If either `range` bound isn't a valid `YYYY-MM-DD` string
      * @throws {Error} If the statement fetch operation fails or data is invalid
      *
      * @example
      * ```typescript
      * // Method 1: Using wallet object (recommended)
      * const wallet = await repo.getWallets().then(w => w[0]);
-     * const currentMonthEntries = await repo.getStatement({ wallet });
-     *
-     * // Method 2: Using account number
-     * const entriesForAccount = await repo.getStatement({
-     *   accountNo: '123456789'
+     * const entries = await repo.getStatement({
+     *   wallet,
+     *   range: { startDate: "2024-01-01", endDate: "2024-01-31" },
      * });
      *
-     * // Custom date range with wallet
-     * const customRangeEntries = await repo.getStatement({
-     *   wallet,
-     *   range: {
-     *     startDate: new Date('2024-01-01'),
-     *     endDate: new Date('2024-01-31')
-     *   }
+     * // Method 2: Using account number
+     * const byAccount = await repo.getStatement({
+     *   accountNo: '123456789',
+     *   range: { startDate: "2024-01-01", endDate: "2024-01-31" },
      * });
      *
      * // Process payout transactions
-     * const payoutEntries = currentMonthEntries.filter(entry => entry.isPayout);
+     * const payoutEntries = entries.filter(entry => entry.isPayout);
      * payoutEntries.forEach(entry => {
      *   console.log(`Payout ID: ${entry.payoutId}, Amount: ${entry.amountDebited.label}`);
      * });
      * ```
      */
     getStatement(props: {
-        range?: {
-            startDate: Date;
-            endDate: Date;
+        range: {
+            startDate: string;
+            endDate: string;
         };
         wallet?: Wallet;
         accountNo?: string;
+        timezone?: string;
     }): Promise<WalletStatementEntry[]>;
     /**
      * Check if a wallet exists with the given query
@@ -203,3 +214,15 @@ export declare class WalletRepository extends BaseRepository<typeof contract> {
      */
     count(query?: WalletQueryInput): Promise<number>;
 }
+/**
+ * Format a `Date` as `YYYY-MM-DD` using its local (browser/runtime)
+ * Y/M/D fields. Use this to convert a picker-emitted `Date` into the
+ * plain-date string `getStatement` expects.
+ *
+ * The local-field choice is intentional: a `react-day-picker` (or any
+ * grid-based) calendar picks a wall-clock day in the runtime's clock,
+ * and that's the calendar day the user expects to filter against. If
+ * you need to bias the conversion toward a specific zone, pre-position
+ * the `Date` (e.g. via `@date-fns/tz`'s `TZDate`) before calling this.
+ */
+export declare function toPlainDate(date: Date): string;

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.10",
+  "version": "0.2.1-beta.13",
   "description": "A foundational library for Temboplus-Afloat projects.",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",