up-bank-cli 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# up-bank-cli
+
+CLI for the [Up Banking API](https://developer.up.com.au/) — view accounts, balances, and transactions.
+
+## Install
+
+```bash
+bun install -g up-bank-cli
+```
+
+## Setup
+
+Generate a Personal Access Token at [api.up.com.au](https://api.up.com.au) and set it:
+
+```bash
+export UP_BANK_API_TOKEN="up:yeah:your-token-here"
+```
+
+## Commands
+
+```bash
+up-bank accounts                    # List all accounts
+up-bank accounts --type saver       # Filter by type
+up-bank transactions                # Recent transactions
+up-bank transactions --since 2026-03-01 --until 2026-03-15
+up-bank transactions --category groceries --limit 10
+up-bank ping                        # Test token
+```
+
+Add `--json` to any command for raw JSON output.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "up-bank-cli",
+  "version": "0.1.0",
+  "description": "CLI for the Up Banking API — accounts, transactions, and balances",
+  "bin": {
+    "up-bank": "./src/index.ts"
+  },
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanmikan/up-bank-cli"
+  },
+  "keywords": [
+    "up-bank",
+    "banking",
+    "finance",
+    "cli"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/commands/accounts.ts

@@ -0,0 +1,61 @@
+import { parseArgs, apiRequest } from "../utils.js"
+
+function formatMoney(value: string, currencyCode: string): string {
+  const num = Number.parseFloat(value)
+  return num.toLocaleString("en-AU", { style: "currency", currency: currencyCode })
+}
+
+export function formatAccount(account: any): string {
+  const a = account.attributes
+  const balance = formatMoney(a.balance.value, a.balance.currencyCode)
+  return `${a.displayName} (${a.accountType})\n  Balance: ${balance}\n  Owner: ${a.ownershipType}`
+}
+
+export function formatAccountList(accounts: any[]): string {
+  if (accounts.length === 0) return "No accounts found."
+  return accounts
+    .map((acc) => {
+      const a = acc.attributes
+      const balance = formatMoney(a.balance.value, a.balance.currencyCode)
+      return `  ${a.displayName.padEnd(25)} ${a.accountType.padEnd(16)} ${balance}`
+    })
+    .join("\n")
+}
+
+export async function accounts(argv: string[]) {
+  const { positional, flags } = parseArgs(argv)
+
+  if (flags.help === "true" || flags.h === "true") {
+    console.log(`Usage:
+  up-bank accounts [--type saver|transactional|home_loan] [--json]
+  up-bank accounts <id> [--json]`)
+    process.exit(0)
+  }
+
+  const json = flags.json === "true"
+  const accountId = positional[0]
+
+  if (accountId) {
+    // Get specific account
+    const response = await apiRequest(`/accounts/${accountId}`)
+    if (json) {
+      console.log(JSON.stringify(response, null, 2))
+    } else {
+      console.log(formatAccount(response.data))
+    }
+    return
+  }
+
+  // List accounts
+  const params: Record<string, string> = {}
+  if (flags.type) {
+    params["filter[accountType]"] = flags.type.toUpperCase()
+  }
+
+  const response = await apiRequest("/accounts", params)
+  if (json) {
+    console.log(JSON.stringify(response, null, 2))
+  } else {
+    console.log(formatAccountList(response.data))
+  }
+}

package/src/commands/ping.ts

@@ -0,0 +1,11 @@
+import { apiRequest } from "../utils.js"
+
+export async function ping(_argv: string[]) {
+  try {
+    const response = await apiRequest("/util/ping")
+    const meta = response.meta ?? {}
+    console.log(`✓ Authenticated — ${meta.statusEmoji ?? "🙂"}`)
+  } catch {
+    // apiRequest already handles error output and process.exit(1)
+  }
+}

package/src/commands/transactions.ts

@@ -0,0 +1,78 @@
+import { parseArgs, apiRequest, apiRequestPaginated } from "../utils.js"
+
+function formatMoney(value: string, currencyCode: string): string {
+  const num = Number.parseFloat(value)
+  const formatted = Math.abs(num).toLocaleString("en-AU", {
+    style: "currency",
+    currency: currencyCode,
+  })
+  return num < 0 ? `-${formatted}` : `+${formatted}`
+}
+
+function formatDate(iso: string | null): string {
+  if (!iso) return "pending"
+  const d = new Date(iso)
+  return d.toLocaleDateString("en-AU", { day: "2-digit", month: "short", year: "numeric" })
+}
+
+export function formatTransaction(txn: any): string {
+  const a = txn.attributes
+  const amount = formatMoney(a.amount.value, a.amount.currencyCode)
+  const date = formatDate(a.settledAt ?? a.createdAt)
+  const category = txn.relationships?.category?.data?.id ?? ""
+  const status = a.status === "HELD" ? " [HELD]" : ""
+  return `${date}  ${amount.padStart(12)}  ${a.description}${status}${category ? `  (${category})` : ""}`
+}
+
+export function formatTransactionList(transactions: any[]): string {
+  if (transactions.length === 0) return "No transactions found."
+  return transactions.map(formatTransaction).join("\n")
+}
+
+export async function transactions(argv: string[]) {
+  const { positional, flags } = parseArgs(argv)
+
+  if (flags.help === "true" || flags.h === "true") {
+    console.log(`Usage:
+  up-bank transactions [options]
+  up-bank transactions <id> [--json]
+
+Options:
+  --since <YYYY-MM-DD>   Filter from date
+  --until <YYYY-MM-DD>   Filter to date
+  --category <name>      Filter by category
+  --status <settled|held> Filter by status
+  --limit <n>            Max results (default: 50)
+  --json                 Output raw JSON`)
+    process.exit(0)
+  }
+
+  const json = flags.json === "true"
+  const txnId = positional[0]
+
+  if (txnId) {
+    const response = await apiRequest(`/transactions/${txnId}`)
+    if (json) {
+      console.log(JSON.stringify(response, null, 2))
+    } else {
+      console.log(formatTransaction(response.data))
+    }
+    return
+  }
+
+  // Build filter params
+  const params: Record<string, string> = {}
+  if (flags.since) params["filter[since]"] = new Date(flags.since).toISOString()
+  if (flags.until) params["filter[until]"] = new Date(flags.until).toISOString()
+  if (flags.status) params["filter[status]"] = flags.status.toUpperCase()
+  if (flags.category) params["filter[category]"] = flags.category
+
+  const limit = flags.limit ? parseInt(flags.limit, 10) : 50
+  const data = await apiRequestPaginated("/transactions", params, limit)
+
+  if (json) {
+    console.log(JSON.stringify({ data }, null, 2))
+  } else {
+    console.log(formatTransactionList(data))
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env bun
+
+import { accounts } from "./commands/accounts.js"
+import { transactions } from "./commands/transactions.js"
+import { ping } from "./commands/ping.js"
+
+const args = process.argv.slice(2)
+const command = args[0]
+const commandArgs = args.slice(1)
+
+if (!command || command === "--help" || command === "-h") {
+  console.log(`up-bank — Up Banking API CLI
+
+Usage:
+  up-bank accounts [options]              List accounts
+  up-bank accounts <id> [options]         Get specific account
+  up-bank transactions [options]          List transactions
+  up-bank transactions <id> [options]     Get specific transaction
+  up-bank ping                            Test API token
+
+Options:
+  --type <saver|transactional|home_loan>  Filter accounts by type
+  --since <YYYY-MM-DD>                    Transactions since date
+  --until <YYYY-MM-DD>                    Transactions until date
+  --category <name>                       Filter by category
+  --status <settled|held>                 Filter by status
+  --limit <n>                             Max results
+  --json                                  Output raw JSON
+  --help, -h                              Show help
+
+Environment:
+  UP_BANK_API_TOKEN  Required. Personal access token from api.up.com.au`)
+  process.exit(0)
+}
+
+const commands: Record<string, (argv: string[]) => Promise<void>> = {
+  accounts,
+  transactions,
+  ping,
+}
+
+const handler = commands[command]
+if (!handler) {
+  console.error(`Unknown command: ${command}. Run 'up-bank --help' for usage.`)
+  process.exit(1)
+}
+
+await handler(commandArgs)

package/src/utils.ts

@@ -0,0 +1,98 @@
+const BASE_URL = "https://api.up.com.au/api/v1"
+
+export function getApiToken(): string {
+  const token = process.env.UP_BANK_API_TOKEN
+  if (!token) {
+    console.error("Error: UP_BANK_API_TOKEN environment variable is required.")
+    console.error("Generate a token at https://api.up.com.au")
+    process.exit(1)
+  }
+  return token
+}
+
+export function parseArgs(argv: string[]): { positional: string[]; flags: Record<string, string> } {
+  const positional: string[] = []
+  const flags: Record<string, string> = {}
+  let i = 0
+  while (i < argv.length) {
+    const arg = argv[i]
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+      if (next && !next.startsWith("--")) {
+        flags[key] = next
+        i += 2
+      } else {
+        flags[key] = "true"
+        i += 1
+      }
+    } else {
+      positional.push(arg)
+      i += 1
+    }
+  }
+  return { positional, flags }
+}
+
+export async function apiRequest(
+  path: string,
+  params?: Record<string, string>,
+): Promise<any> {
+  const token = getApiToken()
+  const url = new URL(`${BASE_URL}${path}`)
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value)
+    }
+  }
+
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+    },
+  })
+
+  if (response.status === 401) {
+    console.error("Error: Invalid or expired token. Regenerate at https://api.up.com.au")
+    process.exit(1)
+  }
+  if (response.status === 429) {
+    console.error("Error: Rate limited. Try again shortly.")
+    process.exit(1)
+  }
+  if (!response.ok) {
+    const body = await response.text()
+    console.error(`Error: Up API returned ${response.status}: ${body}`)
+    process.exit(1)
+  }
+
+  return response.json()
+}
+
+/** Fetch all pages up to a limit, following cursor-based pagination */
+export async function apiRequestPaginated(
+  path: string,
+  params?: Record<string, string>,
+  limit?: number,
+): Promise<any[]> {
+  const firstPage = await apiRequest(path, { ...params, "page[size]": "100" })
+  let allData = firstPage.data ?? []
+  let nextUrl = firstPage.links?.next
+
+  while (nextUrl && (!limit || allData.length < limit)) {
+    const response = await fetch(nextUrl, {
+      headers: {
+        Authorization: `Bearer ${getApiToken()}`,
+        Accept: "application/json",
+      },
+    })
+    if (!response.ok) break
+    const page = await response.json()
+    allData = allData.concat(page.data ?? [])
+    nextUrl = page.links?.next
+  }
+
+  if (limit) allData = allData.slice(0, limit)
+  return allData
+}