financy 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "financy",
+  "version": "0.1.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"
+  },
+  "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": {
+    "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": "^2.0.5"
+  }
+}

package/skills/financy-setup/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: financy-setup
+description: >
+  Onboard a user onto the financy CLI so their Open-Finance banking data is
+  available to you. Use when the user asks to "set up financy", "connect my
+  bank data", "configure the financy CLI", when any financy command fails with
+  a NOT_CONFIGURED or AUTH error, or when you need account/transaction data and
+  no working financy credentials exist yet. Covers installing the CLI, locating
+  clientId/clientSecret/userId in the Financy app, saving them without ever
+  reading the secret, verifying the result, and explaining the paid-plan
+  requirement when the account is not eligible.
+---
+
+# financy setup
+
+Get the `financy` CLI configured and verified for this user. When you are done,
+`financy status` exits `0` and every other financy command works.
+
+**Minimum CLI version:** 0.1.0
+
+## Guardrails
+
+These are not optional and they apply to every step below.
+
+- **Never handle the client secret at all.** Do not ask the user to paste it into
+  the conversation, and never place it in a command you run — a command you run
+  is recorded in the transcript, and it is visible in shell history and to
+  anything that can list processes. The user types the secret into
+  `financy setup`, which masks it at the prompt; you never see it. If the user
+  pastes it anyway, do not repeat it, do not use it in a command, and tell them
+  to rotate it in Financy → Settings → API. Never print it, read it back for
+  confirmation, or include it in a summary, and never `cat` the config file.
+- **Confirm before spending credits.** `financy refresh` costs 20 credits per
+  run. Never run it without the user explicitly agreeing to that cost in this
+  conversation.
+- **Exit code 4 means the plan, not the credentials.** The credentials are
+  valid but the account is not on a paid plan. Do not retry, do not suggest
+  re-entering the credentials — point the user at the upgrade path and stop.
+
+## What the user needs before you start
+
+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
+   plan.
+3. Three values from the Financy app → **Settings → API**: `clientId`,
+   `clientSecret`, and `userId`.
+
+If the user does not have a paid plan yet, say so up front rather than letting
+them collect credentials that will fail at the last step.
+
+## Method
+
+### 1. Check whether it is already configured
+
+```bash
+financy status --json
+```
+
+Branch on the exit code:
+
+- `0` — already configured and working. Report the connection summary and stop;
+  there is nothing to set up.
+- `3` with `"code":"NOT_CONFIGURED"` — no credentials yet. Continue to step 2.
+- `3` with any other code — credentials exist but are rejected. Continue to
+  step 2 to replace them.
+- `4` — credentials are fine, the plan is not. Jump to *Handling exit 4*.
+- `127` / command-not-found — the CLI is not installed. Continue to step 2.
+
+### 2. Make the CLI available
+
+Prefer a global install so later sessions do not re-download it:
+
+```bash
+npm install -g financy
+```
+
+If the user cannot or does not want to install globally, every command in this
+skill also works as `npx financy <command>`.
+
+### 3. Have the user run setup themselves
+
+**Do not collect the credentials and run setup for them.** Ask the user to run
+this in their own terminal:
+
+```bash
+financy setup
+```
+
+It prompts for `clientId`, `clientSecret` and `userId` in turn, and **masks the
+secret as they type it** — so the secret goes straight from the user to the CLI
+and never passes through you, this conversation, or a command line. Tell them
+where to find the three values: the Financy app → **Settings → API**.
+
+`setup` validates the credentials against the live API before saving, so a wrong
+value fails immediately rather than on their first real command. On success it
+writes `~/.config/financy/config.json` with permissions `600` and prints the path.
+
+Ask the user to tell you the exit code or what it printed — that is all you need.
+Do not ask them to paste any of the three values.
+
+Exit codes from `setup`:
+
+- `0` — saved and verified.
+- `3` — the credentials were rejected. Ask them to run `financy setup` again and
+  re-copy the values; a partial paste or a stray space is the usual cause.
+- `4` — the credentials are valid but the plan is not eligible. The CLI still
+  saves them so a later upgrade works immediately. Go to *Handling exit 4*.
+- `7` — the API could not be reached. This is a network or endpoint problem, not
+  a credential problem; retry once, then report it.
+
+### 5. Verify
+
+```bash
+financy status
+```
+
+Exit `0` with a connection table means setup is done. Report what you see:
+how many connections there are, and whether any are stale or in error. If the
+user has no connections yet, tell them to connect a bank in the Financy app —
+the CLI reads data, it does not create connections.
+
+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.
+
+## Handling exit 4
+
+Exit `4` (`NOT_AVAILABLE_ON_PLAN`) means the account is registered and the
+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
+> 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
+do not look for a workaround.
+
+## Non-interactive and CI environments
+
+If `FINANCY_CLIENT_ID`, `FINANCY_CLIENT_SECRET` and `FINANCY_USER_ID` are
+**already present in the environment** — put there by CI, a secret manager, or
+the user's own shell profile — the CLI reads them directly and no config file is
+needed. There is nothing for you to do; just run `financy status` and continue.
+
+`financy setup --no-input` reads those same variables and persists them for
+future sessions. Use it only when the environment already carries them. Never
+set them yourself as a prefix to the command in order to pass along a secret the
+user gave you — `FINANCY_CLIENT_SECRET=… financy setup --no-input` puts the
+secret in the command line, which defeats the whole point. In that situation the
+answer is always step 3: let the user run `financy setup` and type it.
+
+To see which endpoints and credential sources are in effect without exposing
+the secret:
+
+```bash
+financy config
+```
+
+It prints the resolved endpoints and marks each credential as coming from the
+environment or the config file, with the secret masked.
+
+## MCP alternative
+
+If the user runs agents against the financy MCP server instead of the CLI, the
+same surface is available as tools. Register it once:
+
+```bash
+claude mcp add financy -- npx financy mcp
+```
+
+The server resolves credentials exactly as the CLI does. Until setup is
+complete, every tool returns a structured `NOT_CONFIGURED` error — which is your
+signal to run this skill.

package/skills/freshness-check/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: freshness-check
+description: >
+  Decide whether the user's Open-Finance banking data is current enough to
+  answer with, and offer a refresh when it is not. Use before any analysis that
+  depends on recent transactions or balances ("what did I spend this week",
+  "what is my balance", "did the card charge clear"), and whenever the user asks
+  "is my data up to date", "why is this missing", "refresh my accounts", or a
+  recent transaction they expect is absent. Interprets financy status --json,
+  applies the staleness threshold, and confirms the 20-credit cost with the user
+  before ever triggering financy refresh.
+---
+
+# freshness check
+
+Answer one question — *is this data current enough to use?* — and act on the
+answer. Every analysis skill that reads financy data should start here.
+
+**Minimum CLI version:** 0.1.0
+
+## Guardrails
+
+- **Confirm before spending credits.** `financy refresh` costs **20 credits**
+  every time it is called. Never run it without stating the cost and getting an
+  explicit yes from the user in this conversation. "The data is stale, want me
+  to refresh?" is not enough — say the number.
+- **Never echo the client secret** or the contents of the config file. If you
+  need to show what is configured, use `financy config`, which masks the secret.
+- **Exit code 4 means the plan, not the credentials.** Point the user at the
+  upgrade path at <https://open-finance.ai> and stop; do not retry and do not
+  ask for new credentials.
+
+## Method
+
+### 1. Read the status
+
+```bash
+financy status --json
+```
+
+The envelope:
+
+```json
+{
+  "data": [
+    {
+      "provider": "hapoalim",
+      "status": "ACTIVE",
+      "fresh": "2026-08-01",
+      "expires": "2026-11-14",
+      "accounts": 3
+    }
+  ],
+  "staleThresholdDays": 2
+}
+```
+
+Per row:
+
+- `provider` — the bank or card issuer. `null` while a connection is still
+  being established.
+- `status` — `ACTIVE` means the connection itself is healthy. Anything else is
+  a broken connection, not a staleness problem.
+- `fresh` — the date the data runs through, as `YYYY-MM-DD`. `null` means the
+  connection has never fetched anything.
+- `expires` — when the user's bank consent lapses. Not a freshness signal, but
+  worth surfacing when it is close.
+- `accounts` — how many accounts, cards, savings, loans and securities this
+  connection covers.
+
+`staleThresholdDays` is the CLI's own threshold (2 days). Read it from the
+response rather than hard-coding it.
+
+Handle the exit code before the body: `3` → the CLI is not configured or the
+credentials are rejected, so run the `financy-setup` skill instead; `4` → see
+the guardrail above; `7` → the API is unreachable, retry once then report.
+
+### 2. Classify each connection
+
+Compare `fresh` to today, in whole calendar days:
+
+| Condition | Meaning | What to do |
+|---|---|---|
+| `status` is not `ACTIVE` | The connection is broken | A refresh will not fix it — the user must reconnect the bank in the Financy app |
+| `fresh` is `null` | Never fetched | A refresh is worth offering; if it has been pending a long time, reconnecting is more likely to help |
+| days since `fresh` ≤ `staleThresholdDays` | Fresh | Proceed with the analysis |
+| days since `fresh` > `staleThresholdDays` | Stale | Offer a refresh (step 3) |
+
+Weigh this against what the user actually asked. Banks post transactions with a
+lag, so a one-day-old feed is normal and a weekend gap is expected. Two facts
+matter more than the raw number:
+
+- **How stale relative to the question.** "What did I spend last month" is fine
+  on three-day-old data. "Did this morning's transfer land" is not.
+- **Which connection is stale.** If only an unrelated card is behind, say so and
+  carry on rather than refreshing everything.
+
+### 3. Offer the refresh
+
+When a refresh would genuinely help, ask — with the cost stated:
+
+> Your Hapoalim data runs through 2026-07-28, which is 6 days old. I can trigger
+> a refresh, which costs **20 credits** and takes a few minutes. Want me to?
+
+Only after an explicit yes:
+
+```bash
+financy refresh --json
+```
+
+Notes on the behaviour:
+
+- Refresh is **org-wide** — it refreshes every connection, not the one you named.
+  Say that when you ask, so 20 credits does not read as a per-bank price.
+- `{"data":{"status":"already_running"}}` means a refresh was already in flight.
+  No new charge; just wait.
+- It is asynchronous. Data lands in a few minutes; `financy refresh` returning
+  does not mean the data is there. Poll `financy status --json` and watch `fresh`
+  advance.
+- Exit `5` (`INSUFFICIENT_CREDITS`) — the account is out of credits. Tell the
+  user and stop.
+
+### 4. Report and proceed
+
+Say what you found before you answer the actual question, in one line — for
+example *"Data is current through yesterday across all 3 banks"* or *"Leumi is
+4 days behind; the rest are current, so the card analysis below is complete but
+the checking-account view may be missing a few days."*
+
+If the user declines the refresh, proceed with the stale data and state the
+as-of date in your answer. Do not silently analyse stale data as if it were
+current.
+
+## MCP alternative
+
+Against the financy MCP server the same flow is `get_status` followed, only
+after confirmation, by `refresh_connections`. The envelopes are identical to the
+CLI's `--json` output. `refresh_connections` carries the 20-credit warning in its
+tool description — treat that as binding, not advisory.