@slothmoney/agent-cli 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.17.0 - 2026-08-25
+
+- Run applied transaction-assignment batches through resumable server
+  operations while keeping the existing `assign --input ... --apply` command
+  and terminal `succeeded`/`failed` JSON output unchanged.
+- Retry transient submission and status requests with a deterministic
+  request key, so re-running an interrupted command resumes the same operation.
+- Strictly validate operation progress, expiry, counts, and ordered terminal
+  item receipts before printing an assignment result.
+
+## 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.17.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
@@ -256,6 +302,10 @@ assignment, set `"assignmentScope": "joint"` in the assignment payload and use
 
 These are placeholders. Do not submit the example values.
 
+Each `transactionRef` may appear only once in an assignment file. Split one
+transaction across categories with `categorySplits` instead of adding the same
+transaction twice.
+
 4. Preview the assignment without writing:
 
 ```bash
@@ -275,7 +325,17 @@ sloth-agent assign --input assignments.json --apply
 
 This step requires a token created with **Allow changes**.
 
-Inspect every item in the returned `succeeded` and `failed` arrays.
+The CLI submits a durable server operation and polls its authenticated status
+until every item has finished. It then prints the same `succeeded` and `failed`
+arrays as before, so existing agent workflows do not need to change. Inspect
+every item in both arrays.
+
+If the command is interrupted or a request times out, re-run the same command
+with the same assignment input. The CLI derives the same request key
+from the validated assignments, so the server resumes the existing operation
+instead of applying the batch again. The server retains operation status and
+item receipts for seven days. Changing the assignments creates a different
+operation.
 
 6. Check the result in the same assignment scope that you changed. Successful
    assignments update the category and optional budget line item on the
@@ -719,8 +779,10 @@ Command results are JSON on stdout. Diagnostics are written to stderr.
 | `2` | Invalid command, option, URL, date, auth input, goal input, or assignment input |
 | `3` | No credential or native secure storage is unavailable |
 
-Assignment writes are best-effort. A response containing any failed assignment
-returns exit code `1` while preserving the complete API response on stdout.
+Assignment writes run as durable, best-effort operations. The CLI waits for the
+terminal result and returns exit code `1` when any item failed, while preserving
+the complete `succeeded` and `failed` arrays on stdout. Re-running an interrupted
+command with the same input resumes the same server operation.
 
 ## Development
 

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,14 @@
+import { createHash } from 'node:crypto';
 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, parseAssignmentOperationResponse, toLegacyAssignmentResponse, 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.17.0';
 const REQUEST_TIMEOUT_MS = 60_000;
+const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
     '',
     'API origin:',
@@ -14,6 +17,8 @@ const API_ORIGIN_HELP_LINES = [
     '  Use an origin-only URL with no credentials, path, query, or fragment.',
     '  HTTPS is required except for localhost development.',
 ];
+const ASSIGNMENT_REQUEST_ATTEMPTS = 3;
+const ASSIGNMENT_RETRY_DELAY_MS = 500;
 export function usageText() {
     return [
         'Sloth Agent CLI',
@@ -50,6 +55,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]',
@@ -648,13 +657,19 @@ export function assignHelpText() {
         '  the payload it would send. It does not contact Sloth Money, verify the',
         '  transactionRef or category values, or write anything.',
         '  A successful preview does not guarantee that applying it will succeed.',
-        '  With --apply, assignments are best-effort; any failed item makes the command',
-        '  exit with code 1 while the complete result remains available on stdout.',
+        '  With --apply, the CLI submits one durable server operation, then polls authenticated status',
+        '  until every item finishes. Transient submission and status failures are retried.',
+        '  Re-run the same command with the same assignment input after an interruption;',
+        '  the CLI resumes the same operation instead of duplicating its work.',
+        '  Operation status and item receipts remain available on the server for seven days.',
+        '  Assignments are best-effort; any failed item makes the command exit with code 1',
+        '  while the complete terminal result remains available on stdout.',
         '  Applying requires a write-enabled token created with Allow changes.',
         '',
         'Input:',
         '  The top-level object must contain an assignments array.',
         '  Each assignment requires transactionRef and at least one category operation or sharing object.',
+        '  Each transactionRef may appear only once in the assignments array.',
         '  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.',
@@ -696,7 +711,7 @@ export function assignHelpText() {
         '',
         'Output:',
         '  Preview mode returns dryRun, endpoint, and the validated payload.',
-        '  Apply mode returns succeeded and failed assignment arrays.',
+        '  Apply mode waits for the durable operation and returns succeeded and failed arrays.',
         '  Successful assignments update the original transaction. See the result in',
         '  Sloth Money → Transactions or read the transaction again through the CLI.',
         '  Assignments do not create a separate list.',
@@ -980,6 +995,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 +1067,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 +1085,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 +1149,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 +1189,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 +1318,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) {
@@ -1282,6 +1416,99 @@ function requestHeaders(token) {
         'User-Agent': `sloth-agent/${CLI_VERSION}`,
     };
 }
+function assignmentIdempotencyKey(payload) {
+    return createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+function isRetryableAssignmentRequestError(error) {
+    if (error instanceof ApiError) {
+        return error.status !== undefined
+            && [408, 425, 429, 499, 500, 502, 503, 504].includes(error.status);
+    }
+    return error instanceof TypeError
+        || (error instanceof Error && error.name === 'AbortError');
+}
+async function withAssignmentRequestRecovery(request, sleep) {
+    let lastError;
+    for (let attempt = 1; attempt <= ASSIGNMENT_REQUEST_ATTEMPTS; attempt += 1) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isRetryableAssignmentRequestError(error) || attempt === ASSIGNMENT_REQUEST_ATTEMPTS) {
+                throw error;
+            }
+            await sleep(ASSIGNMENT_RETRY_DELAY_MS * attempt);
+        }
+    }
+    throw lastError;
+}
+async function parseAssignmentOperationHttpResponse(response, token, expectedStatus) {
+    const data = await parseHttpResponse(response, token);
+    if (response.status !== expectedStatus) {
+        throw new ApiError(`Agent API returned status ${response.status}; expected ${expectedStatus}`, response.status);
+    }
+    return parseAssignmentOperationResponse(data);
+}
+function assertAssignmentOperationMatchesPayload(operation, payload, expectedOperationId) {
+    if (operation.itemCount !== payload.assignments.length
+        || (expectedOperationId !== undefined && operation.operationId !== expectedOperationId)
+        || (operation.status === 'completed'
+            && operation.results?.some((result, index) => (result.transactionRef !== payload.assignments[index]?.transactionRef)))) {
+        throw new ApiError('Assignment operation response did not match the submitted assignment order');
+    }
+}
+async function applyAssignments(fetchImplementation, sleep, baseUrl, token, payload) {
+    const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
+    const idempotencyKey = assignmentIdempotencyKey(payload);
+    let operation;
+    try {
+        operation = await withAssignmentRequestRecovery(async () => {
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: {
+                    ...requestHeaders(token),
+                    'Content-Type': 'application/json',
+                    'Idempotency-Key': idempotencyKey,
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            return parseAssignmentOperationHttpResponse(response, token, 202);
+        }, sleep);
+    }
+    catch (error) {
+        if (!isRetryableAssignmentRequestError(error))
+            throw error;
+        throw new ApiError('Assignment submission could not be confirmed. '
+            + 'Re-run the same command with the same assignment input to resume it.');
+    }
+    assertAssignmentOperationMatchesPayload(operation, payload);
+    const operationId = operation.operationId;
+    while (operation.status !== 'completed') {
+        await sleep(operation.pollAfterMs);
+        const statusEndpoint = `${endpoint}/${encodeURIComponent(operationId)}`;
+        try {
+            const nextOperation = await withAssignmentRequestRecovery(async () => {
+                const response = await fetchImplementation(statusEndpoint, {
+                    method: 'GET',
+                    headers: requestHeaders(token),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                return parseAssignmentOperationHttpResponse(response, token, 200);
+            }, sleep);
+            assertAssignmentOperationMatchesPayload(nextOperation, payload, operationId);
+            operation = nextOperation;
+        }
+        catch (error) {
+            if (!isRetryableAssignmentRequestError(error))
+                throw error;
+            throw new ApiError('Assignment status could not be recovered. '
+                + 'Re-run the same command with the same assignment input to resume it.');
+        }
+    }
+    return toLegacyAssignmentResponse(operation);
+}
 async function validateCredentialRemotely(fetchImplementation, origin, token) {
     const response = await fetchImplementation(`${origin}/api/agent/v1/categories`, {
         method: 'GET',
@@ -1317,6 +1544,9 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
     const readSecret = options.readSecret ?? defaultReadSecret;
     const readStdin = options.readStdin ?? defaultReadStdin;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    }));
     const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value));
     const writeStderr = options.writeStderr ?? ((value) => process.stderr.write(value));
     let token;
@@ -1457,6 +1687,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 +1755,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, {
@@ -1679,17 +1989,7 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
         }
         if (parsed.command === 'assign') {
             const payload = assignmentPayload;
-            const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
-            const response = await fetchImplementation(endpoint, {
-                method: 'POST',
-                headers: {
-                    ...headers,
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(payload),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-            const data = parseApiResponse('assign', await parseHttpResponse(response, token));
+            const data = await applyAssignments(fetchImplementation, sleep, baseUrl, token, payload);
             writeJson(writeStdout, data);
             return hasFailures(data) ? 1 : 0;
         }
@@ -1730,8 +2030,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) {
@@ -257,7 +269,15 @@ export function validateAssignmentPayload(value) {
     if (payload.assignments.length < 1 || payload.assignments.length > 100) {
         throw new UsageError('assignments must contain between 1 and 100 items');
     }
-    return { assignments: payload.assignments.map(validateAssignment) };
+    const assignments = payload.assignments.map(validateAssignment);
+    const transactionRefs = new Set();
+    for (const assignment of assignments) {
+        if (transactionRefs.has(assignment.transactionRef)) {
+            throw new UsageError('Each assignments[].transactionRef must be unique');
+        }
+        transactionRefs.add(assignment.transactionRef);
+    }
+    return { assignments };
 }
 export function validateBudgetUpdatePayload(value) {
     const payload = requireObject(value, 'budget update payload');
@@ -289,6 +309,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;
@@ -463,6 +513,73 @@ function isAssignmentResponse(value) {
             && typeof item.error === 'string'
             && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
 }
+function isAssignmentOperationResult(value) {
+    if (!isObject(value) || typeof value.transactionRef !== 'string')
+        return false;
+    const { status, ...legacyResult } = value;
+    if (status === 'succeeded') {
+        return isAssignmentResponse({ succeeded: [legacyResult], failed: [] });
+    }
+    if (status === 'failed') {
+        return isAssignmentResponse({ succeeded: [], failed: [legacyResult] });
+    }
+    return false;
+}
+export function parseAssignmentOperationResponse(value) {
+    const validBase = isObject(value)
+        && hasOnlyFields(value, [
+            'operationId', 'status', 'itemCount', 'completedCount', 'failedCount',
+            'expiresAt', 'pollAfterMs', 'results',
+        ])
+        && typeof value.operationId === 'string'
+        && /^[a-f0-9]{64}$/.test(value.operationId)
+        && (value.status === 'pending'
+            || value.status === 'processing'
+            || value.status === 'completed')
+        && Number.isSafeInteger(value.itemCount)
+        && Number(value.itemCount) >= 1
+        && Number(value.itemCount) <= 100
+        && isNonnegativeSafeInteger(value.completedCount)
+        && Number(value.completedCount) <= Number(value.itemCount)
+        && isNonnegativeSafeInteger(value.failedCount)
+        && Number(value.failedCount) <= Number(value.completedCount)
+        && isIsoDateTime(value.expiresAt)
+        && isNonnegativeSafeInteger(value.pollAfterMs)
+        && Number(value.pollAfterMs) >= 100
+        && Number(value.pollAfterMs) <= 10_000;
+    if (!validBase) {
+        throw new ApiError('Invalid assignment operation response from the Agent API');
+    }
+    const isComplete = value.status === 'completed';
+    const resultsAreValid = isComplete
+        ? (Number(value.completedCount) === Number(value.itemCount)
+            && Array.isArray(value.results)
+            && value.results.length === Number(value.itemCount)
+            && value.results.every(isAssignmentOperationResult)
+            && value.results.filter((result) => result.status === 'failed').length
+                === Number(value.failedCount))
+        : value.results === undefined;
+    if (!resultsAreValid) {
+        throw new ApiError('Invalid assignment operation response from the Agent API');
+    }
+    return value;
+}
+export function toLegacyAssignmentResponse(value) {
+    const operation = parseAssignmentOperationResponse(value);
+    if (operation.status !== 'completed' || !operation.results) {
+        throw new ApiError('Assignment operation is not complete');
+    }
+    const succeeded = [];
+    const failed = [];
+    for (const result of operation.results) {
+        const { status, ...legacyResult } = result;
+        if (status === 'succeeded')
+            succeeded.push(legacyResult);
+        else
+            failed.push(legacyResult);
+    }
+    return { succeeded, failed };
+}
 function isHttpUrl(value) {
     if (typeof value !== 'string')
         return false;
@@ -819,6 +936,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 +1016,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.17.0",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {