@slothmoney/agent-cli 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.3.1 - 2026-07-31
+
+- Coordinate transaction reads with the Sloth Budget daily refresh process.
+- Wait up to 45 seconds for fresh persisted data, then return readable cached
+  transactions with structured refresh status when work continues or fails.
+- Validate the additive transaction refresh response contract.
+
 ## 0.3.0 - 2026-07-30
 
 - Add command-specific help for every command and auth subcommand, including

package/README.md

@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.3.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.3.1 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -221,6 +221,25 @@ Read uncategorised contributions to the joint budget:
 sloth-agent transactions --assignment-scope joint --uncategorized
 ```
 
+The first transaction read after the UTC day changes may refresh linked bank
+data. The CLI waits up to 45 seconds for that refresh to persist, then returns
+the requested booked transactions. If the refresh is still running, partially
+fails, or fails globally, readable cached transactions are still returned with
+a structured `refresh` object:
+
+```json
+{
+  "refresh": {
+    "status": "in_progress",
+    "reason": "wait_timeout",
+    "utcDate": "2026-07-31"
+  }
+}
+```
+
+Re-run the transaction query later to observe the completed refresh. A partial
+account failure remains eligible for an automatic retry.
+
 Set `"assignmentScope": "joint"` on an assignment to categorise the eligible
 shared portion for the joint budget.
 

package/dist/cli.js

@@ -3,8 +3,8 @@ import { parseArgs, resolveBaseUrl, } from './args.js';
 import { parseApiResponse, validateAssignmentPayload, validateJointBudgetSettingsResponse, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.3.0';
-const REQUEST_TIMEOUT_MS = 30_000;
+export const CLI_VERSION = '0.3.1';
+const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
     'API origin:',
@@ -208,10 +208,14 @@ export function transactionsHelpText() {
         'Constraints:',
         '  All filters are omitted by default.',
         '  --end-date must not be before --start-date.',
-        '  This command is read-only.',
+        '  The first transaction read each UTC day may refresh linked bank data.',
+        '  Refresh remotely persists booked transactions and account balances.',
+        '  The command waits up to 45 seconds, then returns cached data if refresh continues.',
         '',
         'Output:',
-        '  JSON containing transactions and nextCursor. Use nextCursor with --cursor',
+        '  JSON containing transactions, nextCursor, and structured refresh status.',
+        '  Refresh failures do not hide readable cached transactions.',
+        '  Use nextCursor with --cursor',
         '  to request the next page. A null nextCursor means there are no more pages.',
         '',
         'Examples:',
@@ -905,7 +909,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             })()}`;
         const response = await fetchImplementation(`${baseUrl}${path}`, {
             method: 'GET',
-            headers,
+            headers: parsed.command === 'transactions'
+                ? { ...headers, Prefer: 'wait=45' }
+                : headers,
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
         const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));

package/dist/contracts.js

@@ -2,6 +2,12 @@ import { ApiError, UsageError, } from './errors.js';
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+function isIsoDate(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.valueOf()) && parsed.toISOString().slice(0, 10) === value;
+}
 function requireObject(value, label) {
     if (!isObject(value))
         throw new UsageError(`${label} must be an object`);
@@ -158,10 +164,27 @@ function isTransaction(value) {
             || value.incomeSubtype === 'interest'));
 }
 function isTransactionsResponse(value) {
+    const validStatuses = new Set(['skipped', 'completed', 'in_progress', 'partial', 'failed']);
+    const validReasons = new Set([
+        'all_fetched_today',
+        'no_api_connections',
+        'no_selected_accounts',
+        'refreshed',
+        'wait_timeout',
+        'account_failures',
+        'refresh_error',
+    ]);
+    const refresh = isObject(value) ? value.refresh : undefined;
     return (isObject(value)
         && Array.isArray(value.transactions)
         && value.transactions.every(isTransaction)
-        && (value.nextCursor === null || typeof value.nextCursor === 'string'));
+        && (value.nextCursor === null || typeof value.nextCursor === 'string')
+        && isObject(refresh)
+        && typeof refresh.status === 'string'
+        && validStatuses.has(refresh.status)
+        && typeof refresh.reason === 'string'
+        && validReasons.has(refresh.reason)
+        && isIsoDate(refresh.utcDate));
 }
 function isAssignmentResponse(value) {
     return (isObject(value)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {