velirapay 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this library are documented here. It follows [Semantic Versioning](https://semver.org).
 
+## 0.2.2 - 2026-11-12
+
+- `charge.customer.ipCountry`, `ipAsn` and `ipNetwork`: what VeliraPay works out from the customer's IP address, in the API's answers and in webhooks alike. `ipCountry` is the country the hosted checkout placed the address in, as an ISO 3166 two-letter code or `T1` for Tor, and `null` for a charge created through the API; `ipAsn` is the number of the network (autonomous system) the address belongs to, and `ipNetwork` who runs it, such as `24940` and `'Hetzner Online GmbH'`. A customer on a hosting company's network is often a bot or someone hiding behind a server. They are read only, and `null` in a payload that leaves them out.
+
+## 0.2.1 - 2026-11-12
+
+- `invoices.create()` takes `success_url` and `cancel_url`, public https:// addresses the invoice's page and its charges' checkout offer the customer a way back to: a button once they have paid, and a link while it is open. `invoice.successUrl` and `invoice.cancelUrl` read them back, and are `null` in webhooks, which leave them out.
+
 ## 0.2.0 - 2026-11-12
 
 ### Breaking

package/README.md

@@ -203,6 +203,8 @@ charge.customer.metadata;  // { orders: 7 }
 
 Every field is optional, and any other key is refused with a `ValidationError`. The older `customer_email` parameter still works.
 
+The customer also comes back with what VeliraPay works out from the IP address, which you cannot send: `ipCountry`, the country the hosted checkout placed it in, as an ISO 3166 two-letter code or `'T1'` for Tor (`null` for a charge created through the API), and `ipAsn` and `ipNetwork`, the number of the network it belongs to and who runs it, such as `24940` and `'Hetzner Online GmbH'`. A customer on a hosting company's network is often a bot or someone hiding behind a server, and a country that differs from the one they gave is worth a second look.
+
 ### Network surcharges
 
 Passing a payment on costs the same whatever its size on some networks, so the customer pays that part: a charge in USDT on Tron (`Asset.USDT_TRON`) asks for 2.50 USDT on top of the price. The coin says so before it is chosen, as `coin.networkSurcharge` from `assets.list()`, so tell the customer; the checkout does. A charge counts it in `assetAmount` and gives it again as `charge.networkSurcharge`, which is `null` for every coin without one. VeliraPay keeps it: it is not part of your payout, and a refund can never include it.
@@ -243,6 +245,7 @@ const invoice = await velirapay.invoices.create({
         { description: 'Hosting', quantity: '1', unit_amount: '250.00' },
     ],
     due_at: '2026-12-01', // a day, as YYYY-MM-DD
+    success_url: 'https://example.com/orders/1042',
     send_email: true,
 });
 
@@ -469,7 +472,7 @@ The charge and invoice in a delivery are not quite the ones the API answers with
 
 - A charge's coin amounts and exchange rate carry all 18 decimal places (`"0.002500000000000000"` rather than `"0.0025"`). Compare amounts as numbers, not as strings.
 - A charge has no `timeline`, `refunds`, `checkoutUrl`, `receiptUrl`, `successUrl`, `cancelUrl` or `successMessage`. It names its payment link with its title and its invoice with its number: `charge.paymentLink` and `charge.invoice` hold the codes, and `charge.paymentLinkTitle` and `charge.invoiceNumber` the rest, which are `null` on the API's charges.
-- An invoice has no `overdue` or `documentUrl`; both are `null`.
+- An invoice has no `overdue`, `documentUrl`, `successUrl` or `cancelUrl`; all four are `null`.
 - `charge.refunded` carries no refund. Read its amount, txid and reason from the event: `(await velirapay.events.retrieve(eventId)).details`.
 
 Fetch the object when you need what a delivery leaves out.

package/dist/cjs/client.d.ts

@@ -36,7 +36,7 @@ export interface ClientOptions {
 export declare class VeliraPayClient {
     #private;
     /** The version of this library. */
-    static readonly VERSION = "0.2.0";
+    static readonly VERSION = "0.2.2";
     /** The address of the VeliraPay API. */
     static readonly DEFAULT_BASE_URL = "https://api.velirapay.com";
     /** The account the API key belongs to. */

package/dist/cjs/params.d.ts

@@ -93,6 +93,10 @@ export interface InvoiceCreateParams {
     memo?: string | null;
     /** The day it is due, as YYYY-MM-DD. */
     due_at?: string | null;
+    /** A public https:// address the customer is offered a button back to once they have paid. */
+    success_url?: string | null;
+    /** A public https:// address the customer can go back to from the invoice without paying. */
+    cancel_url?: string | null;
     send_email?: boolean;
 }
 export interface InvoiceListParams extends PageParams {

package/dist/cjs/resources/charge.d.ts

@@ -112,6 +112,12 @@ export declare class Customer extends ApiResource {
     readonly name: string | null;
     /** The IP address the customer paid from, recorded by the checkout or passed when the charge was created. */
     readonly ipAddress: string | null;
+    /** The country the hosted checkout placed the IP address in, as an ISO 3166 two-letter code, or T1 for Tor; null for a charge created through the API. */
+    readonly ipCountry: string | null;
+    /** The number of the network (autonomous system) the IP address belongs to, such as 24940. */
+    readonly ipAsn: number | null;
+    /** Who runs that network, such as an internet provider or a hosting company. */
+    readonly ipNetwork: string | null;
     /** The user agent of the browser the customer paid from. */
     readonly userAgent: string | null;
     /** Your own id for the customer. */

package/dist/cjs/resources/charge.js

@@ -153,6 +153,12 @@ class Customer extends api_resource_ts_1.ApiResource {
     name;
     /** The IP address the customer paid from, recorded by the checkout or passed when the charge was created. */
     ipAddress;
+    /** The country the hosted checkout placed the IP address in, as an ISO 3166 two-letter code, or T1 for Tor; null for a charge created through the API. */
+    ipCountry;
+    /** The number of the network (autonomous system) the IP address belongs to, such as 24940. */
+    ipAsn;
+    /** Who runs that network, such as an internet provider or a hosting company. */
+    ipNetwork;
     /** The user agent of the browser the customer paid from. */
     userAgent;
     /** Your own id for the customer. */
@@ -168,6 +174,9 @@ class Customer extends api_resource_ts_1.ApiResource {
         this.email = (0, api_resource_ts_1.nullableString)(attributes, 'email');
         this.name = (0, api_resource_ts_1.nullableString)(attributes, 'name');
         this.ipAddress = (0, api_resource_ts_1.nullableString)(attributes, 'ip_address');
+        this.ipCountry = (0, api_resource_ts_1.nullableString)(attributes, 'ip_country');
+        this.ipAsn = (0, api_resource_ts_1.nullableInt)(attributes, 'ip_asn');
+        this.ipNetwork = (0, api_resource_ts_1.nullableString)(attributes, 'ip_network');
         this.userAgent = (0, api_resource_ts_1.nullableString)(attributes, 'user_agent');
         this.reference = (0, api_resource_ts_1.nullableString)(attributes, 'reference');
         this.phone = (0, api_resource_ts_1.nullableString)(attributes, 'phone');

package/dist/cjs/resources/invoice.d.ts

@@ -46,6 +46,10 @@ export declare class Invoice extends ApiResource {
     readonly voidedAt: Date | null;
     /** When it was created. */
     readonly createdAt: Date | null;
+    /** The page the customer is offered a button back to once they have paid; absent from webhooks. */
+    readonly successUrl: string | null;
+    /** The page the customer can go back to from the invoice without paying; absent from webhooks. */
+    readonly cancelUrl: string | null;
     constructor(attributes: Attributes);
     /** Whether the invoice can still be paid. */
     isOpen(): boolean;

package/dist/cjs/resources/invoice.js

@@ -43,6 +43,10 @@ class Invoice extends api_resource_ts_1.ApiResource {
     voidedAt;
     /** When it was created. */
     createdAt;
+    /** The page the customer is offered a button back to once they have paid; absent from webhooks. */
+    successUrl;
+    /** The page the customer can go back to from the invoice without paying; absent from webhooks. */
+    cancelUrl;
     constructor(attributes) {
         super(attributes);
         this.id = (0, api_resource_ts_1.string)(attributes, 'id', (0, api_resource_ts_1.string)(attributes, 'code'));
@@ -68,6 +72,8 @@ class Invoice extends api_resource_ts_1.ApiResource {
         this.paidAt = (0, api_resource_ts_1.date)(attributes, 'paid_at');
         this.voidedAt = (0, api_resource_ts_1.date)(attributes, 'voided_at');
         this.createdAt = (0, api_resource_ts_1.date)(attributes, 'created_at');
+        this.successUrl = (0, api_resource_ts_1.nullableString)(attributes, 'success_url');
+        this.cancelUrl = (0, api_resource_ts_1.nullableString)(attributes, 'cancel_url');
     }
     /** Whether the invoice can still be paid. */
     isOpen() {

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
 /** The version of this library. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.2";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /** The version of this library. */
-exports.VERSION = '0.2.0';
+exports.VERSION = '0.2.2';

package/dist/esm/client.d.ts

@@ -36,7 +36,7 @@ export interface ClientOptions {
 export declare class VeliraPayClient {
     #private;
     /** The version of this library. */
-    static readonly VERSION = "0.2.0";
+    static readonly VERSION = "0.2.2";
     /** The address of the VeliraPay API. */
     static readonly DEFAULT_BASE_URL = "https://api.velirapay.com";
     /** The account the API key belongs to. */

package/dist/esm/params.d.ts

@@ -93,6 +93,10 @@ export interface InvoiceCreateParams {
     memo?: string | null;
     /** The day it is due, as YYYY-MM-DD. */
     due_at?: string | null;
+    /** A public https:// address the customer is offered a button back to once they have paid. */
+    success_url?: string | null;
+    /** A public https:// address the customer can go back to from the invoice without paying. */
+    cancel_url?: string | null;
     send_email?: boolean;
 }
 export interface InvoiceListParams extends PageParams {

package/dist/esm/resources/charge.d.ts

@@ -112,6 +112,12 @@ export declare class Customer extends ApiResource {
     readonly name: string | null;
     /** The IP address the customer paid from, recorded by the checkout or passed when the charge was created. */
     readonly ipAddress: string | null;
+    /** The country the hosted checkout placed the IP address in, as an ISO 3166 two-letter code, or T1 for Tor; null for a charge created through the API. */
+    readonly ipCountry: string | null;
+    /** The number of the network (autonomous system) the IP address belongs to, such as 24940. */
+    readonly ipAsn: number | null;
+    /** Who runs that network, such as an internet provider or a hosting company. */
+    readonly ipNetwork: string | null;
     /** The user agent of the browser the customer paid from. */
     readonly userAgent: string | null;
     /** Your own id for the customer. */

package/dist/esm/resources/charge.js

@@ -1,5 +1,5 @@
 import { ChargeStatus } from '../enums.js';
-import { ApiResource, bool, date, int, map, nullableString, objects, records, reference, string } from './api-resource.js';
+import { ApiResource, bool, date, int, map, nullableInt, nullableString, objects, records, reference, string } from './api-resource.js';
 /** A single payment in one coin, with the rate locked and a deposit address of its own. */
 export class Charge extends ApiResource {
     /** The charge's public code, also the last segment of its checkout URL. */
@@ -149,6 +149,12 @@ export class Customer extends ApiResource {
     name;
     /** The IP address the customer paid from, recorded by the checkout or passed when the charge was created. */
     ipAddress;
+    /** The country the hosted checkout placed the IP address in, as an ISO 3166 two-letter code, or T1 for Tor; null for a charge created through the API. */
+    ipCountry;
+    /** The number of the network (autonomous system) the IP address belongs to, such as 24940. */
+    ipAsn;
+    /** Who runs that network, such as an internet provider or a hosting company. */
+    ipNetwork;
     /** The user agent of the browser the customer paid from. */
     userAgent;
     /** Your own id for the customer. */
@@ -164,6 +170,9 @@ export class Customer extends ApiResource {
         this.email = nullableString(attributes, 'email');
         this.name = nullableString(attributes, 'name');
         this.ipAddress = nullableString(attributes, 'ip_address');
+        this.ipCountry = nullableString(attributes, 'ip_country');
+        this.ipAsn = nullableInt(attributes, 'ip_asn');
+        this.ipNetwork = nullableString(attributes, 'ip_network');
         this.userAgent = nullableString(attributes, 'user_agent');
         this.reference = nullableString(attributes, 'reference');
         this.phone = nullableString(attributes, 'phone');

package/dist/esm/resources/invoice.d.ts

@@ -46,6 +46,10 @@ export declare class Invoice extends ApiResource {
     readonly voidedAt: Date | null;
     /** When it was created. */
     readonly createdAt: Date | null;
+    /** The page the customer is offered a button back to once they have paid; absent from webhooks. */
+    readonly successUrl: string | null;
+    /** The page the customer can go back to from the invoice without paying; absent from webhooks. */
+    readonly cancelUrl: string | null;
     constructor(attributes: Attributes);
     /** Whether the invoice can still be paid. */
     isOpen(): boolean;

package/dist/esm/resources/invoice.js

@@ -40,6 +40,10 @@ export class Invoice extends ApiResource {
     voidedAt;
     /** When it was created. */
     createdAt;
+    /** The page the customer is offered a button back to once they have paid; absent from webhooks. */
+    successUrl;
+    /** The page the customer can go back to from the invoice without paying; absent from webhooks. */
+    cancelUrl;
     constructor(attributes) {
         super(attributes);
         this.id = string(attributes, 'id', string(attributes, 'code'));
@@ -65,6 +69,8 @@ export class Invoice extends ApiResource {
         this.paidAt = date(attributes, 'paid_at');
         this.voidedAt = date(attributes, 'voided_at');
         this.createdAt = date(attributes, 'created_at');
+        this.successUrl = nullableString(attributes, 'success_url');
+        this.cancelUrl = nullableString(attributes, 'cancel_url');
     }
     /** Whether the invoice can still be paid. */
     isOpen() {

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 /** The version of this library. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.2";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 /** The version of this library. */
-export const VERSION = '0.2.0';
+export const VERSION = '0.2.2';

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://www.schemastore.org/package.json",
     "name": "velirapay",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "description": "The official Node.js library for VeliraPay crypto payments: charges, payment links, invoices, payouts, events and webhook verification.",
     "keywords": [
         "velirapay",