splitwise-mcp 3.4.1 → 3.5.0

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 { blobConfig, signedGetUrl, UPLOAD_ID_PATTERN } from './_blob.js';
 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,59 @@ async function readSandboxed(requested) {
         await handle.close();
     }
 }
+/** 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 cfg = blobConfig();
+    if (!cfg || !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(signedGetUrl(cfg, uploadId, Date.now() + UPLOAD_READ_TTL_MS), {
+            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)

package/dist/tools/_split.js

@@ -0,0 +1,61 @@
+/**
+ * The shares for "`payer` paid it all, everyone in `participants` owes an
+ * equal part". Built here rather than with Splitwise's `split_equally`, which
+ * always makes the CALLER the payer — the 50/50 case where the other parent
+ * paid had to be hand-built as a users[] array.
+ *
+ * Arithmetic is in minor units at the precision the cost string was written
+ * with ("25.01" → cents, "1001" → whole units), so the shares always sum to
+ * the cost exactly. Leftover units go one each to the first participants in
+ * order — deterministic, and shown in the preview before anything is sent.
+ */
+export function equalSplit(cost, payer, participants) {
+    const match = /^(\d+)(?:\.(\d+))?$/.exec(cost);
+    if (!match)
+        throw new Error(`cost must be a plain decimal string like "25.00" for an equal split (got "${cost}")`);
+    const ids = [...new Set(participants)];
+    if (ids.length === 0)
+        throw new Error('split_among must name at least one participant');
+    const decimals = match[2]?.length ?? 0;
+    const total = BigInt(match[1] + (match[2] ?? ''));
+    const count = BigInt(ids.length);
+    const base = total / count;
+    const leftover = Number(total % count);
+    const fmt = (units) => formatUnits(units, decimals);
+    const shares = ids.map((id, i) => ({
+        user_id: id,
+        paid_share: fmt(id === payer ? total : 0n),
+        owed_share: fmt(base + (i < leftover ? 1n : 0n)),
+    }));
+    if (!ids.includes(payer)) {
+        shares.push({ user_id: payer, paid_share: fmt(total), owed_share: fmt(0n) });
+    }
+    return shares;
+}
+function formatUnits(units, decimals) {
+    if (decimals === 0)
+        return units.toString();
+    const digits = units.toString().padStart(decimals + 1, '0');
+    return `${digits.slice(0, -decimals)}.${digits.slice(-decimals)}`;
+}
+const fullName = (m) => [m.first_name, m.last_name].filter(Boolean).join(' ');
+/**
+ * A member named by id, full name, email or a first name only they have.
+ * `field` names the argument in the error, so the caller knows which to fix.
+ */
+export function resolveMember(who, members, field) {
+    if (typeof who === 'number') {
+        if (members.some((m) => m.id === who))
+            return who;
+        throw new Error(`${field}: user ${who} is not a member of this group`);
+    }
+    const want = who.trim().toLowerCase();
+    const exact = members.filter((m) => fullName(m).toLowerCase() === want || (m.email ?? '').toLowerCase() === want);
+    const candidates = exact.length > 0 ? exact : members.filter((m) => (m.first_name ?? '').toLowerCase() === want);
+    if (candidates.length === 1)
+        return candidates[0].id;
+    if (candidates.length > 1) {
+        throw new Error(`${field}: "${who}" is ambiguous — ${candidates.map((m) => `${fullName(m)} (${m.id})`).join(', ')}. Pass the user id.`);
+    }
+    throw new Error(`${field}: "${who}" is not a member of this group (members: ${members.map((m) => `${fullName(m)} (${m.id})`).join(', ')})`);
+}

package/dist/tools/batch.js

@@ -0,0 +1,22 @@
+import { registerBatchTool, registerConfirmTool } from '@chrischall/mcp-utils';
+/**
+ * `sw_confirm` and `sw_batch` — the two ways to spend fewer calls on Splitwise
+ * writes from a client that cannot show a confirmation prompt (claude.ai).
+ *
+ * - `sw_confirm({confirmToken})` finishes any gated write's two-step
+ *   confirmation with the token alone: the server kept the phase-1 arguments,
+ *   so a base64 receipt does not cross the conversation a second time.
+ * - `sw_batch({ops})` previews and approves several expense/comment writes at
+ *   once — "log the expense, comment on it, attach the receipt" in one
+ *   approval, with the new expense's id fed forward through `refs`.
+ *
+ * Both come from `@chrischall/mcp-utils` (docs/CONFIRM-TOKEN.md §13–14).
+ * Registered LAST: the batch tool lists the writes registered before it.
+ */
+export function registerBatchTools(server, _client) {
+    registerConfirmTool(server, { name: 'sw_confirm' });
+    registerBatchTool(server, {
+        name: 'sw_batch',
+        description: 'Several Splitwise writes in one go, e.g. create an expense, then sw_create_comment / sw_attach_receipt on it with refs {"expense_id": "0.expense_id"}.',
+    });
+}