@slothmoney/agent-cli 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.16.0 - 2026-08-21
+
+- Add receipt image extraction plus read, preview-by-default attach, and remove
+  commands for reviewed receipt items.
+- Keep receipt images and extraction drafts transient; only reviewed JSON is
+  sent to the confirmed evidence endpoint.
+- Keep reviewed receipt rows simple: `id`, `label`, and a signed amount, with
+  discounts represented as negative rows.
+- Match notification-rule writes to the Agent API by sending only the optional
+  email choice while keeping in-app delivery server-owned and always enabled.
+- Accept computed renewal reminder dates and nullable rule timestamps in rule
+  responses, and accept a null extracted date when a PDF contains no usable
+  renewal date.
+- Send contract PDFs with the required filename and content fields, and align
+  the local 6 MB limit with the API's encoded-content limit.
+
 ## 0.15.0 - 2026-08-21
 
 - Add `rules` commands to list, read, preview, apply, and delete notification

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.15.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.16.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -114,6 +114,9 @@ sloth-agent line-items create --help
 sloth-agent transactions --help
 sloth-agent rules --help
 sloth-agent assign --help
+sloth-agent receipts --help
+sloth-agent receipts extract --help
+sloth-agent receipts attach --help
 sloth-agent goals create --help
 sloth-agent goals update --help
 sloth-agent goals mark-spent --help
@@ -143,12 +146,14 @@ First, run `sloth-agent transactions` and copy the exact `transactionRef` into
     "leadDays": 30
   },
   "delivery": {
-    "inApp": true,
     "email": true
   }
 }
 ```
 
+In-app notifications are always included. Set `delivery.email` to choose
+whether Sloth also sends an email. `leadDays` accepts an integer from 1 to 365.
+
 Preview the write locally, then apply the same validated file:
 
 ```bash
@@ -171,6 +176,47 @@ 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.
 
+### Attach receipt items end to end
+
+Receipt items are evidence attached to a booked transaction. They do not
+change its category, sharing, partner balance, or budget treatment.
+
+1. Copy the exact `transactionRef` from `sloth-agent transactions`, then
+   extract a transient draft from a JPEG, PNG, or WebP image up to 8 MB:
+
+```bash
+sloth-agent receipts extract --image /path/to/receipt.jpg > receipt-draft.json
+```
+
+The image and draft are not saved by Sloth. Review the JSON, remove the outer
+`draft` key and `warnings`, and keep `schemaVersion`, `currency`, and the
+reviewed `receiptItems` in `receipt.json`. Each item contains only `id`, `label`,
+and a signed integer `amountPence`. Purchases and added charges are positive;
+discounts are negative. Do not add tax already included in other prices as a
+separate row because the signed rows should sum to the printed receipt total.
+
+2. Preview the exact write without contacting the API:
+
+```bash
+sloth-agent receipts attach \
+  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
+  --input receipt.json
+```
+
+3. Apply the reviewed JSON with a write-enabled token:
+
+```bash
+sloth-agent receipts attach \
+  --transaction-ref PASTE_THE_EXACT_TRANSACTION_REF_HERE \
+  --input receipt.json \
+  --apply
+```
+
+Use `sloth-agent receipts get --transaction-ref REF` to read the saved
+revision. Pass `--expected-revision N` when replacing it, or use
+`sloth-agent receipts remove --transaction-ref REF --revision N --apply` to
+remove it.
+
 ### How transaction categorisation is represented
 
 Personal and joint category assignments are separate. A personal assignment

package/dist/args.js

@@ -93,6 +93,93 @@ function parseGoalPriority(value) {
     }
     return priority;
 }
+function parsePositiveRevision(value, name) {
+    if (!/^[1-9]\d*$/.test(value)) {
+        throw new UsageError(`${name} must be a positive whole number`);
+    }
+    const revision = Number(value);
+    if (!Number.isSafeInteger(revision)) {
+        throw new UsageError(`${name} must be a positive whole number`);
+    }
+    return revision;
+}
+function parseReceipts(args, baseUrl) {
+    const subcommand = args.shift();
+    if (!subcommand || !['extract', 'get', 'attach', 'remove'].includes(subcommand)) {
+        throw new UsageError('receipts requires extract, get, attach, or remove');
+    }
+    let transactionRef;
+    let image;
+    let input;
+    let expectedRevision;
+    let revision;
+    let apply = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        const read = (name) => {
+            const value = readOptionValue(args, index, name);
+            index += 1;
+            return value;
+        };
+        if (argument === '--apply') {
+            if (apply)
+                throw new UsageError('--apply may only be provided once');
+            apply = true;
+        }
+        else if (argument === '--transaction-ref') {
+            transactionRef = setOnce(transactionRef, read('--transaction-ref'), '--transaction-ref');
+        }
+        else if (argument === '--image') {
+            image = setOnce(image, read('--image'), '--image');
+        }
+        else if (argument === '--input') {
+            input = setOnce(input, read('--input'), '--input');
+        }
+        else if (argument === '--expected-revision') {
+            expectedRevision = setOnce(expectedRevision, parsePositiveRevision(read('--expected-revision'), '--expected-revision'), '--expected-revision');
+        }
+        else if (argument === '--revision') {
+            revision = setOnce(revision, parsePositiveRevision(read('--revision'), '--revision'), '--revision');
+        }
+        else {
+            throw new UsageError(`Unknown receipts ${subcommand} option: ${argument}`);
+        }
+    }
+    if (subcommand === 'extract') {
+        if (!image)
+            throw new UsageError('receipts extract requires --image <file>');
+        if (transactionRef || input || expectedRevision || revision || apply) {
+            throw new UsageError('receipts extract accepts only --image');
+        }
+        return withBaseUrl({ command: 'receipts-extract', image }, baseUrl);
+    }
+    if (!transactionRef)
+        throw new UsageError(`receipts ${subcommand} requires --transaction-ref <ref>`);
+    if (subcommand === 'get') {
+        if (image || input || expectedRevision || revision || apply) {
+            throw new UsageError('receipts get accepts only --transaction-ref');
+        }
+        return withBaseUrl({ command: 'receipts-get', transactionRef }, baseUrl);
+    }
+    if (subcommand === 'attach') {
+        if (!input)
+            throw new UsageError('receipts attach requires --input <file>');
+        if (image || revision)
+            throw new UsageError('receipts attach received an unsupported option');
+        return withBaseUrl({
+            command: 'receipts-attach',
+            transactionRef,
+            input,
+            ...(expectedRevision === undefined ? {} : { expectedRevision }),
+            apply,
+        }, baseUrl);
+    }
+    if (revision === undefined)
+        throw new UsageError('receipts remove requires --revision <number>');
+    if (image || input || expectedRevision)
+        throw new UsageError('receipts remove received an unsupported option');
+    return withBaseUrl({ command: 'receipts-remove', transactionRef, revision, apply }, baseUrl);
+}
 function parseGoalType(value) {
     if (!isGoalType(value)) {
         throw new UsageError('--type must be keep or spend');
@@ -860,6 +947,17 @@ function helpTopic(argv) {
             return 'budget-move';
         return 'budget';
     }
+    if (command === 'receipts') {
+        if (subcommand === 'extract')
+            return 'receipts-extract';
+        if (subcommand === 'get')
+            return 'receipts-get';
+        if (subcommand === 'attach')
+            return 'receipts-attach';
+        if (subcommand === 'remove')
+            return 'receipts-remove';
+        return 'receipts';
+    }
     if (command === 'accounts'
         || command === 'transactions'
         || command === 'assign'
@@ -909,6 +1007,9 @@ export function parseArgs(argv) {
     if (command === 'budget') {
         return parseBudget(args, baseUrl);
     }
+    if (command === 'receipts') {
+        return parseReceipts(args, baseUrl);
+    }
     if (command === 'transactions') {
         return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);
     }

package/dist/cli.js

@@ -1,11 +1,13 @@
 import fs from 'node:fs';
+import nodePath from 'node:path';
 import { parseArgs, resolveBaseUrl, } from './args.js';
 import { ICON_KEYS } from './category-metadata.js';
-import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, } from './contracts.js';
+import { parseApiResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.15.0';
+export const CLI_VERSION = '0.16.0';
 const REQUEST_TIMEOUT_MS = 60_000;
+const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
     '',
     'API origin:',
@@ -50,6 +52,10 @@ export function usageText() {
         '  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 receipts extract --image FILE [--base-url URL]',
+        '  sloth-agent receipts get --transaction-ref REF [--base-url URL]',
+        '  sloth-agent receipts attach --transaction-ref REF --input receipt.json [--expected-revision N] [--apply]',
+        '  sloth-agent receipts remove --transaction-ref REF --revision N [--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]',
@@ -980,6 +986,53 @@ export function rulesGetHelpText() {
         ...API_ORIGIN_HELP_LINES,
     ].join('\n');
 }
+export function receiptsHelpText() {
+    return [
+        'Sloth Agent CLI — receipts',
+        '',
+        'Extract, review, read, attach, or remove receipt items for a booked transaction.',
+        '',
+        'Commands:',
+        '  sloth-agent receipts extract   Extract a transient draft from an image',
+        '  sloth-agent receipts get       Read saved receipt items',
+        '  sloth-agent receipts attach    Preview or save reviewed JSON',
+        '  sloth-agent receipts remove    Preview or remove saved receipt items',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Receipt items are evidence only. They do not change categories, sharing, or budgets.',
+    ].join('\n');
+}
+export function receiptsExtractHelpText() {
+    return [
+        'Sloth Agent CLI — receipts extract',
+        '',
+        'Usage:',
+        '  sloth-agent receipts extract --image FILE [--base-url URL]',
+        '',
+        'Required input:',
+        '  --image FILE   JPEG, PNG, or WebP image up to 8 MB.',
+        '',
+        'This sends the image for one extraction request and does not save it or the draft.',
+        'Review the returned JSON before using receipts attach.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON containing draft.currency, draft.receiptItems, and draft.warnings.',
+    ].join('\n');
+}
+export function receiptsGetHelpText() {
+    return [
+        'Sloth Agent CLI — receipts get',
+        '',
+        'Usage:',
+        '  sloth-agent receipts get --transaction-ref REF [--base-url URL]',
+        '',
+        '  --transaction-ref REF   Exact transactionRef from transactions output.',
+        '',
+        'This command is read-only. Output contains receipt or null.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function rulesSetHelpText() {
     return [
         'Sloth Agent CLI — rules set',
@@ -1005,13 +1058,13 @@ export function rulesSetHelpText() {
         '      "renewalDate": "2027-07-30",',
         '      "leadDays": 30',
         '    },',
-        '    "delivery": { "inApp": true, "email": true }',
+        '    "delivery": { "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.',
+        '  leadDays is an integer from 1 to 365. At least one condition must be enabled.',
+        '  In-app notifications are always included. delivery.email adds email delivery.',
         '',
         'Write behavior:',
         '  Without --apply, Sloth validates the file and prints a local preview.',
@@ -1023,6 +1076,25 @@ export function rulesSetHelpText() {
         ...API_ORIGIN_HELP_LINES,
     ].join('\n');
 }
+export function receiptsAttachHelpText() {
+    return [
+        'Sloth Agent CLI — receipts attach',
+        '',
+        'Usage:',
+        '  sloth-agent receipts attach --transaction-ref REF --input FILE [--expected-revision N] [--apply]',
+        '',
+        'Required inputs:',
+        '  --transaction-ref REF   Exact transactionRef from transactions output.',
+        '  --input FILE            Reviewed JSON with schemaVersion, currency, and receiptItems.',
+        '                          Each item has id, label, and signed amountPence; use negative for discounts.',
+        '  --expected-revision N   Required when replacing saved evidence; omit for a new receipt.',
+        '',
+        'Write behavior:',
+        '  Without --apply, prints the exact request and makes no API call.',
+        '  With --apply, saves only the reviewed JSON. Images and extraction drafts are not saved.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function rulesDeleteHelpText() {
     return [
         'Sloth Agent CLI — rules delete',
@@ -1068,6 +1140,19 @@ export function rulesScanContractHelpText() {
         ...API_ORIGIN_HELP_LINES,
     ].join('\n');
 }
+export function receiptsRemoveHelpText() {
+    return [
+        'Sloth Agent CLI — receipts remove',
+        '',
+        'Usage:',
+        '  sloth-agent receipts remove --transaction-ref REF --revision N [--apply]',
+        '',
+        '  --revision N   Current positive revision from receipts get.',
+        '',
+        'Without --apply, prints a preview. With --apply, removes saved receipt items.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
 export function commandHelpText(topic) {
     const helpByTopic = {
         auth: authHelpText,
@@ -1095,6 +1180,11 @@ export function commandHelpText(topic) {
         'rules-set': rulesSetHelpText,
         'rules-delete': rulesDeleteHelpText,
         'rules-scan-contract': rulesScanContractHelpText,
+        receipts: receiptsHelpText,
+        'receipts-extract': receiptsExtractHelpText,
+        'receipts-get': receiptsGetHelpText,
+        'receipts-attach': receiptsAttachHelpText,
+        'receipts-remove': receiptsRemoveHelpText,
         goals: goalsHelpText,
         'goals-list': goalsListHelpText,
         'goals-create': goalsCreateHelpText,
@@ -1219,11 +1309,46 @@ function readContractPdf(filePath) {
         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') {
+    if (file.length === 0 || file.length > MAX_CONTRACT_PDF_BYTES || file.subarray(0, 4).toString() !== '%PDF') {
         throw new UsageError('Contract must be a PDF no larger than 6 MB');
     }
     return file;
 }
+function readReceiptFile(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 receipt JSON: ${message}`);
+    }
+}
+function readReceiptImage(filePath) {
+    const extension = filePath.toLowerCase().split('.').pop();
+    const mimeType = extension === 'jpg' || extension === 'jpeg'
+        ? 'image/jpeg'
+        : extension === 'png'
+            ? 'image/png'
+            : extension === 'webp'
+                ? 'image/webp'
+                : null;
+    if (!mimeType)
+        throw new UsageError('Receipt image must be JPEG, PNG, or WebP');
+    try {
+        const body = fs.readFileSync(filePath);
+        if (body.length === 0)
+            throw new UsageError('Receipt image is empty');
+        if (body.length > 8 * 1024 * 1024)
+            throw new UsageError('Receipt image must be 8 MB or smaller');
+        return { body, mimeType };
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Failed to read receipt image: ${message}`);
+    }
+}
 function buildTransactionsQuery(filters) {
     const params = new URLSearchParams();
     if (filters.uncategorized !== undefined) {
@@ -1457,6 +1582,34 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             });
             return 0;
         }
+        const receiptConfirmation = parsed.command === 'receipts-attach'
+            ? validateReceiptConfirmation(readReceiptFile(parsed.input))
+            : undefined;
+        if (parsed.command === 'receipts-attach' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/receipts/confirmed`,
+                method: 'PUT',
+                payload: {
+                    transactionRef: parsed.transactionRef,
+                    expectedRevision: parsed.expectedRevision ?? null,
+                    receipt: receiptConfirmation,
+                },
+            });
+            return 0;
+        }
+        if (parsed.command === 'receipts-remove' && !parsed.apply) {
+            writeJson(writeStdout, {
+                dryRun: true,
+                endpoint: `${baseUrl}/api/agent/v1/receipts/confirmed`,
+                method: 'DELETE',
+                payload: {
+                    transactionRef: parsed.transactionRef,
+                    expectedRevision: parsed.revision,
+                },
+            });
+            return 0;
+        }
         const notificationRulePayload = parsed.command === 'rules-set'
             ? validateNotificationRulePayload(readNotificationRuleFile(parsed.input))
             : undefined;
@@ -1497,6 +1650,58 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         const credential = await resolveCredential(environment, baseUrl, getCredentialStore);
         token = credential.token;
         const headers = requestHeaders(token);
+        if (parsed.command === 'receipts-extract') {
+            const image = readReceiptImage(parsed.image);
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/receipts/extract`, {
+                method: 'POST',
+                headers: { ...headers, 'Content-Type': image.mimeType },
+                body: image.body,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'receipts-get') {
+            const query = new URLSearchParams({ transactionRef: parsed.transactionRef });
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/receipts/confirmed?${query.toString()}`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'receipts-attach') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/receipts/confirmed`, {
+                method: 'PUT',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    transactionRef: parsed.transactionRef,
+                    expectedRevision: parsed.expectedRevision ?? null,
+                    receipt: receiptConfirmation,
+                }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        if (parsed.command === 'receipts-remove') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/receipts/confirmed`, {
+                method: 'DELETE',
+                headers: { ...headers, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    transactionRef: parsed.transactionRef,
+                    expectedRevision: parsed.revision,
+                }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
         if (parsed.command === 'accounts-update') {
             const endpoint = `${baseUrl}/api/agent/v1/accounts/${encodeURIComponent(parsed.accountRef)}`;
             const response = await fetchImplementation(endpoint, {
@@ -1730,8 +1935,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 method: 'POST',
                 headers: { ...headers, 'Content-Type': 'application/json' },
                 body: JSON.stringify({
-                    fileBase64: contract.toString('base64'),
+                    filename: nodePath.basename(parsed.contract),
                     mimeType: 'application/pdf',
+                    contentBase64: contract.toString('base64'),
                 }),
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });

package/dist/contracts.js

@@ -35,7 +35,7 @@ export function validateNotificationRulePayload(value) {
     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');
+    rejectUnknownFields(delivery, new Set(['email']), 'delivery');
     if (typeof amountChange.enabled !== 'boolean')
         throw new UsageError('amountChange.enabled must be true or false');
     if (amountChange.comparison !== 'increase' && amountChange.comparison !== 'any') {
@@ -52,11 +52,11 @@ export function validateNotificationRulePayload(value) {
     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 (!Number.isSafeInteger(renewalReminder.leadDays) || Number(renewalReminder.leadDays) < 1 || Number(renewalReminder.leadDays) > 365) {
+        throw new UsageError('renewalReminder.leadDays must be an integer from 1 to 365');
     }
-    if (delivery.inApp !== true || typeof delivery.email !== 'boolean') {
-        throw new UsageError('delivery must include inApp: true and an email boolean');
+    if (typeof delivery.email !== 'boolean') {
+        throw new UsageError('delivery.email must be true or false');
     }
     if (!amountChange.enabled && !renewalReminder.enabled) {
         throw new UsageError('At least one notification rule must be enabled');
@@ -72,17 +72,25 @@ export function validateNotificationRulePayload(value) {
             renewalDate: renewalReminder.renewalDate,
             leadDays: Number(renewalReminder.leadDays),
         },
-        delivery: { inApp: true, email: delivery.email },
+        delivery: { email: delivery.email },
     };
 }
 function isNotificationRule(value) {
     if (!isObject(value))
         return false;
+    const renewalReminder = value.renewalReminder;
+    const delivery = value.delivery;
+    if (!isObject(renewalReminder) || !isObject(delivery))
+        return false;
     try {
         validateNotificationRulePayload({
             amountChange: value.amountChange,
-            renewalReminder: value.renewalReminder,
-            delivery: value.delivery,
+            renewalReminder: {
+                enabled: renewalReminder.enabled,
+                renewalDate: renewalReminder.renewalDate,
+                leadDays: renewalReminder.leadDays,
+            },
+            delivery: { email: delivery.email },
         });
     }
     catch {
@@ -97,8 +105,12 @@ function isNotificationRule(value) {
         && typeof value.merchantName === 'string'
         && typeof value.currency === 'string'
         && Number.isSafeInteger(value.sourceAmountPence)
-        && typeof value.createdAt === 'string'
-        && typeof value.updatedAt === 'string';
+        && hasOnlyFields(renewalReminder, ['enabled', 'renewalDate', 'leadDays', 'remindOn'])
+        && (renewalReminder.remindOn === null || isIsoDate(renewalReminder.remindOn))
+        && hasOnlyFields(delivery, ['inApp', 'email'])
+        && delivery.inApp === true
+        && (value.createdAt === null || isIsoDateTime(value.createdAt))
+        && (value.updatedAt === null || isIsoDateTime(value.updatedAt));
 }
 function isNotificationRuleResponse(value) {
     return isObject(value)
@@ -120,7 +132,7 @@ function isNotificationRuleDeleteResponse(value) {
 function isRenewalExtractionResponse(value) {
     return isObject(value)
         && hasOnlyFields(value, ['renewalDate', 'confidence'])
-        && isIsoDate(value.renewalDate)
+        && (value.renewalDate === null || isIsoDate(value.renewalDate))
         && (value.confidence === 'high' || value.confidence === 'medium' || value.confidence === 'low');
 }
 function validateSplit(value, index, splitIndex) {
@@ -289,6 +301,36 @@ export function validateBudgetUpdatePayload(value) {
     });
     return { allocations };
 }
+export function validateReceiptConfirmation(value) {
+    const receipt = requireObject(value, 'receipt');
+    rejectUnknownFields(receipt, new Set(['schemaVersion', 'currency', 'receiptItems']), 'receipt');
+    if (receipt.schemaVersion !== 1)
+        throw new UsageError('receipt.schemaVersion must be 1');
+    if (typeof receipt.currency !== 'string' || !/^[A-Z]{3}$/.test(receipt.currency)) {
+        throw new UsageError('receipt.currency must be a three-letter uppercase code');
+    }
+    if (!Array.isArray(receipt.receiptItems) || receipt.receiptItems.length < 1 || receipt.receiptItems.length > 200) {
+        throw new UsageError('receipt.receiptItems must contain between 1 and 200 items');
+    }
+    const receiptItems = receipt.receiptItems.map((value, index) => {
+        const label = `receipt.receiptItems[${index}]`;
+        const item = requireObject(value, label);
+        rejectUnknownFields(item, new Set(['id', 'label', 'amountPence']), label);
+        const id = requireString(item.id, `${label}.id`);
+        const itemLabel = requireString(item.label, `${label}.label`);
+        if (id.length > 80 || itemLabel.length > 160)
+            throw new UsageError(`${label} is too long`);
+        if (!Number.isSafeInteger(item.amountPence)) {
+            throw new UsageError(`${label}.amountPence must be a signed safe integer`);
+        }
+        return {
+            id,
+            label: itemLabel,
+            amountPence: Number(item.amountPence),
+        };
+    });
+    return { schemaVersion: 1, currency: receipt.currency, receiptItems };
+}
 function isLineItemMap(value) {
     if (!isObject(value))
         return false;
@@ -819,6 +861,55 @@ function isGoalDeleteResponse(value) {
         && typeof value.deletedGoalId === 'string'
         && value.deletedGoalId.trim().length > 0);
 }
+function isReceiptConfirmation(value) {
+    try {
+        validateReceiptConfirmation(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isReceiptEvidence(value) {
+    if (!isObject(value))
+        return false;
+    const { revision, receiptTotalPence, confirmedAt, sourceSurface, ...confirmation } = value;
+    return (hasOnlyFields(value, [
+        'schemaVersion',
+        'currency',
+        'receiptItems',
+        'revision',
+        'receiptTotalPence',
+        'confirmedAt',
+        'sourceSurface',
+    ])
+        && isReceiptConfirmation(confirmation)
+        && Number.isSafeInteger(revision)
+        && Number(revision) > 0
+        && Number.isSafeInteger(receiptTotalPence)
+        && isIsoDateTime(confirmedAt)
+        && (sourceSurface === 'web' || sourceSurface === 'agent_api'));
+}
+function isReceiptExtractResponse(value) {
+    if (!isObject(value) || !hasOnlyFields(value, ['draft']) || !isObject(value.draft))
+        return false;
+    const { warnings, ...confirmation } = value.draft;
+    return (isReceiptConfirmation(confirmation)
+        && Array.isArray(warnings)
+        && warnings.length <= 20
+        && warnings.every((warning) => (warning === 'currency_unclear' || warning === 'total_unclear' || warning === 'item_unclear')));
+}
+function isReceiptLookupResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['receipt'])
+        && (value.receipt === null || isReceiptEvidence(value.receipt));
+}
+function isReceiptMutationResponse(value) {
+    return isObject(value) && hasOnlyFields(value, ['receipt']) && isReceiptEvidence(value.receipt);
+}
+function isReceiptDeleteResponse(value) {
+    return isObject(value) && hasOnlyFields(value, ['deleted']) && value.deleted === true;
+}
 export function parseApiResponse(command, value) {
     const valid = command === 'accounts'
         ? isAccountsResponse(value)
@@ -850,15 +941,23 @@ export function parseApiResponse(command, value) {
                                                             ? 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);
+                                                                : command === 'receipts-extract'
+                                                                    ? isReceiptExtractResponse(value)
+                                                                    : command === 'receipts-get'
+                                                                        ? isReceiptLookupResponse(value)
+                                                                        : command === 'receipts-attach'
+                                                                            ? isReceiptMutationResponse(value)
+                                                                            : command === 'receipts-remove'
+                                                                                ? isReceiptDeleteResponse(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.15.0",
+  "version": "0.16.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {