velirapay 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this library are documented here. It follows [Semantic Versioning](https://semver.org).
+
+## 0.1.1 - 2026-11-12
+
+- The charges that `charges.create()`, `retrieve()`, `list()`, `iterator()`, `cancel()`, `recordRefund()`, `send()`, `accept()` and `simulate()` answer with are typed `ApiCharge`, whose `checkoutUrl` is a `string`, so `res.redirect(303, charge.checkoutUrl)` compiles under TypeScript's `strict`. Charges in webhooks and events keep `checkoutUrl: string | null`, since webhooks leave it out. Nothing changes at runtime.
+
+## 0.1.0 - 2026-11-12
+
+The first version, covering what the PHP library covers as of its 0.6.5:
+
+- `VeliraPayClient` with `account`, `assets`, `charges`, `paymentLinks`, `invoices`, `coupons`, `payouts`, `payoutAddresses`, `events`, `webhookEndpoints`, `overview`, `activity`, `apiKeys`, `members`, `invitations` and `billing`, each answering with typed objects that keep every attribute the API sent (`get()`, `toJSON()`).
+- `Page` for lists, with `nextPage()` and `autoPagingIterator()`, and `iterator()` on every paged list for `for await`.
+- An error class per kind of failure, all extending `VeliraPayError`: `AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `ServerError`, `InvalidRequestError`, `UnexpectedResponseError`, `ConnectionError`, `SignatureVerificationError` and `InvalidArgumentError`.
+- Retries of network errors, rate limits and outages, with an `Idempotency-Key` on every write so a retried one is carried out once.
+- `Webhook.constructEvent()` and `constructEventFromRequest()`, which check the signature, the second one sent for a day after a secret is rotated, and its age.
+- `Asset` also has `BTC_LIGHTNING`, `ETH_BASE`, `ETH_ARBITRUM` and `POL`, which the API's contract defines, and charges and coins read the `network_surcharge` the API sends, and charges its `payment_request`.
+- ES module and CommonJS builds with their type definitions, for Node.js 22 or later, without dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VeliraPay
+
+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

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# VeliraPay for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Tests](https://github.com/VeliraPay/velirapay-node/actions/workflows/tests.yml/badge.svg)](https://github.com/VeliraPay/velirapay-node/actions/workflows/tests.yml)
+[![Latest version](https://img.shields.io/npm/v/velirapay)](https://www.npmjs.com/package/velirapay)
+[![License](https://img.shields.io/github/license/VeliraPay/velirapay-node)](LICENSE)
+
+The official Node.js library for [VeliraPay](https://velirapay.com), the crypto payment processor. It covers the v1 API (the coins on offer, charges, invoices, payment links, coupons, payouts, events, webhook endpoints and your account) and verifies the webhooks VeliraPay sends you. It is written in TypeScript, ships its type definitions and has no dependencies.
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Charging a customer](#charging-a-customer)
+- [Verifying webhooks](#verifying-webhooks)
+- [Which one to use](#which-one-to-use)
+- [What the client covers](#what-the-client-covers)
+- [Lists and pagination](#lists-and-pagination)
+- [Errors](#errors)
+- [Retries and idempotency](#retries-and-idempotency)
+- [Test mode](#test-mode)
+- [Configuration](#configuration)
+
+The full API reference is at [velirapay.com/docs](https://velirapay.com/docs).
+
+## Requirements
+
+Node.js 22 or later. The package works with both `import` and `require`.
+
+## Installation
+
+```bash
+npm install velirapay
+```
+
+## Charging a customer
+
+Create an API key in the dashboard under **Developers → API keys**. Keep it on your server: anyone holding it can create charges and read your payments.
+
+To charge a customer, create a charge with what you already know about them, and send them to its checkout page:
+
+```js
+import { VeliraPayClient } from 'velirapay';
+
+const velirapay = new VeliraPayClient(process.env.VELIRAPAY_API_KEY);
+
+const charge = await velirapay.charges.create({
+    amount: '49.90',
+    currency: 'EUR',
+    asset: 'BTC',
+    customer: { email: 'ada@example.com', name: 'Ada Lovelace' },
+    metadata: { order_id: '1042' },
+    success_url: 'https://example.com/orders/1042',
+}, { idempotencyKey: 'order-1042' });
+
+res.redirect(303, charge.checkoutUrl);
+```
+
+They pay there, and VeliraPay tells your server about it with a [webhook](#verifying-webhooks). The exchange rate is locked when the charge is created, and the customer has 30 minutes to pay.
+
+Parameters are sent as the API names them, in snake_case, and objects come back with camelCase properties: `charge.checkoutUrl`, `charge.assetAmount`, `charge.customer.ipAddress`. Amounts are always strings, such as `'49.90'`, never floating-point numbers, so no precision is lost. A charge the API answers with is an `ApiCharge`, whose `checkoutUrl` is always a string. Charges in webhooks leave it out, so theirs is `string | null`.
+
+With CommonJS:
+
+```js
+const { VeliraPayClient } = require('velirapay');
+```
+
+A charge from your server comes from your server rather than the customer, so pass what you know about them as `customer` (`email`, `name`, `ip_address`, `user_agent`, `reference`, `phone`, `country` and `metadata`); it helps you spot fraud before you ship anything. `charge.customer` reads it back.
+
+## Verifying webhooks
+
+Add an endpoint in the dashboard under **Developers → Webhooks** and copy its signing secret (`whsec_…`). `Webhook.constructEvent()` checks a delivery's signature and parses it. Pass it the **raw** body: a body parsed and encoded again no longer matches its signature. With Express:
+
+```js
+import express from 'express';
+import { SignatureVerificationError, Webhook } from 'velirapay';
+
+const app = express();
+
+app.post('/webhooks/velirapay', express.raw({ type: 'application/json' }), (req, res) => {
+    let event;
+
+    try {
+        event = Webhook.constructEvent(req.body, req.get(Webhook.SIGNATURE_HEADER), process.env.VELIRAPAY_WEBHOOK_SECRET);
+    } catch (error) {
+        if (error instanceof SignatureVerificationError) {
+            return res.sendStatus(400);
+        }
+
+        throw error;
+    }
+
+    // Sent when the endpoint is added or moved: it receives nothing else until it answers.
+    if (event.isVerification()) {
+        return res.type('application/json').send(event.challengeResponse());
+    }
+
+    // The same event can arrive more than once: remember this key, and skip the events you have handled.
+    const key = event.eventId ?? event.id;
+
+    if (event.is('charge.paid')) {
+        // Fulfil the order event.charge.metadata.order_id.
+    }
+
+    res.sendStatus(200);
+});
+```
+
+Where a framework hands you a Fetch API `Request`, as Next.js route handlers do, `await Webhook.constructEventFromRequest(request, secret)` reads the body and the header itself.
+
+Some things to know:
+
+- **Answer the verification challenge.** When an endpoint is added, or its URL changes, VeliraPay sends it a signed `webhook.verification` delivery and sends it nothing else until it answers with HTTP 200 and the challenge, as `event.challengeResponse()` gives it. Endpoint URLs must use `https://`.
+- **A second signature for a day after a rotation.** For a day after you rotate the signing secret, the `X-VeliraPay-Signature` header carries a `v1` made with the old secret too, so a receiver that still has the old one keeps working. `constructEvent()` accepts a delivery whichever `v1` matches.
+- **Signatures expire.** A signature more than 5 minutes from the current time is rejected, which stops an intercepted delivery from being replayed. Change the limit with the `tolerance` argument, in seconds; `0` turns the age check off.
+- **Answer quickly.** A delivery counts as delivered when your endpoint answers with a 2xx status within 15 seconds, so queue slow work. Redirects are not followed.
+- **Failed deliveries are retried.** A delivery is tried 14 times over about 3 days.
+- **Skip duplicates by event.** A retried delivery keeps its id (`event.id`), but each endpoint gets its own copy of an event under its own id. `event.eventId` is the same on every copy, so `event.eventId ?? event.id` is the key to remember.
+- **Fulfil once.** A paid invoice sends both `charge.paid`, for the charge that paid it, and `invoice.paid`. Fulfil on one of them.
+- **Deliveries can arrive out of order.** When the order matters, fetch the current state with `velirapay.charges.retrieve(event.charge.id)`.
+
+`charge.payment_detected` arrives as soon as a transfer is seen, before it is confirmed: tell the customer, but do not fulfil. It and `charge.late_payment` carry that transfer as `event.transaction`; `payout.sent` and `payout.confirmed` carry the payout as `event.payout`.
+
+To test your handler, sign a payload yourself: `Webhook.signatureHeader(payload, 'whsec_test')` gives the header VeliraPay would send.
+
+## Which one to use
+
+| When | Use | |
+| --- | --- | --- |
+| You are asking one customer for one payment | A charge | The default. It has one checkout page for that one payment, with the rate locked for 30 minutes. |
+| The customer should choose the coin, or pays later | An invoice | It needs their name and email, has no timer, can be itemised and reminded, and lets them pick the coin on its page. |
+| Many customers pay through the same public page | A payment link, created once | A product sold again and again, a tip jar, a link on your site. |
+
+Do not create a new payment link for each customer or each order.
+
+A charge needs its coin up front, because its exchange rate, amount and deposit address depend on it. Ask the customer on your own page, and offer them the coins from `velirapay.assets.list()`, which also gives the lowest price each can be charged at.
+
+## What the client covers
+
+| Property | Methods |
+| --- | --- |
+| `charges` | `create`, `retrieve`, `list`, `iterator`, `send`, `cancel`, `accept`, `recordRefund`, `simulate` |
+| `invoices` | `create`, `retrieve`, `list`, `iterator`, `send`, `void` |
+| `paymentLinks` | `create`, `retrieve`, `update`, `list`, `iterator`, `archive`, `restore` |
+| `coupons` | `create`, `retrieve`, `update`, `list`, `iterator`, `delete` |
+| `assets` | `list` |
+| `payouts` | `retrieve` (by the charge's id), `list`, `iterator`, `summary` |
+| `payoutAddresses` | `list`, `update`, `delete` |
+| `events` | `retrieve`, `list`, `iterator` |
+| `webhookEndpoints` | `create`, `retrieve`, `update`, `delete`, `list`, `iterator`, `verify`, `test`, `rotateSecret`, `deliveries`, `retrieveDelivery`, `retryDelivery` |
+| `account` | `retrieve`, `update`, `updatePaymentSettings` |
+| `overview` | `retrieve` |
+| `activity` | `list`, `iterator` |
+| `apiKeys` | `create`, `update`, `revoke`, `list`, `iterator` |
+| `members` | `update`, `remove`, `list`, `iterator` |
+| `invitations` | `create`, `cancel`, `list`, `iterator` |
+| `billing` | `startProPayment` |
+
+Each takes the parameters the [API reference](https://velirapay.com/docs) gives, typed, and answers with an object such as a `Charge`. `get('field')` reads an attribute this version of the library does not know yet, and `JSON.stringify()` gives the object as the API sent it. Status values are in exported constants, such as `ChargeStatus.Paid` and `Asset.USDT`, and objects have helpers such as `charge.isPaid()`.
+
+Most endpoints need a permission, which a key with full access has, except the sensitive ones, such as `webhook_endpoints:write` and `api_keys:write`: only a key made with them ticked has those. A key without the permission an endpoint needs gets a `PermissionError` naming it.
+
+For an endpoint the library has no method for yet, send the request yourself: `await velirapay.request('GET', '/v1/charges', { per_page: 5 })` answers with the response, whose `json()` decodes it.
+
+## Lists and pagination
+
+`list()` methods answer with one page, newest first (members oldest first). Pass `page` and `per_page` (up to 100, 25 by default):
+
+```js
+const page = await velirapay.charges.list({ status: 'paid', per_page: 100 });
+
+for (const charge of page) {
+    // …
+}
+
+page.total;
+page.hasMore();
+const next = await page.nextPage(); // null on the last page
+```
+
+`iterator()` walks every page, fetching each one as it is reached:
+
+```js
+for await (const charge of velirapay.charges.iterator({ status: 'paid' })) {
+    // …
+}
+```
+
+`assets.list()` answers with a single page holding every coin, and `payoutAddresses.list()` and `payouts.summary()` with arrays.
+
+## Errors
+
+A failed request throws an error carrying the API's message. They are exported, and all extend `VeliraPayError`:
+
+| Error | When |
+| --- | --- |
+| `AuthenticationError` | The API key is missing, wrong or revoked (401). |
+| `PermissionError` | The API key may not do this (403): a restricted key without the permission the endpoint needs, or a key used from an IP address it does not allow. |
+| `NotFoundError` | The object does not exist, or belongs to the other mode (404). |
+| `ConflictError` | The object cannot make that change (409), such as canceling a charge that is no longer pending, or an idempotency key reused for a different request. |
+| `ValidationError` | The request has invalid fields (422). `errors()` lists them by field, and `firstError('amount')` gives the first message for one. |
+| `RateLimitError` | Too many requests (429). `retryAfter()` says how many seconds to wait. |
+| `ServerError` | VeliraPay had a problem (5xx). |
+| `InvalidRequestError` | Any other 4xx. |
+| `ConnectionError` | The API could not be reached, after any retries. |
+| `SignatureVerificationError` | A webhook's signature is missing, does not match, or is too old. |
+| `InvalidArgumentError` | The library was given something it cannot use, such as an API key that does not start with `vp_live_` or `vp_test_`. |
+
+Every error from an API answer extends `ApiError`, with `status`, `body` (the decoded response), `header(name)` and `retryAfter()`.
+
+```js
+import { ApiError, ValidationError } from 'velirapay';
+
+try {
+    await velirapay.charges.create({ amount: '0', currency: 'EUR', asset: 'BTC' });
+} catch (error) {
+    if (error instanceof ValidationError) {
+        error.errors(); // { amount: ['…'] }
+    } else if (error instanceof ApiError) {
+        error.status;
+    }
+}
+```
+
+## Retries and idempotency
+
+Requests that fail with a network error, a rate limit (429) or an outage (502, 503, 504) are tried again up to twice, waiting a little longer each time, or as long as the API's `Retry-After` header asks. A 500 is retried for reads only, since a write may have been carried out. A `Retry-After` longer than `maxRetryAfter` (10 seconds unless [configured](#configuration) otherwise) is not waited out: the error is thrown straight away, and its `retryAfter()` says how long to wait.
+
+While retries are on, each write carries an `Idempotency-Key` header, so the API carries out a retried request once. The library makes up a key per call; pass your own, such as an order number, to make a call safe to repeat across processes:
+
+```js
+const charge = await velirapay.charges.create(params, { idempotencyKey: 'order-1042' });
+```
+
+For 24 hours, a request repeating a key gets the first successful response, and `velirapay.lastResponse()?.wasReplayed()` is then true. Reusing a key with a different body throws a `ConflictError`. A key covers one account, one mode, one method and one path, and is at most 255 characters.
+
+## Test mode
+
+Keys starting with `vp_test_` work in test mode: charges are paid with test coins on each chain's test network, and nothing touches real funds. Test and live objects are fully separate, and each mode has its own webhooks.
+
+```js
+velirapay.isTestMode(); // read from the key's prefix
+
+// Pay a test charge without any coins: it becomes paid, and the webhooks go out as for a real payment.
+await velirapay.charges.simulate('k3v9x2m7q8wz');
+await velirapay.charges.simulate('k3v9x2m7q8wz', { amount: '0.001' }); // less than is due, to try an underpayment
+```
+
+## Configuration
+
+```js
+const velirapay = new VeliraPayClient(process.env.VELIRAPAY_API_KEY, {
+    maxRetries: 2,         // 0 turns retries off
+    maxRetryAfter: 10,     // the longest Retry-After, in seconds, waited out before trying again
+    timeout: 30,           // seconds an attempt may take
+    appInfo: 'MyShop/2.1', // added to the User-Agent
+    fetch: globalThis.fetch,
+});
+```
+
+`fetch` takes any implementation of the Fetch API, such as one that goes through a proxy or one that answers your tests.
+
+## Development
+
+```bash
+npm install
+npm run check   # types, the build and the tests
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cjs/client.d.ts

@@ -0,0 +1,94 @@
+import { Mode } from './enums.ts';
+import type { ApiResponse } from './http/api-response.ts';
+import { type Fetch } from './http/transport.ts';
+import type { RequestOptions } from './params.ts';
+import { AccountService } from './services/account.ts';
+import { ActivityService } from './services/activity.ts';
+import { ApiKeyService } from './services/api-keys.ts';
+import { AssetService } from './services/assets.ts';
+import { BillingService } from './services/billing.ts';
+import { ChargeService } from './services/charges.ts';
+import { CouponService } from './services/coupons.ts';
+import { EventService } from './services/events.ts';
+import { InvoiceService } from './services/invoices.ts';
+import { InvitationService, MemberService } from './services/members.ts';
+import { OverviewService } from './services/overview.ts';
+import { PaymentLinkService } from './services/payment-links.ts';
+import { PayoutAddressService } from './services/payout-addresses.ts';
+import { PayoutService } from './services/payouts.ts';
+import { WebhookEndpointService } from './services/webhook-endpoints.ts';
+/** How the client reaches the API. */
+export interface ClientOptions {
+    /** The API's address; https://api.velirapay.com unless given. */
+    baseUrl?: string;
+    /** How many times a request is tried again after a network error, a rate limit, an outage, or while one with the same idempotency key is still being processed; 0 turns retries off. 2 unless given. */
+    maxRetries?: number;
+    /** The longest Retry-After, in seconds, that is waited out before trying again; a longer one is thrown straight away. 10 unless given. */
+    maxRetryAfter?: number;
+    /** How many seconds an attempt may take. 30 unless given. */
+    timeout?: number;
+    /** Your application's name and version, added to the User-Agent. */
+    appInfo?: string;
+    /** The fetch implementation to send requests with; the global one unless given. */
+    fetch?: Fetch;
+}
+/** A client for the VeliraPay API, authenticated with one API key. */
+export declare class VeliraPayClient {
+    #private;
+    /** The version of this library. */
+    static readonly VERSION = "0.1.1";
+    /** The address of the VeliraPay API. */
+    static readonly DEFAULT_BASE_URL = "https://api.velirapay.com";
+    /** The account the API key belongs to. */
+    readonly account: AccountService;
+    /** Assets: the coins on offer, and the lowest price each can be charged at. */
+    readonly assets: AssetService;
+    /** Charges: how to ask a customer for a payment, in one coin. */
+    readonly charges: ChargeService;
+    /** Payment links: reusable checkout pages many customers pay through. */
+    readonly paymentLinks: PaymentLinkService;
+    /** Invoices: itemised bills customers pay in the coin of their choice. */
+    readonly invoices: InvoiceService;
+    /** Coupons: discount codes for the hosted checkout and new charges. */
+    readonly coupons: CouponService;
+    /** Payouts: what became of each paid charge. */
+    readonly payouts: PayoutService;
+    /** Events: the history of every charge and invoice. */
+    readonly events: EventService;
+    /** Webhook endpoints: where webhooks are delivered, and whether they can be. */
+    readonly webhookEndpoints: WebhookEndpointService;
+    /** The overview: the dashboard's figures for the last 30 days. */
+    readonly overview: OverviewService;
+    /** Payout addresses: where the account's payouts go on each network. */
+    readonly payoutAddresses: PayoutAddressService;
+    /** The activity log: everything done in the account, and who did it. */
+    readonly activity: ActivityService;
+    /** API keys: the account's keys, never reaching further than the one asking. */
+    readonly apiKeys: ApiKeyService;
+    /** Members: the people in the account and their roles. */
+    readonly members: MemberService;
+    /** Invitations: who has been asked to join and has not yet. */
+    readonly invitations: InvitationService;
+    /** Billing: paying for Pro in crypto. */
+    readonly billing: BillingService;
+    /**
+     * Create a new client.
+     *
+     * @param apiKey A secret key from the dashboard, starting with "vp_live_" or "vp_test_". Keep it on your server.
+     */
+    constructor(apiKey: string | undefined, options?: ClientOptions);
+    /** The mode the API key works in, read from its prefix. */
+    mode(): Mode;
+    /** Whether the API key moves real funds. */
+    isLiveMode(): boolean;
+    /** Whether the API key works on test networks. */
+    isTestMode(): boolean;
+    /** The response to the most recent request this client made, such as to read its headers; with requests running side by side, whichever finished last. */
+    lastResponse(): ApiResponse | null;
+    /**
+     * Send a request to an endpoint this library has no method for yet.
+     *
+     * @param params The query string for GET requests, the JSON body otherwise.
+     */
+    request(method: string, path: string, params?: object, options?: RequestOptions): Promise<ApiResponse>;
+}

package/dist/cjs/client.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeliraPayClient = void 0;
+const enums_ts_1 = require("./enums.js");
+const errors_ts_1 = require("./errors.js");
+const transport_ts_1 = require("./http/transport.js");
+const account_ts_1 = require("./services/account.js");
+const activity_ts_1 = require("./services/activity.js");
+const api_keys_ts_1 = require("./services/api-keys.js");
+const assets_ts_1 = require("./services/assets.js");
+const billing_ts_1 = require("./services/billing.js");
+const charges_ts_1 = require("./services/charges.js");
+const coupons_ts_1 = require("./services/coupons.js");
+const events_ts_1 = require("./services/events.js");
+const invoices_ts_1 = require("./services/invoices.js");
+const members_ts_1 = require("./services/members.js");
+const overview_ts_1 = require("./services/overview.js");
+const payment_links_ts_1 = require("./services/payment-links.js");
+const payout_addresses_ts_1 = require("./services/payout-addresses.js");
+const payouts_ts_1 = require("./services/payouts.js");
+const webhook_endpoints_ts_1 = require("./services/webhook-endpoints.js");
+const version_ts_1 = require("./version.js");
+/** A client for the VeliraPay API, authenticated with one API key. */
+class VeliraPayClient {
+    /** The version of this library. */
+    static VERSION = version_ts_1.VERSION;
+    /** The address of the VeliraPay API. */
+    static DEFAULT_BASE_URL = 'https://api.velirapay.com';
+    /** The account the API key belongs to. */
+    account;
+    /** Assets: the coins on offer, and the lowest price each can be charged at. */
+    assets;
+    /** Charges: how to ask a customer for a payment, in one coin. */
+    charges;
+    /** Payment links: reusable checkout pages many customers pay through. */
+    paymentLinks;
+    /** Invoices: itemised bills customers pay in the coin of their choice. */
+    invoices;
+    /** Coupons: discount codes for the hosted checkout and new charges. */
+    coupons;
+    /** Payouts: what became of each paid charge. */
+    payouts;
+    /** Events: the history of every charge and invoice. */
+    events;
+    /** Webhook endpoints: where webhooks are delivered, and whether they can be. */
+    webhookEndpoints;
+    /** The overview: the dashboard's figures for the last 30 days. */
+    overview;
+    /** Payout addresses: where the account's payouts go on each network. */
+    payoutAddresses;
+    /** The activity log: everything done in the account, and who did it. */
+    activity;
+    /** API keys: the account's keys, never reaching further than the one asking. */
+    apiKeys;
+    /** Members: the people in the account and their roles. */
+    members;
+    /** Invitations: who has been asked to join and has not yet. */
+    invitations;
+    /** Billing: paying for Pro in crypto. */
+    billing;
+    #mode;
+    #transport;
+    /**
+     * Create a new client.
+     *
+     * @param apiKey A secret key from the dashboard, starting with "vp_live_" or "vp_test_". Keep it on your server.
+     */
+    constructor(apiKey, options = {}) {
+        if (typeof apiKey !== 'string' || apiKey.trim() === '') {
+            throw new errors_ts_1.InvalidArgumentError('A VeliraPay API key is required. Create one in the dashboard under Developers > API keys.');
+        }
+        const mode = Object.values(enums_ts_1.Mode).find((candidate) => apiKey.startsWith(`vp_${candidate}_`));
+        if (mode === undefined) {
+            throw new errors_ts_1.InvalidArgumentError('A VeliraPay API key starts with "vp_live_" or "vp_test_". Copy yours from the dashboard under Developers > API keys.');
+        }
+        if (!/^[\x21-\x7e]+$/.test(apiKey)) {
+            throw new errors_ts_1.InvalidArgumentError('The API key holds a character no key has, such as a space or a line break. Check how it is loaded.');
+        }
+        const { baseUrl = VeliraPayClient.DEFAULT_BASE_URL, maxRetries = 2, maxRetryAfter = 10, timeout = 30, appInfo } = options;
+        const fetch = options.fetch ?? globalThis.fetch;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+            throw new errors_ts_1.InvalidArgumentError('The number of retries must be a whole number, 0 or more.');
+        }
+        if (!(maxRetryAfter >= 0)) {
+            throw new errors_ts_1.InvalidArgumentError('The longest Retry-After to wait out cannot be negative.');
+        }
+        if (!(timeout > 0) || !Number.isFinite(timeout)) {
+            throw new errors_ts_1.InvalidArgumentError('The timeout must be a number of seconds above 0.');
+        }
+        if (!/^https?:\/\/[^\s/]+/i.test(baseUrl) || !URL.canParse(baseUrl)) {
+            throw new errors_ts_1.InvalidArgumentError('The base URL must be an http or https address.');
+        }
+        if (typeof fetch !== 'function') {
+            throw new errors_ts_1.InvalidArgumentError('No fetch implementation was found. Use Node.js 22 or later, or pass one as the fetch option.');
+        }
+        let userAgent = `VeliraPay-Node/${version_ts_1.VERSION} Node/${globalThis.process?.versions?.node ?? 'unknown'}`;
+        if (appInfo !== undefined && appInfo.trim() !== '') {
+            if (!/^[\x20-\x7e]+$/.test(appInfo)) {
+                throw new errors_ts_1.InvalidArgumentError('The app info can only hold printable ASCII characters, as it is sent in the User-Agent header.');
+            }
+            userAgent += ` ${appInfo.trim()}`;
+        }
+        this.#mode = mode;
+        this.#transport = new transport_ts_1.HttpTransport({ apiKey, fetch, baseUrl, maxRetries, maxRetryAfter, timeout, userAgent });
+        this.account = new account_ts_1.AccountService(this.#transport);
+        this.assets = new assets_ts_1.AssetService(this.#transport);
+        this.charges = new charges_ts_1.ChargeService(this.#transport);
+        this.paymentLinks = new payment_links_ts_1.PaymentLinkService(this.#transport);
+        this.invoices = new invoices_ts_1.InvoiceService(this.#transport);
+        this.coupons = new coupons_ts_1.CouponService(this.#transport);
+        this.payouts = new payouts_ts_1.PayoutService(this.#transport);
+        this.events = new events_ts_1.EventService(this.#transport);
+        this.webhookEndpoints = new webhook_endpoints_ts_1.WebhookEndpointService(this.#transport);
+        this.overview = new overview_ts_1.OverviewService(this.#transport);
+        this.payoutAddresses = new payout_addresses_ts_1.PayoutAddressService(this.#transport);
+        this.activity = new activity_ts_1.ActivityService(this.#transport);
+        this.apiKeys = new api_keys_ts_1.ApiKeyService(this.#transport);
+        this.members = new members_ts_1.MemberService(this.#transport);
+        this.invitations = new members_ts_1.InvitationService(this.#transport);
+        this.billing = new billing_ts_1.BillingService(this.#transport);
+    }
+    /** The mode the API key works in, read from its prefix. */
+    mode() {
+        return this.#mode;
+    }
+    /** Whether the API key moves real funds. */
+    isLiveMode() {
+        return this.#mode === enums_ts_1.Mode.Live;
+    }
+    /** Whether the API key works on test networks. */
+    isTestMode() {
+        return this.#mode === enums_ts_1.Mode.Test;
+    }
+    /** The response to the most recent request this client made, such as to read its headers; with requests running side by side, whichever finished last. */
+    lastResponse() {
+        return this.#transport.lastResponse();
+    }
+    /**
+     * Send a request to an endpoint this library has no method for yet.
+     *
+     * @param params The query string for GET requests, the JSON body otherwise.
+     */
+    request(method, path, params = {}, options = {}) {
+        if (method.toUpperCase() === 'GET') {
+            return this.#transport.request('GET', path, params);
+        }
+        return this.#transport.request(method, path, {}, Object.keys(params).length === 0 ? undefined : params, options.idempotencyKey);
+    }
+}
+exports.VeliraPayClient = VeliraPayClient;