clearbank-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `clearbank-sdk` are documented here.
+
+## [1.0.0] - 2026-06-09
+
+### Added
+- Initial release
+- **GBP Accounts** — real and virtual account management, transactions, Bacs DDIs, camt.053 statements
+- **Payments** — FPS (single + bulk), CHAPS (customer credit + return), Bacs returns, cheque deposits (ICS), internal transfers (single + bulk), CoP outbound name verification, SEPA SCT UK, GBP Cross-Border (deprecated)
+- **Multi-currency & FX** — MCCY account management, virtual accounts, international payment batches, FX spot trading, FX RFQ (request-for-quote), SEPA SCT UK
+- **Embedded Banking** — retail/sole-trader/legal-entity customer management, payment/savings/hub/ISA accounts, embedded FPS, ISA transfer-in, interest products, KYC submission and status
+- **Webhooks** — RSA-SHA256 signature verification, typed event parsing, `dispatch()` router for all 19 event types, `buildAck()` helper
+- RSA-SHA256 `DigitalSignature` signing via Web Crypto API (PKCS#1 v1.5 + SHA-256)
+- Full-jitter exponential backoff retries for 429/500/503
+- Pinnable `X-Request-Id` for idempotent mutation retries
+- Telemetry hook for structured observability events
+- Dual CJS/ESM output with TypeScript declaration files
+- 100+ unit tests using Vitest + MSW

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanishka Naik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# clearbank-sdk
+
+> Production-grade TypeScript SDK for the [ClearBank UK API](https://docs.clear.bank/)
+
+[![npm version](https://img.shields.io/npm/v/clearbank-sdk)](https://www.npmjs.com/package/clearbank-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Full API coverage** — GBP Accounts, FPS/CHAPS/Bacs/Cheques/CoP Payments, Multi-currency & FX, Embedded Banking, Webhooks
+- **TypeScript-first** — Complete type definitions for every request, response, and webhook event
+- **Dual CJS/ESM output** — Works in Node.js, Bun, Deno, and modern bundlers
+- **RSA-SHA256 signing** — Automatic `DigitalSignature` header using Web Crypto API (Node 18+)
+- **Idempotent retries** — Exponential backoff with full jitter; pinnable `X-Request-Id` for safe mutation retries
+- **Telemetry hooks** — Emit structured events to any observability provider
+- **Zero mandatory dependencies** — Uses native `fetch` and Web Crypto
+
+## Installation
+
+```bash
+npm install clearbank-sdk
+# or
+pnpm add clearbank-sdk
+# or
+yarn add clearbank-sdk
+```
+
+**Requires Node.js ≥ 18** (for native `fetch` and `crypto.subtle`).
+
+## Quick Start
+
+```ts
+import { ClearBankClient } from 'clearbank-sdk';
+
+const client = new ClearBankClient({
+  apiToken: process.env.CLEARBANK_API_TOKEN!,
+  privateKey: process.env.CLEARBANK_PRIVATE_KEY!,  // PEM string
+  environment: 'simulation',                        // or 'production'
+});
+
+// List GBP accounts
+const { data: accounts } = await client.accounts.list({ pageNumber: 1, pageSize: 20 });
+
+// Send a Faster Payment
+await client.payments.sendFPS({
+  accountId: 'your-account-id',
+  payment: {
+    amount: '250.00',
+    destinationSortCode: '040004',
+    destinationAccountNumber: '12345678',
+    destinationAccountName: 'Jane Smith',
+    reference: 'Invoice 001',
+  },
+});
+
+// Execute an FX trade
+const trade = await client.multiCurrency.executeFXTrade({
+  sellAccountId: 'gbp-account-id',
+  buyAccountId: 'eur-account-id',
+  sellCurrency: 'GBP',
+  buyCurrency: 'EUR',
+  sellAmount: '10000.00',
+});
+console.log(`Traded at rate: ${trade.rate}`);
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiToken` | `string` | **required** | Bearer token from ClearBank Portal |
+| `privateKey` | `string` | — | RSA private key PEM (required for POST/PUT/PATCH) |
+| `environment` | `'simulation' \| 'production'` | `'simulation'` | API environment |
+| `baseUrl` | `string` | — | Override base URL (useful for testing) |
+| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds |
+| `maxRetries` | `number` | `3` | Max retry attempts on 429/500/503 |
+| `retryBaseDelayMs` | `number` | `1000` | Backoff base delay in milliseconds |
+| `telemetryHook` | `TelemetryHook` | — | Called after every HTTP request |
+
+## Error Handling
+
+All API errors are thrown as `ClearBankError`:
+
+```ts
+import { ClearBankError } from 'clearbank-sdk';
+
+try {
+  await client.accounts.get('nonexistent-id');
+} catch (err) {
+  if (err instanceof ClearBankError) {
+    console.log(err.statusCode);      // 404
+    console.log(err.message);         // "Not Found"
+    console.log(err.correlationId);   // X-Correlation-Id for support
+    console.log(err.isNotFound());    // true
+    console.log(err.isRetryable());   // false
+  }
+}
+```
+
+### ClearBankError methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `isNotFound()` | `boolean` | HTTP 404 |
+| `isConflict()` | `boolean` | HTTP 409 (duplicate X-Request-Id) |
+| `isRateLimited()` | `boolean` | HTTP 429 |
+| `isUnprocessable()` | `boolean` | HTTP 422 |
+| `isRetryable()` | `boolean` | HTTP 429, 500, or 503 |
+
+## Idempotent Retries
+
+ClearBank requires mutating requests (POST/PUT/PATCH) that fail with 5XX to be retried with the **same** `X-Request-Id`:
+
+```ts
+const requestId = ClearBankClient.generateRequestId();
+
+try {
+  await client.payments.sendFPS(params, { requestId });
+} catch (err) {
+  if (err instanceof ClearBankError && err.isRetryable()) {
+    // Retry with identical requestId — ClearBank deduplicates on their side
+    await client.payments.sendFPS(params, { requestId });
+  }
+}
+```
+
+## Webhooks
+
+```ts
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/webhooks', async (req, res) => {
+  // 1. Verify signature (using ClearBank's public key from Portal)
+  const rawBody = JSON.stringify(req.body);
+  const isValid = await client.webhooks.verifySignature(
+    rawBody,
+    req.headers['digitalsignature'] as string,
+    process.env.CLEARBANK_PUBLIC_KEY!,
+  );
+  if (!isValid) return res.status(401).json({ error: 'Invalid signature' });
+
+  // 2. Parse and dispatch
+  const envelope = client.webhooks.parseEnvelope(req.body);
+  await client.webhooks.dispatch(envelope, {
+    TransactionSettled: async (event) => {
+      console.log(`Payment settled: £${event.amount} on account ${event.accountId}`);
+      await yourDatabase.recordSettlement(event);
+    },
+    FxTradeSettled: async (event) => {
+      console.log(`FX trade ${event.tradeId} settled`);
+    },
+    CustomerKycStatusChanged: async (event) => {
+      if (event.newStatus === 'Approved') {
+        await activateCustomerAccount(event.customerId);
+      }
+    },
+    onUnknown: (envelope) => {
+      console.log('Unknown webhook event:', envelope.Type);
+    },
+  });
+
+  // 3. Acknowledge
+  res.json(client.webhooks.buildAck(envelope));
+});
+```
+
+## Domain Services
+
+### `client.accounts` — GBP Accounts
+
+```ts
+// Real accounts
+await client.accounts.list({ pageNumber: 1, pageSize: 50 });
+await client.accounts.get(accountId);
+await client.accounts.create({ accountName: 'Segregated Pool', accountType: 'SegregatedPooled' });
+await client.accounts.update(accountId, { accountName: 'Renamed', copEnabled: true });
+
+// Virtual accounts
+await client.accounts.listVirtual(accountId);
+await client.accounts.createVirtual(accountId, { accountName: 'Customer 1', owner: customerId });
+await client.accounts.getVirtual(accountId, virtualAccountId);
+
+// Transactions
+await client.accounts.listAllTransactions({ startDate: '2024-01-01', endDate: '2024-01-31' });
+await client.accounts.listTransactions(accountId, { pageSize: 100 });
+await client.accounts.getTransaction(accountId, transactionId);
+
+// Bacs DDIs
+await client.accounts.createDDI(accountId, { serviceUserNumber, reference, payerName, payerSortCode, payerAccountNumber });
+await client.accounts.listDDIs(accountId);
+await client.accounts.cancelDDI(accountId, mandateId);
+
+// camt.053 statements
+const messageId = await client.accounts.requestStatement({ accountId, startDate, endDate });
+const allPages = await client.accounts.getAllStatementPages(messageId);
+```
+
+### `client.payments` — GBP Payments
+
+```ts
+// Faster Payments
+await client.payments.sendFPS({ accountId, payment: { amount, destinationSortCode, ... } });
+await client.payments.sendFPSBulk({ accountId, payments: [...] });
+
+// CHAPS
+await client.payments.sendCHAPS({ debtorAccountId, amount, creditorName, creditorAddress: { country: 'GB' }, ... });
+await client.payments.returnCHAPS({ originalInstructionId, debtorAccountId, returnReasonCode, amount });
+
+// Internal transfers
+await client.payments.sendInternalTransfer({ debtorAccountId, creditorAccountId, amount });
+await client.payments.sendBulkInternalTransfer([...transfers]);
+
+// Bacs returns
+await client.payments.returnBacs(accountId, { transactionId, reasonCode });
+
+// Cheques
+await client.payments.submitChequeDeposit({ accountId, amount, chequeImageFront, chequeImageBack, micrLine });
+
+// Confirmation of Payee
+const result = await client.payments.checkCoP({ accountName, sortCode, accountNumber });
+// result.matchResult: 'MATC' | 'CLOSE' | 'NOMATCH' | 'INAM' | 'PANM'
+await client.payments.optOutAccountCoP(accountId);
+
+// SEPA SCT UK
+await client.payments.sendSEPA({ debtorAccountId, amount, creditorName, creditorIban, creditorBic });
+```
+
+### `client.multiCurrency` — Multi-currency & FX
+
+```ts
+// Accounts
+await client.multiCurrency.listAccounts('EUR');
+await client.multiCurrency.createAccount({ accountName, accountType: 'YourFunds', currency: 'EUR' });
+
+// International payments
+await client.multiCurrency.sendPayment({ accountId, amount, currency, creditorName, creditorIban, creditorBic });
+await client.multiCurrency.sendBulkPayments([...payments]);
+
+// FX Spot
+const trade = await client.multiCurrency.executeFXTrade({ sellAccountId, buyAccountId, sellCurrency, buyCurrency, sellAmount });
+
+// FX RFQ
+const quote = await client.multiCurrency.requestFXQuote({ sellAccountId, buyAccountId, ... });
+if (!quote.isExpired()) {
+  const trade = await client.multiCurrency.executeFXQuote(quote.quoteId);
+}
+```
+
+### `client.embedded` — Embedded Banking
+
+```ts
+// Customers
+await client.embedded.createRetailCustomer({ firstName, lastName, dateOfBirth });
+await client.embedded.createSoleTraderCustomer({ firstName, lastName, dateOfBirth, tradingName });
+await client.embedded.createLegalEntityCustomer({ companyName, registrationNumber, registeredCountry, companyType });
+
+// Accounts
+await client.embedded.createPaymentAccount({ customerId, accountName });
+await client.embedded.createSavingsAccount({ customerId, accountName });
+await client.embedded.createISA({ customerId, accountName });
+await client.embedded.sendFPS({ accountId, amount, destinationSortCode, destinationAccountNumber, destinationName });
+
+// KYC
+await client.embedded.submitKYC(customerId, { idDocumentType, idDocumentNumber, idDocumentExpiry, idDocumentCountry });
+const status = await client.embedded.getKYCStatus(customerId);
+
+// Interest
+const products = await client.embedded.listInterestProducts();
+await client.embedded.configureInterest(accountId, { productId });
+```
+
+## Telemetry
+
+```ts
+const client = new ClearBankClient({
+  apiToken: '...',
+  telemetryHook: (event) => {
+    yourMetrics.histogram('clearbank.request.duration', event.durationMs, {
+      method: event.method,
+      statusCode: String(event.statusCode ?? 'network_error'),
+    });
+    if (event.error) {
+      yourLogger.error('ClearBank request failed', { error: event.error, requestId: event.requestId });
+    }
+  },
+});
+```
+
+## License
+
+MIT © [Kanishka Naik](https://github.com/iamkanishka)

package/dist/cjs/core/config.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+const BASE_URLS = {
+    simulation: 'https://institution-api-sim.clearbank.co.uk',
+    production: 'https://institution-api.clearbank.co.uk',
+};
+function resolveConfig(config) {
+    if (!config.apiToken || config.apiToken.trim() === '') {
+        throw new Error('ClearBank SDK: apiToken is required and must not be empty.');
+    }
+    const environment = config.environment ?? 'simulation';
+    const baseUrl = config.baseUrl ?? BASE_URLS[environment];
+    return {
+        apiToken: config.apiToken,
+        privateKey: config.privateKey ?? null,
+        baseUrl,
+        timeoutMs: config.timeoutMs ?? 30000,
+        maxRetries: config.maxRetries ?? 3,
+        retryBaseDelayMs: config.retryBaseDelayMs ?? 1000,
+        retryMaxDelayMs: config.retryMaxDelayMs ?? 30000,
+        telemetryHook: config.telemetryHook ?? null,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/cjs/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/config.ts"],"names":[],"mappings":";;AAyCA,sCAkBC;AAvDD,MAAM,SAAS,GAAgC;IAC7C,UAAU,EAAE,6CAA6C;IACzD,UAAU,EAAE,yCAAyC;CAC7C,CAAC;AAkCX,SAAgB,aAAa,CAAC,MAAuB;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IAED,MAAM,WAAW,GAAgB,MAAM,CAAC,WAAW,IAAI,YAAY,CAAC;IACpE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC,WAAW,CAAC,CAAC;IAEzD,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;QACrC,OAAO;QACP,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,KAAM;QACrC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC;QAClC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAK;QAClD,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,KAAM;QACjD,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;KAC5C,CAAC;AACJ,CAAC"}

package/dist/cjs/core/crypto.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Cryptographic utilities for the ClearBank SDK.
+ *
+ * Uses the Web Crypto API (globally available in Node.js ≥ 18 and all modern browsers).
+ * A Node.js `crypto` module fallback handles PKCS#1 RSA private keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUUID = generateUUID;
+exports.signRequestBody = signRequestBody;
+exports.verifySignature = verifySignature;
+/**
+ * Generates a UUID v4 string using cryptographically secure random bytes.
+ */
+function generateUUID() {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, '0'));
+    return [
+        hex.slice(0, 4).join(''),
+        hex.slice(4, 6).join(''),
+        hex.slice(6, 8).join(''),
+        hex.slice(8, 10).join(''),
+        hex.slice(10, 16).join(''),
+    ].join('-');
+}
+/**
+ * Signs a request body with an RSA private key (PKCS#1 v1.5 + SHA-256).
+ * Returns Base64-encoded signature for the `DigitalSignature` header.
+ */
+async function signRequestBody(body, privateKeyPem) {
+    const cryptoKey = await importRsaPrivateKey(privateKeyPem);
+    const bodyBytes = toArrayBuffer(new TextEncoder().encode(body));
+    const signature = await globalThis.crypto.subtle.sign({ name: 'RSASSA-PKCS1-v1_5' }, cryptoKey, bodyBytes);
+    return bytesToBase64(new Uint8Array(signature));
+}
+/**
+ * Verifies a ClearBank `DigitalSignature` against the raw body using their RSA public key.
+ */
+async function verifySignature(body, signatureBase64, publicKeyPem) {
+    const cryptoKey = await importRsaPublicKey(publicKeyPem);
+    const bodyBytes = typeof body === 'string' ? toArrayBuffer(new TextEncoder().encode(body)) : toArrayBuffer(body);
+    const sigBytes = toArrayBuffer(base64ToUint8Array(signatureBase64));
+    return globalThis.crypto.subtle.verify({ name: 'RSASSA-PKCS1-v1_5' }, cryptoKey, sigBytes, bodyBytes);
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+async function importRsaPrivateKey(pem) {
+    try {
+        const der = pemToDer(pem);
+        return await globalThis.crypto.subtle.importKey('pkcs8', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+    }
+    catch {
+        // Fall back to Node.js crypto for PKCS#1 (BEGIN RSA PRIVATE KEY)
+        return importPkcs1ViaNode(pem);
+    }
+}
+async function importRsaPublicKey(pem) {
+    const der = pemToDer(pem);
+    return globalThis.crypto.subtle.importKey('spki', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+}
+/** Strips PEM headers and returns a plain ArrayBuffer. */
+function pemToDer(pem) {
+    const stripped = pem
+        .split('\n')
+        .filter((line) => !line.startsWith('-----'))
+        .join('');
+    return toArrayBuffer(base64ToUint8Array(stripped));
+}
+/**
+ * Copies a Uint8Array into a fresh ArrayBuffer.
+ * Required because TypeScript's Web Crypto types expect a plain ArrayBuffer,
+ * not an ArrayBufferLike (which includes SharedArrayBuffer).
+ */
+function toArrayBuffer(bytes) {
+    const buf = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buf).set(bytes);
+    return buf;
+}
+/** Decodes a Base64 string to a Uint8Array. */
+function base64ToUint8Array(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/** Encodes a Uint8Array to a Base64 string. */
+function bytesToBase64(bytes) {
+    return btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+}
+/** Node.js fallback: convert PKCS#1 PEM to Web CryptoKey via the `crypto` built-in. */
+async function importPkcs1ViaNode(pem) {
+    const { createPrivateKey } = await Promise.resolve().then(() => require('node:crypto'));
+    const nodeKey = createPrivateKey(pem);
+    const pkcs8Buffer = nodeKey.export({ type: 'pkcs8', format: 'der' });
+    // Slice into a plain ArrayBuffer to satisfy Web Crypto's strict BufferSource constraint.
+    const der = pkcs8Buffer.buffer.slice(pkcs8Buffer.byteOffset, pkcs8Buffer.byteOffset + pkcs8Buffer.byteLength);
+    return globalThis.crypto.subtle.importKey('pkcs8', der, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/cjs/core/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../../src/core/crypto.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/http.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const index_js_1 = require("../types/index.js");
+const crypto_js_1 = require("./crypto.js");
+const retry_js_1 = require("./retry.js");
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+/**
+ * Core HTTP client. All domain services use this.
+ */
+class HttpClient {
+    constructor(config) {
+        this.config = config;
+    }
+    async get(path, params, opts) {
+        const url = buildUrl(this.config.baseUrl, path, params);
+        return this.request('GET', url, undefined, opts);
+    }
+    async post(path, body, opts) {
+        return this.request('POST', buildUrl(this.config.baseUrl, path), body, opts);
+    }
+    async put(path, body, opts) {
+        return this.request('PUT', buildUrl(this.config.baseUrl, path), body, opts);
+    }
+    async patch(path, body, opts) {
+        return this.request('PATCH', buildUrl(this.config.baseUrl, path), body, opts);
+    }
+    async delete(path, opts) {
+        return this.request('DELETE', buildUrl(this.config.baseUrl, path), undefined, opts);
+    }
+    static generateRequestId() {
+        return (0, crypto_js_1.generateUUID)();
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    async request(method, url, body, opts) {
+        const requestId = opts?.requestId ?? (0, crypto_js_1.generateUUID)();
+        const maxRetries = opts?.maxRetries ?? this.config.maxRetries;
+        const execute = () => this.executeOnce(method, url, body, requestId, opts?.headers);
+        return (0, retry_js_1.withRetry)(execute, { ...this.config, maxRetries }, (e) => e instanceof index_js_1.ClearBankError);
+    }
+    async executeOnce(method, url, body, requestId, extraHeaders) {
+        const bodyStr = body !== undefined ? JSON.stringify(body) : null;
+        const headers = await this.buildHeaders(method, bodyStr, requestId, extraHeaders);
+        const startMs = Date.now();
+        let response;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                const init = {
+                    method,
+                    headers,
+                    signal: controller.signal,
+                };
+                if (bodyStr !== null) {
+                    init.body = bodyStr;
+                }
+                response = await fetch(url, init);
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        catch (err) {
+            const durationMs = Date.now() - startMs;
+            const error = new index_js_1.ClearBankError({
+                message: err instanceof Error ? err.message : 'Network request failed',
+                requestId,
+                details: { cause: String(err) },
+            });
+            this.emitTelemetry({ method, url, statusCode: null, durationMs, requestId, error });
+            throw error;
+        }
+        const durationMs = Date.now() - startMs;
+        const correlationId = response.headers.get('x-correlation-id');
+        this.emitTelemetry({
+            method,
+            url,
+            statusCode: response.status,
+            durationMs,
+            requestId,
+            correlationId,
+            error: null,
+        });
+        return this.handleResponse(response, requestId, correlationId);
+    }
+    async buildHeaders(method, bodyStr, requestId, extraHeaders) {
+        const headers = {
+            Authorization: `Bearer ${this.config.apiToken}`,
+            'X-Request-Id': requestId,
+            Accept: 'application/json',
+        };
+        if (bodyStr !== null) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (MUTATING_METHODS.has(method) && bodyStr !== null && this.config.privateKey) {
+            headers['DigitalSignature'] = await (0, crypto_js_1.signRequestBody)(bodyStr, this.config.privateKey);
+        }
+        if (extraHeaders) {
+            Object.assign(headers, extraHeaders);
+        }
+        return headers;
+    }
+    async handleResponse(response, requestId, correlationId) {
+        if (response.status >= 200 && response.status < 300) {
+            const data = response.status === 204 ? undefined : (await parseJsonBody(response));
+            return { data, requestId, correlationId };
+        }
+        const rawBody = await parseJsonBody(response);
+        const retryAfter = parseRetryAfter(response.headers.get('retry-after'));
+        throw buildApiError(response.status, rawBody, requestId, correlationId, retryAfter);
+    }
+    emitTelemetry(event) {
+        if (this.config.telemetryHook) {
+            this.config.telemetryHook({
+                method: event.method,
+                url: event.url,
+                statusCode: event.statusCode,
+                durationMs: event.durationMs,
+                requestId: event.requestId,
+                correlationId: event.correlationId ?? null,
+                error: event.error,
+            });
+        }
+    }
+}
+exports.HttpClient = HttpClient;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildUrl(base, path, params) {
+    const url = base + path;
+    if (!params)
+        return url;
+    const qs = Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+        .join('&');
+    return qs ? `${url}?${qs}` : url;
+}
+async function parseJsonBody(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const n = parseInt(value, 10);
+    return isNaN(n) ? null : n;
+}
+function buildApiError(status, body, requestId, correlationId, retryAfterSeconds) {
+    let message = `HTTP ${status}`;
+    let code = null;
+    let details = null;
+    if (body && typeof body === 'object') {
+        const b = body;
+        if (typeof b['title'] === 'string' && typeof b['detail'] === 'string') {
+            message = `${b['title']}: ${b['detail']}`;
+        }
+        else if (typeof b['title'] === 'string') {
+            message = b['title'];
+        }
+        else if (typeof b['message'] === 'string') {
+            message = b['message'];
+        }
+        else if (typeof b['error'] === 'string') {
+            message = b['error'];
+            code = b['error'];
+        }
+        details = b;
+    }
+    return new index_js_1.ClearBankError({
+        message,
+        statusCode: status,
+        code,
+        correlationId,
+        requestId,
+        details,
+        retryAfterSeconds,
+    });
+}
+//# sourceMappingURL=http.js.map