@bananasplitapp/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BananaSplit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# BananaSplit CLI
+
+Standalone access to the BananaSplit API for people and shell-enabled agents.
+
+## Install
+
+macOS and Linux (no Bun or Node required):
+
+```sh
+curl -fsSL https://github.com/teotti/banana-cli/releases/latest/download/install.sh | sh
+```
+
+Windows PowerShell (no Bun or Node required):
+
+```powershell
+irm https://github.com/teotti/banana-cli/releases/latest/download/install.ps1 | iex
+```
+
+Or install the TypeScript package with [Bun](https://bun.sh):
+
+```sh
+bun install -g @bananasplitapp/cli
+```
+
+Set `BANANA_INSTALL_DIR` to choose a different destination. To install a
+specific standalone release instead of the latest:
+
+```sh
+curl -fsSL https://github.com/teotti/banana-cli/releases/latest/download/install.sh \
+  | BANANA_VERSION=v0.1.0 sh
+```
+
+```powershell
+$env:BANANA_VERSION = "v0.1.0"
+irm https://github.com/teotti/banana-cli/releases/latest/download/install.ps1 | iex
+```
+
+Release downloads are verified against the published SHA-256 checksums before
+an existing installation is replaced.
+
+## Setup
+
+Set your BananaSplit session token:
+
+```sh
+export BANANASPLIT_TOKEN="your-bearer-session-token"
+# Optional; defaults to production:
+export BANANASPLIT_API_URL="http://localhost:8080"
+```
+
+## Usage
+
+Run `banana` from any directory:
+
+```sh
+banana me
+banana balance
+banana balances
+banana currencies
+banana friends
+banana groups
+banana groups members GROUP_ID
+banana groups activities GROUP_ID --search dinner
+banana expenses list
+banana expenses get EXPENSE_ID
+banana payments get PAYMENT_ID
+```
+
+List expenses across the authenticated account, sorted by date or amount:
+
+```sh
+banana expenses list --sort amount --direction desc --limit 10
+banana expenses list --recurring --sort date --direction asc
+banana expenses list --no-recurring --json
+```
+
+Omit both recurring flags to include all expenses. In the interactive browser,
+reaching the last item loads and appends the next page with the same sorting,
+filtering, and page size. Outside the browser, use `--cursor CURSOR` with the
+same options to retrieve the next page. JSON output includes `items`, `hasMore`, and
+`nextCursor`. Each item includes `share`, the current user's share amount,
+and `isRecurring`. Full splits are available through expense details.
+
+Create groups, expenses, and payments with explicit API IDs:
+
+```sh
+banana groups create --name "Lisbon trip" --currency-id CURRENCY_ID \
+  --type travel --member USER_ID
+
+banana expenses add --title Dinner --amount 42 --currency-id CURRENCY_ID \
+  --paid-by-id USER_ID --date 2026-09-01 --group-id GROUP_ID \
+  --split-type custom --split USER_ID=22 --split FRIEND_ID=20
+
+banana payments add --amount 20 --currency-id CURRENCY_ID \
+  --from-user-id USER_ID --to-user-id FRIEND_ID --date 2026-09-01 \
+  --description "Settle up"
+```
+
+Edit an expense in place. Only the fields you pass change; everything else
+keeps its current value:
+
+```sh
+banana expenses edit EXPENSE_ID --title "Chinese dinner"
+banana expenses edit EXPENSE_ID --group-id GROUP_ID
+banana expenses edit EXPENSE_ID --amount 60 --split USER_ID=30 --split FRIEND_ID=30
+banana expenses edit EXPENSE_ID '{"description":null}'
+```
+
+Moving an expense into a group with `--group-id` clears its direct friendship
+link; `--no-group` does the reverse. Changing `--amount` on an equal split
+redistributes the splits automatically; any other split type needs matching
+`--split` values.
+
+Each create command also accepts its API body as one quoted JSON object:
+
+```sh
+banana groups create '{"name":"Lisbon trip","currencyId":"CURRENCY_ID"}'
+banana expenses add '{"title":"Dinner","amount":"42","currencyId":"CURRENCY_ID","paidById":"USER_ID","date":"2026-09-01","splits":[{"userId":"USER_ID","amount":"42"}]}'
+banana payments add '{"amount":"20","currencyId":"CURRENCY_ID","fromUserId":"USER_ID","toUserId":"FRIEND_ID","date":"2026-09-01"}'
+```
+
+Direct expenses require at least one `--split USER_ID=AMOUNT`. Group expenses
+may omit `--split` to use the group's configured default split.
+
+Commands print a clean, human-readable summary by default. Use `--json` for
+the same operational fields as compact JSON, or `--raw` for the complete API
+response:
+
+```sh
+banana me
+banana --json groups list --limit 10
+banana groups get GROUP_ID --raw
+```
+
+The output flag may appear before or after the command. `--json` and `--raw`
+cannot be used together.
+
+In an interactive terminal, `balance users`, `friends list`, `groups list`, `expenses list`,
+`groups members`, and `groups activities` open searchable browsers; type to
+filter, use the arrow keys to select an item, press Enter to open its details,
+Esc to return, and `q` to quit. In a non-interactive command card, friend and
+group lists fall back to five items and print a copyable `Next page` cursor
+command. Expense lists also default to five items outside the browser and show
+the next cursor. In the browser they use the API's default page size and load
+more as you reach the end. Search filters all loaded expenses; press ↓ at the
+end (or when no items match) to load another page. If loading fails, press ↓
+to retry. Use `--limit N` to choose a page size.
+
+## Development
+
+Install Bun, clone this repository, then install dependencies and expose
+`banana` on your path:
+
+```sh
+bun install
+bun link
+banana --help
+```
+
+Run the checks with:
+
+```sh
+bun test
+bun run typecheck
+```
+
+## Releasing
+
+The repository must be public and the `@bananasplitapp` npm organization must
+exist before the first release. Store a temporary granular npm publishing
+token with bypass 2FA as the `NPM_TOKEN` repository secret, update the version
+in `package.json`, then push its matching stable tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The tag workflow tests all targets, publishes the GitHub release, and publishes
+the npm package. After the first npm release, configure `release.yml` as the
+package's trusted GitHub Actions publisher and remove `NPM_TOKEN`; subsequent
+publishes use OIDC automatically.
+
+Configuration, network, API, and usage errors are written to stderr. Human
+commands print `Error: MESSAGE`, `--json` prints a structured error object, and
+`--raw` prints the API error body when available.
+Session tokens currently expire after 90 days; interactive login and stored
+credentials are not included in this first version.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bananasplitapp/cli",
+  "description": "Command-line access to the BananaSplit API",
+  "type": "module",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teotti/banana-cli.git"
+  },
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "banana": "./src/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "banana": "bun run ./src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,360 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { emitKeypressEvents } from "node:readline";
+import { asArray, asRecord, display } from "./shared";
+import {
+  CliFailure,
+  type BrowserDetailLoader,
+  type BrowserPageLoader,
+  type BrowserPresentation,
+  type Presentation,
+} from "./types";
+
+const PAGER_PROMPT = "↑/↓ navigate · q quit";
+const ANSI = {
+  bold: "\x1b[1m",
+  yellow: "\x1b[38;2;255;228;0m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  reset: "\x1b[0m",
+};
+
+type BrowserDetailState =
+  | { status: "loading"; title: string }
+  | { status: "loaded"; title: string; value: string }
+  | { status: "error"; title: string; message: string };
+
+export function hasInteractivePager() {
+  if (process.env.CI || spawnSync("less", ["--version"]).status !== 0) {
+    return false;
+  }
+  try {
+    const terminal = openSync("/dev/tty", "r+");
+    closeSync(terminal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function pageWithLess(value: string) {
+  let terminal: number;
+  try {
+    terminal = openSync("/dev/tty", "r+");
+  } catch {
+    return false;
+  }
+
+  try {
+    const pager = spawn("less", ["-X", "-Q", `-Ps${PAGER_PROMPT}`], {
+      stdio: ["pipe", terminal, terminal],
+    });
+    const exited = new Promise<boolean>((resolve) => {
+      pager.once("error", () => resolve(false));
+      pager.once("close", (code) => resolve(code === 0));
+    });
+    if (!pager.stdin) {
+      pager.kill();
+      return false;
+    }
+    pager.stdin.end(`${value}\n`);
+    return await exited;
+  } finally {
+    closeSync(terminal);
+  }
+}
+
+export function isListPresentation(presentation: Presentation) {
+  return (
+    presentation === "balance-users" ||
+    presentation === "currency-list" ||
+    presentation === "expense-list" ||
+    presentation === "friend-list" ||
+    presentation === "group-list" ||
+    presentation === "members" ||
+    presentation === "activities"
+  );
+}
+
+export function isBrowserPresentation(
+  presentation: Presentation,
+): presentation is BrowserPresentation {
+  return (
+    presentation === "expense-list" ||
+    presentation === "balance-users" ||
+    presentation === "friend-list" ||
+    presentation === "group-list" ||
+    presentation === "members" ||
+    presentation === "activities"
+  );
+}
+
+function browserItems(presentation: BrowserPresentation, body: unknown) {
+  return asArray(
+    presentation === "group-list" ||
+    presentation === "friend-list" ||
+    presentation === "expense-list"
+      ? asRecord(body).items
+      : body,
+  ).map(asRecord);
+}
+
+function filterBrowserItems(
+  presentation: BrowserPresentation,
+  body: unknown,
+  query: string,
+) {
+  const normalizedQuery = query.trim().toLowerCase();
+  return browserItems(presentation, body).filter((item) =>
+    JSON.stringify(item).toLowerCase().includes(normalizedQuery),
+  );
+}
+
+function browserItemTitle(
+  presentation: BrowserPresentation,
+  item: Record<string, unknown>,
+) {
+  if (presentation === "balance-users" || presentation === "friend-list") {
+    return display(asRecord(item.user).name);
+  }
+  if (presentation === "group-list" || presentation === "members") {
+    return display(item.name);
+  }
+  return item.entity === "payment"
+    ? `Payment: ${display(item.description)}`
+    : `Expense: ${display(item.title)}`;
+}
+
+export function renderCollectionBrowser(
+  presentation: BrowserPresentation,
+  body: unknown,
+  query = "",
+  selectedIndex = 0,
+  detail?: BrowserDetailState,
+  rows = Infinity,
+  pageStatus?: string,
+) {
+  if (detail) {
+    return [
+      `${ANSI.bold}${ANSI.yellow}BANANA${ANSI.reset}`,
+      "",
+      `◆ ${ANSI.bold}${detail.title}${ANSI.reset}`,
+      `  ${ANSI.dim}esc/← back · q quit${ANSI.reset}`,
+      "",
+      detail.status === "loading"
+        ? `${ANSI.dim}Loading details…${ANSI.reset}`
+        : detail.status === "error"
+          ? `Unable to load details: ${detail.message}`
+          : detail.value,
+    ].join("\n");
+  }
+
+  const response = asRecord(body);
+  const normalizedQuery = query.trim().toLowerCase();
+  const allItems = browserItems(presentation, body);
+  const items = filterBrowserItems(presentation, body, query);
+  const activeIndex = Math.min(selectedIndex, Math.max(items.length - 1, 0));
+  const visibleCount = Math.max(1, rows - 13);
+  const start = Math.max(0, activeIndex - visibleCount + 1);
+  const label = {
+    "balance-users": "user balances",
+    "friend-list": "friends",
+    "group-list": "groups",
+    "expense-list": "expenses",
+    members: "group members",
+    activities: "group activities",
+  }[presentation];
+  const count = `${ANSI.green}${items.length}${
+    normalizedQuery ? `/${allItems.length}` : ""
+  }${ANSI.reset}`;
+  const lines = [
+    `${ANSI.bold}${ANSI.yellow}BANANA${ANSI.reset}`,
+    "",
+    `┌─ ${ANSI.yellow} ${label} ${ANSI.reset}`,
+    "│",
+    `◇ Found ${count} ${label}`,
+    "│",
+    `◆ ${ANSI.bold}Browse ${label}${ANSI.reset}`,
+    `  Search: ${query}${ANSI.yellow}█${ANSI.reset}`,
+    `  ${ANSI.dim}↑↓ move · type search · enter/→ details · esc/← clear · q quit${ANSI.reset}`,
+    "",
+    ...(items.length
+      ? items.slice(start, start + visibleCount).map(
+          (item, index) =>
+            `${start + index === activeIndex ? `${ANSI.yellow}› ●${ANSI.reset}` : "  ○"} ${browserItemTitle(presentation, item)}`,
+        )
+      : [`  ${ANSI.dim}No matching ${label}.${ANSI.reset}`]),
+  ];
+
+  if (pageStatus) {
+    lines.push("", pageStatus);
+  } else if (
+    (presentation === "group-list" ||
+      presentation === "friend-list" ||
+      presentation === "expense-list") &&
+    response.hasMore
+  ) {
+    lines.push(
+      "",
+      `${ANSI.dim}${presentation === "expense-list"
+        ? "Reach the last item to load more expenses (↓ to continue)."
+        : `More ${label} are available from the API.`}${ANSI.reset}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+export function renderGroupBrowser(
+  body: unknown,
+  query = "",
+  selectedIndex = 0,
+) {
+  return renderCollectionBrowser("group-list", body, query, selectedIndex);
+}
+
+export function hasInteractiveBrowser() {
+  return Boolean(
+    !process.env.CI &&
+      process.stdin.isTTY &&
+      process.stdout.isTTY &&
+      typeof process.stdin.setRawMode === "function",
+  );
+}
+
+export async function browseCollection(
+  presentation: BrowserPresentation,
+  body: unknown,
+  loadDetail: BrowserDetailLoader,
+  loadPage?: BrowserPageLoader,
+) {
+  if (!hasInteractiveBrowser()) return false;
+
+  const input = process.stdin;
+  const output = process.stdout;
+  const wasRaw = input.isRaw;
+  let query = "";
+  let selectedIndex = 0;
+  let detail: BrowserDetailState | undefined;
+  let detailGeneration = 0;
+  let finished = false;
+  let loadingPage = false;
+  let pageStatus: string | undefined;
+
+  emitKeypressEvents(input);
+  input.setRawMode(true);
+  input.resume();
+  output.write("\x1b[?1049h\x1b[?25l");
+
+  return await new Promise<boolean>((resolve) => {
+    const draw = () => {
+      if (finished) return;
+      output.write(
+        `\x1b[H\x1b[2J${renderCollectionBrowser(presentation, body, query, selectedIndex, detail, output.rows, pageStatus)}`,
+      );
+    };
+    const finish = () => {
+      finished = true;
+      detailGeneration++;
+      input.off("keypress", onKeypress);
+      process.off("SIGWINCH", draw);
+      input.setRawMode(wasRaw);
+      input.pause();
+      output.write("\x1b[?25h\x1b[?1049l");
+      resolve(true);
+    };
+    const openDetail = async (item: Record<string, unknown>) => {
+      const generation = ++detailGeneration;
+      const title = browserItemTitle(presentation, item);
+      detail = { status: "loading", title };
+      draw();
+      try {
+        const value = await loadDetail(item);
+        if (finished || generation !== detailGeneration) return;
+        detail = { status: "loaded", title, value };
+      } catch (error) {
+        if (finished || generation !== detailGeneration) return;
+        detail = {
+          status: "error",
+          title,
+          message:
+            error instanceof CliFailure ? error.message : "Unexpected error",
+        };
+      }
+      draw();
+    };
+    const loadNextPage = async () => {
+      const response = asRecord(body);
+      const cursor = response.nextCursor;
+      if (finished || loadingPage || !loadPage || !response.hasMore ||
+          typeof cursor !== "string" || !cursor) return;
+      loadingPage = true;
+      pageStatus = "Loading more expenses…";
+      draw();
+      try {
+        const page = asRecord(await loadPage(cursor));
+        if (finished) return;
+        if (page.hasMore && page.nextCursor === cursor) {
+          throw new CliFailure("api", "Expense pagination did not advance");
+        }
+        body = { ...page, items: [...asArray(response.items), ...asArray(page.items)] };
+        pageStatus = undefined;
+      } catch (error) {
+        if (finished) return;
+        pageStatus = `Unable to load more expenses: ${error instanceof CliFailure
+          ? error.message : "Unexpected error"}. Press ↓ to retry.`;
+      } finally {
+        loadingPage = false;
+      }
+      draw();
+    };
+    const onKeypress = (
+      text: string,
+      key: { ctrl?: boolean; meta?: boolean; name?: string },
+    ) => {
+      const itemCount = filterBrowserItems(presentation, body, query).length;
+      if ((key.ctrl && key.name === "c") || key.name === "q") {
+        finish();
+        return;
+      }
+      if (detail) {
+        if (key.name === "escape" || key.name === "left") {
+          detailGeneration++;
+          detail = undefined;
+          draw();
+        }
+        return;
+      }
+      if (key.name === "escape" || key.name === "left") {
+        query = "";
+        selectedIndex = 0;
+      } else if (key.name === "up") {
+        selectedIndex = Math.max(0, selectedIndex - 1);
+      } else if (key.name === "down") {
+        selectedIndex = Math.min(Math.max(itemCount - 1, 0), selectedIndex + 1);
+        if (selectedIndex >= itemCount - 1) void loadNextPage();
+      } else if (key.name === "backspace" || key.name === "delete") {
+        query = query.slice(0, -1);
+        selectedIndex = 0;
+      } else if (key.name === "return" || key.name === "enter" || key.name === "right") {
+        const items = filterBrowserItems(presentation, body, query);
+        const selected = items[Math.min(selectedIndex, items.length - 1)];
+        if (selected) void openDetail(selected);
+        return;
+      } else if (
+        text &&
+        !key.ctrl &&
+        !key.meta &&
+        text >= " " &&
+        text !== "\x7f"
+      ) {
+        query += text;
+        selectedIndex = 0;
+      }
+      draw();
+    };
+
+    input.on("keypress", onKeypress);
+    process.on("SIGWINCH", draw);
+    draw();
+  });
+}