splitwise-mcp 3.4.1 → 3.5.1

package/dist/index.js

@@ -7,6 +7,8 @@ import { registerGroupTools } from './tools/groups.js';
 import { registerFriendTools } from './tools/friends.js';
 import { registerExpenseTools } from './tools/expenses.js';
 import { registerReceiptTools } from './tools/receipts.js';
+import { registerUploadTools } from './tools/uploads.js';
+import { registerBatchTools } from './tools/batch.js';
 import { registerUtilityTools } from './tools/utilities.js';
 // runMcp builds the McpServer, applies the registrars (threading `client`
 // through as deps), prints the banner to stderr, wires graceful shutdown, and
@@ -19,7 +21,7 @@ import { registerUtilityTools } from './tools/utilities.js';
 // client into the same registrars instead of this singleton.
 await runMcp({
     name: 'splitwise-mcp',
-    version: '3.4.1', // x-release-please-version
+    version: '3.5.1', // x-release-please-version
     deps: client,
     banner: '[splitwise-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion.',
     tools: [
@@ -29,6 +31,9 @@ await runMcp({
         registerFriendTools,
         registerExpenseTools,
         registerReceiptTools,
+        registerUploadTools,
         registerUtilityTools,
+        // Last: sw_batch lists the writes registered before it.
+        registerBatchTools,
     ],
 });

package/dist/project.js

@@ -29,7 +29,7 @@ function asList(v) {
     return Array.isArray(v) ? v : [];
 }
 /** "Alison Hall" from the first/last pair Splitwise returns on every user shape. */
-function nameOf(user) {
+export function nameOf(user) {
     if (!user)
         return undefined;
     const parts = [user.first_name, user.last_name].filter((p) => typeof p === 'string' && p !== '');
@@ -105,8 +105,6 @@ export function compactGroup(raw) {
  */
 export function compactExpense(raw) {
     const e = asDict(raw) ?? {};
-    const receipt = asDict(e.receipt);
-    const original = receipt?.original;
     return pruneUndefined({
         id: e.id,
         group_id: e.group_id,
@@ -119,9 +117,14 @@ export function compactExpense(raw) {
         payment: e.payment === true ? true : undefined,
         created_by: nameOf(asDict(e.created_by)),
         updated_at: e.updated_at,
+        updated_by: nameOf(asDict(e.updated_by)),
         // Kept only when set. A deleted expense still comes back from the list
         // endpoint, and a caller that cannot see `deleted_at` will count it.
         deleted_at: e.deleted_at ?? undefined,
+        // Who deleted it is the first question after "is it deleted" — in a shared
+        // group it is often not the caller. Without it here, every reconciliation
+        // needed a second `view: "full"` read.
+        deleted_by: e.deleted_at ? nameOf(asDict(e.deleted_by)) : undefined,
         comments_count: e.comments_count,
         repayments: e.repayments,
         users: asList(e.users).map((entry) => {
@@ -135,9 +138,38 @@ export function compactExpense(raw) {
             };
         }),
         // A receipt is evidence; `sw_get_receipt` is how a caller fetches it.
-        has_receipt: typeof original === 'string' ? true : undefined,
+        // Always stated: "no receipt" is a fact a reconciliation acts on.
+        has_receipt: hasReceipt(e),
     });
 }
+function hasReceipt(e) {
+    return typeof asDict(e.receipt)?.original === 'string';
+}
+/**
+ * The `rows` rung of `sw_list_expenses`: one flat line per expense, for
+ * reconciling a long history. A year of one group came back as ~110K
+ * characters on `compact` — the share breakdown and repayments are most of
+ * that, and a "which of these are duplicates / who deleted what" pass needs
+ * none of it. `sw_get_expense` has the rest.
+ */
+export function rowExpense(raw) {
+    const e = asDict(raw) ?? {};
+    return pruneUndefined({
+        id: e.id,
+        date: e.date,
+        description: e.description,
+        cost: e.cost,
+        currency_code: e.currency_code,
+        category: asDict(e.category)?.name,
+        created_by: nameOf(asDict(e.created_by)),
+        deleted_at: e.deleted_at ?? undefined,
+        deleted_by: e.deleted_at ? nameOf(asDict(e.deleted_by)) : undefined,
+        comments_count: e.comments_count,
+        has_receipt: hasReceipt(e),
+    });
+}
+/** `sw_list_expenses` alone also offers `rows`. */
+export const EXPENSE_LIST_VIEWS = [...SW_VIEWS, 'rows'];
 /**
  * Project a payload's `<key>` array, or hand the whole thing back.
  *

package/dist/tools/_confirm.js

@@ -19,7 +19,7 @@ export function confirmWrite(ctx, gate) {
         path: gate.path,
         ...(gate.body !== undefined ? { willSend: gate.body } : {}),
     };
-    const preview = { action: gate.summary, ...request };
+    const preview = { ...gate.extra, action: gate.summary, ...request };
     return requireConfirmationWithFallback(ctx, confirmationFromEnv({
         action: gate.action,
         message: `Review and confirm: ${gate.summary}`,

package/dist/tools/_create.js

@@ -0,0 +1,174 @@
+import { buildQueryString } from '@chrischall/mcp-utils';
+import { equalSplit, resolveMember } from './_split.js';
+const asDict = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+const asList = (v) => (Array.isArray(v) ? v : []);
+/** Categories barely change; one fetch per client per hour. Keyed by client: a hosted server has one per user. */
+const CATEGORY_TTL_MS = 60 * 60 * 1000;
+let categoryCache = new WeakMap();
+/** Forget every cached category list (tests). */
+export function clearCategoryCache() {
+    categoryCache = new WeakMap();
+}
+async function loadCategories(client) {
+    const cached = categoryCache.get(client);
+    if (cached && Date.now() - cached.at < CATEGORY_TTL_MS) {
+        return cached.list;
+    }
+    const list = client.request('GET', '/get_categories').then((data) => {
+        const subs = [];
+        const parents = new Map();
+        for (const raw of asList(asDict(data)?.categories)) {
+            const parent = asDict(raw);
+            if (!parent || typeof parent.name !== 'string')
+                continue;
+            const children = asList(parent.subcategories)
+                .map(asDict)
+                .filter((c) => typeof c?.id === 'number' && typeof c.name === 'string')
+                .map((c) => ({ id: c.id, name: c.name, parent: parent.name }));
+            subs.push(...children);
+            parents.set(parent.name.toLowerCase(), children);
+        }
+        return { subs, parents };
+    });
+    // A failed fetch must not be cached as the answer for the next hour.
+    list.catch(() => categoryCache.delete(client));
+    categoryCache.set(client, { at: Date.now(), list });
+    return list;
+}
+/**
+ * A category name → its id. Matches subcategory names case-insensitively
+ * (an expense always takes a subcategory id; "General" is the one under
+ * "Uncategorized"). A parent name is refused with its subcategories listed,
+ * and an unknown name with the closest names.
+ */
+export async function resolveCategory(client, name) {
+    const { subs, parents } = await loadCategories(client);
+    const want = name.trim().toLowerCase();
+    const exact = subs.filter((c) => c.name.toLowerCase() === want);
+    if (exact.length === 1)
+        return exact[0];
+    if (exact.length > 1) {
+        throw new Error(`category "${name}" is ambiguous: ${exact.map((c) => `${c.parent} › ${c.name} (${c.id})`).join(', ')}. Pass category_id.`);
+    }
+    const children = parents.get(want);
+    if (children) {
+        throw new Error(`category "${name}" is a parent category; pick one of its subcategories: ${children.map((c) => c.name).join(', ')}`);
+    }
+    const words = want.split(/\W+/).filter(Boolean);
+    const close = subs
+        .filter((c) => {
+        const n = c.name.toLowerCase();
+        return n.includes(want) || want.includes(n) || words.some((w) => w.length > 2 && n.includes(w));
+    })
+        .slice(0, 8)
+        .map((c) => c.name);
+    throw new Error(`No Splitwise category named "${name}".${close.length ? ` Did you mean: ${close.join(', ')}?` : ''} sw_get_categories lists them all.`);
+}
+// ---------------------------------------------------------------- similarity
+const tokens = (s) => new Set(s.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+/** Same thing, written slightly differently: one contains the other, or at least half the words overlap. */
+export function similarDescriptions(a, b) {
+    const x = a.trim().toLowerCase();
+    const y = b.trim().toLowerCase();
+    if (!x || !y)
+        return false;
+    if (x.includes(y) || y.includes(x))
+        return true;
+    const tx = tokens(x);
+    const ty = tokens(y);
+    const shared = [...tx].filter((t) => ty.has(t)).length;
+    const union = new Set([...tx, ...ty]).size;
+    return union > 0 && shared / union >= 0.5;
+}
+// ---------------------------------------------------------------- inference
+/**
+ * The most common category among the group's recent expenses with a similar
+ * description — "General" excluded, since it is what an unset category
+ * becomes. Advisory: no match, or a failed read, infers nothing.
+ */
+export async function inferCategory(client, groupId, description) {
+    let recent;
+    try {
+        const data = await client.request('GET', `/get_expenses${buildQueryString({ group_id: groupId, limit: 200 })}`);
+        recent = asList(asDict(data)?.expenses);
+    }
+    catch {
+        return undefined;
+    }
+    const counts = new Map();
+    for (const raw of recent) {
+        const e = asDict(raw);
+        const category = asDict(e?.category);
+        if (!e || typeof e.description !== 'string' || typeof category?.id !== 'number')
+            continue;
+        if (String(category.name).toLowerCase() === 'general')
+            continue;
+        if (!similarDescriptions(e.description, description))
+            continue;
+        const entry = counts.get(category.id) ?? { name: String(category.name), n: 0 };
+        entry.n++;
+        counts.set(category.id, entry);
+    }
+    let best;
+    // Map keeps first-seen order and the list is newest first, so a tie goes to the most recent use.
+    for (const [id, { name, n }] of counts) {
+        if (!best || n > best.similar_expenses)
+            best = { id, name, similar_expenses: n };
+    }
+    return best;
+}
+// ---------------------------------------------------------------- duplicates
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Expenses in the group — live or deleted — with the same cost, a similar
+ * description and a date within a day either side. A warning for the preview,
+ * never a refusal; a failed read finds nothing rather than blocking the create.
+ */
+export async function findDuplicates(client, input) {
+    const when = input.date ? new Date(input.date) : new Date();
+    if (Number.isNaN(when.getTime()))
+        return [];
+    const qs = buildQueryString({
+        group_id: input.group_id,
+        dated_after: new Date(when.getTime() - DAY_MS).toISOString(),
+        dated_before: new Date(when.getTime() + DAY_MS).toISOString(),
+        limit: 200,
+    });
+    let candidates;
+    try {
+        candidates = asList(asDict(await client.request('GET', `/get_expenses${qs}`))?.expenses);
+    }
+    catch {
+        return [];
+    }
+    const cost = Number(input.cost);
+    return candidates
+        .map(asDict)
+        .filter((e) => !!e && Number(e.cost) === cost && typeof e.description === 'string' && similarDescriptions(e.description, input.description))
+        .map((e) => ({ id: e.id, date: e.date, description: e.description, cost: e.cost, deleted: Boolean(e.deleted_at) }));
+}
+// ---------------------------------------------------------------- equal split
+/**
+ * The users[] for `split: "equal"`: `paid_by` paid the whole cost, everyone in
+ * `split_among` (default: every group member) owes an equal part. Names are
+ * resolved against the group's members, which are read only when needed.
+ */
+export async function resolveEqualSplit(client, input) {
+    const needMembers = input.split_among === undefined || typeof input.paid_by === 'string' || input.split_among.some((m) => typeof m === 'string');
+    let members;
+    if (needMembers) {
+        if (!(input.group_id > 0)) {
+            throw new Error('split:"equal" outside a group needs paid_by and split_among as user ids (there are no group members to resolve names against)');
+        }
+        const data = await client.request('GET', `/get_group/${input.group_id}`);
+        members = asList(asDict(asDict(data)?.group)?.members)
+            .map(asDict)
+            .filter((m) => typeof m?.id === 'number');
+        if (members.length === 0)
+            throw new Error(`Could not read the members of group ${input.group_id}`);
+    }
+    const resolve = (who, field) => members ? resolveMember(who, members, field) : who;
+    const payer = resolve(input.paid_by, 'paid_by');
+    const among = input.split_among ? input.split_among.map((m) => resolve(m, 'split_among')) : members.map((m) => m.id);
+    return equalSplit(input.cost, payer, among);
+}

package/dist/tools/_expense-state.js

@@ -0,0 +1,86 @@
+import { ApiError } from '@chrischall/mcp-utils';
+import { nameOf } from '../project.js';
+const asDict = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+/** The expense from a `GET /get_expense/{id}` response, or undefined when it has none. */
+export async function readExpense(client, id) {
+    const data = await client.request('GET', `/get_expense/${id}`);
+    return asDict(asDict(data)?.expense);
+}
+/**
+ * The few fields that say what a write actually left behind. A shared group
+ * has another writer: a restore can be undone by the other member within
+ * seconds, so "the request succeeded" and "the expense is live" are different
+ * facts, and only this one answers the second.
+ */
+export function postState(expense) {
+    return {
+        id: expense.id,
+        deleted_at: expense.deleted_at ?? null,
+        deleted_by: expense.deleted_at ? (nameOf(asDict(expense.deleted_by)) ?? null) : null,
+        updated_at: expense.updated_at ?? null,
+        updated_by: nameOf(asDict(expense.updated_by)) ?? null,
+    };
+}
+/** "by Alison Hall at 2026-10-02T09:15:00Z", from whatever of the two Splitwise reported. */
+function deletedBy(expense) {
+    const who = nameOf(asDict(expense.deleted_by)) ?? 'unknown';
+    return `by ${who} at ${String(expense.deleted_at)}`;
+}
+export function deletedError(id, expense) {
+    return new Error(`Splitwise expense ${id} is deleted (${deletedBy(expense)}); restore it with sw_undelete_expense first. ` +
+        'Splitwise answers a write to a deleted expense with a bare 403 "you do not have permission".');
+}
+/**
+ * Refuse a write to a deleted expense up front, with who deleted it, instead
+ * of letting Splitwise answer a bare 403. Runs before the confirm gate, so the
+ * caller hears it on the first call. The read is advisory: when it fails or
+ * finds nothing, the write goes ahead and reports its own error, so the check
+ * can never block a write that would have worked.
+ */
+export async function assertNotDeleted(client, id) {
+    const expense = await readExpense(client, id).catch(() => undefined);
+    if (expense?.deleted_at)
+        throw deletedError(id, expense);
+}
+/**
+ * Run a write to an existing expense; if Splitwise answers 403, re-read the
+ * expense, and when it turns out deleted (between the pre-check and the write)
+ * say so rather than "you do not have permission". Any other failure, or a 403
+ * on a live expense, is passed through unchanged.
+ */
+export async function explainForbidden(client, id, write) {
+    try {
+        return await write();
+    }
+    catch (err) {
+        if (!(err instanceof ApiError) || err.status !== 403)
+            throw err;
+        const expense = await readExpense(client, id).catch(() => undefined);
+        if (expense?.deleted_at)
+            throw deletedError(id, expense);
+        throw err;
+    }
+}
+/** The response of a create/update with `post_state` lifted to the top, from the expense it returned. */
+export function withPostState(data) {
+    const box = asDict(data);
+    const expense = asDict(box?.expenses?.[0]);
+    if (!box || !expense)
+        return data;
+    return { post_state: postState(expense), ...box };
+}
+/**
+ * After a restore, read the expense back. Still deleted is an error that names
+ * who deleted it and when — never `{success: true}`.
+ */
+export async function verifyRestored(client, id, data) {
+    const expense = await readExpense(client, id);
+    if (!expense) {
+        return { ...(asDict(data) ?? {}), post_state: null, note: `Could not re-read expense ${id} to confirm the restore` };
+    }
+    if (expense.deleted_at) {
+        throw new Error(`Splitwise accepted the restore of expense ${id}, but it is still deleted (${deletedBy(expense)}). ` +
+            'Another group member may have deleted it again — read its comments (sw_get_comments) before restoring it a second time.');
+    }
+    return { ...(asDict(data) ?? {}), post_state: postState(expense) };
+}

package/dist/tools/_list.js

@@ -0,0 +1,166 @@
+import { createHash } from 'crypto';
+import { buildQueryString } from '@chrischall/mcp-utils';
+import { compactExpense, nameOf, rowExpense } from '../project.js';
+const asDict = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+/** Splitwise's own page cap; the scan reads this many per request. */
+export const UPSTREAM_PAGE = 200;
+/** Records one call may read before it hands back a cursor instead. */
+export const SCAN_BUDGET = 1000;
+/** Matched rows that may have their comments inlined in one call. */
+export const MAX_COMMENT_ROWS = 25;
+export function hasLocalFilters(f) {
+    return (f.description_contains !== undefined ||
+        (f.include_deleted !== undefined && f.include_deleted !== true) ||
+        f.created_by !== undefined ||
+        f.min_cost !== undefined ||
+        f.max_cost !== undefined ||
+        f.category !== undefined);
+}
+export function matches(raw, f) {
+    const e = asDict(raw) ?? {};
+    const deleted = Boolean(e.deleted_at);
+    if (f.include_deleted === false && deleted)
+        return false;
+    if (f.include_deleted === 'only' && !deleted)
+        return false;
+    if (f.description_contains !== undefined) {
+        const description = typeof e.description === 'string' ? e.description.toLowerCase() : '';
+        if (!description.includes(f.description_contains.toLowerCase()))
+            return false;
+    }
+    if (f.created_by !== undefined) {
+        const creator = asDict(e.created_by);
+        if (typeof f.created_by === 'number') {
+            if (creator?.id !== f.created_by)
+                return false;
+        }
+        else {
+            const want = f.created_by.trim().toLowerCase();
+            const name = (nameOf(creator) ?? '').toLowerCase();
+            const email = typeof creator?.email === 'string' ? creator.email.toLowerCase() : '';
+            if (!name.includes(want) && email !== want)
+                return false;
+        }
+    }
+    const cost = Number(e.cost);
+    if (f.min_cost !== undefined && !(cost >= f.min_cost))
+        return false;
+    if (f.max_cost !== undefined && !(cost <= f.max_cost))
+        return false;
+    if (f.category !== undefined) {
+        const category = asDict(e.category);
+        if (typeof f.category === 'number') {
+            if (category?.id !== f.category)
+                return false;
+        }
+        else if (String(category?.name ?? '').toLowerCase() !== f.category.trim().toLowerCase()) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * An opaque resume point: the upstream offset to continue from, plus a hash
+ * of the query it belongs to, so a cursor from one query is refused by
+ * another instead of silently skipping rows of it.
+ */
+function queryHash(q, f) {
+    return createHash('sha256').update(JSON.stringify([q, f])).digest('base64url').slice(0, 16);
+}
+export function encodeCursor(offset, q, f) {
+    return Buffer.from(JSON.stringify({ o: offset, q: queryHash(q, f) })).toString('base64url');
+}
+export function decodeCursor(cursor, q, f) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('cursor is not one this tool issued');
+    }
+    if (typeof parsed.o !== 'number' || !Number.isInteger(parsed.o) || parsed.o < 0) {
+        throw new Error('cursor is not one this tool issued');
+    }
+    if (parsed.q !== queryHash(q, f)) {
+        throw new Error('cursor belongs to a different query — pass the same filters it was issued with, or drop it to start over');
+    }
+    return parsed.o;
+}
+/**
+ * Page through Splitwise 200 at a time from `start`, keeping the records that
+ * pass `filters`, until `want` have matched, the history ends, or
+ * {@link SCAN_BUDGET} records have been read. Resumes exactly after the last
+ * record examined, so paging never skips or repeats a match.
+ */
+export async function scanExpenses(client, q, filters, start, want) {
+    const found = [];
+    let offset = start;
+    let scanned = 0;
+    while (scanned < SCAN_BUDGET) {
+        const path = `/get_expenses${buildQueryString({ ...q, limit: UPSTREAM_PAGE, offset })}`;
+        const data = await client.request('GET', path);
+        const page = asDict(data)?.expenses;
+        if (!Array.isArray(page))
+            throw new Error('Splitwise returned no expenses[] array');
+        for (let i = 0; i < page.length; i++) {
+            scanned++;
+            if (matches(page[i], filters))
+                found.push(page[i]);
+            if (found.length === want) {
+                // More may follow even when this was the page's last record — unless
+                // the page was short, which means the history ended here.
+                const exhausted = i === page.length - 1 && page.length < UPSTREAM_PAGE;
+                return { expenses: found, scanned, ...(exhausted ? {} : { nextOffset: offset + i + 1 }) };
+            }
+        }
+        offset += page.length;
+        if (page.length < UPSTREAM_PAGE)
+            return { expenses: found, scanned };
+    }
+    return { expenses: found, scanned, nextOffset: offset };
+}
+/** One comment, as a reconciliation reads it: who said what, and when. */
+function compactComment(raw) {
+    const c = asDict(raw) ?? {};
+    const out = {
+        id: c.id,
+        author: nameOf(asDict(c.user)),
+        content: c.content,
+        comment_type: c.comment_type,
+        created_at: c.created_at,
+    };
+    if (c.deleted_at)
+        out.deleted_at = c.deleted_at;
+    return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined));
+}
+/**
+ * Inline each matched row's comments — the reason an entry was deleted is
+ * usually written there. Only rows that HAVE comments are fetched, and only the
+ * first {@link MAX_COMMENT_ROWS} of them, one request each.
+ */
+export async function attachComments(client, raws, rows) {
+    let fetched = 0;
+    let truncated = false;
+    for (let i = 0; i < raws.length; i++) {
+        const e = asDict(raws[i]);
+        if (!e || !(Number(e.comments_count) > 0))
+            continue;
+        if (fetched === MAX_COMMENT_ROWS) {
+            truncated = true;
+            break;
+        }
+        fetched++;
+        const data = await client.request('GET', `/get_comments${buildQueryString({ expense_id: e.id })}`);
+        const comments = asDict(data)?.comments;
+        rows[i].comments = Array.isArray(comments) ? comments.map(compactComment) : [];
+    }
+    return { truncated };
+}
+/** One record on the requested rung; `full` is Splitwise's record untouched. */
+export function projectForList(view, raw) {
+    if (view === 'rows')
+        return rowExpense(raw);
+    if (view === 'compact')
+        return compactExpense(raw);
+    return (asDict(raw) ?? {});
+}

package/dist/tools/_receipt.js

@@ -1,5 +1,6 @@
 import { createHash } from 'crypto';
-import { readEnvVar } from '@chrischall/mcp-utils';
+import { ApiError, readEnvVar } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv } from '@chrischall/mcp-utils/export';
 import { z } from 'zod';
 /**
  * Splitwise does not document an upload cap, so this is a conservative 10 MiB:
@@ -22,12 +23,17 @@ export const receiptSchema = z
     base64: z
         .string()
         .min(1)
-        .describe('The file bytes, base64-encoded (a data: URL prefix is accepted and stripped). The normal way to pass a receipt.')
+        .describe('The file bytes, base64-encoded (a data: URL prefix is accepted and stripped). Costs context for every byte — on the hosted server prefer upload_id.')
         .optional(),
     path: z
         .string()
         .min(1)
-        .describe('A file inside SPLITWISE_INPUT_DIR on the machine running this server (relative to it, or absolute). Only works when that variable is set — never on a hosted server; use base64 there.')
+        .describe('A file inside SPLITWISE_INPUT_DIR on the machine running this server (relative to it, or absolute). Only works when that variable is set — never on a hosted server; use upload_id (or base64) there.')
+        .optional(),
+    upload_id: z
+        .string()
+        .min(1)
+        .describe('The upload_id from sw_get_upload_url, after the file was PUT to its upload_url. The way to send a full-size file to the hosted server without base64.')
         .optional(),
     filename: z.string().min(1).max(200).describe('Name to store the file under, e.g. "receipt.pdf".'),
     mime_type: z
@@ -35,7 +41,7 @@ export const receiptSchema = z
         .describe('Optional. If given, it must match the type detected from the file contents.')
         .optional(),
 })
-    .describe(`Receipt to attach: PNG, JPEG, GIF or PDF, up to ${LIMIT_LABEL}. Give exactly one of base64 or path. The type is detected from the file contents. Replaces any receipt already on the expense.`);
+    .describe(`Receipt to attach: PNG, JPEG, GIF or PDF, up to ${LIMIT_LABEL}. Give exactly one of upload_id, path or base64. The type is detected from the file contents. Replaces any receipt already on the expense.`);
 export const receiptParam = receiptSchema.optional();
 const tooBig = (size) => new Error(`Receipt is ${size} bytes, over the ${LIMIT_LABEL} limit (${MAX_RECEIPT_BYTES} bytes)`);
 function sniff(bytes) {
@@ -106,17 +112,71 @@ async function readSandboxed(requested) {
         await handle.close();
     }
 }
+/**
+ * The only keys `receipt.upload_id` may name: `up/<uuid>/<safe name>`, exactly
+ * what `sw_get_upload_url` mints. Anything else in this registration's space
+ * is not the caller's to read through a receipt.
+ */
+export const UPLOAD_ID_PATTERN = /^up\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[A-Za-z0-9_-][A-Za-z0-9._-]{0,99}$/;
+/** A filename made safe for a blob key segment: no separators, no dot-dot, no surprises. */
+export function safeKeyName(filename) {
+    const base = filename.split(/[\\/]/).pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._]+/, '').slice(0, 100);
+    return cleaned || 'receipt';
+}
+/** How long the server's own read link for an upload lives — it is used at once. */
+const UPLOAD_READ_TTL_MS = 5 * 60 * 1000;
+/**
+ * Read a file the caller PUT to a `sw_get_upload_url` link, through a signed
+ * GET on the same blob store. Only `up/<uuid>/<name>` keys are accepted.
+ */
+async function readUpload(uploadId, client) {
+    if (!UPLOAD_ID_PATTERN.test(uploadId)) {
+        throw new Error('receipt.upload_id is not one sw_get_upload_url issued (expected up/<uuid>/<filename>)');
+    }
+    const store = blobStoreFromEnv();
+    if (!store || !client) {
+        throw new Error('receipt.upload_id only works on the hosted server; pass receipt.path or receipt.base64 here.');
+    }
+    try {
+        const asset = await client.fetchAsset(store.signGetUrl(uploadId, { ttlMs: UPLOAD_READ_TTL_MS }).url, {
+            maxBytes: MAX_RECEIPT_BYTES,
+        });
+        return Uint8Array.from(asset.bytes);
+    }
+    catch (err) {
+        if (err instanceof ApiError && (err.status === 404 || err.status === 403)) {
+            throw new Error(`No upload found for receipt.upload_id ${uploadId} — the PUT may not have run, failed, or the upload expired. Get a fresh link with sw_get_upload_url and upload the file again.`);
+        }
+        if (err.kind === 'too_large') {
+            throw new Error(`The uploaded receipt is over the ${LIMIT_LABEL} limit (${MAX_RECEIPT_BYTES} bytes)`);
+        }
+        throw err;
+    }
+}
+/** The canonical MIME type for an upload, or an error naming the ones Splitwise takes. */
+export function canonicalReceiptMime(contentType) {
+    const claimed = contentType.trim().toLowerCase();
+    const mime = MIME_ALIASES[claimed] ?? claimed;
+    if (!RECEIPT_TYPES.some((t) => t.mime === mime)) {
+        throw new Error(`content_type must be one of ${RECEIPT_TYPES.map((t) => t.mime).join(', ')} (got ${contentType})`);
+    }
+    return mime;
+}
 /**
  * Read and validate a receipt before the confirmation gate, so a bad file is
  * refused on the first call and the preview can name exactly what will be sent.
  */
-export async function loadReceipt(input) {
-    const hasPath = input.path !== undefined;
-    const hasBase64 = input.base64 !== undefined;
-    if (hasPath === hasBase64) {
-        throw new Error('receipt needs exactly one of path or base64');
+export async function loadReceipt(input, client) {
+    const sources = [input.upload_id, input.path, input.base64].filter((v) => v !== undefined).length;
+    if (sources !== 1) {
+        throw new Error('receipt needs exactly one of upload_id, path or base64');
     }
-    const bytes = hasPath ? await readSandboxed(input.path) : decodeBase64(input.base64);
+    const bytes = input.upload_id !== undefined
+        ? await readUpload(input.upload_id, client)
+        : input.path !== undefined
+            ? await readSandboxed(input.path)
+            : decodeBase64(input.base64);
     if (bytes.length === 0)
         throw new Error('Receipt file is empty');
     if (bytes.length > MAX_RECEIPT_BYTES)