@bananasplitapp/cli 0.1.0

package/src/cli.ts

@@ -0,0 +1,289 @@
+import {
+  browseCollection,
+  hasInteractiveBrowser,
+  hasInteractivePager,
+  isBrowserPresentation,
+  isListPresentation,
+  pageWithLess,
+} from "./browser";
+import { balancePresenters, parseBalance } from "./commands/balance";
+import { currencyPresenters, parseCurrencies } from "./commands/currencies";
+import {
+  expensePresenters,
+  mergeExpenseBody,
+  parseExpenses,
+} from "./commands/expenses";
+import { friendPresenters, parseFriends } from "./commands/friends";
+import { groupPresenters, parseGroups } from "./commands/groups";
+import { mePresenters, parseMe } from "./commands/me";
+import { parsePayments, paymentPresenters } from "./commands/payments";
+import { DEFAULT_API_URL, REQUEST_TIMEOUT_MS, request } from "./request";
+import { asArray, asRecord } from "./shared";
+import {
+  CliFailure,
+  type CliRuntime,
+  type CommandParser,
+  type OutputMode,
+  type Presentation,
+  type Presenter,
+  type RequestCommand,
+} from "./types";
+
+const ROOT_HELP = `Usage: banana [--json | --raw] <command>
+
+Commands:
+  me                         Show the authenticated user
+  balance                    Show the aggregate balance
+  balance users              Show balances by user
+  balances                   Show balances by user
+  currencies [list]          List currencies
+  friends [list]             List friends
+  groups [list]              List groups
+  groups create              Create a group
+  groups get <group-id>      Show a group
+  groups members <group-id>  List group members
+  groups activities <group-id>
+                             List group activities
+  expenses list              List the authenticated user's expenses
+  expenses add               Add an expense
+  expenses get <expense-id>  Show an expense
+  expenses edit <expense-id> Edit an expense
+  payments add               Add a payment
+  payments get <payment-id>  Show a payment
+
+Output:
+  --json                     Print curated operational JSON
+  --raw                      Print the complete API response as JSON
+
+Environment:
+  BANANASPLIT_TOKEN          Required bearer session token
+  BANANASPLIT_API_URL        API base URL (default: ${DEFAULT_API_URL})`;
+
+const COMMANDS: Record<string, CommandParser> = {
+  balance: parseBalance,
+  currencies: parseCurrencies,
+  expenses: parseExpenses,
+  friends: parseFriends,
+  groups: parseGroups,
+  me: parseMe,
+  payments: parsePayments,
+};
+
+const PRESENTERS: Record<Presentation, Presenter> = {
+  ...mePresenters,
+  ...balancePresenters,
+  ...currencyPresenters,
+  ...friendPresenters,
+  ...groupPresenters,
+  ...expensePresenters,
+  ...paymentPresenters,
+};
+
+function parseOutputFlags(args: string[]) {
+  const commandArgs = args.filter((arg) => arg !== "--json" && arg !== "--raw");
+  const json = args.includes("--json");
+  const raw = args.includes("--raw");
+  if (json && raw) {
+    throw new CliFailure("usage", "Choose only one of --json or --raw");
+  }
+  return {
+    args: commandArgs,
+    mode: (raw ? "raw" : json ? "json" : "human") as OutputMode,
+  };
+}
+
+function parseCommand(args: string[]) {
+  if (
+    args.length === 0 ||
+    args[0] === "--help" ||
+    args[0] === "-h" ||
+    args[0] === "help"
+  ) {
+    return { kind: "help" as const, text: ROOT_HELP };
+  }
+  if (args[0] === "balances") args = ["balance", "users", ...args.slice(1)];
+  const [name, ...rest] = args;
+  const parser = COMMANDS[name];
+  if (!parser) throw new CliFailure("usage", ROOT_HELP);
+  return parser(rest);
+}
+
+function serializeFailure(error: unknown, mode: OutputMode) {
+  const failure =
+    error instanceof CliFailure
+      ? error
+      : new CliFailure(
+          "network",
+          error instanceof Error ? error.message : String(error),
+        );
+  const json = JSON.stringify({
+    error: {
+      type: failure.type,
+      ...(failure.status === undefined ? {} : { status: failure.status }),
+      message: failure.message,
+      ...(failure.body === undefined ? {} : { body: failure.body }),
+    },
+  });
+  return {
+    exitCode: failure.type === "usage" ? 2 : 1,
+    output:
+      mode === "human"
+        ? `Error: ${failure.message}`
+        : mode === "raw" &&
+            failure.type === "api" &&
+            failure.body !== undefined &&
+            failure.body !== null
+          ? JSON.stringify(failure.body)
+          : json,
+  };
+}
+
+export async function runCli(
+  args: string[],
+  runtime: CliRuntime = {},
+): Promise<number> {
+  const stdout = runtime.stdout ?? console.log;
+  const stderr = runtime.stderr ?? console.error;
+  const outputMode: OutputMode = args.includes("--json")
+    ? "json"
+    : args.includes("--raw")
+      ? "raw"
+      : "human";
+
+  try {
+    const output = parseOutputFlags(args);
+    const command = parseCommand(output.args);
+    if (command.kind === "help") {
+      stdout(command.text);
+      return 0;
+    }
+
+    const browserPresentation = isBrowserPresentation(command.presentation)
+      ? command.presentation
+      : undefined;
+    const pager =
+      output.mode === "human" && isListPresentation(command.presentation)
+        ? (runtime.pager ??
+          (runtime.stdout === undefined &&
+          !browserPresentation &&
+          hasInteractivePager()
+            ? pageWithLess
+            : undefined))
+        : undefined;
+    const browser =
+      output.mode === "human" && browserPresentation
+        ? (runtime.browser ??
+          (runtime.stdout === undefined && hasInteractiveBrowser()
+            ? browseCollection
+            : undefined))
+        : undefined;
+    const hasExplicitLimit = output.args.some(
+      (arg) => arg === "--limit" || arg.startsWith("--limit="),
+    );
+    if (
+      (pager || browser) &&
+      (command.presentation === "group-list" ||
+        command.presentation === "expense-list" ||
+        command.presentation === "friend-list") &&
+      !hasExplicitLimit
+    ) {
+      command.query?.delete("l");
+    }
+
+    const requestRuntime = {
+      fetch: runtime.fetch ?? globalThis.fetch,
+      timeoutMs: runtime.timeoutMs ?? REQUEST_TIMEOUT_MS,
+    };
+    const env = runtime.env ?? process.env;
+    if (command.mergeExpense !== undefined) {
+      const current = await request(
+        {
+          kind: "request",
+          path: command.mergeExpense,
+          presentation: "expense",
+        },
+        requestRuntime,
+        env,
+      );
+      command.body = mergeExpenseBody(
+        current,
+        asRecord(command.body) as Record<string, unknown>,
+      );
+    }
+    let body = await request(command, requestRuntime, env);
+    if (output.mode !== "raw" && command.presentation === "expense-updated") {
+      // PUT answers with a flat row, so re-read the expense for its
+      // paidBy / group / category / splits expansions.
+      body = await request(
+        {
+          kind: "request",
+          path: command.path,
+          presentation: "expense-updated",
+        },
+        requestRuntime,
+        env,
+      );
+    }
+    if (output.mode !== "raw" && command.presentation === "group") {
+      const members = await request(
+        {
+          kind: "request",
+          path: `${command.path}/members`,
+          presentation: "members",
+        },
+        requestRuntime,
+        env,
+      );
+      body = { ...asRecord(body), memberCount: asArray(members).length };
+    }
+
+    if (output.mode === "raw") {
+      stdout(JSON.stringify(body));
+      return 0;
+    }
+
+    const presenter = PRESENTERS[command.presentation];
+    const clean = presenter.clean(body);
+    if (output.mode === "json") {
+      stdout(JSON.stringify(clean));
+      return 0;
+    }
+
+    const human = presenter.format(clean);
+    const browserPresenter = presenter.browser;
+    const loadDetail = async (item: Record<string, unknown>) => {
+      if (!browserPresenter) {
+        throw new CliFailure("api", "Details are unavailable for this item");
+      }
+      const detailCommand: RequestCommand = {
+        kind: "request",
+        path: browserPresenter.detailPath(command, item),
+        presentation: command.presentation,
+      };
+      const detail = await request(detailCommand, requestRuntime, env);
+      return browserPresenter.formatDetail(item, detail);
+    };
+    const loadPage = command.presentation === "expense-list"
+      ? async (cursor: string) => {
+          const query = new URLSearchParams(command.query);
+          query.set("cursor", cursor);
+          return presenter.clean(await request(
+            { ...command, query }, requestRuntime, env,
+          ));
+        }
+      : undefined;
+    if (
+      (!browser ||
+        !browserPresentation ||
+        !(await browser(browserPresentation, clean, loadDetail, loadPage))) &&
+      (!pager || !(await pager(human)))
+    ) {
+      stdout(human);
+    }
+    return 0;
+  } catch (error) {
+    const failure = serializeFailure(error, outputMode);
+    stderr(failure.output);
+    return failure.exitCode;
+  }
+}

package/src/commands/balance.ts

@@ -0,0 +1,128 @@
+import {
+  asArray,
+  asRecord,
+  cleanUserSummary,
+  currencyCode,
+  display,
+  encodedDetailId,
+  formatCard,
+  humanAmount,
+  numeric,
+  wantsHelp,
+} from "../shared";
+import { CliFailure, type ParsedCommand, type Presenter } from "../types";
+
+const HELP = "Usage: banana balance [users]";
+
+export function parseBalance(args: string[]): ParsedCommand {
+  if (wantsHelp(args)) return { kind: "help", text: HELP };
+  if (args.length === 0) {
+    return { kind: "request", path: "/balance", presentation: "balance" };
+  }
+  if (args.length === 1 && args[0] === "users") {
+    return {
+      kind: "request",
+      path: "/balance/users",
+      presentation: "balance-users",
+    };
+  }
+  throw new CliFailure("usage", HELP);
+}
+
+function cleanBalanceUsers(body: unknown) {
+  return asArray(body).map((value) => {
+    const entry = asRecord(value);
+    return {
+      user: cleanUserSummary(entry.user),
+      balance: numeric(entry.balance),
+      totalOwed: numeric(entry.totalOwed),
+      totalOwing: numeric(entry.totalOwing),
+    };
+  });
+}
+
+function cleanBalanceDetail(body: unknown, item: Record<string, unknown>) {
+  const response = asRecord(body);
+  return {
+    user: cleanUserSummary(item.user),
+    balance: numeric(response.balance) ?? numeric(item.balance),
+    totalOwed: numeric(item.totalOwed),
+    totalOwing: numeric(item.totalOwing),
+    currency: currencyCode(response.currency),
+    breakdown: asArray(response.balanceByGroup).map((value) => {
+      const entry = asRecord(value);
+      const group = asRecord(entry.group);
+      return {
+        groupId: group.id ?? null,
+        groupName: entry.group == null ? "Direct" : group.name ?? null,
+        balance: numeric(entry.balance),
+      };
+    }),
+  };
+}
+
+export const balancePresenters = {
+  balance: {
+    clean(body) {
+      const response = asRecord(body);
+      return {
+        balance: numeric(response.balance),
+        totalOwed: numeric(response.totalOwed),
+        totalOwing: numeric(response.totalOwing),
+      };
+    },
+    format(body) {
+      const response = asRecord(body);
+      return [
+        `Balance: ${display(response.balance)}`,
+        `Owed: ${display(response.totalOwed)}`,
+        `Owing: ${display(response.totalOwing)}`,
+      ].join("\n");
+    },
+  },
+  "balance-users": {
+    clean: cleanBalanceUsers,
+    format(body) {
+      const items = asArray(body);
+      if (!items.length) return "No user balances.";
+      return [
+        "User balances",
+        ...items.map((value, index) => {
+          const entry = asRecord(value);
+          const user = asRecord(entry.user);
+          return formatCard(index, user.name, [
+            `User ID: ${display(user.id)}`,
+            `Balance: ${display(entry.balance)}`,
+            `Owed: ${display(entry.totalOwed)}`,
+            `Owing: ${display(entry.totalOwing)}`,
+          ]);
+        }),
+      ].join("\n\n");
+    },
+    browser: {
+      detailPath(_command, item) {
+        return `/users/${encodedDetailId(asRecord(item.user).id)}/balances`;
+      },
+      formatDetail(item, body) {
+        const detail = asRecord(cleanBalanceDetail(body, item));
+        const breakdown = asArray(detail.breakdown);
+        return [
+          `Balance: ${humanAmount(detail.balance, detail.currency)}`,
+          `Owed: ${humanAmount(detail.totalOwed, detail.currency)}`,
+          `Owing: ${humanAmount(detail.totalOwing, detail.currency)}`,
+          `User ID: ${display(asRecord(detail.user).id)}`,
+          "",
+          "Balance breakdown",
+          ...(breakdown.length
+            ? breakdown.map((value) => {
+                const entry = asRecord(value);
+                return `${display(entry.groupName)}: ${humanAmount(entry.balance, detail.currency)}${
+                  entry.groupId ? ` · ${String(entry.groupId)}` : ""
+                }`;
+              })
+            : ["—"]),
+        ].join("\n");
+      },
+    },
+  },
+} satisfies Record<"balance" | "balance-users", Presenter>;

package/src/commands/currencies.ts

@@ -0,0 +1,49 @@
+import {
+  asArray,
+  asRecord,
+  display,
+  formatCard,
+  parseOptions,
+  requirePositionals,
+  wantsHelp,
+} from "../shared";
+import type { ParsedCommand, Presenter } from "../types";
+
+const HELP = "Usage: banana currencies [list]";
+
+export function parseCurrencies(args: string[]): ParsedCommand {
+  if (args[0] === "list") args = args.slice(1);
+  if (wantsHelp(args)) return { kind: "help", text: HELP };
+  const { positionals } = parseOptions(args);
+  requirePositionals(positionals, 0, HELP);
+  return {
+    kind: "request",
+    path: "/currencies",
+    presentation: "currency-list",
+  };
+}
+
+export const currencyPresenters = {
+  "currency-list": {
+    clean: (body) => asArray(body),
+    format(body) {
+      const currencies = asArray(body);
+      if (!currencies.length) return "No currencies.";
+      return [
+        "Currencies",
+        ...currencies.map((value, index) => {
+          const currency = asRecord(value);
+          return formatCard(index, currency.name, [
+            `ID: ${display(currency.id)}`,
+            `Code: ${display(currency.code)}`,
+            `Symbol: ${display(currency.symbol)}`,
+            `Type: ${display(currency.type)}`,
+            `Decimals: ${display(currency.decimals)}`,
+            `Rate to base: ${display(currency.exchangeRateToBase)}`,
+            `Updated: ${display(currency.updatedAt)}`,
+          ]);
+        }),
+      ].join("\n\n");
+    },
+  },
+} satisfies Record<"currency-list", Presenter>;