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

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/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,52 +144,60 @@ 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. If you have `Date` objects from a picker, format
+     * them with the exported `toPlainDate` helper.
      *
      * @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; they correspond to calendar days in EAT.
+     * @param props.range.startDate - Start of statement period (inclusive), `YYYY-MM-DD`
+     * @param props.range.endDate - End of statement period (inclusive), `YYYY-MM-DD`
      * @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 });
+     * const entries = await repo.getStatement({
+     *   wallet,
+     *   range: { startDate: "2024-01-01", endDate: "2024-01-31" },
+     * });
      *
      * // Method 2: Using account number
-     * const entriesForAccount = await repo.getStatement({
-     *   accountNo: '123456789'
+     * const byAccount = await repo.getStatement({
+     *   accountNo: '123456789',
+     *   range: { startDate: "2024-01-01", endDate: "2024-01-31" },
      * });
      *
-     * // Custom date range with wallet
-     * const customRangeEntries = await repo.getStatement({
+     * // From a Date picker
+     * const entries = await repo.getStatement({
      *   wallet,
      *   range: {
-     *     startDate: new Date('2024-01-01'),
-     *     endDate: new Date('2024-01-31')
-     *   }
+     *     startDate: toPlainDate(pickedFromDate),
+     *     endDate: toPlainDate(pickedToDate),
+     *   },
      * });
      *
      * // 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;
@@ -203,3 +211,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/package.json

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