@slothmoney/agent-cli 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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
+  required inputs, option constraints, output, examples, and write safety.
+- Explain that categories are parents and line items are scoped children, and
+  that line-item labels may repeat across categories.
+- Clarify local native credential storage and environment-only authentication
+  for containers, CI, and other headless systems.
+- Read and preview or apply the linked joint-budget shared-transaction setting.
+- Filter transactions by personal or joint assignment scope.
+- Categorise shared personal-account contributions against the joint catalogue
+  with `assignmentScope: "joint"`.
+- Validate the nested `jointBudgetContribution` response contract.
+- Add goal listing, creation, partial updates, and deletion through the Agent
+  API, with goal document ID validation and typed response validation.
+- Keep goal writes in preview mode unless `--apply` is provided, including
+  explicit amount and month clearing.
+- Explain that active shared goal target amounts remain app-managed so balance
+  allocations can be recalculated safely.
+
 ## 0.2.0 - 2026-07-23
 
 - Add `auth login`, `auth status`, and `auth logout`.

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to read and categorise transactions through the
+Use your own agent to manage goals and categorise transactions through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,14 +15,19 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.2.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.3.1 -- sloth-agent --help
 ```
 
 ## Authenticate
 
 Create a personal access token in Sloth Money under
-**Settings > Developer access**, then save it in your operating system's
-secure credential store:
+**Settings > Developer access**, then choose the authentication method for
+where the CLI runs.
+
+### Local computer
+
+On an interactive desktop, save the token in your operating system's secure
+credential store:
 
 ```bash
 sloth-agent auth login
@@ -31,36 +36,45 @@ sloth-agent auth login
 The prompt hides the token. The CLI validates it before replacing any
 credential already stored for the selected API origin.
 
-For a non-interactive import, pass the token through stdin or import it from
-the environment:
-
-```bash
-printf '%s' "$SLOTH_AGENT_TOKEN" | sloth-agent auth login --token-stdin
-sloth-agent auth login --from-env
-```
+### Containers, CI, and headless systems
 
-Never put a token in a command argument. For CI and headless systems, keep
-using an environment secret:
+Native credential storage may be unavailable in a container or other headless
+environment. Inject `SLOTH_AGENT_TOKEN` at runtime through your platform's
+secret manager:
 
 ```bash
 export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
+sloth-agent auth status
 ```
 
+Keep using the environment variable for later commands. You do not need to run
+`sloth-agent auth login` in this setup. Do not put the token in a command
+argument, source file, or container image.
+
 `SLOTH_AGENT_TOKEN` always overrides a stored credential.
 
-To migrate from an existing environment-only setup:
+### Import an existing environment token
+
+To save an environment token in native credential storage on a local computer:
 
 ```bash
 sloth-agent auth login --from-env
 unset SLOTH_AGENT_TOKEN
-sloth-agent auth status
-sloth-agent categories
 ```
 
-Check the active credential with a live API request:
+You can also pass a token to the login command through stdin:
+
+```bash
+printf '%s' "$SLOTH_AGENT_TOKEN" | sloth-agent auth login --token-stdin
+```
+
+Both commands validate the token before replacing the stored credential.
+
+Check the active credential and read your categories:
 
 ```bash
 sloth-agent auth status
+sloth-agent categories
 ```
 
 This updates the PAT's `lastUsedAt` value. To remove the local credential:
@@ -74,59 +88,182 @@ remotely in **Sloth Money Settings > Developer access**.
 
 ## Commands
 
-Read categories and available budget line items:
+An assignment categorises an existing transaction e.g. assigning category
+Groceries to a transaction.
+
+Every command has built-in reference documentation covering its inputs,
+options, output, and examples:
+
+```bash
+sloth-agent auth login --help
+sloth-agent categories --help
+sloth-agent transactions --help
+sloth-agent assign --help
+sloth-agent joint-budget-settings --help
+sloth-agent goals create --help
+sloth-agent goals update --help
+sloth-agent ask-partner --help
+```
+
+### Categorise a transaction end to end
+
+1. Read categories and available budget line items:
 
 ```bash
 sloth-agent categories
 ```
 
-Read uncategorised transactions:
+A category is the broader parent. A line item is a child within one category.
+Line-item names such as `Other` may repeat, so preserve the full choice as
+`(scope, categoryId, lineItemId)`. Use the personal or joint line-item map that
+matches the transaction scope. For example, `Bills → Other` and `Subscriptions
+→ Other` are different choices.
+
+2. Read uncategorised transactions:
 
 ```bash
 sloth-agent transactions --uncategorized --limit 50
 ```
 
-Search a date range:
+3. Copy the exact `transactionRef` for the transaction and a `categoryId` from
+   the earlier outputs into `assignments.json`:
 
-```bash
-sloth-agent transactions \
-  --q "tesco" \
-  --start-date 2026-05-01 \
-  --end-date 2026-05-31
+```json
+{
+  "assignments": [
+    {
+      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
+      "categoryId": "PASTE_A_CATEGORY_ID_HERE"
+    }
+  ]
+}
 ```
 
-Preview an assignment file without writing:
+These are placeholders. Do not submit the example values.
+
+4. Preview the assignment without writing:
 
 ```bash
 sloth-agent assign --input assignments.json
 ```
 
-Apply the same file:
+Without `--apply`, the CLI checks that the file is valid and returns the
+payload it would send. It does not contact Sloth Money, verify the
+`transactionRef` or category values, or write anything. A successful preview
+does not guarantee that applying it will succeed.
+
+5. Apply the same file:
 
 ```bash
 sloth-agent assign --input assignments.json --apply
 ```
 
-Create a partner clarification link:
+Inspect every item in the returned `succeeded` and `failed` arrays.
+
+6. Check the result. Successful assignments update the category and optional
+   budget line item on the original transaction. See the result in **Sloth
+   Money → Transactions**, or re-run the original transaction query without
+   `--uncategorized` and inspect its category fields:
+
+```bash
+sloth-agent transactions --limit 50
+```
+
+The transaction should also disappear from the matching `--uncategorized`
+query. Assignments do not create a separate list.
+
+### Other workflows
+
+List your goals:
+
+```bash
+sloth-agent goals
+```
+
+Goal writes are previews unless `--apply` is present:
+
+```bash
+sloth-agent goals create \
+  --name "Emergency fund" \
+  --target-amount 12000 \
+  --target-month 2027-06
+
+sloth-agent goals create \
+  --name "Emergency fund" \
+  --target-amount 12000 \
+  --target-month 2027-06 \
+  --apply
+```
+
+Use the `id` from list or create output to update or delete a goal:
+
+```bash
+sloth-agent goals update \
+  --goal-id goal-id \
+  --clear-target-amount \
+  --target-month 2027-12 \
+  --achieved=false \
+  --apply
+
+sloth-agent goals delete --goal-id goal-id --apply
+```
+
+Updates are partial. Use `--clear-target-amount` or `--clear-target-month` to
+remove an optional value. Marking a goal achieved removes its forecast
+assignment. Deleting a goal also removes its forecast assignments and drift
+history. Goal sharing remains app-managed. Change an active shared goal's
+pot-tracked target amount in the Sloth Budget app, where account balances can
+be reallocated across goals in priority order.
+
+Read uncategorised contributions to the joint budget:
 
 ```bash
-sloth-agent ask-partner --transaction-ref sloth_txn_...
+sloth-agent transactions --assignment-scope joint --uncategorized
 ```
 
-Assignment files use the Agent API request shape:
+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
 {
-  "assignments": [
-    {
-      "transactionRef": "sloth_txn_...",
-      "categoryId": "groceries",
-      "lineItemId": "weekly"
-    }
-  ]
+  "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.
+
+Set whether the shared portions of personal-account transactions count in the
+linked joint budget. The first command previews; the second applies:
+
+```bash
+sloth-agent joint-budget-settings \
+  --include-shared-personal-transactions=true
+sloth-agent joint-budget-settings \
+  --include-shared-personal-transactions=true \
+  --apply
+```
+
+Create a partner clarification link:
+
+```bash
+sloth-agent ask-partner \
+  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE
+```
+
+The value shown is a placeholder. Copy the exact `transactionRef` from
+`sloth-agent transactions` output.
+
 ## Configuration and output
 
 The CLI defaults to `https://budget.slothmoney.app`. For local development,
@@ -144,7 +281,7 @@ Command results are JSON on stdout. Diagnostics are written to stderr.
 | --- | --- |
 | `0` | Success |
 | `1` | API, network, credential-store, response-validation, or partial assignment failure |
-| `2` | Invalid command, option, URL, date, auth input, or assignment input |
+| `2` | Invalid command, option, URL, date, auth input, goal input, or assignment input |
 | `3` | No credential or native secure storage is unavailable |
 
 Assignment writes are best-effort. A response containing any failed assignment

package/dist/args.js

@@ -47,6 +47,47 @@ function requireNonEmpty(value, name) {
         throw new UsageError(`${name} requires a value`);
     return value;
 }
+function parseGoalAmount(value, name) {
+    if (!/^\d+(?:\.\d{1,2})?$/.test(value)) {
+        throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
+    }
+    const amount = Number(value);
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new UsageError(`${name} must be a positive amount with at most two decimal places`);
+    }
+    return amount;
+}
+function parseGoalMonthKey(value, name) {
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(value)) {
+        throw new UsageError(`${name} must be a valid YYYY-MM month`);
+    }
+    return value;
+}
+function parseExplicitBoolean(value, name) {
+    if (value !== 'true' && value !== 'false') {
+        throw new UsageError(`${name} must be true or false`);
+    }
+    return value === 'true';
+}
+function parseGoalName(value) {
+    const name = value.trim();
+    if (name.length > 200) {
+        throw new UsageError('--name must be at most 200 characters');
+    }
+    return name;
+}
+function parseGoalId(value) {
+    const goalId = value.trim();
+    if (goalId.length > 500
+        || goalId.includes('/')
+        || Array.from(goalId).some((character) => {
+            const codePoint = character.codePointAt(0);
+            return codePoint !== undefined && (codePoint < 32 || codePoint === 127);
+        })) {
+        throw new UsageError('--goal-id must be a valid goal document ID');
+    }
+    return goalId;
+}
 function parseTransactions(args) {
     const filters = {};
     for (let index = 0; index < args.length; index += 1) {
@@ -73,6 +114,7 @@ function parseTransactions(args) {
             '--q',
             '--account-id',
             '--category-id',
+            '--assignment-scope',
             '--cursor',
         ]);
         if (!name || !supported.has(name)) {
@@ -108,6 +150,12 @@ function parseTransactions(args) {
         else if (name === '--category-id') {
             filters.categoryId = setOnce(filters.categoryId, value, name);
         }
+        else if (name === '--assignment-scope') {
+            if (value !== 'personal' && value !== 'joint') {
+                throw new UsageError('--assignment-scope must be personal or joint');
+            }
+            filters.assignmentScope = setOnce(filters.assignmentScope, value, name);
+        }
         else if (name === '--cursor') {
             filters.cursor = setOnce(filters.cursor, value, name);
         }
@@ -162,9 +210,221 @@ function parseAuth(args, baseUrl) {
     }
     throw new UsageError(`Unknown auth command: ${authCommand}`);
 }
+function parseGoals(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown goals list option: ${args[0]}`);
+        }
+        return withBaseUrl({ command: 'goals-list' }, baseUrl);
+    }
+    if (subcommand === 'create') {
+        let name;
+        let targetAmount;
+        let targetMonthKey;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--name'
+                && option !== '--target-amount'
+                && option !== '--target-month') {
+                throw new UsageError(`Unknown goals create option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--name') {
+                name = setOnce(name, parseGoalName(value), option);
+            }
+            else if (option === '--target-amount') {
+                targetAmount = setOnce(targetAmount, parseGoalAmount(value, option), option);
+            }
+            else {
+                targetMonthKey = setOnce(targetMonthKey, parseGoalMonthKey(value, option), option);
+            }
+        }
+        if (!name)
+            throw new UsageError('goals create requires --name <name>');
+        return withBaseUrl({
+            command: 'goals-create',
+            name,
+            ...(targetAmount === undefined ? {} : { targetAmount }),
+            ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'update') {
+        let goalId;
+        let name;
+        let targetAmount;
+        let targetMonthKey;
+        let isAchieved;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            if (argument === '--clear-target-amount') {
+                if (targetAmount !== undefined) {
+                    throw new UsageError('--target-amount and --clear-target-amount are mutually exclusive');
+                }
+                targetAmount = null;
+                continue;
+            }
+            if (argument === '--clear-target-month') {
+                if (targetMonthKey !== undefined) {
+                    throw new UsageError('--target-month and --clear-target-month are mutually exclusive');
+                }
+                targetMonthKey = null;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--goal-id'
+                && option !== '--name'
+                && option !== '--target-amount'
+                && option !== '--target-month'
+                && option !== '--achieved') {
+                throw new UsageError(`Unknown goals update option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--goal-id') {
+                goalId = setOnce(goalId, parseGoalId(value), option);
+            }
+            else if (option === '--name') {
+                name = setOnce(name, parseGoalName(value), option);
+            }
+            else if (option === '--target-amount') {
+                if (targetAmount !== undefined) {
+                    throw new UsageError('--target-amount and --clear-target-amount are mutually exclusive');
+                }
+                targetAmount = parseGoalAmount(value, option);
+            }
+            else if (option === '--target-month') {
+                if (targetMonthKey !== undefined) {
+                    throw new UsageError('--target-month and --clear-target-month are mutually exclusive');
+                }
+                targetMonthKey = parseGoalMonthKey(value, option);
+            }
+            else {
+                isAchieved = setOnce(isAchieved, parseExplicitBoolean(value, option), option);
+            }
+        }
+        if (!goalId)
+            throw new UsageError('goals update requires --goal-id <id>');
+        if (name === undefined
+            && targetAmount === undefined
+            && targetMonthKey === undefined
+            && isAchieved === undefined) {
+            throw new UsageError('goals update requires at least one field to update');
+        }
+        return withBaseUrl({
+            command: 'goals-update',
+            goalId,
+            ...(name === undefined ? {} : { name }),
+            ...(targetAmount === undefined ? {} : { targetAmount }),
+            ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
+            ...(isAchieved === undefined ? {} : { isAchieved }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'delete') {
+        let goalId;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--goal-id') {
+                throw new UsageError(`Unknown goals delete option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            goalId = setOnce(goalId, parseGoalId(value), option);
+        }
+        if (!goalId)
+            throw new UsageError('goals delete requires --goal-id <id>');
+        return withBaseUrl({
+            command: 'goals-delete',
+            goalId,
+            apply,
+        }, baseUrl);
+    }
+    throw new UsageError(`Unknown goals command: ${subcommand}`);
+}
+function helpTopic(argv) {
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === undefined)
+            continue;
+        if (argument === '--base-url') {
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--base-url=') || argument.startsWith('-')) {
+            continue;
+        }
+        positionals.push(argument);
+    }
+    const [command, subcommand] = positionals;
+    if (command === 'auth') {
+        if (subcommand === 'login'
+            || subcommand === 'status'
+            || subcommand === 'logout') {
+            return `auth-${subcommand}`;
+        }
+        return 'auth';
+    }
+    if (command === 'goals') {
+        if (subcommand === 'list')
+            return 'goals-list';
+        if (subcommand === 'create')
+            return 'goals-create';
+        if (subcommand === 'update')
+            return 'goals-update';
+        if (subcommand === 'delete')
+            return 'goals-delete';
+        return 'goals';
+    }
+    if (command === 'categories'
+        || command === 'transactions'
+        || command === 'assign'
+        || command === 'joint-budget-settings'
+        || command === 'ask-partner') {
+        return command;
+    }
+    return undefined;
+}
 export function parseArgs(argv) {
-    if (argv.includes('--help') || argv.includes('-h'))
-        return { command: 'help' };
+    if (argv.includes('--help') || argv.includes('-h')) {
+        const topic = helpTopic(argv);
+        return topic ? { command: 'help', topic } : { command: 'help' };
+    }
     if (argv.includes('--version') || argv.includes('-V'))
         return { command: 'version' };
     const { args, baseUrl } = parseGlobalOptions(argv);
@@ -174,6 +434,9 @@ export function parseArgs(argv) {
     if (command === 'auth') {
         return parseAuth(args, baseUrl);
     }
+    if (command === 'goals') {
+        return parseGoals(args, baseUrl);
+    }
     if (command === 'categories') {
         if (args.length > 0) {
             throw new UsageError(`Unknown categories option: ${args[0]}`);
@@ -208,6 +471,43 @@ export function parseArgs(argv) {
             throw new UsageError('assign requires --input <file>');
         return withBaseUrl({ command, input, apply }, baseUrl);
     }
+    if (command === 'joint-budget-settings') {
+        let includeSharedPersonalTransactions;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const optionName = '--include-shared-personal-transactions';
+            if (argument === optionName || argument.startsWith(`${optionName}=`)) {
+                const value = argument === optionName
+                    ? readOptionValue(args, index, optionName)
+                    : argument.slice(`${optionName}=`.length);
+                if (argument === optionName)
+                    index += 1;
+                if (value !== 'true' && value !== 'false') {
+                    throw new UsageError(`${optionName} must be true or false`);
+                }
+                includeSharedPersonalTransactions = setOnce(includeSharedPersonalTransactions, value === 'true', optionName);
+                continue;
+            }
+            throw new UsageError(`Unknown joint-budget-settings option: ${argument}`);
+        }
+        if (apply && includeSharedPersonalTransactions === undefined) {
+            throw new UsageError('--apply requires --include-shared-personal-transactions=true|false');
+        }
+        return withBaseUrl({
+            command,
+            ...(includeSharedPersonalTransactions === undefined
+                ? {}
+                : { includeSharedPersonalTransactions }),
+            apply,
+        }, baseUrl);
+    }
     if (command === 'ask-partner') {
         let transactionRef;
         for (let index = 0; index < args.length; index += 1) {