@bananasplitapp/cli 0.1.0

package/src/commands/payments.ts

@@ -0,0 +1,167 @@
+import {
+  asRecord,
+  cleanUserSummary,
+  display,
+  formatCard,
+  humanAmount,
+  isoDate,
+  namedEntity,
+  numeric,
+  parseJsonBody,
+  parseOptions,
+  requiredString,
+  requirePositionals,
+  wantsHelp,
+  yesNo,
+} from "../shared";
+import { CliFailure, type ParsedCommand, type Presenter } from "../types";
+
+const HELP = `Usage: banana payments add JSON
+   or: banana payments add --amount AMOUNT --currency-id ID
+                           --from-user-id ID --to-user-id ID
+                           --date YYYY-MM-DD|DD-MM-YYYY
+                           [--group-id ID] [--description TEXT]
+   or: banana payments get <payment-id>`;
+const GET_HELP = "Usage: banana payments get <payment-id>";
+
+export function parsePayments(args: string[]): ParsedCommand {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    return { kind: "help", text: HELP };
+  }
+  const [command, ...rest] = args;
+  if (command === "get") {
+    if (wantsHelp(rest)) return { kind: "help", text: GET_HELP };
+    const { positionals } = parseOptions(rest);
+    requirePositionals(positionals, 1, GET_HELP);
+    return {
+      kind: "request",
+      path: `/payments/${encodeURIComponent(positionals[0])}`,
+      presentation: "payment",
+    };
+  }
+  if (command !== "add") throw new CliFailure("usage", HELP);
+  if (wantsHelp(rest)) return { kind: "help", text: HELP };
+
+  const { positionals, values } = parseOptions(rest, {
+    amount: { type: "string" },
+    "currency-id": { type: "string" },
+    date: { type: "string" },
+    description: { type: "string" },
+    "from-user-id": { type: "string" },
+    "group-id": { type: "string" },
+    "to-user-id": { type: "string" },
+  });
+  const jsonBody = parseJsonBody(positionals, values, HELP);
+  if (jsonBody !== undefined) {
+    return {
+      kind: "request",
+      method: "POST",
+      path: "/payments",
+      presentation: "payment-created",
+      body: jsonBody,
+    };
+  }
+  requirePositionals(positionals, 0, HELP);
+
+  const groupId = values["group-id"] as string | undefined;
+  const description = values.description as string | undefined;
+  return {
+    kind: "request",
+    method: "POST",
+    path: "/payments",
+    presentation: "payment-created",
+    body: {
+      amount: requiredString(values.amount, "--amount", HELP),
+      currencyId: requiredString(values["currency-id"], "--currency-id", HELP),
+      fromUserId: requiredString(values["from-user-id"], "--from-user-id", HELP),
+      toUserId: requiredString(values["to-user-id"], "--to-user-id", HELP),
+      date: isoDate(values.date, HELP),
+      ...(groupId === undefined ? {} : { groupId }),
+      ...(description === undefined ? {} : { description }),
+    },
+  };
+}
+
+function cleanPayment(body: unknown) {
+  const payment = asRecord(body);
+  return {
+    id: payment.id ?? null,
+    description: payment.description ?? null,
+    amount: numeric(payment.amount),
+    currency: asRecord(payment.currency).code ?? payment.currencyId ?? null,
+    from: cleanUserSummary(payment.fromUser),
+    to: cleanUserSummary(payment.toUser),
+    group: payment.groupId
+      ? {
+          id: payment.groupId,
+          name: asRecord(payment.group).name ?? null,
+        }
+      : null,
+    date: payment.date ?? null,
+    isSettlement: payment.isSettlement === true,
+    createdAt: payment.createdAt ?? null,
+  };
+}
+
+function cleanCreatedPaymentItem(value: unknown) {
+  const payment = asRecord(value);
+  return {
+    id: payment.id ?? null,
+    description: payment.description ?? null,
+    amount: numeric(payment.amount),
+    currencyId: payment.currencyId ?? null,
+    fromUserId: payment.fromUserId ?? null,
+    toUserId: payment.toUserId ?? null,
+    groupId: payment.groupId ?? null,
+    date: payment.date ?? null,
+    timezone: payment.timezone ?? null,
+    isSettlement: payment.isSettlement === true,
+    usedOptimalSettlement: payment.usedOptimalSettlement === true,
+  };
+}
+
+export const paymentPresenters = {
+  payment: {
+    clean: cleanPayment,
+    format(body) {
+      const response = asRecord(body);
+      const group = asRecord(response.group);
+      return [
+        "Payment",
+        `Amount: ${humanAmount(response.amount, response.currency)}`,
+        `From: ${namedEntity(response.from)}`,
+        `To: ${namedEntity(response.to)}`,
+        `Group: ${response.group ? namedEntity(group) : "—"}`,
+        `Description: ${display(response.description)}`,
+        `Date: ${display(response.date)}`,
+        `Settlement: ${yesNo(response.isSettlement)}`,
+        `ID: ${display(response.id)}`,
+      ].join("\n");
+    },
+  },
+  "payment-created": {
+    clean(body) {
+      return Array.isArray(body)
+        ? body.map(cleanCreatedPaymentItem)
+        : cleanCreatedPaymentItem(body);
+    },
+    format(body) {
+      const payments = Array.isArray(body) ? body : [body];
+      return [
+        payments.length === 1
+          ? "Payment created"
+          : `${payments.length} payments created`,
+        ...payments.map((value, index) => {
+          const payment = asRecord(value);
+          return formatCard(index, payment.id, [
+            `Amount: ${humanAmount(payment.amount, payment.currencyId)}`,
+            `From: ${display(payment.fromUserId)}`,
+            `To: ${display(payment.toUserId)}`,
+            `Group ID: ${display(payment.groupId)}`,
+            `Date: ${display(payment.date)}`,
+          ]);
+        }),
+      ].join("\n\n");
+    },
+  },
+} satisfies Record<"payment" | "payment-created", Presenter>;

package/src/index.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+
+import { runCli } from "./cli";
+
+export { renderCollectionBrowser, renderGroupBrowser } from "./browser";
+export { runCli } from "./cli";
+export type { CliRuntime } from "./types";
+
+if (import.meta.main) {
+  process.exitCode = await runCli(process.argv.slice(2));
+}

package/src/request.ts

@@ -0,0 +1,108 @@
+import {
+  CliFailure,
+  type Environment,
+  type RequestCommand,
+  type CliRuntime,
+} from "./types";
+
+export const DEFAULT_API_URL = "https://api.bananasplit.net";
+export const REQUEST_TIMEOUT_MS = 15_000;
+
+function readApiUrl(raw: string | undefined) {
+  let url: URL;
+  try {
+    url = new URL(raw || DEFAULT_API_URL);
+  } catch {
+    throw new CliFailure("config", "BANANASPLIT_API_URL must be a valid URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new CliFailure(
+      "config",
+      "BANANASPLIT_API_URL must use http or https",
+    );
+  }
+  url.search = "";
+  url.hash = "";
+  if (!url.pathname.endsWith("/")) url.pathname += "/";
+  return url;
+}
+
+function responseMessage(response: Response, body: unknown) {
+  if (typeof body === "string" && body) return body;
+  if (
+    body &&
+    typeof body === "object" &&
+    "message" in body &&
+    typeof body.message === "string"
+  ) {
+    return body.message;
+  }
+  return `${response.status} ${response.statusText || "Request failed"}`;
+}
+
+async function readResponseBody(response: Response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+export async function request(
+  command: RequestCommand,
+  runtime: Required<Pick<CliRuntime, "fetch" | "timeoutMs">>,
+  env: Environment,
+) {
+  const token = env.BANANASPLIT_TOKEN;
+  if (!token) throw new CliFailure("config", "BANANASPLIT_TOKEN is required");
+
+  const url = new URL(
+    command.path.replace(/^\//, ""),
+    readApiUrl(env.BANANASPLIT_API_URL),
+  );
+  command.query?.forEach((value, key) => url.searchParams.set(key, value));
+
+  let response: Response;
+  try {
+    response = await runtime.fetch(url, {
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token}`,
+        ...(command.body === undefined
+          ? {}
+          : { "content-type": "application/json" }),
+        "user-agent": "bananasplit-cli",
+      },
+      ...(command.method === undefined ? {} : { method: command.method }),
+      ...(command.body === undefined
+        ? {}
+        : { body: JSON.stringify(command.body) }),
+      signal: AbortSignal.timeout(runtime.timeoutMs),
+    });
+  } catch (error) {
+    const timedOut =
+      error instanceof Error &&
+      (error.name === "AbortError" || error.name === "TimeoutError");
+    throw new CliFailure(
+      "network",
+      timedOut
+        ? `Request timed out after ${runtime.timeoutMs}ms`
+        : error instanceof Error
+          ? error.message
+          : "Network request failed",
+    );
+  }
+
+  const body = await readResponseBody(response);
+  if (!response.ok) {
+    throw new CliFailure(
+      "api",
+      responseMessage(response, body),
+      response.status,
+      body,
+    );
+  }
+  return body;
+}

package/src/shared.ts

@@ -0,0 +1,183 @@
+import { parseArgs } from "node:util";
+import { CliFailure, type OptionConfig } from "./types";
+
+export const DEFAULT_LIST_LIMIT = 5;
+
+export function parseOptions(args: string[], options: OptionConfig = {}) {
+  try {
+    return parseArgs({ args, options, allowPositionals: true, strict: true });
+  } catch (error) {
+    throw new CliFailure(
+      "usage",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+export function wantsHelp(args: string[]) {
+  return args.includes("--help") || args.includes("-h");
+}
+
+export function requirePositionals(
+  positionals: string[],
+  count: number,
+  usage: string,
+) {
+  if (positionals.length !== count) throw new CliFailure("usage", usage);
+}
+
+export function positiveInteger(value: unknown, name: string) {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new CliFailure("usage", `${name} must be a positive integer`);
+  }
+  return parsed.toString();
+}
+
+export function requiredString(value: unknown, name: string, usage: string) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new CliFailure("usage", `${name} is required\n${usage}`);
+  }
+  return value;
+}
+
+export function isoDate(value: unknown, usage: string) {
+  const input = requiredString(value, "--date", usage);
+  const ymd = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input);
+  const dmy = /^(\d{2})-(\d{2})-(\d{4})$/.exec(input);
+  const normalized = ymd
+    ? input
+    : dmy
+      ? `${dmy[3]}-${dmy[2]}-${dmy[1]}`
+      : "";
+  const date = new Date(`${normalized}T00:00:00.000Z`);
+
+  if (
+    !normalized ||
+    Number.isNaN(date.getTime()) ||
+    date.toISOString().slice(0, 10) !== normalized
+  ) {
+    throw new CliFailure(
+      "usage",
+      "--date must use YYYY-MM-DD or DD-MM-YYYY",
+    );
+  }
+  return date.toISOString();
+}
+
+export function repeatedStrings(value: unknown) {
+  if (value === undefined) return [];
+  return (Array.isArray(value) ? value : [value]).filter(
+    (item): item is string => typeof item === "string",
+  );
+}
+
+export function parseJsonBody(
+  positionals: string[],
+  values: Record<string, unknown>,
+  usage: string,
+) {
+  if (positionals.length === 0) return undefined;
+  if (positionals.length !== 1 || Object.keys(values).length !== 0) {
+    throw new CliFailure(
+      "usage",
+      `Pass one JSON object or use options, not both\n${usage}`,
+    );
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(positionals[0]);
+  } catch {
+    throw new CliFailure("usage", `JSON body must be a valid object\n${usage}`);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new CliFailure("usage", `JSON body must be a valid object\n${usage}`);
+  }
+  return body;
+}
+
+export function enumValue<const Values extends readonly string[]>(
+  value: unknown,
+  name: string,
+  values: Values,
+): Values[number] | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !values.includes(value)) {
+    throw new CliFailure("usage", `${name} must be one of: ${values.join(", ")}`);
+  }
+  return value;
+}
+
+export function appendQuery(
+  query: URLSearchParams,
+  name: string,
+  value: string | boolean | undefined,
+) {
+  if (value !== undefined) query.set(name, String(value));
+}
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function asArray(value: unknown) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function numeric(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (
+    typeof value === "string" &&
+    value.trim() &&
+    Number.isFinite(Number(value))
+  ) {
+    return Number(value);
+  }
+  return null;
+}
+
+export function cleanUserSummary(value: unknown) {
+  const user = asRecord(value);
+  return { id: user.id ?? null, name: user.name ?? null };
+}
+
+export function currencyCode(value: unknown) {
+  return asRecord(value).code ?? null;
+}
+
+export function display(value: unknown) {
+  return value === null || value === undefined || value === ""
+    ? "—"
+    : String(value);
+}
+
+export function namedEntity(value: unknown) {
+  const entity = asRecord(value);
+  return `${display(entity.name)}${entity.id ? ` · ${String(entity.id)}` : ""}`;
+}
+
+export function humanAmount(amount: unknown, currency: unknown) {
+  return `${display(amount)}${currency ? ` ${String(currency)}` : ""}`;
+}
+
+export function yesNo(value: unknown) {
+  return value === true ? "yes" : "no";
+}
+
+export function formatCard(index: number, title: unknown, fields: string[]) {
+  return [
+    `${index + 1}. ${display(title)}`,
+    ...fields.map((field) => `   ${field}`),
+  ].join("\n");
+}
+
+export function encodedDetailId(value: unknown) {
+  if (typeof value !== "string" || !value) {
+    throw new CliFailure("api", "Details are unavailable for this item");
+  }
+  return encodeURIComponent(value);
+}

package/src/types.ts

@@ -0,0 +1,101 @@
+export type ErrorType = "api" | "config" | "network" | "usage";
+export type Environment = Record<string, string | undefined>;
+export type OutputWriter = (value: string) => void;
+export type OutputMode = "human" | "json" | "raw";
+export type Pager = (value: string) => Promise<boolean>;
+export type Presentation =
+  | "user"
+  | "balance"
+  | "balance-users"
+  | "currency-list"
+  | "friend-list"
+  | "group-list"
+  | "group"
+  | "members"
+  | "activities"
+  | "expense-list"
+  | "expense"
+  | "payment"
+  | "expense-updated"
+  | "expense-created"
+  | "payment-created"
+  | "group-created";
+export type BrowserPresentation =
+  | "balance-users"
+  | "friend-list"
+  | "group-list"
+  | "expense-list"
+  | "members"
+  | "activities";
+export type BrowserDetailLoader = (
+  item: Record<string, unknown>,
+) => Promise<string>;
+export type BrowserPageLoader = (cursor: string) => Promise<unknown>;
+export type Browser = (
+  presentation: BrowserPresentation,
+  body: unknown,
+  loadDetail: BrowserDetailLoader,
+  loadPage?: BrowserPageLoader,
+) => Promise<boolean>;
+export type Fetch = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface CliRuntime {
+  browser?: Browser;
+  env?: Environment;
+  fetch?: Fetch;
+  pager?: Pager;
+  stderr?: OutputWriter;
+  stdout?: OutputWriter;
+  timeoutMs?: number;
+}
+
+export type RequestCommand = {
+  kind: "request";
+  path: string;
+  presentation: Presentation;
+  query?: URLSearchParams;
+  method?: "POST" | "PUT";
+  body?: unknown;
+  mergeExpense?: string;
+};
+
+export type HelpCommand = {
+  kind: "help";
+  text: string;
+};
+
+export type ParsedCommand = HelpCommand | RequestCommand;
+export type CommandParser = (args: string[]) => ParsedCommand;
+
+export type BrowserPresenter = {
+  detailPath: (
+    command: RequestCommand,
+    item: Record<string, unknown>,
+  ) => string;
+  formatDetail: (item: Record<string, unknown>, body: unknown) => string;
+};
+
+export type Presenter = {
+  clean: (body: unknown) => unknown;
+  format: (body: unknown) => string;
+  browser?: BrowserPresenter;
+};
+
+export class CliFailure extends Error {
+  constructor(
+    readonly type: ErrorType,
+    message: string,
+    readonly status?: number,
+    readonly body?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+export type OptionConfig = Record<
+  string,
+  { type: "boolean" | "string"; short?: string; multiple?: boolean }
+>;