financy 0.3.0 → 0.4.1

package/dist/server-RVYFSTUB.js

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+import {
+  CliError,
+  EXIT,
+  VERSION,
+  createDraft,
+  fetchAccount,
+  fetchAccounts,
+  fetchBranches,
+  fetchCategories,
+  fetchConnection,
+  fetchConnections,
+  fetchIntegration,
+  fetchIntegrations,
+  fetchInvoicingCustomer,
+  fetchInvoicingCustomers,
+  fetchInvoicingDocument,
+  fetchInvoicingDocuments,
+  fetchProposal,
+  fetchProposals,
+  fetchProviders,
+  fetchReceivables,
+  fetchRefresh,
+  fetchStatus,
+  fetchTransaction,
+  fetchTransactions,
+  loadConfig,
+  notConfigured
+} from "./chunk-FKAHEAV6.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";
+
+// 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 dispatchTool(byName, name, args, io) {
+  try {
+    const tool = byName.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);
+  }
+}
+
+// src/mcp/integration-tools.ts
+var str2 = (v) => v == null ? void 0 : String(v);
+var bool2 = (v) => v === true;
+function required(args, key) {
+  const value = args[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new CliError(EXIT.USAGE, "MISSING_ARGUMENT", `the \`${key}\` argument is required`);
+  }
+  return value;
+}
+function selected(args, keys) {
+  return Object.fromEntries(keys.filter((key) => args[key] !== void 0).map((key) => [key, args[key]]));
+}
+function paymentOf(args) {
+  return {
+    method: args.paymentMethod,
+    date: args.paymentDate,
+    ...args.paymentReference === void 0 ? {} : { reference: args.paymentReference }
+  };
+}
+var AMOUNTS = "Amounts are integers in minor units of their currency (agorot for ILS).";
+var DRAFT = "Create a document DRAFT. Nothing is issued by this call: the user must approve the draft in Financy at the returned approvalUrl, and only then is the document issued in their business system. Show the user the approvalUrl. " + AMOUNTS;
+var PAGING_NOTE = "A page shorter than limit with a non-null nextPage means more may match: call again with that cursor, or pass all.";
+var integrationId = { type: "string", description: "an integration id (intg_\u2026) from list_integrations" };
+var documentId = { type: "string", description: "a document id (idoc_\u2026) from list_invoicing_documents" };
+var counterpartyId = { type: "string", description: "a customer id (icus_\u2026) from list_invoicing_customers" };
+var proposalId = { type: "string", description: "a proposal id (prop_\u2026) returned by a draft tool" };
+var localDate = (description) => ({ type: "string", description });
+var PAGING2 = {
+  limit: { type: "number", description: "page size (1\u2013200)" },
+  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 recipients = {
+  type: "array",
+  items: { type: "string" },
+  description: "up to three email recipients; absent or empty sends no email"
+};
+var paymentProperties = {
+  paymentMethod: { type: "string", enum: ["bank_transfer", "cash", "cheque", "card", "other"] },
+  paymentDate: localDate("payment date, YYYY-MM-DD"),
+  paymentReference: { type: "string", description: "e.g. a transfer reference" }
+};
+var invoiceProperties = {
+  integrationId,
+  counterpartyId,
+  lines: {
+    type: "array",
+    description: "1\u201320 lines",
+    items: {
+      type: "object",
+      properties: {
+        description: { type: "string" },
+        quantity: { type: "integer" },
+        unitPriceMinor: { type: "integer" }
+      },
+      required: ["description", "quantity", "unitPriceMinor"]
+    }
+  },
+  pricesIncludeVat: { type: "boolean" },
+  dueDate: localDate("due date, YYYY-MM-DD"),
+  recipients
+};
+var invoiceRequired = ["integrationId", "counterpartyId", "lines", "pricesIncludeVat"];
+var paymentRequired = ["paymentMethod", "paymentDate"];
+var invoiceItemKeys = ["counterpartyId", "lines", "pricesIncludeVat", "dueDate", "recipients"];
+var amountMinor = { type: "integer", description: "amount in minor units; omit for the full remaining amount" };
+var schema = (properties, req) => ({
+  type: "object",
+  properties,
+  ...req ? { required: req } : {}
+});
+var draft = (a, ctx, body) => createDraft(ctx.config, ctx.now, required(a, "integrationId"), body);
+var INTEGRATION_TOOLS = [
+  {
+    name: "list_integrations",
+    description: "List the business systems (invoicing software such as Invoice4U) connected to Financy, with each one's connection health and sync state. Start here to find an integrationId.",
+    inputSchema: schema({}),
+    run: (_a, ctx) => fetchIntegrations(ctx.config, ctx.now)
+  },
+  {
+    name: "get_integration",
+    description: "Get one connected business system: connection health, per-stream sync state and data freshness.",
+    inputSchema: schema({ integrationId }, ["integrationId"]),
+    run: (a, ctx) => fetchIntegration(ctx.config, ctx.now, required(a, "integrationId"))
+  },
+  {
+    name: "get_receivables",
+    description: `Who owes the business money: open receivables across connected business systems, with totals and aging buckets per currency and per customer. Each integration entry says how fresh its data is and whether its first sync is still running. ${AMOUNTS}`,
+    inputSchema: schema({
+      integrationIds: { type: "array", items: integrationId, description: "limit to these integrations (default: all)" },
+      format: { type: "string", enum: ["concise", "detailed"], description: "detailed also lists each customer's open documents" },
+      asOf: localDate("the date to age receivables against, YYYY-MM-DD (default today)")
+    }),
+    run: (a, ctx) => fetchReceivables(ctx.config, ctx.now, {
+      integrations: Array.isArray(a.integrationIds) ? a.integrationIds.map(String) : void 0,
+      detailed: a.format === "detailed",
+      asOf: str2(a.asOf)
+    })
+  },
+  {
+    name: "list_invoicing_documents",
+    description: `List documents (invoices, receipts, credit notes, proformas and others) of one connected business system, filtered by status, type, customer or issue date. ${PAGING_NOTE} ${AMOUNTS}`,
+    inputSchema: schema(
+      {
+        integrationId,
+        status: { type: "string", enum: ["open", "partially_paid", "paid", "partially_credited", "credited", "cancelled", "closed", "unknown"] },
+        type: { type: "string", enum: ["invoice", "receipt", "invoice_receipt", "credit_note", "proforma", "quote", "order", "delivery_note", "other"] },
+        counterpartyId,
+        issuedFrom: localDate("issued on or after, YYYY-MM-DD"),
+        issuedTo: localDate("issued on or before, YYYY-MM-DD"),
+        receivableOnly: { type: "boolean", description: "only documents that are owed money" },
+        ...PAGING2
+      },
+      ["integrationId"]
+    ),
+    run: (a, ctx) => fetchInvoicingDocuments(ctx.config, ctx.now, required(a, "integrationId"), {
+      status: str2(a.status),
+      type: str2(a.type),
+      customer: str2(a.counterpartyId),
+      from: str2(a.issuedFrom),
+      to: str2(a.issuedTo),
+      receivableOnly: bool2(a.receivableOnly),
+      limit: str2(a.limit),
+      cursor: str2(a.cursor),
+      all: bool2(a.all)
+    })
+  },
+  {
+    name: "get_invoicing_document",
+    description: `Get one invoicing document with its amounts, status, links to related documents and what remains owed. ${AMOUNTS}`,
+    inputSchema: schema({ integrationId, documentId }, ["integrationId", "documentId"]),
+    run: (a, ctx) => fetchInvoicingDocument(ctx.config, ctx.now, required(a, "integrationId"), required(a, "documentId"))
+  },
+  {
+    name: "list_invoicing_customers",
+    description: `List the customers of one connected business system, optionally matching part of the name. ${PAGING_NOTE}`,
+    inputSchema: schema(
+      { integrationId, q: { type: "string", description: "part of the customer name" }, ...PAGING2 },
+      ["integrationId"]
+    ),
+    run: (a, ctx) => fetchInvoicingCustomers(ctx.config, ctx.now, required(a, "integrationId"), {
+      search: str2(a.q),
+      limit: str2(a.limit),
+      cursor: str2(a.cursor),
+      all: bool2(a.all)
+    })
+  },
+  {
+    name: "get_invoicing_customer",
+    description: "Get one customer of a connected business system by id (from list_invoicing_customers).",
+    inputSchema: schema({ integrationId, counterpartyId }, ["integrationId", "counterpartyId"]),
+    run: (a, ctx) => fetchInvoicingCustomer(ctx.config, ctx.now, required(a, "integrationId"), required(a, "counterpartyId"))
+  },
+  {
+    name: "list_proposals",
+    description: "List your document drafts, newest first, with their status (pending_approval until the user approves in Financy). Filter by integrationId or status; limit up to 50 (no cursor).",
+    inputSchema: schema({
+      integrationId,
+      status: { type: "string", enum: ["pending_approval", "approved", "executing", "completed", "partially_failed", "failed", "expired", "cancelled"] },
+      limit: { type: "number", description: "how many (1\u201350)" }
+    }),
+    run: (a, ctx) => fetchProposals(ctx.config, ctx.now, {
+      integration: str2(a.integrationId),
+      status: str2(a.status),
+      limit: str2(a.limit)
+    })
+  },
+  {
+    name: "get_proposal",
+    description: "Get a document draft, its approval link, previews and current status, including any issued document results once the user has approved it in Financy.",
+    inputSchema: schema({ proposalId }, ["proposalId"]),
+    run: (a, ctx) => fetchProposal(ctx.config, ctx.now, required(a, "proposalId"))
+  },
+  {
+    name: "draft_invoice",
+    description: `${DRAFT} Drafts a tax invoice to an existing customer from list_invoicing_customers.`,
+    inputSchema: schema(invoiceProperties, invoiceRequired),
+    run: (a, ctx) => draft(a, ctx, { action: "create_tax_invoice", items: [selected(a, invoiceItemKeys)] })
+  },
+  {
+    name: "draft_invoice_receipt",
+    description: `${DRAFT} Drafts an invoice-receipt, with its payment, to an existing customer from list_invoicing_customers.`,
+    inputSchema: schema({ ...invoiceProperties, ...paymentProperties }, [...invoiceRequired, ...paymentRequired]),
+    run: (a, ctx) => draft(a, ctx, {
+      action: "create_invoice_receipt",
+      items: [{ ...selected(a, invoiceItemKeys), payment: paymentOf(a) }]
+    })
+  },
+  {
+    name: "draft_receipt",
+    description: `${DRAFT} Drafts a receipt against an existing invoice.`,
+    inputSchema: schema(
+      {
+        integrationId,
+        targetDocumentId: documentId,
+        amountMinor,
+        withholdingMinor: { type: "integer", description: "withholding tax at source, minor units" },
+        ...paymentProperties,
+        recipients
+      },
+      ["integrationId", "targetDocumentId", ...paymentRequired]
+    ),
+    run: (a, ctx) => draft(a, ctx, {
+      action: "create_receipt",
+      items: [{ ...selected(a, ["targetDocumentId", "amountMinor", "withholdingMinor", "recipients"]), payment: paymentOf(a) }]
+    })
+  },
+  {
+    name: "draft_credit_note",
+    description: `${DRAFT} Drafts credit notes against existing invoices, each for at most what remains uncredited.`,
+    inputSchema: schema(
+      {
+        integrationId,
+        recipients,
+        items: {
+          type: "array",
+          description: "1\u201350 credit notes",
+          items: {
+            type: "object",
+            properties: { targetDocumentId: documentId, amountMinor, reason: { type: "string" } },
+            required: ["targetDocumentId"]
+          }
+        }
+      },
+      ["integrationId", "items"]
+    ),
+    run: (a, ctx) => draft(a, ctx, {
+      action: "create_credit_note",
+      items: Array.isArray(a.items) ? a.items.map((item) => ({
+        ...item !== null && typeof item === "object" ? item : {},
+        ...a.recipients === void 0 ? {} : { recipients: a.recipients }
+      })) : []
+    })
+  }
+];
+var LOCAL_TOOLS = [...TOOLS, ...INTEGRATION_TOOLS];
+var LOCAL_BY_NAME = new Map(LOCAL_TOOLS.map((t) => [t.name, t]));
+function callLocalTool(name, args, io) {
+  return dispatchTool(LOCAL_BY_NAME, name, args, io);
+}
+
+// src/mcp/server.ts
+async function startMcpServer(env) {
+  const server = new Server(
+    { name: "financy", version: VERSION },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: LOCAL_TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callLocalTool(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,7 +1,7 @@
 {
   "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",
+  "version": "0.4.1",
+  "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"

package/skills/financy-setup/SKILL.md

@@ -45,7 +45,7 @@ These are not optional and they apply to every step below.
 The financy data API is a paid feature. To finish this skill the user must have:
 
 1. A registered Financy account at <https://open-finance.ai>.
-2. A **paid plan** — Starter or Pro. The data API is not available on the free
+2. A **paid plan** — Starter, Pro, or Ultra. The data API is not available on the free
    plan.
 3. Three values from the Financy app → **Settings → API**: `clientId`,
    `clientSecret`, and `userId`.
@@ -143,6 +143,32 @@ If anything looks stale, do not refresh on your own initiative. Hand off to the
 `freshness-check` skill, which knows how to weigh staleness against the 20-credit
 cost.
 
+## Business systems (invoicing)
+
+The invoicing commands need CLI **0.4.0** or later (`financy --version`; `financy update` if older).
+
+Besides bank and card data, the same credentials read a connected invoicing
+system — Invoice4U today. If the user mentions invoices, receipts, customers or
+"who owes me", check what is connected:
+
+```bash
+financy integrations list --json
+```
+
+- An empty list means nothing is connected yet. The user connects Invoice4U in the
+  Financy app, on the **Connections** page; the CLI cannot connect it.
+- Exit `4` with `"code":"UPGRADE_REQUIRED"` means invoicing needs a paid plan
+  (Starter and above). Treat it like *Handling exit 4* below.
+- An unknown-command error means the installed CLI predates these commands —
+  run `financy update`.
+
+Once connected: `financy receivables` (who owes what), `financy documents list
+<integrationId>`, `financy customers list <integrationId>`, and
+`financy proposals list|get`. `financy proposals create <integrationId> --file
+draft.json` only creates a **draft**: nothing is issued until the user approves it
+in Financy at the printed approval link. Never describe a draft as an issued
+invoice, and never try to approve it yourself — the CLI cannot.
+
 ## Handling exit 4
 
 Exit `4` (`NOT_AVAILABLE_ON_PLAN`) means the account is registered and the
@@ -150,8 +176,8 @@ credentials are correct, but the plan does not include the data API.
 
 Tell the user, in plain terms:
 
-> Your credentials are valid, but the data API needs a paid plan (Starter or
-> Pro). You can upgrade at <https://open-finance.ai> — the credentials are
+> Your credentials are valid, but the data API needs a paid plan (Starter, Pro,
+> or Ultra). You can upgrade at <https://open-finance.ai> — the credentials are
 > already saved, so `financy status` will work as soon as the plan is active.
 
 Then stop. Do not retry the command, do not ask for different credentials, and
@@ -193,6 +219,9 @@ same surface is available as tools. Register it once:
 claude mcp add financy -- npx financy mcp
 ```
 
-The server resolves credentials exactly as the CLI does. Until setup is
+The server resolves credentials exactly as the CLI does. It also serves the
+invoicing tools (`list_integrations`, `get_receivables`, `list_invoicing_documents`,
+`draft_invoice`, …); a `draft_*` tool creates a draft the user must approve in
+Financy before anything is issued. Until setup is
 complete, every tool returns a structured `NOT_CONFIGURED` error — which is your
 signal to run this skill.