financy 0.1.2 → 0.2.0

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

@@ -3,12 +3,20 @@
 // package.json
 var package_default = {
   name: "financy",
-  version: "0.1.2",
+  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",
@@ -71,10 +82,64 @@ var package_default = {
 var VERSION = package_default.version;
 var USER_AGENT = `financy-cli/${VERSION}`;
 
+// 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
 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/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";
@@ -94,14 +159,39 @@ function resolveEndpoints(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 {
-    const raw = await readFile(configFile(configDir), "utf8");
-    const parsed = JSON.parse(raw);
-    return parsed.profiles?.default ?? null;
-  } catch {
-    return null;
+    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 };
 }
 async function writeCredentialsFile(configDir, credentials) {
   await mkdir(configDir, { recursive: true, mode: 448 });
@@ -111,63 +201,48 @@ 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;
+  const value = sanitizeCredential(raw);
+  return value === "" ? void 0 : value;
+}
 async function loadConfig(env) {
   const endpoints = resolveEndpoints(env);
-  const file = await readCredentialsFile(endpoints.configDir) ?? {};
-  const clientId = env.FINANCY_CLIENT_ID ?? file.clientId;
-  const clientSecret = env.FINANCY_CLIENT_SECRET ?? file.clientSecret;
-  const userId = env.FINANCY_USER_ID ?? file.userId;
+  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 };
+  if (!clientId || !clientSecret || !userId) return { ok: false, missing, fileProblem };
   return {
     ok: true,
     config: { clientId, clientSecret, userId, ...endpoints }
   };
 }
-
-// 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);
+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}`
+  );
+}
 
 // src/http.ts
 async function httpFetch(url, init) {
@@ -258,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);
@@ -297,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);
@@ -310,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();
@@ -321,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) {
@@ -445,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) {
@@ -468,13 +559,16 @@ function fetchBranches(config, now) {
 }
 
 export {
+  sanitizeCredential,
+  EXIT,
+  CliError,
   resolveEndpoints,
   readCredentialsFile,
   writeCredentialsFile,
+  bearerConfig,
   loadConfig,
+  notConfigured,
   VERSION,
-  EXIT,
-  CliError,
   getConnections,
   mintToken,
   STALE_THRESHOLD_DAYS,

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 };