This commit is contained in:
2025-07-18 10:31:12 +00:00
parent 5abc4e7976
commit 193524f15c
33 changed files with 35866 additions and 3864 deletions

288
readme.md
View File

@@ -1,8 +1,8 @@
# @mojoio/bunq
a bunq api abstraction package
# @apiclient.xyz/bunq
A full-featured TypeScript/JavaScript client for the bunq API
## Availabililty and Links
* [npmjs.org (npm package)](https://www.npmjs.com/package/@mojoio/bunq)
* [npmjs.org (npm package)](https://www.npmjs.com/package/@apiclient.xyz/bunq)
* [gitlab.com (source)](https://gitlab.com/mojoio/bunq)
* [github.com (source mirror)](https://github.com/mojoio/bunq)
* [docs (typedoc)](https://mojoio.gitlab.io/bunq/)
@@ -13,19 +13,289 @@ Status Category | Status Badge
-- | --
GitLab Pipelines | [![pipeline status](https://gitlab.com/mojoio/bunq/badges/master/pipeline.svg)](https://lossless.cloud)
GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/mojoio/bunq/badges/master/coverage.svg)](https://lossless.cloud)
npm | [![npm downloads per month](https://badgen.net/npm/dy/@mojoio/bunq)](https://lossless.cloud)
npm | [![npm downloads per month](https://badgen.net/npm/dy/@apiclient.xyz/bunq)](https://lossless.cloud)
Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/mojoio/bunq)](https://lossless.cloud)
TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud)
node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/)
Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud)
PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@mojoio/bunq)](https://lossless.cloud)
PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@mojoio/bunq)](https://lossless.cloud)
BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@mojoio/bunq)](https://lossless.cloud)
PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@apiclient.xyz/bunq)](https://lossless.cloud)
PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@apiclient.xyz/bunq)](https://lossless.cloud)
BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@apiclient.xyz/bunq)](https://lossless.cloud)
Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud)
## Usage
## Features
Use Typescript for best in class intellisense.
- Complete bunq API implementation
- TypeScript support with full type definitions
- Automatic session management and renewal
- Request signing and response verification
- Support for all account types (personal, business, joint)
- Payment and transaction management
- Card management and controls
- Scheduled and draft payments
- File attachments and exports
- Webhook support
- OAuth authentication
- Sandbox environment support
## Installation
```bash
npm install @apiclient.xyz/bunq
```
## Quick Start
```typescript
import { BunqAccount } from '@apiclient.xyz/bunq';
// Initialize bunq client
const bunq = new BunqAccount({
apiKey: 'your-api-key',
deviceName: 'My App',
environment: 'PRODUCTION' // or 'SANDBOX'
});
// Initialize the client
await bunq.init();
// Get all monetary accounts
const accounts = await bunq.getAccounts();
console.log('My accounts:', accounts);
// Get transactions for an account
const transactions = await accounts[0].getTransactions();
console.log('Recent transactions:', transactions);
// Clean up when done
await bunq.stop();
```
## Usage Examples
### Making Payments
```typescript
import { BunqPayment } from '@apiclient.xyz/bunq';
// Simple payment
const payment = BunqPayment.builder(bunq, monetaryAccount)
.amount('10.00', 'EUR')
.toIban('NL91ABNA0417164300', 'John Doe')
.description('Coffee payment')
.create();
// Batch payment
const batch = new BunqBatchPayment(bunq, monetaryAccount);
batch
.addPayment({
amount: { value: '5.00', currency: 'EUR' },
counterparty_alias: { type: 'IBAN', value: 'NL91ABNA0417164300' },
description: 'Payment 1'
})
.addPayment({
amount: { value: '15.00', currency: 'EUR' },
counterparty_alias: { type: 'EMAIL', value: 'friend@example.com' },
description: 'Payment 2'
});
await batch.create();
```
### Managing Cards
```typescript
import { BunqCard } from '@apiclient.xyz/bunq';
// List all cards
const cards = await BunqCard.list(bunq);
// Activate a card
await cards[0].activate('activation-code');
// Update spending limit
await cards[0].updateLimit('100.00', 'EUR');
// Block a card
await cards[0].block('LOST');
// Order a new card
const newCard = await BunqCard.order(bunq, {
secondLine: 'Travel Card',
nameOnCard: 'JOHN DOE',
type: 'MASTERCARD'
});
```
### Scheduled Payments
```typescript
import { BunqScheduledPayment } from '@apiclient.xyz/bunq';
// Create a recurring payment
const scheduled = BunqScheduledPayment.builder(bunq, monetaryAccount)
.amount('50.00', 'EUR')
.toIban('NL91ABNA0417164300', 'Landlord')
.description('Monthly rent')
.scheduleMonthly('2024-01-01T10:00:00Z', '2024-12-31T10:00:00Z')
.create();
// List scheduled payments
const schedules = await BunqScheduledPayment.list(bunq, monetaryAccount.id);
```
### Request Money
```typescript
import { BunqRequestInquiry } from '@apiclient.xyz/bunq';
// Create a payment request
const request = BunqRequestInquiry.builder(bunq, monetaryAccount)
.amount('25.00', 'EUR')
.fromEmail('friend@example.com', 'My Friend')
.description('Dinner split')
.allowBunqme()
.create();
// The request will include a bunq.me URL for easy sharing
console.log('Share this link:', request.bunqmeShareUrl);
```
### File Attachments
```typescript
import { BunqAttachment } from '@apiclient.xyz/bunq';
// Upload a file
const attachment = new BunqAttachment(bunq);
const attachmentUuid = await attachment.uploadFile('/path/to/receipt.pdf', 'Receipt');
// Attach to a payment
const payment = BunqPayment.builder(bunq, monetaryAccount)
.amount('99.99', 'EUR')
.toIban('NL91ABNA0417164300')
.description('Purchase with receipt')
.attachments([attachmentUuid])
.create();
```
### Export Statements
```typescript
import { BunqExport, ExportBuilder } from '@apiclient.xyz/bunq';
// Export last month's transactions as PDF
await new ExportBuilder(bunq, monetaryAccount)
.asPdf()
.lastMonth()
.downloadTo('/path/to/statement.pdf');
// Export custom date range as CSV
await new ExportBuilder(bunq, monetaryAccount)
.asCsv()
.dateRange('2024-01-01', '2024-03-31')
.regionalFormat('EUROPEAN')
.downloadTo('/path/to/transactions.csv');
```
### Webhooks
```typescript
import { BunqWebhookServer, BunqNotification } from '@apiclient.xyz/bunq';
// Setup webhook server
const webhookServer = new BunqWebhookServer(bunq, {
port: 3000,
publicUrl: 'https://myapp.com'
});
// Register handlers
webhookServer.getHandler().onPayment((payment) => {
console.log('New payment:', payment.amount.value, payment.description);
});
webhookServer.getHandler().onCard((card) => {
console.log('Card event:', card.status);
});
// Start server and register with bunq
await webhookServer.start();
await webhookServer.register();
```
### Sandbox Testing
```typescript
// Create a sandbox account
const sandboxBunq = new BunqAccount({
apiKey: '', // Will be generated
deviceName: 'Sandbox Test',
environment: 'SANDBOX'
});
// Create a sandbox user with API key
const apiKey = await sandboxBunq.createSandboxUser();
console.log('Sandbox API key:', apiKey);
// Now reinitialize with the API key
const bunq = new BunqAccount({
apiKey: apiKey,
deviceName: 'Sandbox Test',
environment: 'SANDBOX'
});
await bunq.init();
```
## API Reference
### Core Classes
- `BunqAccount` - Main entry point for the API
- `BunqMonetaryAccount` - Represents a bank account
- `BunqTransaction` - Represents a transaction
- `BunqUser` - User management
### Payment Classes
- `BunqPayment` - Create and manage payments
- `BunqBatchPayment` - Create multiple payments at once
- `BunqScheduledPayment` - Schedule recurring payments
- `BunqDraftPayment` - Create draft payments requiring approval
- `BunqRequestInquiry` - Request money from others
### Other Features
- `BunqCard` - Card management
- `BunqAttachment` - File uploads and attachments
- `BunqExport` - Export statements in various formats
- `BunqNotification` - Webhook notifications
- `BunqWebhookServer` - Built-in webhook server
## Security
- All requests are signed with RSA signatures
- Response signatures are verified
- API keys are stored securely
- Session tokens are automatically refreshed
- Supports IP whitelisting
## Error Handling
```typescript
try {
await payment.create();
} catch (error) {
if (error instanceof BunqApiError) {
console.error('bunq API error:', error.errors);
} else {
console.error('Unexpected error:', error);
}
}
```
## Requirements
- Node.js 10.x or higher
- TypeScript 3.x or higher (for TypeScript users)
## Contribution