@slothmoney/agent-cli 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.13.0 - 2026-08-19
+
+- Let `assign` share or unshare an owned booked personal transaction, update
+  its ratio and exclusive amounts in pence, and combine sharing with category
+  assignment in one atomic item.
+- Add `transactions --shared[=true|false]` and strict validation for persisted
+  sharing results, including the resulting joint-budget contribution.
+- Keep preview local and credential-free while printing the exact payload that
+  apply mode will send.
+
+## 0.12.0 - 2026-08-16
+
+- Add read-only `budget status` for current-period assigned, spent, and
+  available category amounts, including refresh and unallocated-activity
+  signals for safer automated budget review.
+
 ## 0.11.0 - 2026-08-16
 
 - Add preview-by-default `budget move` for atomically moving current assigned

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.11.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.13.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -94,8 +94,8 @@ remotely in **Sloth Money Settings > Developer access**.
 
 ## Commands
 
-An assignment categorises an existing transaction e.g. assigning category
-Groceries to a transaction.
+An assignment can change an owned transaction's sharing, categorisation, or
+both.
 
 Every command has built-in reference documentation covering its inputs,
 options, output, and examples:
@@ -104,6 +104,7 @@ options, output, and examples:
 sloth-agent auth login --help
 sloth-agent accounts --help
 sloth-agent budget --help
+sloth-agent budget status --help
 sloth-agent budget update --help
 sloth-agent budget move --help
 sloth-agent categories --help
@@ -144,7 +145,8 @@ item is already categorised for the joint budget. For example:
 
 This transaction is uncategorised personally but categorised as Groceries for
 the joint budget. The `--uncategorized` filter applies to the selected
-assignment scope; personal is used when `--assignment-scope` is omitted.
+assignment scope; the transaction's native scope is used when
+`--assignment-scope` is omitted.
 
 ### Categorise a transaction end to end
 
@@ -237,6 +239,71 @@ The transaction should also disappear from the matching `--uncategorized`
 query. Confirm that an existing assignment in the other scope was not changed.
 Assignments do not create a separate list.
 
+### Share and categorise a transaction
+
+Find an owned, unshared booked transaction:
+
+```bash
+sloth-agent transactions --shared=false --q "sainsbury" --limit 20
+```
+
+Copy its exact `transactionRef` into `assignments.json`. This example shares
+the transaction 60/40, keeps £5 for you personally, and categorises the shared
+remainder as Groceries in Joint:
+
+```json
+{
+  "assignments": [
+    {
+      "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
+      "sharing": {
+        "isShared": true,
+        "shareRatio": 0.6,
+        "userExclusiveAmountPence": 500,
+        "partnerExclusiveAmountPence": 0
+      },
+      "assignmentScope": "joint",
+      "categoryId": "groceries"
+    }
+  ]
+}
+```
+
+Preview stays local and does not load credentials or call the API:
+
+```bash
+sloth-agent assign --input assignments.json
+```
+
+Apply with a token created using **Allow changes**, then read back the same
+state shown in the Web App:
+
+```bash
+sloth-agent assign --input assignments.json --apply
+sloth-agent transactions --shared=true --q "sainsbury" --limit 20
+```
+
+When `sharing` contains only `"isShared": true`, a first share uses the
+couple's saved ratio, falling back to `0.5`, and shares the full amount. On an
+already shared transaction, omitted split fields preserve their current values.
+Set both exclusive pence fields to zero to share the full amount again.
+
+To unshare, send `"sharing": { "isShared": false }` without ratio or exclusive
+fields. Sloth clears the active split but keeps the Joint category dormant, so
+sharing it again restores that category. Current-period Joint pay income is
+reconciled; interest and completed periods keep their existing behaviour.
+
+Sharing is available only for your booked personal-account transactions when
+you have an active partner and Joint budget. Partner-owned rows and native
+joint-account rows cannot be changed this way. Foreign-currency rows can still
+be shared for settlement, but their returned contribution has `eligible: false`
+and `included: false`.
+
+If a combined item omits `assignmentScope`, the category uses Joint when you
+have no exclusive amount and Personal when you do. Category-only items retain
+their existing Personal/native default. Each item commits atomically, while a
+bulk request remains best-effort across items.
+
 ### Other workflows
 
 Read a personal or joint budget. Omit `--period` to use Sloth's current budget period:
@@ -249,6 +316,21 @@ The result includes the budget period and status, currency, the effective plan,
 stored funding amounts when available, categories, line items, and planned
 amounts in pence.
 
+Read current assigned, spent, and available money without aggregating
+transactions yourself:
+
+```bash
+sloth-agent budget status --scope personal
+```
+
+The server applies its normal once-per-UTC-day automatic transaction refresh
+policy before returning the current Sloth period dates and signed booked
+activity. For each category, `availablePence` is
+`assignedPence - spentPence`; a negative value is over budget, and refunds
+reduce `spentPence`. Check `refresh`,
+`activity.uncategorizedSpentPence`, and `activity.unmappedSpentPence` before
+using the result to suggest a reallocation. This command is read-only.
+
 Update selected line-item amounts by creating `budget.json`:
 
 ```json

package/dist/args.js

@@ -155,6 +155,18 @@ function parseTransactions(args) {
             filters.uncategorized = setOnce(filters.uncategorized, value === 'true', '--uncategorized');
             continue;
         }
+        if (argument === '--shared') {
+            filters.shared = setOnce(filters.shared, true, '--shared');
+            continue;
+        }
+        if (argument.startsWith('--shared=')) {
+            const value = argument.slice('--shared='.length);
+            if (value !== 'true' && value !== 'false') {
+                throw new UsageError('--shared must be true or false');
+            }
+            filters.shared = setOnce(filters.shared, value === 'true', '--shared');
+            continue;
+        }
         const [name, inlineValue] = argument.includes('=')
             ? argument.split(/=(.*)/s, 2)
             : [argument, undefined];
@@ -372,21 +384,38 @@ function parseInvestments(args, baseUrl) {
     return withBaseUrl({ command: 'investments', ...(accountRef ? { accountRef } : {}) }, baseUrl);
 }
 function parseBudget(args, baseUrl) {
-    const subcommand = args[0] === 'update' || args[0] === 'move' ? args.shift() : undefined;
+    const subcommand = args[0] === 'status' || args[0] === 'update' || args[0] === 'move'
+        ? args.shift()
+        : undefined;
+    const status = subcommand === 'status';
     const update = subcommand === 'update';
     const move = subcommand === 'move';
-    const commandLabel = update ? 'budget update' : move ? 'budget move' : 'budget';
-    const { values, apply } = parseNamedOptions(args, commandLabel, new Set(update
-        ? ['--scope', '--period', '--input']
-        : move
-            ? ['--scope', '--period', '--from-category-id', '--to-category-id', '--amount']
-            : ['--scope', '--period']));
+    const commandLabel = status
+        ? 'budget status'
+        : update
+            ? 'budget update'
+            : move
+                ? 'budget move'
+                : 'budget';
+    const { values, apply } = parseNamedOptions(args, commandLabel, new Set(status
+        ? ['--scope']
+        : update
+            ? ['--scope', '--period', '--input']
+            : move
+                ? ['--scope', '--period', '--from-category-id', '--to-category-id', '--amount']
+                : ['--scope', '--period']));
     if (!update && !move && apply)
-        throw new UsageError('Unknown budget option: --apply');
+        throw new UsageError(`Unknown ${commandLabel} option: --apply`);
     const scope = requiredOption(values, '--scope', commandLabel);
     if (scope !== 'personal' && scope !== 'joint') {
         throw new UsageError('--scope must be personal or joint');
     }
+    if (status) {
+        return withBaseUrl({
+            command: 'budget-status',
+            scope: scope,
+        }, baseUrl);
+    }
     const period = values.get('--period');
     const common = {
         scope: scope,
@@ -769,6 +798,8 @@ function helpTopic(argv) {
         return undefined;
     }
     if (command === 'budget') {
+        if (subcommand === 'status')
+            return 'budget-status';
         if (subcommand === 'update')
             return 'budget-update';
         if (subcommand === 'move')

package/dist/cli.js

@@ -4,7 +4,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.11.0';
+export const CLI_VERSION = '0.13.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -30,6 +30,7 @@ export function usageText() {
         '  sloth-agent accounts remove --account-ref REF [--apply]',
         '  sloth-agent investments [--account-ref REF] [--base-url URL]',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
+        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
         '  sloth-agent budget update --scope personal|joint [--period YYYY-MM]',
         '    --input budget.json [--apply] [--base-url URL]',
         '  sloth-agent budget move --scope personal|joint [--period YYYY-MM]',
@@ -39,7 +40,7 @@ export function usageText() {
         '  sloth-agent categories rename --category-id ID --name NAME [--apply]',
         '  sloth-agent line-items create --scope personal|joint --category-id ID --name NAME [--apply]',
         '  sloth-agent line-items rename --scope personal|joint --category-id ID --line-item-id ID --name NAME [--apply]',
-        '  sloth-agent transactions [--uncategorized[=true|false]] [--limit N]',
+        '  sloth-agent transactions [--uncategorized[=true|false]] [--shared[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
         '    [--account-id ID] [--category-id ID] [--line-item-id ID]',
         '    [--cursor CURSOR] [--base-url URL]',
@@ -421,6 +422,35 @@ export function budgetHelpText() {
         '  Categories also include plannedPence and assignedPence.',
     ].join('\n');
 }
+export function budgetStatusHelpText() {
+    return [
+        'Sloth Agent CLI — budget status',
+        '',
+        'Read assigned, spent, and available money for the current Sloth budget period.',
+        '',
+        'Usage:',
+        '  sloth-agent budget status --scope personal|joint [--base-url URL]',
+        '',
+        'Options:',
+        '  --scope personal|joint  Required. Budget ownership scope.',
+        '  --base-url URL          Optional. Override the API origin.',
+        '  -h, --help              Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Access and freshness:',
+        '  This command is read-only, requires agent:read, and never changes the budget.',
+        '  The server applies its normal once-per-UTC-day automatic transaction refresh policy.',
+        '  Inspect refresh.status and refresh.reason before relying on the result.',
+        '',
+        'Output:',
+        '  categories[].assignedPence is the money assigned to the category.',
+        '  categories[].spentPence is signed booked activity; refunds reduce it.',
+        '  categories[].availablePence equals assignedPence minus spentPence.',
+        '  Negative availablePence means the category is over budget.',
+        '  activity contains the period dates, transaction count, uncategorizedSpentPence,',
+        '  and unmappedSpentPence. Review either nonzero value before moving money.',
+    ].join('\n');
+}
 export function budgetUpdateHelpText() {
     return [
         'Sloth Agent CLI — budget update',
@@ -512,6 +542,7 @@ export function transactionsHelpText() {
         'Options:',
         '  --uncategorized[=true|false]  Optional. Filter the selected assignment scope by state;',
         '                                  with no value, use true.',
+        '  --shared[=true|false]         Optional. Filter by partner-sharing state; with no value, use true.',
         '  --limit N                     Optional. Integer from 1 to 200; omit for API default.',
         '  --start-date YYYY-MM-DD        Optional. Include transactions on or after this date.',
         '  --end-date YYYY-MM-DD          Optional. Include transactions on or before this date.',
@@ -520,7 +551,7 @@ export function transactionsHelpText() {
         '  --category-id ID               Optional. Filter by category ID.',
         '  --line-item-id ID              Optional. Filter primary or split assignments by line-item ID.',
         '  --assignment-scope SCOPE        Optional. Filter assignments by personal or joint.',
-        '                                  Personal is used when omitted.',
+        '                                  The transaction\'s native scope is used when omitted.',
         '  --cursor CURSOR                Optional. Continue from a previous nextCursor.',
         '  --base-url URL                 Optional. Override the API origin.',
         '  -h, --help                     Show this help.',
@@ -553,8 +584,7 @@ export function assignHelpText() {
     return [
         'Sloth Agent CLI — assign',
         '',
-        'An assignment categorises an existing transaction e.g. assigning category Groceries to a transaction.',
-        'Validate, preview, or apply category assignments from a JSON file.',
+        'Validate, preview, or apply transaction sharing and category assignments from a JSON file.',
         '',
         'Usage:',
         '  sloth-agent assign --input FILE [--apply] [--base-url URL]',
@@ -577,7 +607,11 @@ export function assignHelpText() {
         '',
         'Input:',
         '  The top-level object must contain an assignments array.',
-        '  Each assignment requires transactionRef and a categoryId or non-empty categorySplits.',
+        '  Each assignment requires transactionRef and at least one category operation or sharing object.',
+        '  sharing.isShared is required. shareRatio is optional from 0 to 1 and is your share.',
+        '  userExclusiveAmountPence and partnerExclusiveAmountPence are optional nonnegative integers.',
+        '  Omitted split values use saved defaults for a first share and preserve an existing split.',
+        '  Set sharing.isShared to false on its own to unshare and retain the dormant joint category.',
         '  Copy the exact transactionRef from transactions output and categoryId from',
         '  categories output. The example values below are placeholders.',
         '  Set categoryId to null to clear an assignment.',
@@ -589,7 +623,8 @@ export function assignHelpText() {
         '  a split lineItemId is optional.',
         '  incomeSubtype is optional and accepts "pay", "interest", or null.',
         '  assignmentScope is optional and accepts "personal" or "joint".',
-        '  Personal is used when assignmentScope is omitted.',
+        '  The transaction\'s native scope is used when assignmentScope is omitted for category-only requests.',
+        '  Combined requests use Joint when you have no exclusive amount and Personal when you do.',
         '',
         'Workflow:',
         '  sloth-agent categories',
@@ -603,7 +638,8 @@ export function assignHelpText() {
         '    "assignments": [',
         '      {',
         '        "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",',
-        '        "assignmentScope": "personal",',
+        '        "sharing": { "isShared": true, "shareRatio": 0.6 },',
+        '        "assignmentScope": "joint",',
         '        "categoryId": "PASTE_A_CATEGORY_ID_HERE",',
         '        "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"',
         '      }',
@@ -867,6 +903,7 @@ export function commandHelpText(topic) {
         'accounts-remove': accountsRemoveHelpText,
         investments: investmentsHelpText,
         budget: budgetHelpText,
+        'budget-status': budgetStatusHelpText,
         'budget-move': budgetMoveHelpText,
         'budget-update': budgetUpdateHelpText,
         categories: categoriesHelpText,
@@ -987,6 +1024,8 @@ function buildTransactionsQuery(filters) {
     if (filters.uncategorized !== undefined) {
         params.set('uncategorized', String(filters.uncategorized));
     }
+    if (filters.shared !== undefined)
+        params.set('shared', String(filters.shared));
     if (filters.limit !== undefined)
         params.set('limit', String(filters.limit));
     if (filters.startDate !== undefined)
@@ -1202,6 +1241,17 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        const assignmentPayload = parsed.command === 'assign'
+            ? validateAssignmentPayload(readAssignmentFile(parsed.input))
+            : undefined;
+        if (parsed.command === 'assign' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/transaction-assignments`,
+                payload: assignmentPayload,
+            });
+            return 0;
+        }
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
@@ -1386,12 +1436,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             return 0;
         }
         if (parsed.command === 'assign') {
-            const payload = validateAssignmentPayload(readAssignmentFile(parsed.input));
+            const payload = assignmentPayload;
             const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
-            if (!parsed.apply) {
-                writeJson(writeStdout, { dryRun: true, endpoint, payload });
-                return 0;
-            }
             const response = await fetchImplementation(endpoint, {
                 method: 'POST',
                 headers: {
@@ -1429,16 +1475,19 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, withListedGoalPriorities(data));
             return 0;
         }
-        if (parsed.command === 'budget') {
+        if (parsed.command === 'budget' || parsed.command === 'budget-status') {
             const query = new URLSearchParams({ scope: parsed.scope });
-            if (parsed.periodKey !== undefined)
+            if (parsed.command === 'budget' && parsed.periodKey !== undefined) {
                 query.set('periodKey', parsed.periodKey);
-            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/budgets?${query.toString()}`, {
+            }
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/${parsed.command === 'budget' ? 'budgets' : 'budget-status'}?${query.toString()}`, {
                 method: 'GET',
-                headers,
+                headers: parsed.command === 'budget-status'
+                    ? { ...headers, Prefer: 'wait=45' }
+                    : headers,
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
-            const data = parseApiResponse('budget', await parseHttpResponse(response, token));
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
             writeJson(writeStdout, data);
             return 0;
         }

package/dist/contracts.js

@@ -46,6 +46,7 @@ function validateAssignment(value, index) {
     const assignment = requireObject(value, label);
     rejectUnknownFields(assignment, new Set([
         'transactionRef',
+        'sharing',
         'assignmentScope',
         'categoryId',
         'lineItemId',
@@ -53,6 +54,48 @@ function validateAssignment(value, index) {
         'incomeSubtype',
     ]), label);
     requireString(assignment.transactionRef, `${label}.transactionRef`);
+    let sharing;
+    if (assignment.sharing !== undefined) {
+        const sharingValue = requireObject(assignment.sharing, `${label}.sharing`);
+        rejectUnknownFields(sharingValue, new Set([
+            'isShared',
+            'shareRatio',
+            'userExclusiveAmountPence',
+            'partnerExclusiveAmountPence',
+        ]), `${label}.sharing`);
+        if (typeof sharingValue.isShared !== 'boolean') {
+            throw new UsageError(`${label}.sharing.isShared must be true or false`);
+        }
+        if (sharingValue.shareRatio !== undefined
+            && (typeof sharingValue.shareRatio !== 'number'
+                || !Number.isFinite(sharingValue.shareRatio)
+                || sharingValue.shareRatio < 0
+                || sharingValue.shareRatio > 1)) {
+            throw new UsageError(`${label}.sharing.shareRatio must be a number from 0 to 1`);
+        }
+        for (const field of ['userExclusiveAmountPence', 'partnerExclusiveAmountPence']) {
+            if (sharingValue[field] !== undefined
+                && (!Number.isSafeInteger(sharingValue[field]) || Number(sharingValue[field]) < 0)) {
+                throw new UsageError(`${label}.sharing.${field} must be a nonnegative safe integer`);
+            }
+        }
+        if (sharingValue.isShared === false
+            && (sharingValue.shareRatio !== undefined
+                || sharingValue.userExclusiveAmountPence !== undefined
+                || sharingValue.partnerExclusiveAmountPence !== undefined)) {
+            throw new UsageError(`${label}.sharing cannot include split fields when isShared is false`);
+        }
+        sharing = {
+            isShared: sharingValue.isShared,
+            ...(sharingValue.shareRatio === undefined ? {} : { shareRatio: sharingValue.shareRatio }),
+            ...(sharingValue.userExclusiveAmountPence === undefined
+                ? {}
+                : { userExclusiveAmountPence: Number(sharingValue.userExclusiveAmountPence) }),
+            ...(sharingValue.partnerExclusiveAmountPence === undefined
+                ? {}
+                : { partnerExclusiveAmountPence: Number(sharingValue.partnerExclusiveAmountPence) }),
+        };
+    }
     if (assignment.assignmentScope !== undefined
         && assignment.assignmentScope !== 'personal'
         && assignment.assignmentScope !== 'joint') {
@@ -83,11 +126,20 @@ function validateAssignment(value, index) {
     const hasCategory = typeof assignment.categoryId === 'string' && assignment.categoryId.trim().length > 0;
     const isClear = assignment.categoryId === null && (!categorySplits || categorySplits.length === 0);
     const hasSplits = Array.isArray(categorySplits) && categorySplits.length > 0;
-    if (!hasCategory && !isClear && !hasSplits) {
+    const hasCategoryOperation = hasCategory || isClear || hasSplits;
+    if (!hasCategoryOperation && sharing === undefined) {
         throw new UsageError(`${label}.categoryId or categorySplits is required`);
     }
+    if (!hasCategoryOperation
+        && (assignment.assignmentScope !== undefined
+            || assignment.lineItemId !== undefined
+            || assignment.incomeSubtype !== undefined
+            || assignment.categorySplits !== undefined)) {
+        throw new UsageError(`${label} category options require categoryId or categorySplits`);
+    }
     return {
         transactionRef: assignment.transactionRef,
+        ...(sharing === undefined ? {} : { sharing }),
         ...(assignment.assignmentScope !== undefined
             ? { assignmentScope: assignment.assignmentScope }
             : {}),
@@ -227,37 +279,92 @@ function isTransaction(value) {
             || value.incomeSubtype === 'pay'
             || value.incomeSubtype === 'interest'));
 }
+const REFRESH_STATUSES = new Set(['skipped', 'completed', 'in_progress', 'partial', 'failed']);
+const REFRESH_REASONS = new Set([
+    'all_fetched_today',
+    'no_api_connections',
+    'no_selected_accounts',
+    'refreshed',
+    'wait_timeout',
+    'account_failures',
+    'partial_already_attempted',
+    'refresh_error',
+]);
+function isRefreshStatus(value) {
+    return (isObject(value)
+        && hasOnlyFields(value, ['status', 'reason', 'utcDate'])
+        && typeof value.status === 'string'
+        && REFRESH_STATUSES.has(value.status)
+        && typeof value.reason === 'string'
+        && REFRESH_REASONS.has(value.reason)
+        && isIsoDate(value.utcDate));
+}
 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')
-        && isObject(refresh)
-        && typeof refresh.status === 'string'
-        && validStatuses.has(refresh.status)
-        && typeof refresh.reason === 'string'
-        && validReasons.has(refresh.reason)
-        && isIsoDate(refresh.utcDate));
+        && isRefreshStatus(value.refresh));
 }
 function isAssignmentResponse(value) {
+    const isResponseSplit = (split) => (isObject(split)
+        && hasOnlyFields(split, ['categoryId', 'amountPence', 'lineItemId'])
+        && typeof split.categoryId === 'string'
+        && isNonnegativeSafeInteger(split.amountPence)
+        && split.amountPence > 0
+        && (split.lineItemId === undefined || typeof split.lineItemId === 'string'));
+    const isContribution = (contribution) => (isObject(contribution)
+        && hasOnlyFields(contribution, [
+            'eligible', 'included', 'amountPence', 'categoryId', 'lineItemId',
+            'categorySplits', 'incomeSubtype',
+        ])
+        && typeof contribution.eligible === 'boolean'
+        && typeof contribution.included === 'boolean'
+        && isNonnegativeSafeInteger(contribution.amountPence)
+        && contribution.amountPence > 0
+        && (contribution.categoryId === null || typeof contribution.categoryId === 'string')
+        && (contribution.lineItemId === null || typeof contribution.lineItemId === 'string')
+        && Array.isArray(contribution.categorySplits)
+        && contribution.categorySplits.every(isResponseSplit)
+        && (contribution.incomeSubtype === null
+            || contribution.incomeSubtype === 'pay'
+            || contribution.incomeSubtype === 'interest'));
+    const isSharing = (sharing) => (isObject(sharing)
+        && hasOnlyFields(sharing, [
+            'isShared', 'shareRatio', 'sharedAmountPence', 'userExclusiveAmountPence',
+            'partnerExclusiveAmountPence', 'jointBudgetContribution',
+        ])
+        && typeof sharing.isShared === 'boolean'
+        && typeof sharing.shareRatio === 'number'
+        && Number.isFinite(sharing.shareRatio)
+        && sharing.shareRatio >= 0
+        && sharing.shareRatio <= 1
+        && isNonnegativeSafeInteger(sharing.sharedAmountPence)
+        && isNonnegativeSafeInteger(sharing.userExclusiveAmountPence)
+        && isNonnegativeSafeInteger(sharing.partnerExclusiveAmountPence)
+        && (sharing.jointBudgetContribution === null
+            || isContribution(sharing.jointBudgetContribution)));
+    const isCategoryResult = (item) => ((item.assignmentScope === 'personal' || item.assignmentScope === 'joint')
+        && (item.categoryId === null || typeof item.categoryId === 'string')
+        && (item.lineItemId === null || typeof item.lineItemId === 'string')
+        && Array.isArray(item.categorySplits)
+        && item.categorySplits.every(isResponseSplit)
+        && (item.incomeSubtype === null
+            || item.incomeSubtype === 'pay'
+            || item.incomeSubtype === 'interest'));
     return (isObject(value)
         && Array.isArray(value.succeeded)
         && value.succeeded.every((item) => (isObject(item)
+            && hasOnlyFields(item, [
+                'transactionRef', 'categoryId', 'lineItemId', 'categorySplits',
+                'incomeSubtype', 'assignmentScope', 'sharing',
+            ])
             && typeof item.transactionRef === 'string'
-            && (item.assignmentScope === 'personal' || item.assignmentScope === 'joint')))
+            && (isCategoryResult(item) || isSharing(item.sharing))
+            && (item.sharing === undefined || isSharing(item.sharing))))
         && Array.isArray(value.failed)
         && value.failed.every((item) => (isObject(item)
+            && hasOnlyFields(item, ['transactionRef', 'error'])
             && typeof item.error === 'string'
             && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
 }
@@ -375,6 +482,68 @@ function isBudgetResponse(value) {
         && Array.isArray(value.categories)
         && value.categories.every(isBudgetCategory));
 }
+function isBudgetStatusResponse(value) {
+    if (!isObject(value)
+        || !hasOnlyFields(value, [
+            'scope',
+            'periodKey',
+            'periodStatus',
+            'currency',
+            'effectiveFromPeriodKey',
+            'funding',
+            'activity',
+            'refresh',
+            'categories',
+        ]))
+        return false;
+    return ((value.scope === 'personal' || value.scope === 'joint')
+        && typeof value.periodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.periodKey)
+        && value.periodStatus === 'current'
+        && isCurrency(value.currency)
+        && typeof value.effectiveFromPeriodKey === 'string'
+        && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.effectiveFromPeriodKey)
+        && (value.funding === null
+            || (isObject(value.funding)
+                && hasOnlyFields(value.funding, ['toAssignPence', 'nextPeriodReservePence'])
+                && isSafeInteger(value.funding.toAssignPence)
+                && isSafeInteger(value.funding.nextPeriodReservePence)))
+        && isObject(value.activity)
+        && hasOnlyFields(value.activity, [
+            'startDate',
+            'endDate',
+            'transactionCount',
+            'uncategorizedSpentPence',
+            'unmappedSpentPence',
+        ])
+        && isIsoDate(value.activity.startDate)
+        && isIsoDate(value.activity.endDate)
+        && value.activity.startDate <= value.activity.endDate
+        && isNonnegativeSafeInteger(value.activity.transactionCount)
+        && isSafeInteger(value.activity.uncategorizedSpentPence)
+        && isSafeInteger(value.activity.unmappedSpentPence)
+        && isRefreshStatus(value.refresh)
+        && Array.isArray(value.categories)
+        && value.categories.every((category) => (isObject(category)
+            && hasOnlyFields(category, [
+                'id',
+                'name',
+                'plannedPence',
+                'assignedPence',
+                'spentPence',
+                'availablePence',
+            ])
+            && typeof category.id === 'string'
+            && category.id.trim().length > 0
+            && typeof category.name === 'string'
+            && category.name.trim().length > 0
+            && isNonnegativeSafeInteger(category.plannedPence)
+            && isSafeInteger(category.assignedPence)
+            && isSafeInteger(category.spentPence)
+            && isSafeInteger(category.availablePence)
+            && Number.isSafeInteger(category.assignedPence - category.spentPence)
+            && category.availablePence === category.assignedPence - category.spentPence)));
+}
 function isBudgetMovementResponse(value) {
     return (isObject(value)
         && hasOnlyFields(value, [
@@ -568,25 +737,27 @@ export function parseApiResponse(command, value) {
                     ? isInvestmentsResponse(value)
                     : command === 'budget' || command === 'budget-update'
                         ? isBudgetResponse(value)
-                        : command === 'budget-move'
-                            ? isBudgetMovementResponse(value)
-                            : command === 'categories'
-                                ? isCategoryResponse(value)
-                                : command === 'categories-create' || command === 'categories-rename'
-                                    ? isCategoryMutationResponse(value)
-                                    : command === 'line-items-create' || command === 'line-items-rename'
-                                        ? isLineItemMutationResponse(value)
-                                        : command === 'transactions'
-                                            ? isTransactionsResponse(value)
-                                            : command === 'assign'
-                                                ? isAssignmentResponse(value)
-                                                : command === 'ask-partner'
-                                                    ? isPartnerResponse(value)
-                                                    : command === 'goals-list'
-                                                        ? isGoalsResponse(value)
-                                                        : command === 'goals-delete'
-                                                            ? isGoalDeleteResponse(value)
-                                                            : isGoalMutationResponse(value);
+                        : command === 'budget-status'
+                            ? isBudgetStatusResponse(value)
+                            : command === 'budget-move'
+                                ? isBudgetMovementResponse(value)
+                                : command === 'categories'
+                                    ? isCategoryResponse(value)
+                                    : command === 'categories-create' || command === 'categories-rename'
+                                        ? isCategoryMutationResponse(value)
+                                        : command === 'line-items-create' || command === 'line-items-rename'
+                                            ? isLineItemMutationResponse(value)
+                                            : command === 'transactions'
+                                                ? isTransactionsResponse(value)
+                                                : command === 'assign'
+                                                    ? isAssignmentResponse(value)
+                                                    : command === 'ask-partner'
+                                                        ? isPartnerResponse(value)
+                                                        : command === 'goals-list'
+                                                            ? isGoalsResponse(value)
+                                                            : command === 'goals-delete'
+                                                                ? isGoalDeleteResponse(value)
+                                                                : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/package.json

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