@slothmoney/agent-cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.0 - 2026-08-21
+
+- Add `rules` commands to list, read, preview, apply, and delete notification
+  rules anchored to existing transaction references.
+- Add optional one-time PDF renewal-date extraction. Preview mode keeps the
+  file local; apply mode sends it for extraction and the service discards it
+  without storing the contract.
+- Keep recurring predictions and transaction creation outside the Rules
+  contract.
+- Remove the legacy transaction `--account-id` filter and stop exposing
+  internal account and connection locator fields in transaction responses.
+  Use the opaque `accountRef` returned by `sloth-agent accounts`.
+
+## 0.14.1 - 2026-08-21
+
+- Make every parent help page list its nested commands, and give
+  `line-items --help` its own group page instead of generic top-level usage.
+
 ## 0.14.0 - 2026-08-20
 
 - Add `transactions --account-ref REF` using the opaque reference returned by

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect accounts, investments, and budgets, manage goals, move assigned budget money, update planned amounts, and categorise transactions through the
+Use your own agent to inspect accounts, investments, and budgets, manage goals, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.14.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.15.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -98,7 +98,7 @@ 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:
+options, output, and examples. For example:
 
 ```bash
 sloth-agent auth login --help
@@ -109,8 +109,10 @@ sloth-agent budget update --help
 sloth-agent budget move --help
 sloth-agent categories --help
 sloth-agent categories create --help
+sloth-agent line-items --help
 sloth-agent line-items create --help
 sloth-agent transactions --help
+sloth-agent rules --help
 sloth-agent assign --help
 sloth-agent goals create --help
 sloth-agent goals update --help
@@ -119,6 +121,56 @@ sloth-agent goals restore --help
 sloth-agent ask-partner --help
 ```
 
+### Add a transaction notification rule
+
+Rules watch future payments that match an existing transaction. They can alert
+you when the amount changes or before a renewal date. They do not create
+transactions or recurring predictions.
+
+First, run `sloth-agent transactions` and copy the exact `transactionRef` into
+`rule.json` alongside this rule definition:
+
+```json
+{
+  "amountChange": {
+    "enabled": true,
+    "comparison": "increase",
+    "baselinePence": 3184
+  },
+  "renewalReminder": {
+    "enabled": true,
+    "renewalDate": "2027-07-30",
+    "leadDays": 30
+  },
+  "delivery": {
+    "inApp": true,
+    "email": true
+  }
+}
+```
+
+Preview the write locally, then apply the same validated file:
+
+```bash
+sloth-agent rules set \
+  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
+  --input rule.json
+
+sloth-agent rules set \
+  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
+  --input rule.json \
+  --apply
+```
+
+To extract a renewal date first, scan a PDF no larger than 6 MB:
+
+```bash
+sloth-agent rules scan-contract --contract contract.pdf --apply
+```
+
+The PDF is discarded after extraction and is not stored. Scanning only returns
+the date and confidence; use `rules set` to save the resulting reminder.
+
 ### How transaction categorisation is represented
 
 Personal and joint category assignments are separate. A personal assignment
@@ -481,9 +533,8 @@ sloth-agent transactions \
   --limit 50
 ```
 
-Copy the value from `sloth-agent accounts`. The older `--account-id` filter is
-still accepted for compatibility, but new workflows should use
-`--account-ref`. Do not provide both filters in one command.
+Copy the value from `sloth-agent accounts`. Account references are the public
+account identifier for transaction filtering.
 
 Account changes are previews unless `--apply` is present. Connected accounts
 support only goal-savings membership. Manual current accounts support their

package/dist/args.js

@@ -177,7 +177,6 @@ function parseTransactions(args) {
             '--end-date',
             '--q',
             '--account-ref',
-            '--account-id',
             '--category-id',
             '--line-item-id',
             '--assignment-scope',
@@ -213,9 +212,6 @@ function parseTransactions(args) {
         else if (name === '--account-ref') {
             filters.accountRef = setOnce(filters.accountRef, parseAccountRef(value), name);
         }
-        else if (name === '--account-id') {
-            filters.accountId = setOnce(filters.accountId, value, name);
-        }
         else if (name === '--category-id') {
             filters.categoryId = setOnce(filters.categoryId, value, name);
         }
@@ -237,9 +233,6 @@ function parseTransactions(args) {
         && filters.endDate < filters.startDate) {
         throw new UsageError('--end-date must not be before --start-date');
     }
-    if (filters.accountRef !== undefined && filters.accountId !== undefined) {
-        throw new UsageError('Use either --account-ref or --account-id, not both');
-    }
     return filters;
 }
 function parseNamedOptions(args, commandLabel, allowed) {
@@ -752,6 +745,48 @@ function parseGoals(args, baseUrl) {
     }
     throw new UsageError(`Unknown goals command: ${subcommand}`);
 }
+function parseRules(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown rules list option: ${args[0]}`);
+        }
+        return withBaseUrl({ command: 'rules-list' }, baseUrl);
+    }
+    if (subcommand === 'get' || subcommand === 'delete') {
+        const allowed = new Set(['--transaction-ref']);
+        const { values, apply } = parseNamedOptions(args, `rules ${subcommand}`, allowed);
+        const transactionRef = requiredOption(values, '--transaction-ref', `rules ${subcommand}`);
+        if (subcommand === 'get') {
+            if (apply)
+                throw new UsageError('rules get does not accept --apply');
+            return withBaseUrl({ command: 'rules-get', transactionRef }, baseUrl);
+        }
+        return withBaseUrl({
+            command: 'rules-delete',
+            transactionRef,
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'set') {
+        const { values, apply } = parseNamedOptions(args, 'rules set', new Set(['--transaction-ref', '--input']));
+        return withBaseUrl({
+            command: 'rules-set',
+            transactionRef: requiredOption(values, '--transaction-ref', 'rules set'),
+            input: requiredOption(values, '--input', 'rules set'),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'scan-contract') {
+        const { values, apply } = parseNamedOptions(args, 'rules scan-contract', new Set(['--contract']));
+        return withBaseUrl({
+            command: 'rules-scan-contract',
+            contract: requiredOption(values, '--contract', 'rules scan-contract'),
+            apply,
+        }, baseUrl);
+    }
+    throw new UsageError(`Unknown rules command: ${subcommand}`);
+}
 function helpTopic(argv) {
     const positionals = [];
     for (let index = 0; index < argv.length; index += 1) {
@@ -791,6 +826,17 @@ function helpTopic(argv) {
             return 'goals-delete';
         return 'goals';
     }
+    if (command === 'rules') {
+        if (subcommand === 'get')
+            return 'rules-get';
+        if (subcommand === 'set')
+            return 'rules-set';
+        if (subcommand === 'delete')
+            return 'rules-delete';
+        if (subcommand === 'scan-contract')
+            return 'rules-scan-contract';
+        return 'rules';
+    }
     if (command === 'categories') {
         if (subcommand === 'create')
             return 'categories-create';
@@ -803,7 +849,7 @@ function helpTopic(argv) {
             return 'line-items-create';
         if (subcommand === 'rename')
             return 'line-items-rename';
-        return undefined;
+        return 'line-items';
     }
     if (command === 'budget') {
         if (subcommand === 'status')
@@ -845,6 +891,9 @@ export function parseArgs(argv) {
     if (command === 'goals') {
         return parseGoals(args, baseUrl);
     }
+    if (command === 'rules') {
+        return parseRules(args, baseUrl);
+    }
     if (command === 'categories') {
         return parseCategories(args, baseUrl);
     }

package/dist/cli.js

@@ -1,10 +1,10 @@
 import fs from 'node:fs';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { ICON_KEYS } from './category-metadata.js';
-import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.14.0';
+export const CLI_VERSION = '0.15.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -42,9 +42,14 @@ export function usageText() {
         '  sloth-agent line-items rename --scope personal|joint --category-id ID --line-item-id ID --name NAME [--apply]',
         '  sloth-agent transactions [--uncategorized[=true|false]] [--shared[=true|false]] [--limit N]',
         '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
-        '    [--account-ref REF] [--account-id ID] [--category-id ID] [--line-item-id ID]',
+        '    [--account-ref REF] [--category-id ID] [--line-item-id ID]',
         '    [--cursor CURSOR] [--base-url URL]',
         '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
+        '  sloth-agent rules [list] [--base-url URL]',
+        '  sloth-agent rules get --transaction-ref REF [--base-url URL]',
+        '  sloth-agent rules set --transaction-ref REF --input rule.json [--apply]',
+        '  sloth-agent rules delete --transaction-ref REF [--apply]',
+        '  sloth-agent rules scan-contract --contract FILE.pdf [--apply]',
         '  sloth-agent goals [list] [--base-url URL]',
         '  sloth-agent goals create --name NAME --target-amount AMOUNT',
         '    --type keep|spend [--target-month YYYY-MM] [--apply] [--base-url URL]',
@@ -56,7 +61,7 @@ export function usageText() {
         '',
         'Help:',
         '  Run sloth-agent <command> --help for options, inputs, output, and examples.',
-        '  Auth and goal subcommands also have help, for example:',
+        '  Every nested subcommand has its own help, for example:',
         '  sloth-agent auth login --help',
         '  sloth-agent goals update --help',
         '',
@@ -176,6 +181,14 @@ export function categoriesHelpText() {
         '',
         'Read categories and the personal and joint line items within them.',
         '',
+        'Commands:',
+        '  sloth-agent categories list    List categories; "sloth-agent categories" is equivalent.',
+        '  sloth-agent categories create  Preview or create a custom category.',
+        '  sloth-agent categories rename  Preview or rename a custom category.',
+        '',
+        'Help:',
+        '  Run sloth-agent categories <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent categories [list] [--base-url URL]',
         '',
@@ -286,12 +299,35 @@ export function lineItemsCreateHelpText() {
 export function lineItemsRenameHelpText() {
     return lineItemsMutationHelpText('rename');
 }
+export function lineItemsHelpText() {
+    return [
+        'Sloth Agent CLI — line-items',
+        '',
+        'Create or rename personal or joint budget line items.',
+        '',
+        'Commands:',
+        '  sloth-agent line-items create  Preview or create a scoped line item.',
+        '  sloth-agent line-items rename  Preview or rename a scoped line item.',
+        '',
+        'Help:',
+        '  Run sloth-agent line-items <command> --help for command-specific details.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function accountsHelpText() {
     return [
         'Sloth Agent CLI — accounts',
         '',
         'Read the existing Sloth account inventory known to the authenticated user.',
         '',
+        'Commands:',
+        '  sloth-agent accounts list    List accounts; "sloth-agent accounts" is equivalent.',
+        '  sloth-agent accounts update  Preview or update an owned account.',
+        '  sloth-agent accounts remove  Preview or archive an owned manual account.',
+        '',
+        'Help:',
+        '  Run sloth-agent accounts <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent accounts [list] [--base-url URL]',
         '',
@@ -402,6 +438,15 @@ export function budgetHelpText() {
         '',
         'Read one personal or joint budget period.',
         '',
+        'Commands:',
+        '  sloth-agent budget         Read one budget period.',
+        '  sloth-agent budget status  Read assigned, spent, and available money.',
+        '  sloth-agent budget update  Preview or update planned line-item amounts.',
+        '  sloth-agent budget move    Preview or move assigned money.',
+        '',
+        'Help:',
+        '  Run sloth-agent budget <command> --help for command-specific details.',
+        '',
         'Usage:',
         '  sloth-agent budget --scope personal|joint [--period YYYY-MM] [--base-url URL]',
         '',
@@ -549,7 +594,6 @@ export function transactionsHelpText() {
         '  --q TEXT                       Optional. Search transactions by text.',
         '  --account-ref REF              Optional. Filter by the opaque accountRef from sloth-agent accounts.',
         '                                  Copy the exact sloth_account_v1_... value.',
-        '  --account-id ID                Optional legacy filter by provider or stored account ID.',
         '  --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.',
@@ -561,7 +605,6 @@ export function transactionsHelpText() {
         '',
         'Constraints:',
         '  All filters are omitted by default.',
-        '  Use either --account-ref or --account-id, not both.',
         '  --end-date must not be before --start-date.',
         '  The first transaction read each UTC day may refresh linked bank data.',
         '  Refresh remotely persists booked transactions and account balances.',
@@ -896,6 +939,135 @@ export function askPartnerHelpText() {
         '  JSON containing requestId, publicUrl, message, expiresAt, and status.',
     ].join('\n');
 }
+export function rulesHelpText() {
+    return [
+        'Sloth Agent CLI — rules',
+        '',
+        'Manage notifications for future payments that match an existing transaction.',
+        'Rules do not create transactions or recurring predictions.',
+        '',
+        'Commands:',
+        '  rules list           List every saved notification rule.',
+        '  rules get            Read the rule for one transaction.',
+        '  rules set            Preview or save a rule for one transaction.',
+        '  rules delete         Preview or remove a rule.',
+        '  rules scan-contract  Validate or scan a PDF for its renewal date.',
+        '',
+        'Use the exact transactionRef returned by sloth-agent transactions.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function rulesGetHelpText() {
+    return [
+        'Sloth Agent CLI — rules get',
+        '',
+        'Read the saved notification rule for one existing transaction.',
+        '',
+        'Usage:',
+        '  sloth-agent rules get --transaction-ref REF',
+        '',
+        'Required:',
+        '  --transaction-ref REF  The exact transactionRef from sloth-agent transactions.',
+        '',
+        'Behavior:',
+        '  This command is read-only and requires an agent:read token.',
+        '',
+        'Output:',
+        '  JSON containing the saved rule, or rule: null when no rule exists.',
+        '',
+        'Example:',
+        '  sloth-agent rules get --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function rulesSetHelpText() {
+    return [
+        'Sloth Agent CLI — rules set',
+        '',
+        'Preview or save notification conditions for one existing transaction.',
+        '',
+        'Usage:',
+        '  sloth-agent rules set --transaction-ref REF --input FILE [--apply]',
+        '',
+        'Required:',
+        '  --transaction-ref REF  The exact transactionRef from sloth-agent transactions.',
+        '  --input FILE            A JSON rule file such as rule.json.',
+        '',
+        'Input:',
+        '  {',
+        '    "amountChange": {',
+        '      "enabled": true,',
+        '      "comparison": "increase",',
+        '      "baselinePence": 3184',
+        '    },',
+        '    "renewalReminder": {',
+        '      "enabled": true,',
+        '      "renewalDate": "2027-07-30",',
+        '      "leadDays": 30',
+        '    },',
+        '    "delivery": { "inApp": true, "email": true }',
+        '  }',
+        '',
+        '  comparison accepts increase or any. baselinePence is a positive integer.',
+        '  renewalDate is YYYY-MM-DD or null when its reminder is disabled.',
+        '  leadDays is an integer from 0 to 365. At least one condition must be enabled.',
+        '  delivery.inApp must be true; delivery.email adds email delivery.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth validates the file and prints a local preview.',
+        '  With --apply, Sloth replaces the saved rule using a write-enabled token.',
+        '',
+        'Example:',
+        '  sloth-agent rules set --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \\',
+        '    --input rule.json --apply',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function rulesDeleteHelpText() {
+    return [
+        'Sloth Agent CLI — rules delete',
+        '',
+        'Preview or remove the notification rule for one existing transaction.',
+        '',
+        'Usage:',
+        '  sloth-agent rules delete --transaction-ref REF [--apply]',
+        '',
+        'Required:',
+        '  --transaction-ref REF  The exact transactionRef from sloth-agent transactions.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth prints a local deletion preview.',
+        '  With --apply, Sloth removes the rule using a write-enabled token.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function rulesScanContractHelpText() {
+    return [
+        'Sloth Agent CLI — rules scan-contract',
+        '',
+        'Validate or scan a contract PDF for its renewal date.',
+        '',
+        'Usage:',
+        '  sloth-agent rules scan-contract --contract FILE.pdf [--apply]',
+        '',
+        'Required:',
+        '  --contract FILE.pdf  A PDF no larger than 6 MB.',
+        '',
+        'Behavior:',
+        '  Without --apply, the PDF is validated locally and is not sent anywhere.',
+        '  With --apply, the PDF is sent using a write-enabled token.',
+        '',
+        'Contract privacy:',
+        '  Sloth extracts a renewal date and then discards the file. It is not stored.',
+        '',
+        'Output:',
+        '  JSON containing renewalDate and confidence: high, medium, or low.',
+        '',
+        'Example:',
+        '  sloth-agent rules scan-contract --contract contract.pdf --apply',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function commandHelpText(topic) {
     const helpByTopic = {
         auth: authHelpText,
@@ -913,10 +1085,16 @@ export function commandHelpText(topic) {
         categories: categoriesHelpText,
         'categories-create': categoriesCreateHelpText,
         'categories-rename': categoriesRenameHelpText,
+        'line-items': lineItemsHelpText,
         'line-items-create': lineItemsCreateHelpText,
         'line-items-rename': lineItemsRenameHelpText,
         transactions: transactionsHelpText,
         assign: assignHelpText,
+        rules: rulesHelpText,
+        'rules-get': rulesGetHelpText,
+        'rules-set': rulesSetHelpText,
+        'rules-delete': rulesDeleteHelpText,
+        'rules-scan-contract': rulesScanContractHelpText,
         goals: goalsHelpText,
         'goals-list': goalsListHelpText,
         'goals-create': goalsCreateHelpText,
@@ -1023,6 +1201,29 @@ function readBudgetFile(filePath) {
         throw new UsageError(`Failed to read budget JSON: ${message}`);
     }
 }
+function readNotificationRuleFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Failed to read notification rule JSON: ${message}`);
+    }
+}
+function readContractPdf(filePath) {
+    let file;
+    try {
+        file = fs.readFileSync(filePath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Failed to read contract PDF: ${message}`);
+    }
+    if (file.length === 0 || file.length > 6 * 1024 * 1024 || file.subarray(0, 4).toString() !== '%PDF') {
+        throw new UsageError('Contract must be a PDF no larger than 6 MB');
+    }
+    return file;
+}
 function buildTransactionsQuery(filters) {
     const params = new URLSearchParams();
     if (filters.uncategorized !== undefined) {
@@ -1040,8 +1241,6 @@ function buildTransactionsQuery(filters) {
         params.set('q', filters.q);
     if (filters.accountRef !== undefined)
         params.set('accountRef', filters.accountRef);
-    if (filters.accountId !== undefined)
-        params.set('accountId', filters.accountId);
     if (filters.categoryId !== undefined)
         params.set('categoryId', filters.categoryId);
     if (filters.lineItemId !== undefined)
@@ -1258,6 +1457,43 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        const notificationRulePayload = parsed.command === 'rules-set'
+            ? validateNotificationRulePayload(readNotificationRuleFile(parsed.input))
+            : undefined;
+        const notificationRuleEndpoint = (parsed.command === 'rules-get'
+            || parsed.command === 'rules-set'
+            || parsed.command === 'rules-delete')
+            ? `${baseUrl}/api/agent/v1/notification-rules/for-transaction?${new URLSearchParams({
+                transactionRef: parsed.transactionRef,
+            }).toString()}`
+            : undefined;
+        if (parsed.command === 'rules-set' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: notificationRuleEndpoint,
+                method: 'PUT',
+                payload: { transactionRef: parsed.transactionRef, ...notificationRulePayload },
+            });
+            return 0;
+        }
+        if (parsed.command === 'rules-delete' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: notificationRuleEndpoint,
+                method: 'DELETE',
+            });
+            return 0;
+        }
+        if (parsed.command === 'rules-scan-contract' && !parsed.apply) {
+            const contract = readContractPdf(parsed.contract);
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/notification-rules/extract-renewal`,
+                method: 'POST',
+                contract: { bytes: contract.length, mimeType: 'application/pdf' },
+            });
+            return 0;
+        }
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
@@ -1457,6 +1693,51 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return hasFailures(data) ? 1 : 0;
         }
+        if (parsed.command === 'rules-list') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/notification-rules`, {
+                method: 'GET', headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('rules-list', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'rules-get') {
+            const response = await fetchImplementation(notificationRuleEndpoint, {
+                method: 'GET', headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('rules-get', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'rules-set') {
+            const response = await fetchImplementation(notificationRuleEndpoint, {
+                method: 'PUT',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ transactionRef: parsed.transactionRef, ...notificationRulePayload }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('rules-set', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'rules-delete') {
+            const response = await fetchImplementation(notificationRuleEndpoint, {
+                method: 'DELETE', headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('rules-delete', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'rules-scan-contract') {
+            const contract = readContractPdf(parsed.contract);
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/notification-rules/extract-renewal`, {
+                method: 'POST',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    fileBase64: contract.toString('base64'),
+                    mimeType: 'application/pdf',
+                }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('rules-scan-contract', await parseHttpResponse(response, token)));
+            return 0;
+        }
         if (parsed.command === 'ask-partner') {
             const response = await fetchImplementation(`${baseUrl}/api/agent/v1/transaction-explanation-requests`, {
                 method: 'POST',

package/dist/contracts.js

@@ -27,6 +27,102 @@ function rejectUnknownFields(value, allowed, label) {
     if (unknown)
         throw new UsageError(`${label} contains unknown field: ${unknown}`);
 }
+export function validateNotificationRulePayload(value) {
+    const payload = requireObject(value, 'notification rule payload');
+    rejectUnknownFields(payload, new Set(['amountChange', 'renewalReminder', 'delivery']), 'notification rule payload');
+    const amountChange = requireObject(payload.amountChange, 'amountChange');
+    const renewalReminder = requireObject(payload.renewalReminder, 'renewalReminder');
+    const delivery = requireObject(payload.delivery, 'delivery');
+    rejectUnknownFields(amountChange, new Set(['enabled', 'comparison', 'baselinePence']), 'amountChange');
+    rejectUnknownFields(renewalReminder, new Set(['enabled', 'renewalDate', 'leadDays']), 'renewalReminder');
+    rejectUnknownFields(delivery, new Set(['inApp', 'email']), 'delivery');
+    if (typeof amountChange.enabled !== 'boolean')
+        throw new UsageError('amountChange.enabled must be true or false');
+    if (amountChange.comparison !== 'increase' && amountChange.comparison !== 'any') {
+        throw new UsageError('amountChange.comparison must be increase or any');
+    }
+    if (!Number.isSafeInteger(amountChange.baselinePence) || Number(amountChange.baselinePence) <= 0) {
+        throw new UsageError('amountChange.baselinePence must be a positive integer');
+    }
+    if (typeof renewalReminder.enabled !== 'boolean')
+        throw new UsageError('renewalReminder.enabled must be true or false');
+    if (renewalReminder.renewalDate !== null && !isIsoDate(renewalReminder.renewalDate)) {
+        throw new UsageError('renewalReminder.renewalDate must be YYYY-MM-DD or null');
+    }
+    if (renewalReminder.enabled && renewalReminder.renewalDate === null) {
+        throw new UsageError('renewalReminder.renewalDate is required when enabled');
+    }
+    if (!Number.isSafeInteger(renewalReminder.leadDays) || Number(renewalReminder.leadDays) < 0 || Number(renewalReminder.leadDays) > 365) {
+        throw new UsageError('renewalReminder.leadDays must be an integer from 0 to 365');
+    }
+    if (delivery.inApp !== true || typeof delivery.email !== 'boolean') {
+        throw new UsageError('delivery must include inApp: true and an email boolean');
+    }
+    if (!amountChange.enabled && !renewalReminder.enabled) {
+        throw new UsageError('At least one notification rule must be enabled');
+    }
+    return {
+        amountChange: {
+            enabled: amountChange.enabled,
+            comparison: amountChange.comparison,
+            baselinePence: Number(amountChange.baselinePence),
+        },
+        renewalReminder: {
+            enabled: renewalReminder.enabled,
+            renewalDate: renewalReminder.renewalDate,
+            leadDays: Number(renewalReminder.leadDays),
+        },
+        delivery: { inApp: true, email: delivery.email },
+    };
+}
+function isNotificationRule(value) {
+    if (!isObject(value))
+        return false;
+    try {
+        validateNotificationRulePayload({
+            amountChange: value.amountChange,
+            renewalReminder: value.renewalReminder,
+            delivery: value.delivery,
+        });
+    }
+    catch {
+        return false;
+    }
+    return hasOnlyFields(value, [
+        'id', 'transactionRef', 'merchantName', 'currency', 'sourceAmountPence', 'amountChange',
+        'renewalReminder', 'delivery', 'createdAt', 'updatedAt',
+    ])
+        && typeof value.id === 'string'
+        && typeof value.transactionRef === 'string'
+        && typeof value.merchantName === 'string'
+        && typeof value.currency === 'string'
+        && Number.isSafeInteger(value.sourceAmountPence)
+        && typeof value.createdAt === 'string'
+        && typeof value.updatedAt === 'string';
+}
+function isNotificationRuleResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['rule'])
+        && (value.rule === null || isNotificationRule(value.rule));
+}
+function isNotificationRuleListResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['rules'])
+        && Array.isArray(value.rules)
+        && value.rules.every(isNotificationRule);
+}
+function isNotificationRuleDeleteResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['deleted', 'transactionRef'])
+        && value.deleted === true
+        && typeof value.transactionRef === 'string';
+}
+function isRenewalExtractionResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['renewalDate', 'confidence'])
+        && isIsoDate(value.renewalDate)
+        && (value.confidence === 'high' || value.confidence === 'medium' || value.confidence === 'low');
+}
 function validateSplit(value, index, splitIndex) {
     const label = `assignments[${index}].categorySplits[${splitIndex}]`;
     const split = requireObject(value, label);
@@ -254,9 +350,6 @@ function isTransaction(value) {
         && typeof value.date === 'string'
         && value.status === 'booked'
         && isAccountRef(value.accountRef)
-        && typeof value.accountId === 'string'
-        && typeof value.accountDocId === 'string'
-        && typeof value.requisitionId === 'string'
         && (value.scope === 'personal' || value.scope === 'joint')
         && (value.categoryId === null || typeof value.categoryId === 'string')
         && (value.lineItemId === null || typeof value.lineItemId === 'string')
@@ -749,15 +842,23 @@ export function parseApiResponse(command, value) {
                                             ? 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 === 'rules-list'
+                                                    ? isNotificationRuleListResponse(value)
+                                                    : command === 'rules-get' || command === 'rules-set'
+                                                        ? isNotificationRuleResponse(value)
+                                                        : command === 'rules-delete'
+                                                            ? isNotificationRuleDeleteResponse(value)
+                                                            : command === 'rules-scan-contract'
+                                                                ? isRenewalExtractionResponse(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.14.0",
+  "version": "0.15.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {