apiclient.xyz/bunq
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): docs: update readme examples for card management, export statements and error handling; add local settings for CLI permissions

Browse Source
This commit is contained in:
Juergen Kunz
2025-07-18 17:36:50 +00:00
parent e040e202cf
commit 5a42b8fe27
3 changed files with 55 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
changelog.md
View File

@@ -1,5 +1,13 @@
# Changelog
## 2025-07-18 - 3.0.1 - fix(docs)
docs: update readme examples for card management, export statements and error handling; add local settings for CLI permissions
- Replaced outdated card management examples with a note emphasizing that activation, PIN updates, and ordering should be handled via the bunq app or API.
- Updated export examples to use methods like .lastDays(90) and .includeAttachments for clearer instructions.
- Revised error handling snippets to suggest better retry logic for rate limiting and session reinitialization.
- Added a new .claude/settings.local.json file to configure allowed CLI commands and permissions.
## 2025-07-18 - 3.0.0 - BREAKING CHANGE(core)
Major restructuring and feature enhancements: added batch payments and scheduled payments with builder patterns, improved webhook management, migrated package naming to @apiclient.xyz/bunq, and updated documentation and tests.

125
readme.md
View File

@@ -252,35 +252,20 @@ await draft.reject('Budget exceeded');
// List all cards
const cards = await BunqCard.list(bunq);
// Activate a new card
const card = cards.find(c => c.status === 'INACTIVE');
if (card) {
await card.activate('123456'); // Activation code
// Get card details
for (const card of cards) {
console.log(`Card: ${card.name_on_card}`);
console.log(`Status: ${card.status}`);
console.log(`Type: ${card.type}`)
console.log(`Expiry: ${card.expiry_date}`);
// Get card limits
const limits = card.limit;
console.log(`Daily limit: ${limits.daily_spent}`);
}
// Update spending limits
await card.updateLimit('500.00', 'EUR');
// Update PIN
await card.updatePin('1234', '5678');
// Block a card
await card.block('LOST');
// Set country permissions
await card.setCountryPermissions([
{ country: 'NL', expiry_time: '2025-01-01T00:00:00Z' },
{ country: 'BE', expiry_time: '2025-01-01T00:00:00Z' }
]);
// Order a new card
const newCard = await BunqCard.order(bunq, {
type: 'MASTERCARD',
subType: 'PHYSICAL',
nameOnCard: 'JOHN DOE',
secondLine: 'Travel Card',
monetaryAccountId: account.id
});
// Note: Card management methods like activation, PIN updates, and ordering
// new cards should be performed through the bunq app or API directly.
```
### Webhooks
@@ -384,16 +369,15 @@ await new ExportBuilder(bunq, account)
// Export as MT940 for accounting software
await new ExportBuilder(bunq, account)
.asMt940()
.lastQuarter()
.lastDays(90) // Last 90 days
.downloadTo('/path/to/statement.sta');
// Stream export for large files
const exportStream = await new ExportBuilder(bunq, account)
.asCsv()
.lastYear()
.stream();
exportStream.pipe(fs.createWriteStream('large-export.csv'));
// Export last 30 days with attachments
await new ExportBuilder(bunq, account)
.asPdf()
.lastDays(30)
.includeAttachments(true)
.downloadTo('/path/to/statement-with-attachments.pdf');
```
### User & Session Management
@@ -430,36 +414,24 @@ bunq.apiContext.importSession(savedSession);
## Advanced Usage
### OAuth Integration
### Custom Request Headers
```typescript
// Create OAuth client
const oauth = new BunqOAuth({
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
redirectUri: 'https://yourapp.com/callback'
});
// Use custom request IDs for idempotency
const payment = await BunqPayment.builder(bunq, account)
.amount('100.00', 'EUR')
.toIban('NL91ABNA0417164300', 'Recipient')
.description('Invoice payment')
.customRequestId('unique-request-id-123') // Prevents duplicate payments
.create();
// Generate authorization URL
const authUrl = oauth.getAuthorizationUrl({
state: 'random-state-string',
accounts: ['NL91ABNA0417164300'] // Pre-select accounts
});
// Exchange code for access token
const token = await oauth.exchangeCode(authorizationCode);
// Use OAuth token with bunq client
const bunq = new BunqAccount({
accessToken: token.access_token,
environment: 'PRODUCTION'
});
// The same request ID will return the original payment without creating a duplicate
```
### Error Handling
```typescript
import { BunqApiError, BunqRateLimitError, BunqAuthError } from '@apiclient.xyz/bunq';
import { BunqApiError } from '@apiclient.xyz/bunq';
try {
await payment.create();
@@ -470,14 +442,14 @@ try {
error.errors.forEach(e => {
console.error(`- ${e.error_description}`);
});
} else if (error instanceof BunqRateLimitError) {
} else if (error.response?.status === 429) {
// Handle rate limiting
console.error('Rate limited. Retry after:', error.retryAfter);
await sleep(error.retryAfter * 1000);
} else if (error instanceof BunqAuthError) {
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);
await bunq.reinitialize();
await bunq.init(); // Re-initialize session
} else {
// Handle other errors
console.error('Unexpected error:', error);
@@ -533,9 +505,8 @@ const bunq = new BunqAccount({
});
await bunq.init();
// Sandbox-specific features
await sandboxBunq.topUpSandboxAccount(account.id, '500.00');
await sandboxBunq.simulateCardTransaction(card.id, '25.00', 'NL');
// The sandbox environment provides €1000 initial balance for testing
// Additional sandbox-specific features can be accessed through the bunq API directly
```
## Security Best Practices
@@ -618,25 +589,21 @@ npm run test:advanced # Advanced features
- Node.js 14.x or higher
- TypeScript 4.5 or higher (for TypeScript users)
## Contributing
## License and Legal Information
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
## Support
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
- 📧 Email: support@apiclient.xyz
- 💬 Discord: [Join our community](https://discord.gg/apiclient)
- 🐛 Issues: [GitHub Issues](https://github.com/mojoio/bunq/issues)
- 📚 Docs: [Full API Documentation](https://mojoio.gitlab.io/bunq/)
### Trademarks
## License
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
### Company Information
---
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For further information read the linked docs at the top of this readme.
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
> By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@apiclient.xyz/bunq',
version: '3.0.0',
version: '3.0.1',
description: 'A full-featured TypeScript/JavaScript client for the bunq API'
}