financy 0.1.3 → 0.3.0

package/dist/bin.js

@@ -23,7 +23,7 @@ import {
   resolveEndpoints,
   sanitizeCredential,
   writeCredentialsFile
-} from "./chunk-YOW6MO6F.js";
+} from "./chunk-VE5WZRGU.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-RM4BAVES.js");
     await startMcpServer(env);
   });
   const skills = program.command("skills").description("Agent skills bundled with financy (Claude Code and other agents)");

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

@@ -3,12 +3,20 @@
 // package.json
 var package_default = {
   name: "financy",
-  version: "0.1.3",
+  version: "0.3.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,6 +50,7 @@ var package_default = {
     node: ">=20"
   },
   scripts: {
+    prebuild: `node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})"`,
     build: "tsup",
     test: "vitest run",
     "test:watch": "vitest",
@@ -312,6 +321,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 +361,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 +377,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 +391,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 +516,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) {

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,710 @@
+// 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.3.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",
+    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"
+  },
+  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/{server-FZPZL65M.js → server-RM4BAVES.js}

@@ -16,7 +16,7 @@ import {
   fetchTransactions,
   loadConfig,
   notConfigured
-} from "./chunk-YOW6MO6F.js";
+} from "./chunk-VE5WZRGU.js";
 
 // src/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -90,7 +90,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 +113,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,9 +171,13 @@ 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);
   }

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "financy",
-  "version": "0.1.3",
-  "description": "Your Open-Finance accounts, balances and transactions in the terminal — with an embedded MCP server and agent skills",
+  "version": "0.3.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",
@@ -39,6 +47,7 @@
     "node": ">=20"
   },
   "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",