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:
Jürgen 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 # 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) ## 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. 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 // List all cards
const cards = await BunqCard.list(bunq); const cards = await BunqCard.list(bunq);
// Activate a new card // Get card details
const card = cards.find(c => c.status === 'INACTIVE'); for (const card of cards) {
if (card) { console.log(`Card: ${card.name_on_card}`);
await card.activate('123456'); // Activation code 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 // Note: Card management methods like activation, PIN updates, and ordering
await card.updateLimit('500.00', 'EUR'); // new cards should be performed through the bunq app or API directly.
// 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
});
``` ```
### Webhooks ### Webhooks
@@ -384,16 +369,15 @@ await new ExportBuilder(bunq, account)
// Export as MT940 for accounting software // Export as MT940 for accounting software
await new ExportBuilder(bunq, account) await new ExportBuilder(bunq, account)
.asMt940() .asMt940()
.lastQuarter() .lastDays(90) // Last 90 days
.downloadTo('/path/to/statement.sta'); .downloadTo('/path/to/statement.sta');
// Stream export for large files // Export last 30 days with attachments
const exportStream = await new ExportBuilder(bunq, account) await new ExportBuilder(bunq, account)
.asCsv() .asPdf()
.lastYear() .lastDays(30)
.stream(); .includeAttachments(true)
.downloadTo('/path/to/statement-with-attachments.pdf');
exportStream.pipe(fs.createWriteStream('large-export.csv'));
``` ```
### User & Session Management ### User & Session Management
@@ -430,36 +414,24 @@ bunq.apiContext.importSession(savedSession);
## Advanced Usage ## Advanced Usage
### OAuth Integration ### Custom Request Headers
```typescript ```typescript
// Create OAuth client // Use custom request IDs for idempotency
const oauth = new BunqOAuth({ const payment = await BunqPayment.builder(bunq, account)
clientId: 'your-client-id', .amount('100.00', 'EUR')
clientSecret: 'your-client-secret', .toIban('NL91ABNA0417164300', 'Recipient')
redirectUri: 'https://yourapp.com/callback' .description('Invoice payment')
}); .customRequestId('unique-request-id-123') // Prevents duplicate payments
.create();
// Generate authorization URL // The same request ID will return the original payment without creating a duplicate
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'
});
``` ```
### Error Handling ### Error Handling
```typescript ```typescript
import { BunqApiError, BunqRateLimitError, BunqAuthError } from '@apiclient.xyz/bunq'; import { BunqApiError } from '@apiclient.xyz/bunq';
try { try {
await payment.create(); await payment.create();
@@ -470,14 +442,14 @@ try {
error.errors.forEach(e => { error.errors.forEach(e => {
console.error(`- ${e.error_description}`); console.error(`- ${e.error_description}`);
}); });
} else if (error instanceof BunqRateLimitError) { } else if (error.response?.status === 429) {
// Handle rate limiting // Handle rate limiting
console.error('Rate limited. Retry after:', error.retryAfter); console.error('Rate limited. Please retry after a few seconds.');
await sleep(error.retryAfter * 1000); await new Promise(resolve => setTimeout(resolve, 5000));
} else if (error instanceof BunqAuthError) { } else if (error.response?.status === 401) {
// Handle authentication errors // Handle authentication errors
console.error('Authentication failed:', error.message); console.error('Authentication failed:', error.message);
await bunq.reinitialize(); await bunq.init(); // Re-initialize session
} else { } else {
// Handle other errors // Handle other errors
console.error('Unexpected error:', error); console.error('Unexpected error:', error);
@@ -533,9 +505,8 @@ const bunq = new BunqAccount({
}); });
await bunq.init(); await bunq.init();
// Sandbox-specific features // The sandbox environment provides €1000 initial balance for testing
await sandboxBunq.topUpSandboxAccount(account.id, '500.00'); // Additional sandbox-specific features can be accessed through the bunq API directly
await sandboxBunq.simulateCardTransaction(card.id, '25.00', 'NL');
``` ```
## Security Best Practices ## Security Best Practices
@@ -618,25 +589,21 @@ npm run test:advanced # Advanced features
- Node.js 14.x or higher - Node.js 14.x or higher
- TypeScript 4.5 or higher (for TypeScript users) - 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 ### Trademarks
- 💬 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/)
## 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) 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.
[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)

2
ts/00_commitinfo_data.ts
View File

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