docs: Add comprehensive use cases and practical examples

[Copilot]

The documentation lacked practical examples for common operations. Added concrete use cases with working code snippets for both library and CLI usage.

Changes

Main README (README.md)

• Quick Start: Minimal client initialization with TypeScript and CLI examples
• Common Use Cases: 5 production-ready patterns
  • Account balance queries
  • Transaction fetching (last 30 days)
  • SEPA credit transfers with TAN handling
  • SEPA direct debits with TAN handling
  • Multi-account operations
• Tips & Troubleshooting: Authentication errors, TAN requirements, timeout handling, best practices

Library README (packages/fints/README.md)

• Replaced minimal example with detailed Quick Start
• Added 4 use cases with proper error handling and environment variable validation

CLI README (packages/fints-cli/README.md)

• Practical Examples: 5 automation scripts
  • Environment variables setup
  • JSON export with jq integration
  • Monthly statement automation (Linux/macOS)
  • Multi-account checking
• Tips: CLI best practices and tool recommendations

Example

import { PinTanClient } from "fints-lib";

const client = new PinTanClient({
    url: process.env.FINTS_URL,
    name: process.env.FINTS_USERNAME,
    pin: process.env.FINTS_PIN,
    blz: process.env.FINTS_BLZ,
});

// Fetch last 30 days
const endDate = new Date();
const startDate = new Date(endDate.getTime() - 30 * 24 * 60 * 60 * 1000);
const statements = await client.statements(accounts[0], startDate, endDate);

All examples use environment variables for credentials and include proper error handling.

Stats: +594 lines across 3 files

Original prompt

Es wäre gut, wenn wir die Dokumentation um ein paar direkte Use Cases erweitern.

• README: Beispiele für grundlegende Client-Initialisierung, typische Use‑Cases (Kontostand, Umsätze, SEPA), Short CLI‑Beispiele, Quickstart mit minimaler Konfiguration.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR significantly enhances the documentation by adding comprehensive practical examples and use cases for both library and CLI usage. The changes transform the documentation from minimal examples to production-ready code snippets that demonstrate common banking operations with proper error handling and best practices.

Key changes:

• Added Quick Start section with minimal configuration examples for TypeScript and CLI
• Introduced 5 detailed use cases covering account queries, transactions, SEPA transfers, direct debits, and multi-account operations
• Added Tips & Troubleshooting section with authentication, TAN handling, timeout configuration, and best practices

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
README.md	Enhanced with minimal configuration quick start, 5 comprehensive use cases with library and CLI examples, and extensive tips/troubleshooting section
packages/fints/README.md	Replaced basic example with detailed Quick Start and added 4 common use cases with environment variable handling
packages/fints-cli/README.md	Added 5 practical CLI automation scripts including environment setup, JSON export with jq, monthly statements, and multi-account checking

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The bash script comment describes fetching "last month's transactions" but the date calculation logic appears inconsistent. The START_DATE correctly gets the first day of last month, but the END_DATE calculation date -d "-1 day $(date +%Y-%m-01)" will subtract one day from the first of the current month (giving the last day of last month), which is correct. However, this nested command substitution may not work as expected in all shells. Consider using a clearer approach like date -d "$(date +%Y-%m-01) -1 day" +%Y-%m-%d or calculating both dates relative to "last month".

Suggested change

	END_DATE=$(date -d "-1 day $(date +%Y-%m-01)" +%Y-%m-%d)
	# For macOS (BSD date), install GNU coreutils and use 'gdate':
	# brew install coreutils
	# START_DATE=$(gdate -d "last month" +%Y-%m-01)
	# END_DATE=$(gdate -d "-1 day $(gdate +%Y-%m-01)" +%Y-%m-%d)
	END_DATE=$(date -d "$(date +%Y-%m-01) -1 day" +%Y-%m-%d)
	# For macOS (BSD date), install GNU coreutils and use 'gdate':
	# brew install coreutils
	# START_DATE=$(gdate -d "last month" +%Y-%m-01)
	# END_DATE=$(gdate -d "$(gdate +%Y-%m-01) -1 day" +%Y-%m-%d)

[Copilot]

All CLI examples in this README (starting with this snippet) pass the banking PIN via the -p command-line option, which exposes credentials in process listings (ps, system monitors) and often in shell history, allowing other local users or system tooling to capture the PIN. An attacker on the same host could read the full command line and reuse the stolen username/PIN against the bank’s FinTS endpoint. Consider adjusting the examples (and ideally the CLI UX) to avoid passing the PIN on the command line (e.g., reading from a secure prompt or protected store) and at minimum document the risk of using -p with real credentials.

[Copilot]

These CLI usage examples consistently pass the banking PIN using the -p flag (including the commented fints-env.sh usage and the automation scripts), which can leak credentials via process listings (ps, system monitors) and shell history on multi-user systems. A local attacker or monitoring tool could capture the full command line and reuse the PIN to access the victim’s bank account. It’s safer to avoid putting the PIN on the command line at all (e.g., have the CLI prompt for it or read it from a secure store) and to explicitly warn users in the docs about the risks of --pin/-p.