financy 0.1.3 → 0.2.0

package/dist/bin.js

@@ -23,7 +23,7 @@ import {
   resolveEndpoints,
   sanitizeCredential,
   writeCredentialsFile
-} from "./chunk-YOW6MO6F.js";
+} from "./chunk-QYWDNIM2.js";
 
 // src/run.ts
 import { Command, CommanderError } from "commander";
@@ -346,7 +346,10 @@ var TRANSACTION_COLUMNS = [
   { header: "DESCRIPTION", value: (t) => dash(t.merchantName ?? t.description?.description) },
   { header: "CATEGORY", value: (t) => `${dash(t.category?.main)}/${dash(t.category?.sub)}` },
   { header: "TYPE", value: (t) => dash(t.type) },
-  { header: "ID", value: (t) => t.id }
+  // The SK, not the id: this column exists to be pasted into `transactions get`,
+  // and that route is keyed by SK. Matches accounts/connections, whose ID column
+  // likewise prints the value their `get` accepts.
+  { header: "SK", value: (t) => t.SK ?? t.id }
 ];
 var PROVIDER_COLUMNS = [
   { header: "ID", value: (p) => dash(p.providerFriendlyId ?? p.id) },
@@ -388,9 +391,9 @@ function registerReadCommands(program, base, setExit) {
     const envelope = await fetchTransactions(config, base.now, opts);
     setExit(renderList(ctx, envelope, TRANSACTION_COLUMNS));
   });
-  transactions.command("get <id>").option("--json", "machine-readable output").action(async (id) => {
+  transactions.command("get <sk>").description("Read one transaction by its SK (the SK column of `transactions list`)").option("--json", "machine-readable output").action(async (sk) => {
     const config = await loadOrThrow(base.env);
-    setExit(renderGet(ctx, await fetchTransaction(config, base.now, id)));
+    setExit(renderGet(ctx, await fetchTransaction(config, base.now, sk)));
   });
   program.command("categories").description("The category taxonomy (English + Hebrew)").option("--json", "machine-readable output").action(async () => {
     const config = await loadOrThrow(base.env);
@@ -737,7 +740,7 @@ async function run(argv, io = {}) {
     exitCode = await configCommand({ env, json, out });
   });
   program.command("mcp").description("Run the embedded MCP server (stdio) exposing the CLI as agent tools").action(async () => {
-    const { startMcpServer } = await import("./server-FZPZL65M.js");
+    const { startMcpServer } = await import("./server-N5ZPO432.js");
     await startMcpServer(env);
   });
   const skills = program.command("skills").description("Agent skills bundled with financy (Claude Code and other agents)");

package/dist/{server-FZPZL65M.js → chunk-74AQOXZZ.js}

@@ -2,7 +2,6 @@
 import {
   CliError,
   EXIT,
-  VERSION,
   fetchAccount,
   fetchAccounts,
   fetchBranches,
@@ -16,15 +15,7 @@ import {
   fetchTransactions,
   loadConfig,
   notConfigured
-} from "./chunk-YOW6MO6F.js";
-
-// src/mcp/server.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema
-} from "@modelcontextprotocol/sdk/types.js";
+} from "./chunk-QYWDNIM2.js";
 
 // src/mcp/tools.ts
 var str = (v) => v == null ? void 0 : String(v);
@@ -90,7 +81,7 @@ var TOOLS = [
   },
   {
     name: "list_transactions",
-    description: "List transactions, most useful with filters: from/to (YYYY-MM-DD), account, connection, type (BANK|CARD). Page with limit/cursor or fetch everything with all. Hebrew merchant names are returned as-is.",
+    description: "List transactions, most useful with filters: from/to (YYYY-MM-DD), account, connection, type (BANK|CARD). Page with limit/cursor or fetch everything with all. Hebrew merchant names are returned as-is. To then read one transaction, pass its `SK` (not its `id`) to get_transaction.",
     inputSchema: {
       type: "object",
       properties: {
@@ -113,8 +104,17 @@ var TOOLS = [
   },
   {
     name: "get_transaction",
-    description: "Read a single transaction by id (from list_transactions). Errors TRANSACTION_NOT_FOUND if not in scope.",
-    inputSchema: idSchema("transaction"),
+    description: "Read a single transaction by its `SK` \u2014 the composite key from list_transactions, NOT the short `id` field, which this route does not accept. Errors TRANSACTION_NOT_FOUND if not in scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: 'the transaction\'s `SK` from list_transactions, e.g. "TRANSACTION#TYPE#CHECKING#PROVIDER#leumi#RESOURCE<uuid>#<ulid>". The short `id` field of the same transaction will NOT resolve.'
+        }
+      },
+      required: ["id"]
+    },
     run: (a, ctx) => fetchTransaction(ctx.config, ctx.now, requireId(a))
   },
   {
@@ -162,33 +162,19 @@ async function callTool(name, args, io) {
     if (!tool) {
       throw new CliError(EXIT.USAGE, "UNKNOWN_TOOL", `no tool named '${name}'`);
     }
-    const result = await loadConfig(io.env);
-    if (!result.ok) throw notConfigured(result);
-    return await tool.run(args ?? {}, { config: result.config, now: io.now ?? /* @__PURE__ */ new Date() });
+    let config = io.config;
+    if (!config) {
+      const result = await loadConfig(io.env);
+      if (!result.ok) throw notConfigured(result);
+      config = result.config;
+    }
+    return await tool.run(args ?? {}, { config, now: io.now ?? /* @__PURE__ */ new Date() });
   } catch (error) {
     return errorEnvelope(error);
   }
 }
 
-// src/mcp/server.ts
-async function startMcpServer(env) {
-  const server = new Server(
-    { name: "financy", version: VERSION },
-    { capabilities: { tools: {} } }
-  );
-  server.setRequestHandler(ListToolsRequestSchema, () => ({
-    tools: TOOLS.map((t) => ({
-      name: t.name,
-      description: t.description,
-      inputSchema: t.inputSchema
-    }))
-  }));
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const result = await callTool(request.params.name, request.params.arguments ?? {}, { env });
-    return { content: [{ type: "text", text: JSON.stringify(result) }] };
-  });
-  await server.connect(new StdioServerTransport());
-}
 export {
-  startMcpServer
+  TOOLS,
+  callTool
 };

package/dist/{chunk-YOW6MO6F.js → chunk-QYWDNIM2.js}

@@ -3,12 +3,20 @@
 // package.json
 var package_default = {
   name: "financy",
-  version: "0.1.3",
+  version: "0.2.0",
   description: "Your Open-Finance accounts, balances and transactions in the terminal \u2014 with an embedded MCP server and agent skills",
   type: "module",
   bin: {
     financy: "dist/bin.js"
   },
+  types: "./dist/lib.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/lib.d.ts",
+      import: "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
   license: "Apache-2.0",
   author: "Open Finance AI <hello@open-finance.ai>",
   homepage: "https://github.com/open-finance-ai/financy#readme",
@@ -42,7 +50,9 @@ var package_default = {
     node: ">=20"
   },
   scripts: {
+    prebuild: `node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})"`,
     build: "tsup",
+    "build:lambda": "tsup --config tsup.lambda.config.ts",
     test: "vitest run",
     "test:watch": "vitest",
     typecheck: "tsc --noEmit",
@@ -52,7 +62,8 @@ var package_default = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    commander: "^12.1.0"
+    commander: "^12.1.0",
+    jose: "^6.2.9"
   },
   devDependencies: {
     "@eslint/js": "^10.0.1",
@@ -190,6 +201,16 @@ async function writeCredentialsFile(configDir, credentials) {
     { mode: 384 }
   );
 }
+function bearerConfig(env, bearerToken, abortSignal) {
+  return {
+    ...resolveEndpoints(env),
+    clientId: "",
+    clientSecret: "",
+    userId: "",
+    bearerToken,
+    abortSignal
+  };
+}
 function pick(envValue, fileValue) {
   const raw = envValue ?? fileValue;
   if (raw === void 0) return void 0;
@@ -312,6 +333,7 @@ async function getAccessToken(config, now) {
   return mintAndCache(config);
 }
 async function authorized(config, now, request) {
+  if (config.bearerToken) return request(config.bearerToken);
   const token = await getAccessToken(config, now);
   try {
     return await request(token);
@@ -351,7 +373,10 @@ async function getPage(config, token, path, query = {}) {
   for (const [key, value] of Object.entries(query)) {
     if (value !== void 0) url.searchParams.set(key, value);
   }
-  const res = await httpFetch(url.toString(), { headers: authHeaders(token) });
+  const res = await httpFetch(url.toString(), {
+    headers: authHeaders(token),
+    signal: config.abortSignal
+  });
   await ensureOk(res);
   const raw = await res.json().catch(() => ({}));
   debugBody(path, raw);
@@ -364,7 +389,10 @@ function normalizePage(raw) {
   return { items, nextPage: obj.nextPage ?? null, count: obj.count ?? items.length };
 }
 async function getById(config, token, path) {
-  const res = await httpFetch(config.apiBaseUrl + path, { headers: authHeaders(token) });
+  const res = await httpFetch(config.apiBaseUrl + path, {
+    headers: authHeaders(token),
+    signal: config.abortSignal
+  });
   if (res.status === 404) return null;
   await ensureOk(res);
   const body = await res.json();
@@ -375,7 +403,8 @@ async function getById(config, token, path) {
 async function postRefresh(config, token) {
   const res = await httpFetch(config.chatBaseUrl + "/connections/refresh", {
     method: "POST",
-    headers: authHeaders(token)
+    headers: authHeaders(token),
+    signal: config.abortSignal
   });
   if (res.status === 401) throw authFailed();
   if (res.status === 402) {
@@ -499,12 +528,20 @@ function fetchTransactions(config, now, args) {
     !!args.all
   );
 }
-function fetchTransaction(config, now, id) {
+var BARE_TRANSACTION_ID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+function fetchTransaction(config, now, key) {
+  if (BARE_TRANSACTION_ID.test(key)) {
+    throw new CliError(
+      EXIT.USAGE,
+      "INVALID_ARGUMENT",
+      `'${key}' is a transaction's \`id\`, but this lookup is keyed by its \`SK\` \u2014 use the \`SK\` field from the same transaction (it looks like "TRANSACTION#TYPE#\u2026#${key}")`
+    );
+  }
   return getOne(
     config,
     now,
-    `/data/transactions/${encodeURIComponent(id)}`,
-    notFound("TRANSACTION_NOT_FOUND", `no transaction ${id} in your scope`)
+    `/data/transactions/${encodeURIComponent(key)}`,
+    notFound("TRANSACTION_NOT_FOUND", `no transaction ${key} in your scope`)
   );
 }
 function fetchCategories(config, now) {
@@ -528,6 +565,7 @@ export {
   resolveEndpoints,
   readCredentialsFile,
   writeCredentialsFile,
+  bearerConfig,
   loadConfig,
   notConfigured,
   VERSION,

package/dist/lib.d.ts

@@ -0,0 +1,50 @@
+interface Credentials {
+    clientId: string;
+    clientSecret: string;
+    userId: string;
+}
+interface Endpoints {
+    authTokenUrl: string;
+    apiBaseUrl: string;
+    chatBaseUrl: string;
+    configDir: string;
+}
+type Config = Credentials & Endpoints & {
+    bearerToken?: string;
+    abortSignal?: AbortSignal;
+};
+declare function bearerConfig(env: NodeJS.ProcessEnv, bearerToken: string, abortSignal?: AbortSignal): Config;
+
+/** JSON-Schema fragment for a tool's arguments (kept plain so tests need no SDK/zod). */
+type JsonSchema = {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+};
+interface ToolContext {
+    config: Config;
+    now: Date;
+}
+interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    run: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+}
+declare const TOOLS: ToolDef[];
+interface CallToolIO {
+    env: NodeJS.ProcessEnv;
+    now?: Date;
+    config?: Config;
+}
+/**
+ * Dispatch a tool by name: resolve config (unconfigured → the structured
+ * NOT_CONFIGURED error, on every tool), run it, and return its envelope. Errors
+ * are returned as the `{error:{code,message}}` envelope rather than thrown, so
+ * the server surfaces them to the agent as machine-readable tool output.
+ */
+declare function callTool(name: string, args: Record<string, unknown>, io: CallToolIO): Promise<unknown>;
+
+declare const VERSION: string;
+
+export { type CallToolIO, type Config, type JsonSchema, TOOLS, type ToolContext, type ToolDef, VERSION, bearerConfig, callTool };

package/dist/lib.js

@@ -0,0 +1,712 @@
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdir, readFile, writeFile } from "fs/promises";
+
+// src/credentials.ts
+function isControl(ch) {
+  const code = ch.codePointAt(0) ?? 0;
+  return code < 32 || code === 127;
+}
+function sanitizeCredential(raw) {
+  const stripped = Array.from(raw).filter((ch) => !isControl(ch)).join("").trim();
+  const quoted = /^(["'])(.*)\1$/.exec(stripped);
+  return (quoted?.[2] ?? stripped).trim();
+}
+
+// src/exit-codes.ts
+var EXIT = {
+  OK: 0,
+  UNEXPECTED: 1,
+  USAGE: 2,
+  AUTH: 3,
+  PLAN: 4,
+  CREDITS: 5,
+  NOT_FOUND: 6,
+  API: 7
+};
+
+// src/errors.ts
+var CliError = class extends Error {
+  code;
+  exitCode;
+  extra;
+  constructor(exitCode, code, message, extra = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.extra = extra;
+  }
+};
+var authFailed = (message = "authentication failed \u2014 check your credentials or run financy setup") => new CliError(EXIT.AUTH, "AUTH_FAILED", message);
+var planNotEligible = () => new CliError(
+  EXIT.PLAN,
+  "NOT_AVAILABLE_ON_PLAN",
+  "the API is available on Starter and Pro plans \u2014 upgrade in Financy \u2192 Settings \u2192 Plan"
+);
+var forbidden = (detail) => new CliError(EXIT.PLAN, "FORBIDDEN", `the API denied this request (403): ${detail}`);
+var insufficientCredits = (cost, balance) => new CliError(
+  EXIT.CREDITS,
+  "INSUFFICIENT_CREDITS",
+  `an initiated refresh costs ${cost} credits; you have ${balance}`,
+  { cost, balance }
+);
+var noRefreshableConnections = (message = "no connections are eligible for refresh") => new CliError(EXIT.UNEXPECTED, "NO_REFRESHABLE_CONNECTIONS", message);
+var apiUnavailable = (message = "the Open-Finance API is unavailable \u2014 check your connection and try again") => new CliError(EXIT.API, "API_UNAVAILABLE", message);
+
+// src/config.ts
+var DEFAULT_AUTH_TOKEN_URL = "https://api.open-finance.ai/oauth/token";
+var DEFAULT_API_BASE_URL = "https://api.open-finance.ai/v2";
+var DEFAULT_CHAT_BASE_URL = "https://api.open-finance.ai/chat/chat";
+function resolveConfigDir(env) {
+  if (env.FINANCY_CONFIG_DIR) return env.FINANCY_CONFIG_DIR;
+  const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "financy");
+}
+function resolveEndpoints(env) {
+  return {
+    authTokenUrl: env.FINANCY_AUTH_URL ?? DEFAULT_AUTH_TOKEN_URL,
+    apiBaseUrl: env.FINANCY_API_URL ?? DEFAULT_API_BASE_URL,
+    chatBaseUrl: env.FINANCY_CHAT_URL ?? DEFAULT_CHAT_BASE_URL,
+    configDir: resolveConfigDir(env)
+  };
+}
+function configFile(configDir) {
+  return join(configDir, "config.json");
+}
+function decodeConfigBytes(bytes) {
+  if (bytes[0] === 255 && bytes[1] === 254) return bytes.subarray(2).toString("utf16le");
+  if (bytes[0] === 254 && bytes[1] === 255) {
+    return Buffer.from(bytes.subarray(2)).swap16().toString("utf16le");
+  }
+  if (bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191) {
+    return bytes.subarray(3).toString("utf8");
+  }
+  return bytes.toString("utf8");
+}
+async function readCredentialsFile(configDir) {
+  let bytes;
+  try {
+    bytes = await readFile(configFile(configDir));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return { status: "missing" };
+    return { status: "unreadable", detail: code ?? String(error) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(decodeConfigBytes(bytes));
+  } catch (error) {
+    return { status: "malformed", detail: `not valid JSON (${error.message})` };
+  }
+  const credentials = parsed?.profiles?.default;
+  if (!credentials || typeof credentials !== "object") {
+    return {
+      status: "malformed",
+      detail: 'no "profiles.default" object \u2014 expected {"profiles":{"default":{\u2026}}}'
+    };
+  }
+  return { status: "ok", credentials };
+}
+function bearerConfig(env, bearerToken, abortSignal) {
+  return {
+    ...resolveEndpoints(env),
+    clientId: "",
+    clientSecret: "",
+    userId: "",
+    bearerToken,
+    abortSignal
+  };
+}
+function pick(envValue, fileValue) {
+  const raw = envValue ?? fileValue;
+  if (raw === void 0) return void 0;
+  const value = sanitizeCredential(raw);
+  return value === "" ? void 0 : value;
+}
+async function loadConfig(env) {
+  const endpoints = resolveEndpoints(env);
+  const result = await readCredentialsFile(endpoints.configDir);
+  const file = result.status === "ok" ? result.credentials : {};
+  const fileProblem = result.status === "missing" || result.status === "ok" ? void 0 : `${configFile(endpoints.configDir)} could not be read: ${result.detail}`;
+  const clientId = pick(env.FINANCY_CLIENT_ID, file.clientId);
+  const clientSecret = pick(env.FINANCY_CLIENT_SECRET, file.clientSecret);
+  const userId = pick(env.FINANCY_USER_ID, file.userId);
+  const missing = [];
+  if (!clientId) missing.push("FINANCY_CLIENT_ID");
+  if (!clientSecret) missing.push("FINANCY_CLIENT_SECRET");
+  if (!userId) missing.push("FINANCY_USER_ID");
+  if (!clientId || !clientSecret || !userId) return { ok: false, missing, fileProblem };
+  return {
+    ok: true,
+    config: { clientId, clientSecret, userId, ...endpoints }
+  };
+}
+function notConfigured(result) {
+  const suffix = result.fileProblem ? ` \u2014 ${result.fileProblem}` : "";
+  return new CliError(
+    EXIT.AUTH,
+    "NOT_CONFIGURED",
+    `missing ${result.missing.join(", ")} \u2014 run financy setup${suffix}`
+  );
+}
+
+// package.json
+var package_default = {
+  name: "financy",
+  version: "0.2.0",
+  description: "Your Open-Finance accounts, balances and transactions in the terminal \u2014 with an embedded MCP server and agent skills",
+  type: "module",
+  bin: {
+    financy: "dist/bin.js"
+  },
+  types: "./dist/lib.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/lib.d.ts",
+      import: "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
+  license: "Apache-2.0",
+  author: "Open Finance AI <hello@open-finance.ai>",
+  homepage: "https://github.com/open-finance-ai/financy#readme",
+  bugs: {
+    url: "https://github.com/open-finance-ai/financy/issues"
+  },
+  keywords: [
+    "financy",
+    "open-finance",
+    "open-banking",
+    "cli",
+    "mcp",
+    "claude-code",
+    "agent-skills",
+    "fintech",
+    "israel"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/open-finance-ai/financy.git"
+  },
+  publishConfig: {
+    access: "public",
+    provenance: true
+  },
+  files: [
+    "dist",
+    "skills"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    prebuild: `node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})"`,
+    build: "tsup",
+    "build:lambda": "tsup --config tsup.lambda.config.ts",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    lint: "eslint .",
+    smoke: "node scripts/smoke.mjs",
+    prepublishOnly: "npm run build"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    commander: "^12.1.0",
+    jose: "^6.2.9"
+  },
+  devDependencies: {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^20.14.0",
+    eslint: "^10.7.0",
+    globals: "^17.7.0",
+    tsup: "^8.2.4",
+    typescript: "^5.5.4",
+    "typescript-eslint": "^8.65.0",
+    undici: "^6.19.8",
+    vitest: "^4.1.10"
+  }
+};
+
+// src/version.ts
+var VERSION = package_default.version;
+var USER_AGENT = `financy-cli/${VERSION}`;
+
+// src/http.ts
+async function httpFetch(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch {
+    throw apiUnavailable();
+  }
+}
+
+// src/token-store.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
+function jwtExp(token) {
+  const payload = token.split(".")[1];
+  if (!payload) return null;
+  try {
+    const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return typeof decoded.exp === "number" ? decoded.exp : null;
+  } catch {
+    return null;
+  }
+}
+function tokenFile(configDir) {
+  return join2(configDir, "token.json");
+}
+async function readCachedToken(configDir) {
+  try {
+    const raw = await readFile2(tokenFile(configDir), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.accessToken === "string" && typeof parsed.exp === "number") {
+      return { accessToken: parsed.accessToken, exp: parsed.exp };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeCachedToken(configDir, token) {
+  await mkdir2(configDir, { recursive: true, mode: 448 });
+  await writeFile2(tokenFile(configDir), JSON.stringify(token), { mode: 384 });
+}
+
+// src/auth.ts
+var EXPIRY_SKEW_SECONDS = 30;
+async function mintToken(config) {
+  const res = await httpFetch(config.authTokenUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "user-agent": USER_AGENT
+    },
+    body: JSON.stringify({
+      userId: config.userId,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret
+    })
+  });
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => "")).slice(0, 400);
+    throw authFailed(
+      `token endpoint ${config.authTokenUrl} returned HTTP ${res.status}` + (detail ? `: ${detail}` : "") + " \u2014 check credentials, or set FINANCY_AUTH_URL if the endpoint differs"
+    );
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!body.accessToken) {
+    const keys = body && typeof body === "object" ? Object.keys(body) : [];
+    throw authFailed(
+      `token endpoint returned 200 but no "accessToken" field; response keys: [${keys.join(", ")}]`
+    );
+  }
+  return body.accessToken;
+}
+async function mintAndCache(config) {
+  const accessToken = await mintToken(config);
+  const exp = jwtExp(accessToken);
+  if (exp !== null) {
+    await writeCachedToken(config.configDir, { accessToken, exp });
+  }
+  return accessToken;
+}
+async function getAccessToken(config, now) {
+  const cached = await readCachedToken(config.configDir);
+  const nowSeconds = Math.floor(now.getTime() / 1e3);
+  if (cached && cached.exp - EXPIRY_SKEW_SECONDS > nowSeconds) {
+    return cached.accessToken;
+  }
+  return mintAndCache(config);
+}
+async function authorized(config, now, request) {
+  if (config.bearerToken) return request(config.bearerToken);
+  const token = await getAccessToken(config, now);
+  try {
+    return await request(token);
+  } catch (error) {
+    if (error instanceof CliError && error.code === "AUTH_FAILED") {
+      return await request(await mintAndCache(config));
+    }
+    throw error;
+  }
+}
+
+// src/api.ts
+function authHeaders(token) {
+  return { authorization: `Bearer ${token}`, "user-agent": USER_AGENT };
+}
+async function ensureOk(res) {
+  if (res.ok) return;
+  if (res.status === 401) throw authFailed();
+  const detail = (await res.text().catch(() => "")).slice(0, 300);
+  if (res.status === 403) {
+    if (!detail || /NOT_AVAILABLE_ON_PLAN|plan/i.test(detail)) throw planNotEligible();
+    throw forbidden(detail);
+  }
+  throw apiUnavailable(
+    `the API returned HTTP ${res.status}${detail ? `: ${detail}` : ""}`
+  );
+}
+function debugBody(path, body) {
+  if (process.env.FINANCY_DEBUG) {
+    process.stderr.write(`[financy:debug] ${path} \u2192
+${JSON.stringify(body, null, 2)}
+`);
+  }
+}
+async function getPage(config, token, path, query = {}) {
+  const url = new URL(config.apiBaseUrl + path);
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) url.searchParams.set(key, value);
+  }
+  const res = await httpFetch(url.toString(), {
+    headers: authHeaders(token),
+    signal: config.abortSignal
+  });
+  await ensureOk(res);
+  const raw = await res.json().catch(() => ({}));
+  debugBody(path, raw);
+  return normalizePage(raw);
+}
+function normalizePage(raw) {
+  if (Array.isArray(raw)) return { items: raw, nextPage: null, count: raw.length };
+  const obj = raw ?? {};
+  const items = Array.isArray(obj.items) ? obj.items : [];
+  return { items, nextPage: obj.nextPage ?? null, count: obj.count ?? items.length };
+}
+async function getById(config, token, path) {
+  const res = await httpFetch(config.apiBaseUrl + path, {
+    headers: authHeaders(token),
+    signal: config.abortSignal
+  });
+  if (res.status === 404) return null;
+  await ensureOk(res);
+  const body = await res.json();
+  debugBody(path, body);
+  if (body && typeof body === "object" && Object.keys(body).length === 0) return null;
+  return body;
+}
+async function postRefresh(config, token) {
+  const res = await httpFetch(config.chatBaseUrl + "/connections/refresh", {
+    method: "POST",
+    headers: authHeaders(token),
+    signal: config.abortSignal
+  });
+  if (res.status === 401) throw authFailed();
+  if (res.status === 402) {
+    const body = await res.json().catch(() => ({}));
+    throw insufficientCredits(body.cost ?? 20, body.balance ?? 0);
+  }
+  if (res.status === 409) {
+    const body = await res.json().catch(() => ({}));
+    throw noRefreshableConnections(body.message);
+  }
+  await ensureOk(res);
+  return await res.json();
+}
+async function getConnections(config, token) {
+  return getPage(config, token, "/connections");
+}
+
+// src/core/read.ts
+var upper = (v) => v === void 0 ? void 0 : v.toUpperCase();
+async function fetchPage(config, now, path, query) {
+  return authorized(config, now, (token) => getPage(config, token, path, query));
+}
+async function collectAll(config, now, path, query) {
+  const data = [];
+  let cursor = query.nextPage;
+  do {
+    const page = await fetchPage(config, now, path, { ...query, nextPage: cursor });
+    data.push(...page.items);
+    cursor = page.nextPage ?? void 0;
+  } while (cursor);
+  return { data, nextPage: null, count: data.length };
+}
+async function list(config, now, path, query, all) {
+  if (all) return collectAll(config, now, path, query);
+  const page = await fetchPage(config, now, path, query);
+  return { data: page.items, count: page.count, nextPage: page.nextPage };
+}
+async function getOne(config, now, path, notFound2) {
+  const resource = await authorized(
+    config,
+    now,
+    (token) => getById(config, token, path)
+  );
+  if (resource === null) throw notFound2;
+  return { data: resource };
+}
+var notFound = (code, message) => new CliError(EXIT.NOT_FOUND, code, message);
+function fetchConnections(config, now, args) {
+  return list(config, now, "/connections", { limit: args.limit, nextPage: args.cursor }, !!args.all);
+}
+function fetchConnection(config, now, id) {
+  return getOne(
+    config,
+    now,
+    `/connections/${encodeURIComponent(id)}`,
+    notFound("CONNECTION_NOT_FOUND", `no connection ${id} in your scope`)
+  );
+}
+function fetchAccounts(config, now, args) {
+  return list(
+    config,
+    now,
+    "/data/accounts",
+    {
+      accountType: upper(args.type),
+      connectionId: args.connection,
+      limit: args.limit,
+      nextPage: args.cursor
+    },
+    !!args.all
+  );
+}
+function fetchAccount(config, now, id) {
+  return getOne(
+    config,
+    now,
+    `/data/accounts/${encodeURIComponent(id)}`,
+    notFound("ACCOUNT_NOT_FOUND", `no account ${id} in your scope`)
+  );
+}
+function fetchTransactions(config, now, args) {
+  return list(
+    config,
+    now,
+    "/data/transactions",
+    {
+      dateFrom: args.from,
+      dateTo: args.to,
+      accountId: args.account,
+      connectionId: args.connection,
+      type: upper(args.type),
+      limit: args.limit,
+      nextPage: args.cursor
+    },
+    !!args.all
+  );
+}
+var BARE_TRANSACTION_ID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+function fetchTransaction(config, now, key) {
+  if (BARE_TRANSACTION_ID.test(key)) {
+    throw new CliError(
+      EXIT.USAGE,
+      "INVALID_ARGUMENT",
+      `'${key}' is a transaction's \`id\`, but this lookup is keyed by its \`SK\` \u2014 use the \`SK\` field from the same transaction (it looks like "TRANSACTION#TYPE#\u2026#${key}")`
+    );
+  }
+  return getOne(
+    config,
+    now,
+    `/data/transactions/${encodeURIComponent(key)}`,
+    notFound("TRANSACTION_NOT_FOUND", `no transaction ${key} in your scope`)
+  );
+}
+function fetchCategories(config, now) {
+  return authorized(
+    config,
+    now,
+    (token) => getById(config, token, "/data/transaction-categories")
+  );
+}
+function fetchProviders(config, now) {
+  return list(config, now, "/providers", {}, false);
+}
+function fetchBranches(config, now) {
+  return list(config, now, "/bank-branches", {}, false);
+}
+
+// src/core/status.ts
+var STALE_THRESHOLD_DAYS = 2;
+function toRow(c) {
+  return {
+    provider: c.providerId ?? null,
+    status: c.status,
+    fresh: c.lastFetchedDataDate ?? null,
+    expires: c.expiryDate ?? null,
+    accounts: (c.accounts ?? 0) + (c.cards ?? 0) + (c.savings ?? 0) + (c.loans ?? 0) + (c.securities ?? 0)
+  };
+}
+async function fetchStatus(config, now) {
+  const { items } = await authorized(config, now, (token) => getConnections(config, token));
+  return {
+    data: items.map(toRow),
+    staleThresholdDays: STALE_THRESHOLD_DAYS,
+    connections: items
+  };
+}
+
+// src/core/refresh.ts
+async function fetchRefresh(config, now) {
+  const result = await authorized(config, now, (token) => postRefresh(config, token));
+  return { data: result };
+}
+
+// src/mcp/tools.ts
+var str = (v) => v == null ? void 0 : String(v);
+var bool = (v) => v === true;
+function requireId(args) {
+  const id = args.id;
+  if (typeof id !== "string" || id.length === 0) {
+    throw new CliError(EXIT.USAGE, "MISSING_ARGUMENT", "the `id` argument is required");
+  }
+  return id;
+}
+var PAGING = {
+  limit: { type: "number", description: "page size (defaults to the API default)" },
+  cursor: { type: "string", description: "opaque nextPage cursor from a prior call" },
+  all: { type: "boolean", description: "auto-paginate to the end (ignores cursor/limit paging)" }
+};
+var NO_ARGS = { type: "object", properties: {} };
+var idSchema = (noun) => ({
+  type: "object",
+  properties: { id: { type: "string", description: `the ${noun} id` } },
+  required: ["id"]
+});
+var listArgs = (a) => ({
+  limit: str(a.limit),
+  cursor: str(a.cursor),
+  all: bool(a.all)
+});
+var TOOLS = [
+  {
+    name: "list_connections",
+    description: "List the user's bank/card connections and their fetch state (status, data-through date, consent expiry, per-type counts). Start here to see what is connected. Supports limit/cursor paging and all.",
+    inputSchema: { type: "object", properties: { ...PAGING } },
+    run: (a, ctx) => fetchConnections(ctx.config, ctx.now, listArgs(a))
+  },
+  {
+    name: "get_connection",
+    description: "Read a single connection by id (from list_connections). Errors CONNECTION_NOT_FOUND if it is not in the user's scope.",
+    inputSchema: idSchema("connection"),
+    run: (a, ctx) => fetchConnection(ctx.config, ctx.now, requireId(a))
+  },
+  {
+    name: "list_accounts",
+    description: "List accounts with balances (securities embedded). Filter by type (CHECKING|CARD|LOAN|SAVINGS|SECURITY) or connection. Supports limit/cursor/all.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "CHECKING|CARD|LOAN|SAVINGS|SECURITY" },
+        connection: { type: "string", description: "filter to one connection id" },
+        ...PAGING
+      }
+    },
+    run: (a, ctx) => fetchAccounts(ctx.config, ctx.now, {
+      ...listArgs(a),
+      type: str(a.type),
+      connection: str(a.connection)
+    })
+  },
+  {
+    name: "get_account",
+    description: "Read a single account by id (from list_accounts). Errors ACCOUNT_NOT_FOUND if not in scope.",
+    inputSchema: idSchema("account"),
+    run: (a, ctx) => fetchAccount(ctx.config, ctx.now, requireId(a))
+  },
+  {
+    name: "list_transactions",
+    description: "List transactions, most useful with filters: from/to (YYYY-MM-DD), account, connection, type (BANK|CARD). Page with limit/cursor or fetch everything with all. Hebrew merchant names are returned as-is. To then read one transaction, pass its `SK` (not its `id`) to get_transaction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "earliest transaction date (YYYY-MM-DD)" },
+        to: { type: "string", description: "latest transaction date (YYYY-MM-DD)" },
+        account: { type: "string", description: "filter to one account id" },
+        connection: { type: "string", description: "filter to one connection id" },
+        type: { type: "string", description: "BANK|CARD" },
+        ...PAGING
+      }
+    },
+    run: (a, ctx) => fetchTransactions(ctx.config, ctx.now, {
+      ...listArgs(a),
+      from: str(a.from),
+      to: str(a.to),
+      account: str(a.account),
+      connection: str(a.connection),
+      type: str(a.type)
+    })
+  },
+  {
+    name: "get_transaction",
+    description: "Read a single transaction by its `SK` \u2014 the composite key from list_transactions, NOT the short `id` field, which this route does not accept. Errors TRANSACTION_NOT_FOUND if not in scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: 'the transaction\'s `SK` from list_transactions, e.g. "TRANSACTION#TYPE#CHECKING#PROVIDER#leumi#RESOURCE<uuid>#<ulid>". The short `id` field of the same transaction will NOT resolve.'
+        }
+      },
+      required: ["id"]
+    },
+    run: (a, ctx) => fetchTransaction(ctx.config, ctx.now, requireId(a))
+  },
+  {
+    name: "list_categories",
+    description: "The static transaction-category taxonomy (English + Hebrew). Use to interpret transaction category fields. No arguments.",
+    inputSchema: NO_ARGS,
+    run: async (_a, ctx) => ({ data: await fetchCategories(ctx.config, ctx.now) })
+  },
+  {
+    name: "list_providers",
+    description: "Reference data: the list of banks/providers, to resolve providerId values. No arguments.",
+    inputSchema: NO_ARGS,
+    run: (_a, ctx) => fetchProviders(ctx.config, ctx.now)
+  },
+  {
+    name: "list_bank_branches",
+    description: "Reference data: bank branches. No arguments (this route takes no paging).",
+    inputSchema: NO_ARGS,
+    run: (_a, ctx) => fetchBranches(ctx.config, ctx.now)
+  },
+  {
+    name: "get_status",
+    description: "Per-connection freshness rollup: for each connection its status, data-through date, consent expiry, and account count, plus staleThresholdDays. Call this first to decide whether data is fresh enough before answering questions about balances or transactions.",
+    inputSchema: NO_ARGS,
+    run: async (_a, ctx) => {
+      const { data, staleThresholdDays } = await fetchStatus(ctx.config, ctx.now);
+      return { data, staleThresholdDays };
+    }
+  },
+  {
+    name: "refresh_connections",
+    description: "Trigger an on-demand refresh of ALL connections (org-wide). This COSTS 20 credits \u2014 always confirm with the user before calling it. Data lands after a few minutes; poll get_status to watch progress. Returns the refresh outcome (accepted / already_running).",
+    inputSchema: NO_ARGS,
+    run: (_a, ctx) => fetchRefresh(ctx.config, ctx.now)
+  }
+];
+var BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+function errorEnvelope(error) {
+  const e = error instanceof CliError ? error : new CliError(EXIT.UNEXPECTED, "UNEXPECTED", String(error?.message ?? error));
+  return { error: { code: e.code, message: e.message, ...e.extra } };
+}
+async function callTool(name, args, io) {
+  try {
+    const tool = BY_NAME.get(name);
+    if (!tool) {
+      throw new CliError(EXIT.USAGE, "UNKNOWN_TOOL", `no tool named '${name}'`);
+    }
+    let config = io.config;
+    if (!config) {
+      const result = await loadConfig(io.env);
+      if (!result.ok) throw notConfigured(result);
+      config = result.config;
+    }
+    return await tool.run(args ?? {}, { config, now: io.now ?? /* @__PURE__ */ new Date() });
+  } catch (error) {
+    return errorEnvelope(error);
+  }
+}
+export {
+  TOOLS,
+  VERSION,
+  bearerConfig,
+  callTool
+};

package/dist/remote/start.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import {
+  TOOLS,
+  callTool
+} from "../chunk-74AQOXZZ.js";
+import {
+  VERSION,
+  bearerConfig
+} from "../chunk-QYWDNIM2.js";
+
+// src/remote/server.ts
+import {
+  createServer
+} from "http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/remote/auth.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+var RemoteAuthError = class extends Error {
+};
+function remoteAuthFromEnv(env, getKey) {
+  const domain = env.FINANCY_MCP_AUTH0_DOMAIN;
+  if (!domain) {
+    throw new Error("FINANCY_MCP_AUTH0_DOMAIN is required to run the remote MCP server");
+  }
+  const issuer = `https://${domain}/`;
+  return {
+    issuer,
+    audience: env.FINANCY_MCP_AUDIENCE ?? "https://mcp.open-finance.ai/",
+    getKey: getKey ?? createRemoteJWKSet(new URL(`${issuer}.well-known/jwks.json`))
+  };
+}
+async function verifyBearer(auth, header) {
+  const token = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : void 0;
+  if (!token) throw new RemoteAuthError("missing bearer token");
+  let scope;
+  try {
+    const { payload } = await jwtVerify(token, auth.getKey, {
+      issuer: auth.issuer,
+      audience: auth.audience,
+      requiredClaims: ["exp"]
+    });
+    scope = payload.scope;
+  } catch {
+    throw new RemoteAuthError("invalid or expired token");
+  }
+  const scopes = typeof scope === "string" ? scope.split(" ") : [];
+  if (!scopes.includes("mcp:read")) {
+    throw new RemoteAuthError("token is missing the mcp:read scope \u2014 reconnect the Financy connector");
+  }
+  return token;
+}
+
+// src/remote/server.ts
+var METADATA_PATH = "/.well-known/oauth-protected-resource";
+var MCP_PATH = "/mcp";
+var REMOTE_TOOLS = TOOLS.filter((tool) => tool.name !== "refresh_connections");
+var REMOTE_TOOL_NAMES = new Set(REMOTE_TOOLS.map((tool) => tool.name));
+var sendJson = (res, status, body, headers = {}) => {
+  res.writeHead(status, { "content-type": "application/json", ...headers });
+  res.end(JSON.stringify(body));
+};
+var MAX_BODY_BYTES = 256 * 1024;
+async function readBoundedJson(req, res) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) {
+      sendJson(res, 413, { error: "payload_too_large" });
+      req.destroy();
+      return { ok: false };
+    }
+    chunks.push(chunk);
+  }
+  let body;
+  try {
+    body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : void 0;
+  } catch {
+    sendJson(res, 400, { error: "invalid_json" });
+    return { ok: false };
+  }
+  if (Array.isArray(body)) {
+    sendJson(res, 400, { error: "batch_not_supported" });
+    return { ok: false };
+  }
+  return { ok: true, body };
+}
+function createRemoteHandler(env, options = {}) {
+  const auth = remoteAuthFromEnv(env, options.getKey);
+  return async (req, res) => {
+    const pathname = new URL(req.url ?? "/", "http://placeholder").pathname;
+    if (req.method === "GET" && pathname === METADATA_PATH) {
+      sendJson(res, 200, {
+        resource: auth.audience,
+        authorization_servers: [auth.issuer],
+        scopes_supported: ["mcp:read"],
+        bearer_methods_supported: ["header"]
+      });
+      return;
+    }
+    if (pathname !== MCP_PATH) {
+      sendJson(res, 404, { error: "not_found" });
+      return;
+    }
+    if (req.method !== "POST") {
+      sendJson(res, 405, { error: "method_not_allowed" }, { allow: "POST" });
+      return;
+    }
+    let token;
+    try {
+      token = await verifyBearer(auth, req.headers.authorization);
+    } catch (error) {
+      const proto = req.headers["x-forwarded-proto"] ?? "http";
+      const host = req.headers["x-forwarded-host"] ?? req.headers.host;
+      const message = error instanceof RemoteAuthError ? error.message : "unauthorized";
+      sendJson(res, 401, { error: "unauthorized", message }, {
+        "www-authenticate": `Bearer resource_metadata="${proto}://${host}${METADATA_PATH}"`
+      });
+      return;
+    }
+    const parsed = await readBoundedJson(req, res);
+    if (!parsed.ok) return;
+    const server = new Server(
+      { name: "financy", version: VERSION },
+      { capabilities: { tools: {} } }
+    );
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+      tools: REMOTE_TOOLS.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      }))
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+      const name = request.params.name;
+      const result = REMOTE_TOOL_NAMES.has(name) ? await callTool(name, request.params.arguments ?? {}, {
+        env,
+        config: bearerConfig(env, token, extra.signal)
+      }) : { error: { code: "UNKNOWN_TOOL", message: `no tool named '${name}'` } };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, parsed.body);
+  };
+}
+function startRemoteServer(env, port2, options = {}) {
+  const handler = createRemoteHandler(env, options);
+  const httpServer = createServer((req, res) => {
+    void handler(req, res).catch(() => {
+      if (!res.headersSent) sendJson(res, 500, { error: "internal_error" });
+      else res.end();
+    });
+  });
+  return new Promise((resolve) => {
+    httpServer.listen(port2, () => resolve(httpServer));
+  });
+}
+
+// src/remote/start.ts
+var port = Number(process.env.PORT ?? 8790);
+startRemoteServer(process.env, port).then((server) => {
+  const address = server.address();
+  const shown = typeof address === "object" && address ? address.port : port;
+  console.error(`financy remote MCP server listening on :${shown}`);
+});

package/dist/server-N5ZPO432.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import {
+  TOOLS,
+  callTool
+} from "./chunk-74AQOXZZ.js";
+import {
+  VERSION
+} from "./chunk-QYWDNIM2.js";
+
+// src/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+async function startMcpServer(env) {
+  const server = new Server(
+    { name: "financy", version: VERSION },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callTool(request.params.name, request.params.arguments ?? {}, { env });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  await server.connect(new StdioServerTransport());
+}
+export {
+  startMcpServer
+};

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "financy",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Your Open-Finance accounts, balances and transactions in the terminal — with an embedded MCP server and agent skills",
   "type": "module",
   "bin": {
     "financy": "dist/bin.js"
   },
+  "types": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
   "license": "Apache-2.0",
   "author": "Open Finance AI <hello@open-finance.ai>",
   "homepage": "https://github.com/open-finance-ai/financy#readme",
@@ -39,7 +47,9 @@
     "node": ">=20"
   },
   "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsup",
+    "build:lambda": "tsup --config tsup.lambda.config.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -49,7 +59,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "jose": "^6.2.9"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",