update
This commit is contained in:
288
readme.md
288
readme.md
@@ -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 | [](https://lossless.cloud)
|
||||
GitLab Pipline Test Coverage | [](https://lossless.cloud)
|
||||
npm | [](https://lossless.cloud)
|
||||
npm | [](https://lossless.cloud)
|
||||
Snyk | [](https://lossless.cloud)
|
||||
TypeScript Support | [](https://lossless.cloud)
|
||||
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
|
||||
Code Style | [](https://lossless.cloud)
|
||||
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
||||
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
||||
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
||||
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
||||
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
||||
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
||||
Platform support | [](https://lossless.cloud) [](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
|
||||
|
||||
|
Reference in New Issue
Block a user