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:
91
readme.md
91
readme.md
@@ -1,6 +1,34 @@
|
||||
# @apiclient.xyz/bunq
|
||||
|
||||
[](https://www.npmjs.com/package/@apiclient.xyz/bunq)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](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
|
||||
|
Reference in New Issue
Block a user