feat(export): add buffer download methods to ExportBuilder

- Added download() method to get statements as Buffer without saving to disk
- Added downloadAsArrayBuffer() method for web API compatibility
- Enhanced documentation for getAccountStatement() method
- Updated README with comprehensive examples
- No breaking changes, backward compatible
This commit is contained in:
2025-08-02 10:56:17 +00:00
parent 4c0ad95eb1
commit 40f9142d70
8 changed files with 218 additions and 124 deletions

View File

@@ -1,6 +1,34 @@
# @apiclient.xyz/bunq
[![npm version](https://img.shields.io/npm/v/@apiclient.xyz/bunq.svg)](https://www.npmjs.com/package/@apiclient.xyz/bunq)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
A powerful, type-safe TypeScript/JavaScript client for the bunq API with full feature coverage
## Table of Contents
- [Features](#features)
- [Stateless Architecture](#stateless-architecture-v400)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Examples](#core-examples)
- [Account Management](#account-management)
- [Making Payments](#making-payments)
- [Payment Requests](#payment-requests)
- [Draft Payments](#draft-payments-requires-approval)
- [Card Management](#card-management)
- [Webhooks](#webhooks)
- [File Attachments](#file-attachments)
- [Export Statements](#export-statements)
- [Session Management](#stateless-session-management)
- [User Management](#user-management)
- [Advanced Usage](#advanced-usage)
- [Security Best Practices](#security-best-practices)
- [Migration Guides](#migration-guide)
- [Testing](#testing)
- [Requirements](#requirements)
- [License](#license-and-legal-information)
## Features
### Core Banking Operations
@@ -26,6 +54,7 @@ A powerful, type-safe TypeScript/JavaScript client for the bunq API with full fe
-**Promise-based** - Modern async/await support throughout
- 🛡️ **Type Safety** - Compile-time type checking for all operations
- 📚 **Comprehensive Documentation** - Detailed examples for every feature
- 🔄 **Robust HTTP Client** - Built-in retry logic and rate limit handling
## Stateless Architecture (v4.0.0+)
@@ -405,6 +434,44 @@ await new ExportBuilder(bunq, account)
.lastDays(30)
.includeAttachments(true)
.downloadTo('/path/to/statement-with-attachments.pdf');
// Get statement as Buffer (no file saving)
const buffer = await new ExportBuilder(bunq, account)
.asPdf()
.lastMonth()
.download();
// Use the buffer directly, e.g., send as email attachment
await emailService.sendWithAttachment(buffer, 'statement.pdf');
// Get statement as ArrayBuffer for web APIs
const arrayBuffer = await new ExportBuilder(bunq, account)
.asCsv()
.lastDays(30)
.downloadAsArrayBuffer();
// Use with web APIs like Blob
const blob = new Blob([arrayBuffer], { type: 'text/csv' });
// Using account's getAccountStatement method for easy month selection
const statement1 = account.getAccountStatement({
monthlyIndexedFrom1: 1, // Last month (1 = last month, 2 = two months ago, etc.)
includeTransactionAttachments: true
});
await statement1.asPdf().downloadTo('/path/to/last-month.pdf');
// Or using 0-based indexing
const statement2 = account.getAccountStatement({
monthlyIndexedFrom0: 0, // Current month (0 = current, 1 = last month, etc.)
includeTransactionAttachments: false
});
await statement2.asCsv().downloadTo('/path/to/current-month.csv');
// Or specify exact date range
const statement3 = account.getAccountStatement({
from: new Date('2024-01-01'),
to: new Date('2024-03-31'),
includeTransactionAttachments: true
});
await statement3.asMt940().downloadTo('/path/to/q1-statement.sta');
```
### Stateless Session Management
@@ -552,10 +619,6 @@ try {
error.errors.forEach(e => {
console.error(`- ${e.error_description}`);
});
} else if (error.response?.status === 429) {
// Handle rate limiting
console.error('Rate limited. Please retry after a few seconds.');
await new Promise(resolve => setTimeout(resolve, 5000));
} else if (error.response?.status === 401) {
// Handle authentication errors
console.error('Authentication failed:', error.message);
@@ -567,6 +630,26 @@ try {
}
```
### Automatic Rate Limit Handling
The library automatically handles rate limiting (HTTP 429 responses) with intelligent exponential backoff:
```typescript
// No special handling needed - rate limits are handled automatically
const payments = await Promise.all([
payment1.create(),
payment2.create(),
payment3.create(),
// ... many more payments
]);
// The HTTP client will automatically:
// 1. Detect 429 responses
// 2. Wait for the time specified in Retry-After header
// 3. Use exponential backoff if no Retry-After is provided
// 4. Retry the request automatically (up to 3 times)
```
### Pagination
```typescript