paperless-tax-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,30 @@
 # paperless-tax-mcp
 
-An **unofficial** MCP server for [paperless.tax](https://www.paperless.tax), the Israeli
-bookkeeping/expense platform.
+An **unofficial** MCP server and CLI for [paperless.tax](https://www.paperless.tax), the
+Israeli bookkeeping/expense platform.
 
 > ⚠️ Not affiliated with, endorsed by, or supported by Paperless. This talks to the app's
 > own private backend, not a published developer API, and can break without notice.
 > Use it against your own account.
 
-> 🚧 **Authentication is unresolved.** The self-service API key the UI issues is *not*
-> accepted as a bearer token on these endpoints — see
-> [`docs/api-surface.md`](docs/api-surface.md#authentication--unresolved). The server is
-> usable today only with a token taken from a logged-in browser session, which is
-> short-lived. Getting this to a durable credential is the project's main open problem;
-> help welcome.
-
 The value here is as much [`docs/api-surface.md`](docs/api-surface.md) as the code — no
-public documentation of this API exists anywhere, so the map is the point. The server
-grows as the surface gets documented.
+public documentation of this API exists anywhere, so the map is the point.
+
+## Authentication
+
+Use the **session JWT** the web app holds after login, as `Authorization: Bearer <jwt>`.
+
+The self-service API key from the UI's API/webhooks modal is **not** a credential for these
+endpoints — it returns 401 under every scheme, and paying for the API add-on does not change
+that. Do not buy the add-on expecting it to help.
+
+The good news, contrary to what you would assume of a "session" token: **its `exp` is about
+ten months out**, so one interactive login covers scheduled work for most of a year. Login
+is passwordless (email → entry code), so a fresh token needs a browser once; after that it
+can be lifted from the browser profile.
+[`docs/api-surface.md`](docs/api-surface.md#authentication--resolved) has both.
 
-## Use
+## Use as an MCP server
 
 Register with any MCP client — Claude Code, Claude Desktop, or a gateway. No install step:
 
@@ -40,47 +46,91 @@ Claude Code, in one line:
 claude mcp add paperless-tax --env PAPERLESS_TOKEN=... -- npx -y paperless-tax-mcp
 ```
 
+## Use as a CLI
+
+The same client, for exports and poking at the API:
+
+```bash
+export PAPERLESS_TOKEN=...
+
+npx paperless-tax whoami                       # verify the token, print the account id
+npx paperless-tax probe                        # hit each read endpoint, report what answers
+npx paperless-tax list --type 1                # expenses only
+npx paperless-tax list --from 2025-01 --to 2025-12
+npx paperless-tax export --out export/         # files plus metadata sidecars
+npx paperless-tax raw POST documents/get/downloadurl --json '{"sDocID":"..."}'
+```
+
+`export` writes `{docid}.pdf` plus a `{docid}.json` sidecar under
+`export/expenses/{YYYY}/{YYYY-MM}/`, with a `manifest.jsonl` index. It is resumable —
+documents already on disk are skipped — and the manifest is rewritten from scratch each run,
+so it describes the whole export rather than only what that run fetched.
+
+`--from`/`--to` accept `YYYY-MM-DD`, `YYYY-MM` or the API's native `YYMM`. Omit them to get
+everything: the default range is the app's own unbounded `1001..2912`.
+
+### Use as a library
+
+```ts
+import { PaperlessClient } from "paperless-tax-mcp/client";
+import { Exporter } from "paperless-tax-mcp/export";
+
+const client = new PaperlessClient({ token });
+const docs = await client.byDate();            // whole history, one call
+const pdfUrl = await client.downloadUrl(docs[0].id);
+```
+
 ### Configuration
 
 | Variable | Required | Meaning |
 |---|---|---|
-| `PAPERLESS_TOKEN` | yes | Bearer token — see the auth caveat above |
+| `PAPERLESS_TOKEN` | yes | The session JWT — see above |
 | `PAPERLESS_USER_ID` | no | 10-char account id; `whoami` discovers it |
 | `PAPERLESS_BASE_URL` | no | Defaults to `https://api.paperless.tax/` |
 
 ### From source
 
 ```bash
-npm install && npm run build && node dist/index.js
+npm install && npm run build && npm test
 ```
 
 ## Tools
 
 | Tool | Endpoint | Confidence |
 |---|---|---|
-| `whoami` | `GET users/get/params` | endpoint confirmed |
-| `pending_documents` | `GET documents/get/pending/{sUserID}` | endpoint confirmed |
-| `list_documents` | `POST bydate` | endpoint confirmed, body inferred |
-| `get_document` | `GET document/{id}` | inferred |
-| `get_download_url` | `POST downloadurl` | endpoint confirmed, response inferred |
+| `whoami` | `GET users/get/params` | confirmed live |
+| `pending_documents` | `GET documents/get/pending/{uid}` | confirmed live |
+| `list_documents` | `POST documents/get/bydate` | confirmed live |
+| `get_document` | `GET documents/get/document/{id}` | confirmed live |
+| `get_download_url` | `POST documents/get/downloadurl` | confirmed live |
 | `raw_request` | anything | escape hatch for mapping new surface |
 
-## Two things that will bite you
+## Four things that will bite you
+
+All documented at length in `docs/api-surface.md`, and all of them cost real time to find:
 
-Both are documented at length in `docs/api-surface.md`, and both cost real time to find:
+1. **The controller prefix is not optional.** `POST /bydate` is a 404; the route is
+   `POST documents/get/bydate`. Same for `downloadurl`, `searchdp`, `document/{id}`.
+2. **A 401 does not mean the route exists.** Auth runs before routing, so unauthenticated
+   *every* path 401s — including nonsense ones. This is what produced the earlier, wrong
+   version of the endpoint map. Never infer existence from a 401 here.
+3. **`bydate` takes `YYMM` period strings, not ISO dates.** `sStart: "2506"` is June 2025.
+   Give it a date and you get a narrower result set rather than an error.
+4. **A 204 is not success.** Send no credentials at all and you get the same 204. Control-test
+   every auth scheme against a deliberately invalid credential.
 
-1. **`bydate` returns an empty list for a bad parameter, not an error.** A zero-document
-   response is indistinguishable from a genuinely empty range. Cross-check any count
-   against the web UI before believing it.
-2. **A 204 from this API is not success.** Send no credentials at all and you get the same
-   204. Control-test every auth scheme against a deliberately invalid credential.
+Also worth knowing: `documents/get/bydate` returns an entire account history in one
+unpaginated response, and its records are identical to what the per-document detail endpoint
+returns — so a per-document loop is pure waste. And `export/download` with
+`iExportType: 8` (Backup) answers 503 `NotImplementedException`; there is no whole-account
+backup on that route.
 
 ## Contributing
 
 Corrections to `docs/api-surface.md` are the most valuable contribution — especially
-anything that moves a row from *inferred* to *confirmed*, or that cracks authentication.
-Please mark what you verified versus what you assumed, and never include account
-identifiers, tokens, or ingest addresses in an issue or PR.
+anything that moves a row from *inferred* to *confirmed*. Please mark what you verified
+versus what you assumed, and never include account identifiers, tokens, or ingest addresses
+in an issue or PR.
 
 ## Licence
 

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `paperless-tax` — command line access to the same client the MCP server uses.
+ *
+ * Deliberately dependency-free argument parsing: this package ships as an npx
+ * one-liner, and a CLI framework would be most of its install weight.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * `paperless-tax` — command line access to the same client the MCP server uses.
+ *
+ * Deliberately dependency-free argument parsing: this package ships as an npx
+ * one-liner, and a CLI framework would be most of its install weight.
+ */
+import { PERIOD_MAX, PERIOD_MIN, PaperlessClient, PaperlessError, toPeriod } from "./client.js";
+import { Exporter } from "./export.js";
+const USAGE = `paperless-tax — unofficial CLI for api.paperless.tax
+
+  whoami                      Verify the token and print the account id
+  probe                       Hit each read endpoint once and report what answers
+  list [--from X] [--to Y]    List documents without downloading
+  export [--out DIR]          Export PDFs plus metadata sidecars
+  raw METHOD PATH [--json S]  Call an arbitrary endpoint
+
+Options
+  --from, --to    YYYY-MM-DD, YYYY-MM or YYMM. Default is the app's unbounded
+                  range (${PERIOD_MIN}..${PERIOD_MAX}), which returns everything.
+  --type N        iDocType filter; 1 = expense
+  --out DIR       Export destination (default: export)
+  --metadata-only Skip file downloads
+
+Requires PAPERLESS_TOKEN — the SPA session JWT, not a self-service API key.
+See docs/api-surface.md §Authentication.`;
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { command: positional.shift(), positional, flags };
+}
+const period = (value, fallback) => typeof value === "string" ? toPeriod(value) : fallback;
+async function main() {
+    const { command, positional, flags } = parseArgs(process.argv.slice(2));
+    if (!command || flags.help || command === "help") {
+        console.log(USAGE);
+        return command ? 0 : 2;
+    }
+    const client = new PaperlessClient();
+    switch (command) {
+        case "whoami": {
+            console.log(JSON.stringify(await client.getParams(), null, 2));
+            console.log(`\naccount id: ${await client.resolveUserId()}`);
+            return 0;
+        }
+        case "probe": {
+            const periodStart = period(flags.from, PERIOD_MIN);
+            const periodEnd = period(flags.to, PERIOD_MAX);
+            const checks = [
+                ["users/get/params", () => client.getParams()],
+                ["documents/get/pending", () => client.pending()],
+                ["documents/get/bydate", () => client.byDate({ periodStart, periodEnd })],
+            ];
+            for (const [name, call] of checks) {
+                try {
+                    const result = await call();
+                    const count = Array.isArray(result) ? `${result.length} record(s)` : "ok";
+                    console.log(`  ${name.padEnd(24)} ok — ${count}`);
+                }
+                catch (error) {
+                    console.log(`  ${name.padEnd(24)} ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            return 0;
+        }
+        case "list": {
+            let docs = await client.byDate({
+                periodStart: period(flags.from, PERIOD_MIN),
+                periodEnd: period(flags.to, PERIOD_MAX),
+            });
+            if (typeof flags.type === "string") {
+                docs = docs.filter((doc) => doc.iDocType === Number(flags.type));
+            }
+            for (const doc of docs) {
+                const amount = typeof doc.iAmount === "number" ? (doc.iAmount / 100).toFixed(2) : "";
+                console.log([
+                    doc.id,
+                    doc.sPeriod ?? "",
+                    String(doc.iDocType ?? ""),
+                    (doc.sSupplierName ?? "").slice(0, 28).padEnd(28),
+                    amount.padStart(10),
+                ].join("  "));
+            }
+            console.log(`\n${docs.length} document(s)`);
+            return 0;
+        }
+        case "export": {
+            const out = typeof flags.out === "string" ? flags.out : "export";
+            console.log(`account: ${await client.resolveUserId()}`);
+            const exporter = new Exporter(client, out);
+            const stats = await exporter.exportRange({
+                periodStart: period(flags.from, PERIOD_MIN),
+                periodEnd: period(flags.to, PERIOD_MAX),
+                docType: typeof flags.type === "string" ? Number(flags.type) : undefined,
+                metadataOnly: Boolean(flags["metadata-only"]),
+            });
+            console.log(`\nlisted ${stats.listed}  downloaded ${stats.downloaded}  skipped ${stats.skipped}  ` +
+                `no attachment ${stats.noAttachment}  failed ${stats.failed}  ` +
+                `(${(stats.bytes / 1e6).toFixed(1)} MB)`);
+            if (stats.failed)
+                console.error(`failures logged to ${exporter.errorsPath}`);
+            return stats.failed ? 1 : 0;
+        }
+        case "raw": {
+            const [method, path] = positional;
+            if (!method || !path) {
+                console.error("raw needs METHOD and PATH");
+                return 2;
+            }
+            let body;
+            if (typeof flags.json === "string") {
+                body = JSON.parse(flags.json);
+                if (body && typeof body === "object") {
+                    const record = body;
+                    if (record.sUserID === "auto")
+                        record.sUserID = await client.resolveUserId();
+                }
+            }
+            console.log(JSON.stringify(await client.request(method, path, body), null, 2));
+            return 0;
+        }
+        default:
+            console.error(`unknown command: ${command}\n`);
+            console.error(USAGE);
+            return 2;
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+    if (error instanceof PaperlessError) {
+        console.error(`error: ${error.message}`);
+    }
+    else {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,17 +1,74 @@
 /**
- * Minimal HTTP client for api.paperless.tax.
+ * HTTP client for api.paperless.tax.
  *
- * Endpoint names were read out of the vendor's own Angular bundle; request and
- * response *shapes* are largely inferred, so nothing here assumes a field exists.
- * See docs/api-surface.md for what is confirmed versus guessed.
+ * Endpoint names and request shapes were read out of the vendor's own Angular
+ * bundle and then checked against the live API. See docs/api-surface.md for what
+ * is confirmed versus inferred, and for the traps that produced earlier wrong
+ * answers — chiefly that this API authenticates *before* it routes, so an
+ * unauthenticated 401 says nothing about whether a path exists.
  */
 export declare const DEFAULT_BASE_URL = "https://api.paperless.tax/";
+/** Enum values read from the SPA bundle. */
+export declare const DocType: {
+    readonly Undefined: 0;
+    readonly Expense: 1;
+    readonly Income: 2;
+    readonly Other: 3;
+    readonly IncomeExpense: 4;
+};
+export declare const DateMode: {
+    readonly Year: 1;
+    readonly Month: 2;
+    readonly Day: 3;
+};
+export declare const DateType: {
+    readonly ByPeriod: 0;
+    readonly ByTrans: 1;
+};
+export declare const ExportType: {
+    readonly BKMV: 1;
+    readonly Backup: 8;
+    readonly MOVEIN: 9;
+    readonly DocumentGroup: 12;
+};
+/** The app's own defaults for an unbounded range: YYMM, Jan 2010 → Dec 2029. */
+export declare const PERIOD_MIN = "1001";
+export declare const PERIOD_MAX = "2912";
+/**
+ * Coerce YYYY-MM-DD / YYYY-MM / YYMM to the YYMM the API wants.
+ *
+ * `bydate` takes period strings, not dates. Given something else it returns a
+ * narrower set rather than complaining, so this throws instead of guessing.
+ */
+export declare function toPeriod(value: string): string;
+/** A document as returned by `documents/get/bydate`. Fields beyond `id` are optional. */
+export interface PaperlessDocument {
+    id: string;
+    sID?: string;
+    sPeriod?: string;
+    dtTrans?: string;
+    dtCapture?: string;
+    iDocType?: number;
+    sDocNumber?: string;
+    sSupplierName?: string;
+    sCurrency?: string;
+    /** Integer agorot — iAmount 10341 is ₪103.41. */
+    iAmount?: number;
+    iVAT?: number;
+    iExpenseDeductible?: number;
+    aTags?: string[];
+    /** Page renders: _1000.jpg for page 1, then _1.jpg, _2.jpg … at 707×1000. */
+    aDocURLs?: string[];
+    sDocURLEdit?: string;
+    sDocTNURL?: string;
+    [key: string]: unknown;
+}
 export declare class PaperlessError extends Error {
     status?: number;
     body?: string;
     constructor(message: string, status?: number, body?: string);
 }
-/** 401/403 — see docs/api-surface.md §Authentication, which is unresolved. */
+/** 401/403. A self-service API key is not a credential here; use the session JWT. */
 export declare class PaperlessAuthError extends PaperlessError {
     constructor(message: string, status?: number, body?: string);
 }
@@ -32,16 +89,82 @@ export declare class PaperlessClient {
     private maxRetries;
     private lastCall;
     constructor(options?: ClientOptions);
+    /**
+     * Join a path. Every route sits behind a controller prefix — the SPA builds
+     * URLs as base + controller + "/" + action + "/" + param, and the prefix is
+     * not optional: `POST /bydate` is a 404, `POST documents/get/bydate` is not.
+     */
     buildUrl(...parts: string[]): string;
     private throttle;
+    private headersFor;
+    /** Shared transport: throttle, retry on 5xx and network errors, classify failures. */
+    private send;
     request(method: string, path: string, body?: unknown): Promise<unknown>;
+    /** Fetch binary content — presigned S3 URLs and `export/download` blobs. */
+    requestBinary(method: string, path: string, body?: unknown): Promise<Uint8Array>;
     getParams(): Promise<unknown>;
+    /**
+     * The 10-character account id.
+     *
+     * `users/get/params` carries no `sUserID` field at all, despite that being the
+     * parameter name every other endpoint expects. The id is `sID` at the top
+     * level; the nested business record repeats it as "V_" + id.
+     */
     resolveUserId(): Promise<string>;
     pending(): Promise<unknown>;
-    byDate(dateStart: string, dateEnd: string, docType?: number, extra?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * `POST documents/get/bydate` — the listing call.
+     *
+     * Returns a bare JSON array with no envelope and no pagination; one call can
+     * carry an entire account history. The records are complete — `document()` on
+     * any of them returns the same field set, so there is no reason to follow up
+     * per document.
+     *
+     * Periods are YYMM strings, not ISO dates.
+     */
+    byDate(options?: {
+        periodStart?: string;
+        periodEnd?: string;
+        dateMode?: number;
+        dateType?: number;
+        extra?: Record<string, unknown>;
+    }): Promise<PaperlessDocument[]>;
+    /** `GET documents/get/document/{id}`. Same fields as the listing; for spot checks. */
     document(docId: string): Promise<unknown>;
-    downloadUrl(docId: string, english?: boolean): Promise<unknown>;
+    /**
+     * `POST documents/get/downloadurl` — presigned URL for the document PDF.
+     *
+     * Answers with a bare JSON string. `english` asks for the `_eng.pdf` variant.
+     * Documents with nothing scanned against them have no PDF and this fails
+     * rather than returning an empty URL — check {@link hasAttachment} first.
+     */
+    downloadUrl(docId: string, english?: boolean): Promise<string>;
+    /** Fetch a presigned URL. No Authorization header — the signature does not cover one. */
+    fetchFile(url: string): Promise<Uint8Array>;
+    /**
+     * `POST export/download` with iExportType=12 — the document's pages as a zip
+     * of JPEGs. A lossy alternative to {@link downloadUrl}, kept because it is the
+     * app's own download path. Requires a doc id; without one the server answers
+     * 503 NotImplementedException rather than producing a bulk archive.
+     */
+    documentZip(docId: string): Promise<Uint8Array>;
 }
+/**
+ * Whether a record has any file behind it.
+ *
+ * A sizeable minority are hand-keyed ledger entries with nothing scanned; they
+ * carry no render URLs, and `downloadurl` errors rather than returning nothing.
+ */
+export declare function hasAttachment(doc: PaperlessDocument): boolean;
+/** Pull the URL out of a `downloadurl` response — a bare string, or wrapped. */
+export declare function resolveFileUrl(payload: unknown): string | undefined;
+/**
+ * Locate the document list in a response.
+ *
+ * `bydate` returns a bare array, but other endpoints wrap their payload, so this
+ * finds the longest document-like list by structure rather than by a fixed path.
+ */
+export declare function extractDocuments(payload: unknown): PaperlessDocument[];
 /**
  * Depth-first search for a key anywhere in a nested structure. Response
  * envelopes are inconsistent between endpoints, so locating a field by name is