@slothmoney/agent-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-07-18
+
+- Publish the first installable Sloth Agent CLI.
+- Read categories and filtered transactions from the Agent API.
+- Preview or apply transaction assignments.
+- Create partner clarification links.
+- Validate commands, payloads, API responses, and production URL safety.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rath Bala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Sloth Agent CLI
+
+Use your own agent to read and categorise transactions through the
+[Sloth Money Agent API](https://slothmoney.app/developers/).
+
+## Install
+
+The CLI requires Node.js 22 or newer.
+
+```bash
+npm install --global @slothmoney/agent-cli
+sloth-agent --version
+```
+
+For a one-off pinned run:
+
+```bash
+npm exec --yes --package=@slothmoney/agent-cli@0.1.0 -- sloth-agent --help
+```
+
+## Authenticate
+
+Create a personal access token in Sloth Money under
+**Settings > Developer access**. Load it from your environment or secret
+manager:
+
+```bash
+export SLOTH_AGENT_TOKEN="sloth_pat_v1_..."
+```
+
+Do not paste the token into prompts, chat, source control, shared logs, or
+assignment files. The CLI reads the token from the environment, sends it only
+as an HTTPS bearer token, and never stores it.
+
+## Commands
+
+Read categories and available budget line items:
+
+```bash
+sloth-agent categories
+```
+
+Read uncategorised transactions:
+
+```bash
+sloth-agent transactions --uncategorized --limit 50
+```
+
+Search a date range:
+
+```bash
+sloth-agent transactions \
+  --q "tesco" \
+  --start-date 2026-05-01 \
+  --end-date 2026-05-31
+```
+
+Preview an assignment file without writing:
+
+```bash
+sloth-agent assign --input assignments.json
+```
+
+Apply the same file:
+
+```bash
+sloth-agent assign --input assignments.json --apply
+```
+
+Create a partner clarification link:
+
+```bash
+sloth-agent ask-partner --transaction-ref sloth_txn_...
+```
+
+Assignment files use the Agent API request shape:
+
+```json
+{
+  "assignments": [
+    {
+      "transactionRef": "sloth_txn_...",
+      "categoryId": "groceries",
+      "lineItemId": "weekly"
+    }
+  ]
+}
+```
+
+## Configuration and output
+
+The CLI defaults to `https://budget.slothmoney.app`. For local development,
+set `SLOTH_AGENT_API_BASE_URL=http://localhost:4000` or pass
+`--base-url http://localhost:4000`. Non-local HTTP origins are rejected so a
+token cannot be sent over an unencrypted connection.
+
+Command results are JSON on stdout. Diagnostics are written to stderr.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | API, network, response-validation, or partial assignment failure |
+| `2` | Invalid command, option, URL, date, or assignment input |
+| `3` | Missing required configuration |
+
+Assignment writes are best-effort. A response containing any failed assignment
+returns exit code `1` while preserving the complete API response on stdout.
+
+## Development
+
+```bash
+npm ci
+npm run verify
+```
+
+`npm run test:package` packs the exact npm artifact, installs it into a clean
+temporary project, and runs the installed binary.

package/dist/args.js

@@ -0,0 +1,212 @@
+import { UsageError } from './errors.js';
+const PRODUCTION_BASE_URL = 'https://budget.slothmoney.app';
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+function readOptionValue(args, index, name) {
+    const value = args[index + 1];
+    if (value === undefined || value.length === 0 || value.startsWith('--')) {
+        throw new UsageError(`${name} requires a value`);
+    }
+    return value;
+}
+function setOnce(current, value, name) {
+    if (current !== undefined) {
+        throw new UsageError(`${name} may only be provided once`);
+    }
+    return value;
+}
+function parseGlobalOptions(argv) {
+    const args = [...argv];
+    let baseUrl;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--base-url') {
+            baseUrl = setOnce(baseUrl, readOptionValue(args, index, '--base-url'), '--base-url');
+            args.splice(index, 2);
+            index -= 1;
+            continue;
+        }
+        if (argument?.startsWith('--base-url=')) {
+            const value = argument.slice('--base-url='.length);
+            if (!value)
+                throw new UsageError('--base-url requires a value');
+            baseUrl = setOnce(baseUrl, value, '--base-url');
+            args.splice(index, 1);
+            index -= 1;
+        }
+    }
+    return baseUrl === undefined ? { args } : { args, baseUrl };
+}
+function isValidDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.valueOf()) && parsed.toISOString().slice(0, 10) === value;
+}
+function requireNonEmpty(value, name) {
+    if (!value.trim())
+        throw new UsageError(`${name} requires a value`);
+    return value;
+}
+function parseTransactions(args) {
+    const filters = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--uncategorized') {
+            filters.uncategorized = setOnce(filters.uncategorized, true, '--uncategorized');
+            continue;
+        }
+        if (argument.startsWith('--uncategorized=')) {
+            const value = argument.slice('--uncategorized='.length);
+            if (value !== 'true' && value !== 'false') {
+                throw new UsageError('--uncategorized must be true or false');
+            }
+            filters.uncategorized = setOnce(filters.uncategorized, value === 'true', '--uncategorized');
+            continue;
+        }
+        const [name, inlineValue] = argument.includes('=')
+            ? argument.split(/=(.*)/s, 2)
+            : [argument, undefined];
+        const supported = new Set([
+            '--limit',
+            '--start-date',
+            '--end-date',
+            '--q',
+            '--account-id',
+            '--category-id',
+            '--cursor',
+        ]);
+        if (!name || !supported.has(name)) {
+            throw new UsageError(`Unknown transactions option: ${argument}`);
+        }
+        const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, name), name);
+        if (inlineValue === undefined)
+            index += 1;
+        if (name === '--limit') {
+            const limit = Number(value);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+                throw new UsageError('--limit must be an integer between 1 and 200');
+            }
+            filters.limit = setOnce(filters.limit, limit, name);
+        }
+        else if (name === '--start-date' || name === '--end-date') {
+            if (!isValidDate(value)) {
+                throw new UsageError(`${name} must be a valid YYYY-MM-DD date`);
+            }
+            if (name === '--start-date') {
+                filters.startDate = setOnce(filters.startDate, value, name);
+            }
+            else {
+                filters.endDate = setOnce(filters.endDate, value, name);
+            }
+        }
+        else if (name === '--q') {
+            filters.q = setOnce(filters.q, 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);
+        }
+        else if (name === '--cursor') {
+            filters.cursor = setOnce(filters.cursor, value, name);
+        }
+    }
+    if (filters.startDate !== undefined
+        && filters.endDate !== undefined
+        && filters.endDate < filters.startDate) {
+        throw new UsageError('--end-date must not be before --start-date');
+    }
+    return filters;
+}
+function withBaseUrl(value, baseUrl) {
+    return baseUrl === undefined ? value : { ...value, baseUrl };
+}
+export function parseArgs(argv) {
+    if (argv.includes('--help') || argv.includes('-h'))
+        return { command: 'help' };
+    if (argv.includes('--version') || argv.includes('-V'))
+        return { command: 'version' };
+    const { args, baseUrl } = parseGlobalOptions(argv);
+    const command = args.shift();
+    if (!command)
+        return { command: 'help' };
+    if (command === 'categories') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown categories option: ${args[0]}`);
+        }
+        return withBaseUrl({ command }, baseUrl);
+    }
+    if (command === 'transactions') {
+        return withBaseUrl({ command, filters: parseTransactions(args) }, baseUrl);
+    }
+    if (command === 'assign') {
+        let input;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+            }
+            else if (argument === '--input') {
+                input = setOnce(input, readOptionValue(args, index, '--input'), '--input');
+                index += 1;
+            }
+            else if (argument.startsWith('--input=')) {
+                input = setOnce(input, requireNonEmpty(argument.slice('--input='.length), '--input'), '--input');
+            }
+            else {
+                throw new UsageError(`Unknown assign option: ${argument}`);
+            }
+        }
+        if (!input)
+            throw new UsageError('assign requires --input <file>');
+        return withBaseUrl({ command, input, apply }, baseUrl);
+    }
+    if (command === 'ask-partner') {
+        let transactionRef;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--transaction-ref') {
+                transactionRef = setOnce(transactionRef, readOptionValue(args, index, '--transaction-ref'), '--transaction-ref');
+                index += 1;
+            }
+            else if (argument.startsWith('--transaction-ref=')) {
+                transactionRef = setOnce(transactionRef, requireNonEmpty(argument.slice('--transaction-ref='.length), '--transaction-ref'), '--transaction-ref');
+            }
+            else {
+                throw new UsageError(`Unknown ask-partner option: ${argument}`);
+            }
+        }
+        if (!transactionRef) {
+            throw new UsageError('ask-partner requires --transaction-ref <ref>');
+        }
+        return withBaseUrl({ command, transactionRef }, baseUrl);
+    }
+    throw new UsageError(`Unknown command: ${command}`);
+}
+export function resolveBaseUrl(environment, override) {
+    const rawValue = override || environment.SLOTH_AGENT_API_BASE_URL || PRODUCTION_BASE_URL;
+    let url;
+    try {
+        url = new URL(rawValue);
+    }
+    catch {
+        throw new UsageError('--base-url must be a valid URL');
+    }
+    if (url.username || url.password) {
+        throw new UsageError('--base-url must not include credentials');
+    }
+    if (url.pathname !== '/' || url.search || url.hash) {
+        throw new UsageError('--base-url must be an origin only');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))) {
+        throw new UsageError('--base-url must use HTTPS unless it targets localhost');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new UsageError('--base-url must use HTTPS unless it targets localhost');
+    }
+    return url.origin;
+}

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+process.exitCode = await runCli();

package/dist/cli.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import { parseArgs, resolveBaseUrl, } from './args.js';
+import { parseApiResponse, validateAssignmentPayload, } from './contracts.js';
+import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
+export const CLI_VERSION = '0.1.0';
+const REQUEST_TIMEOUT_MS = 30_000;
+export function usageText() {
+    return [
+        'Sloth Agent CLI',
+        '',
+        'Usage:',
+        '  sloth-agent categories [--base-url URL]',
+        '  sloth-agent transactions [--uncategorized[=true|false]] [--limit N]',
+        '    [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--q TEXT]',
+        '    [--account-id ID] [--category-id ID] [--cursor CURSOR] [--base-url URL]',
+        '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
+        '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
+        '  sloth-agent --help',
+        '  sloth-agent --version',
+        '',
+        'Environment:',
+        '  SLOTH_AGENT_TOKEN         Personal access token from Settings > Developer access',
+        '  SLOTH_AGENT_API_BASE_URL  Optional API origin; defaults to https://budget.slothmoney.app',
+    ].join('\n');
+}
+function writeJson(write, data) {
+    write(`${JSON.stringify(data, null, 2)}\n`);
+}
+function requireToken(environment) {
+    const token = environment.SLOTH_AGENT_TOKEN;
+    if (!token?.trim())
+        throw new ConfigError('SLOTH_AGENT_TOKEN is required');
+    return token;
+}
+function redact(value, token) {
+    return token ? value.split(token).join('[REDACTED]') : value;
+}
+function readAssignmentFile(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 assignment JSON: ${message}`);
+    }
+}
+function buildTransactionsQuery(filters) {
+    const params = new URLSearchParams();
+    if (filters.uncategorized !== undefined) {
+        params.set('uncategorized', String(filters.uncategorized));
+    }
+    if (filters.limit !== undefined)
+        params.set('limit', String(filters.limit));
+    if (filters.startDate !== undefined)
+        params.set('startDate', filters.startDate);
+    if (filters.endDate !== undefined)
+        params.set('endDate', filters.endDate);
+    if (filters.q !== undefined)
+        params.set('q', filters.q);
+    if (filters.accountId !== undefined)
+        params.set('accountId', filters.accountId);
+    if (filters.categoryId !== undefined)
+        params.set('categoryId', filters.categoryId);
+    if (filters.cursor !== undefined)
+        params.set('cursor', filters.cursor);
+    return params.toString();
+}
+async function parseHttpResponse(response, token) {
+    const text = await response.text();
+    let data = null;
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            if (response.ok)
+                throw new ApiError('Agent API returned invalid JSON');
+        }
+    }
+    if (!response.ok) {
+        const message = (data
+            && typeof data === 'object'
+            && 'error' in data
+            && typeof data.error === 'string')
+            ? data.error
+            : `Agent API request failed with status ${response.status}`;
+        throw new ApiError(redact(message, token));
+    }
+    return data;
+}
+function hasFailures(value) {
+    if (!value || typeof value !== 'object' || !('failed' in value))
+        return false;
+    return Array.isArray(value.failed) && value.failed.length > 0;
+}
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+    const environment = options.env ?? process.env;
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value));
+    const writeStderr = options.writeStderr ?? ((value) => process.stderr.write(value));
+    let token;
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.command === 'help') {
+            writeStdout(`${usageText()}\n`);
+            return 0;
+        }
+        if (parsed.command === 'version') {
+            writeStdout(`${CLI_VERSION}\n`);
+            return 0;
+        }
+        token = requireToken(environment);
+        const baseUrl = resolveBaseUrl(environment, parsed.baseUrl);
+        const headers = {
+            Accept: 'application/json',
+            Authorization: `Bearer ${token}`,
+            'User-Agent': `sloth-agent/${CLI_VERSION}`,
+        };
+        if (parsed.command === 'assign') {
+            const payload = validateAssignmentPayload(readAssignmentFile(parsed.input));
+            const endpoint = `${baseUrl}/api/agent/v1/transaction-assignments`;
+            if (!parsed.apply) {
+                writeJson(writeStdout, { dryRun: true, endpoint, payload });
+                return 0;
+            }
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: {
+                    ...headers,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('assign', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return hasFailures(data) ? 1 : 0;
+        }
+        if (parsed.command === 'ask-partner') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/transaction-explanation-requests`, {
+                method: 'POST',
+                headers: {
+                    ...headers,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ transactionRef: parsed.transactionRef }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = parseApiResponse('ask-partner', await parseHttpResponse(response, token));
+            writeJson(writeStdout, data);
+            return 0;
+        }
+        const path = parsed.command === 'categories'
+            ? '/api/agent/v1/categories'
+            : `/api/agent/v1/transactions${(() => {
+                const query = buildTransactionsQuery(parsed.filters);
+                return query ? `?${query}` : '';
+            })()}`;
+        const response = await fetchImplementation(`${baseUrl}${path}`, {
+            method: 'GET',
+            headers,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+        writeJson(writeStdout, data);
+        return 0;
+    }
+    catch (error) {
+        const exitCode = error instanceof CliError ? error.exitCode : 1;
+        const message = error instanceof Error ? error.message : String(error);
+        writeStderr(`${redact(message, token)}\n`);
+        return exitCode;
+    }
+}

package/dist/contracts.js

@@ -0,0 +1,191 @@
+import { ApiError, UsageError, } from './errors.js';
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function requireObject(value, label) {
+    if (!isObject(value))
+        throw new UsageError(`${label} must be an object`);
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new UsageError(`${label} is required`);
+    }
+    return value;
+}
+function rejectUnknownFields(value, allowed, label) {
+    const unknown = Object.keys(value).find((key) => !allowed.has(key));
+    if (unknown)
+        throw new UsageError(`${label} contains unknown field: ${unknown}`);
+}
+function validateSplit(value, index, splitIndex) {
+    const label = `assignments[${index}].categorySplits[${splitIndex}]`;
+    const split = requireObject(value, label);
+    rejectUnknownFields(split, new Set(['categoryId', 'amountPence', 'lineItemId']), label);
+    const categoryId = requireString(split.categoryId, `${label}.categoryId`);
+    if (!Number.isInteger(split.amountPence) || Number(split.amountPence) <= 0) {
+        throw new UsageError(`${label}.amountPence must be a positive integer`);
+    }
+    if (split.lineItemId !== undefined) {
+        requireString(split.lineItemId, `${label}.lineItemId`);
+    }
+    return typeof split.lineItemId === 'string'
+        ? { categoryId, amountPence: Number(split.amountPence), lineItemId: split.lineItemId }
+        : { categoryId, amountPence: Number(split.amountPence) };
+}
+function validateAssignment(value, index) {
+    const label = `assignments[${index}]`;
+    const assignment = requireObject(value, label);
+    rejectUnknownFields(assignment, new Set([
+        'transactionRef',
+        'categoryId',
+        'lineItemId',
+        'categorySplits',
+        'incomeSubtype',
+    ]), label);
+    requireString(assignment.transactionRef, `${label}.transactionRef`);
+    if (assignment.categoryId !== undefined && assignment.categoryId !== null) {
+        requireString(assignment.categoryId, `${label}.categoryId`);
+    }
+    if (assignment.lineItemId !== undefined && assignment.lineItemId !== null) {
+        requireString(assignment.lineItemId, `${label}.lineItemId`);
+    }
+    if (assignment.incomeSubtype !== undefined
+        && assignment.incomeSubtype !== null
+        && assignment.incomeSubtype !== 'pay'
+        && assignment.incomeSubtype !== 'interest') {
+        throw new UsageError(`${label}.incomeSubtype must be pay, interest, or null`);
+    }
+    let categorySplits;
+    if (assignment.categorySplits === null) {
+        categorySplits = null;
+    }
+    else if (assignment.categorySplits !== undefined) {
+        if (!Array.isArray(assignment.categorySplits) || assignment.categorySplits.length === 0) {
+            throw new UsageError(`${label}.categorySplits must be a non-empty array or null`);
+        }
+        categorySplits = assignment.categorySplits.map((split, splitIndex) => (validateSplit(split, index, splitIndex)));
+    }
+    const hasCategory = typeof assignment.categoryId === 'string' && assignment.categoryId.trim().length > 0;
+    const isClear = assignment.categoryId === null && (!categorySplits || categorySplits.length === 0);
+    const hasSplits = Array.isArray(categorySplits) && categorySplits.length > 0;
+    if (!hasCategory && !isClear && !hasSplits) {
+        throw new UsageError(`${label}.categoryId or categorySplits is required`);
+    }
+    return {
+        transactionRef: assignment.transactionRef,
+        ...(assignment.categoryId !== undefined ? { categoryId: assignment.categoryId } : {}),
+        ...(assignment.lineItemId !== undefined ? { lineItemId: assignment.lineItemId } : {}),
+        ...(categorySplits !== undefined ? { categorySplits } : {}),
+        ...(assignment.incomeSubtype !== undefined
+            ? { incomeSubtype: assignment.incomeSubtype }
+            : {}),
+    };
+}
+export function validateAssignmentPayload(value) {
+    const payload = requireObject(value, 'assignment payload');
+    rejectUnknownFields(payload, new Set(['assignments']), 'assignment payload');
+    if (!Array.isArray(payload.assignments)) {
+        throw new UsageError('assignments array is required');
+    }
+    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) };
+}
+function isLineItemMap(value) {
+    if (!isObject(value))
+        return false;
+    return Object.values(value).every((items) => (Array.isArray(items)
+        && items.every((item) => (isObject(item)
+            && typeof item.id === 'string'
+            && item.id.length > 0
+            && typeof item.name === 'string'
+            && item.name.length > 0))));
+}
+function isCategoryResponse(value) {
+    return (isObject(value)
+        && Array.isArray(value.categories)
+        && value.categories.every((category) => (isObject(category)
+            && typeof category.id === 'string'
+            && typeof category.name === 'string'
+            && (category.source === 'default' || category.source === 'user')))
+        && isLineItemMap(value.personalLineItemsByCategoryId)
+        && isLineItemMap(value.jointLineItemsByCategoryId));
+}
+function isTransaction(value) {
+    return (isObject(value)
+        && typeof value.transactionRef === 'string'
+        && typeof value.id === 'string'
+        && typeof value.name === 'string'
+        && typeof value.amount === 'number'
+        && Number.isFinite(value.amount)
+        && typeof value.currency === 'string'
+        && typeof value.date === 'string'
+        && value.status === 'booked'
+        && 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')
+        && Array.isArray(value.categorySplits)
+        && (value.incomeSubtype === null
+            || value.incomeSubtype === 'pay'
+            || value.incomeSubtype === 'interest'));
+}
+function isTransactionsResponse(value) {
+    return (isObject(value)
+        && Array.isArray(value.transactions)
+        && value.transactions.every(isTransaction)
+        && (value.nextCursor === null || typeof value.nextCursor === 'string'));
+}
+function isAssignmentResponse(value) {
+    return (isObject(value)
+        && Array.isArray(value.succeeded)
+        && value.succeeded.every((item) => isObject(item) && typeof item.transactionRef === 'string')
+        && Array.isArray(value.failed)
+        && value.failed.every((item) => (isObject(item)
+            && typeof item.error === 'string'
+            && (item.transactionRef === undefined || typeof item.transactionRef === 'string'))));
+}
+function isHttpUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === 'https:' || parsed.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+function isIsoDateTime(value) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = new Date(value);
+    return (!Number.isNaN(parsed.valueOf())
+        && parsed.toISOString() === value);
+}
+function isPartnerResponse(value) {
+    return (isObject(value)
+        && typeof value.requestId === 'string'
+        && isHttpUrl(value.publicUrl)
+        && typeof value.message === 'string'
+        && isIsoDateTime(value.expiresAt)
+        && value.status === 'open');
+}
+export function parseApiResponse(command, value) {
+    const valid = command === 'categories'
+        ? isCategoryResponse(value)
+        : command === 'transactions'
+            ? isTransactionsResponse(value)
+            : command === 'assign'
+                ? isAssignmentResponse(value)
+                : isPartnerResponse(value);
+    if (!valid) {
+        const label = command === 'assign' ? 'assignment' : command;
+        throw new ApiError(`Invalid ${label} response from the Agent API`);
+    }
+    return value;
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, 2);
+    }
+}
+export class ConfigError extends CliError {
+    constructor(message) {
+        super(message, 3);
+    }
+}
+export class ApiError extends CliError {
+    constructor(message) {
+        super(message, 1);
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@slothmoney/agent-cli",
+  "version": "0.1.0",
+  "description": "Command-line access to the Sloth Money Agent API.",
+  "type": "module",
+  "bin": {
+    "sloth-agent": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:package": "node scripts/test-package.mjs",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run lint && npm run typecheck && npm test && npm run build && npm run test:package"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RathBala/sloth-agent-cli.git"
+  },
+  "homepage": "https://slothmoney.app/developers/",
+  "bugs": {
+    "url": "https://github.com/RathBala/sloth-agent-cli/issues"
+  },
+  "keywords": [
+    "sloth-money",
+    "personal-finance",
+    "agent",
+    "cli"
+  ],
+  "author": "Rath Bala",
+  "license": "MIT",
+  "packageManager": "npm@11.18.0",
+  "devDependencies": {
+    "@eslint/js": "^9.30.1",
+    "@types/node": "^22.15.0",
+    "eslint": "^9.30.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.1",
+    "vitest": "^3.2.4"
+  }
+}