@afriex/sdk 5.0.0 → 6.0.0

package/dist/cjs/client.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Afriex = exports.API_VERSION = exports.ENVIRONMENTS = void 0;
+const api_promise_js_1 = require("./core/api-promise.js");
+const errors_js_1 = require("./core/errors.js");
+const pagination_js_1 = require("./core/pagination.js");
+const balance_js_1 = require("./resources/balance.js");
+const checkout_js_1 = require("./resources/checkout.js");
+const customers_js_1 = require("./resources/customers.js");
+const media_js_1 = require("./resources/media.js");
+const payment_batches_js_1 = require("./resources/payment-batches.js");
+const payment_methods_js_1 = require("./resources/payment-methods.js");
+const rates_js_1 = require("./resources/rates.js");
+const sme_registration_js_1 = require("./resources/sme-registration.js");
+const transactions_js_1 = require("./resources/transactions.js");
+const webhooks_js_1 = require("./resources/webhooks.js");
+const version_js_1 = require("./version.js");
+/** The base URL of each environment. `staging` is the sandbox's older name. */
+exports.ENVIRONMENTS = {
+    sandbox: 'https://sandbox.api.afriex.com',
+    staging: 'https://sandbox.api.afriex.com',
+    production: 'https://api.afriex.com',
+};
+/**
+ * The API version this release of the SDK was built against, sent as
+ * `x-api-version`. Each SDK release targets one API version.
+ */
+exports.API_VERSION = '2026-05-18';
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_RETRY_AFTER_SECONDS = 60;
+class Afriex {
+    customers = new customers_js_1.Customers(this);
+    transactions = new transactions_js_1.Transactions(this);
+    paymentMethods = new payment_methods_js_1.PaymentMethods(this);
+    paymentBatches = new payment_batches_js_1.PaymentBatches(this);
+    balance = new balance_js_1.Balance(this);
+    rates = new rates_js_1.Rates(this);
+    checkout = new checkout_js_1.Checkout(this);
+    media = new media_js_1.Media(this);
+    smeRegistration = new sme_registration_js_1.SmeRegistration(this);
+    webhooks;
+    baseURL;
+    apiVersion;
+    timeout;
+    maxRetries;
+    #apiKey;
+    #signRequest;
+    #defaultHeaders;
+    #fetch;
+    constructor(options = {}) {
+        if (!options.dangerouslyAllowBrowser && isBrowser()) {
+            throw new errors_js_1.AfriexError('The Afriex SDK must not run in a browser, where your API key would be visible to anyone. Call the API from your server.');
+        }
+        const apiKey = options.apiKey ?? readEnv('AFRIEX_API_KEY');
+        if (!apiKey) {
+            throw new errors_js_1.AfriexError('Missing API key. Pass `apiKey` or set the AFRIEX_API_KEY environment variable.');
+        }
+        const environment = options.environment ?? 'production';
+        if (!(environment in exports.ENVIRONMENTS)) {
+            throw new errors_js_1.AfriexError(`Unknown environment "${environment}". Use "sandbox" or "production".`);
+        }
+        this.#apiKey = apiKey;
+        this.baseURL = (options.baseURL ?? exports.ENVIRONMENTS[environment]).replace(/\/+$/, '');
+        this.apiVersion = options.apiVersion ?? exports.API_VERSION;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.#signRequest = options.signRequest;
+        this.#defaultHeaders = options.defaultHeaders ?? {};
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.webhooks = new webhooks_js_1.Webhooks(this, options.webhookPublicKey);
+    }
+    /**
+     * Sends a request and returns the parsed JSON body. The resource methods
+     * call this; use it yourself only for an endpoint they don't cover yet.
+     */
+    request(method, path, init = {}) {
+        return new api_promise_js_1.APIPromise(this.#send(method, path, init), (raw) => raw.body);
+    }
+    /** @internal Fetches one page of a list endpoint. */
+    getPage(path, query = {}, options) {
+        const fetchPage = (page, limit) => this.getPage(path, { ...query, page, limit }, options);
+        return new pagination_js_1.PagePromise(this.#send('get', path, { query, options }), query, fetchPage);
+    }
+    /** @internal Sends a request with the configured `fetch`, without the API key. For presigned upload URLs. */
+    fetchUnauthenticated(url, init) {
+        return this.#fetch(url, init);
+    }
+    async #send(method, path, init) {
+        const url = this.#buildURL(path, init.query);
+        const body = init.body === undefined ? undefined : JSON.stringify(init.body);
+        const headers = await this.#buildHeaders(method, url, body, init.options);
+        const maxRetries = init.options?.maxRetries ?? this.maxRetries;
+        const timeout = init.options?.timeout ?? this.timeout;
+        const signal = init.options?.signal;
+        // A request that can't be repeated safely is retried only on 429, which
+        // the API sends before it does anything.
+        const safeToRepeat = method === 'get' || init.idempotent === true;
+        for (let attempt = 0;; attempt++) {
+            let raw;
+            try {
+                raw = await this.#attempt(url, { method: method.toUpperCase(), headers, body }, timeout, signal);
+            }
+            catch (error) {
+                if (error instanceof errors_js_1.APIUserAbortError || !safeToRepeat || attempt >= maxRetries) {
+                    throw error;
+                }
+                await sleep(backoff(attempt));
+                continue;
+            }
+            const { response } = raw;
+            if (response.ok)
+                return raw;
+            const retryable = response.status === 429 ||
+                (safeToRepeat && (response.status === 408 || response.status >= 500));
+            if (retryable && attempt < maxRetries) {
+                await sleep(retryAfter(response.headers) ?? backoff(attempt));
+                continue;
+            }
+            throw errors_js_1.APIError.from(response.status, raw.body, response.headers);
+        }
+    }
+    async #attempt(url, init, timeout, signal) {
+        if (signal?.aborted)
+            throw new errors_js_1.APIUserAbortError();
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        const onAbort = () => controller.abort();
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const response = await this.#fetch(url, { ...init, signal: controller.signal });
+            return { response, body: await parseBody(response) };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new errors_js_1.APIUserAbortError();
+            if (timedOut)
+                throw new errors_js_1.APIConnectionTimeoutError();
+            throw new errors_js_1.APIConnectionError(undefined, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    #buildURL(path, query) {
+        const url = new URL(this.baseURL + path);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            // The API takes list filters as comma-separated values (form style, explode=false).
+            url.searchParams.set(key, Array.isArray(value) ? value.join(',') : String(value));
+        }
+        return url.toString();
+    }
+    async #buildHeaders(method, url, body, options) {
+        const headers = new Headers({
+            Accept: 'application/json',
+            'User-Agent': `afriex-node/${version_js_1.VERSION}`,
+            'x-api-key': this.#apiKey,
+            'x-api-version': this.apiVersion,
+            ...this.#defaultHeaders,
+        });
+        if (body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        if (this.#signRequest) {
+            const signature = await this.#signRequest({
+                method: method.toUpperCase(),
+                url,
+                body: body ?? '',
+            });
+            if (signature)
+                headers.set('x-api-signature', signature);
+        }
+        for (const [name, value] of Object.entries(options?.headers ?? {})) {
+            if (value === null || value === undefined)
+                headers.delete(name);
+            else
+                headers.set(name, value);
+        }
+        return headers;
+    }
+}
+exports.Afriex = Afriex;
+async function parseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('json')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/** 0.5s doubling per attempt, capped at 8s, with up to 25% jitter. */
+function backoff(attempt) {
+    const delay = Math.min(0.5 * 2 ** attempt, 8);
+    return delay * (1 - Math.random() * 0.25) * 1000;
+}
+/** The server's `Retry-After`, in milliseconds, when it is a sensible value. */
+function retryAfter(headers) {
+    const value = headers.get('retry-after');
+    if (!value)
+        return undefined;
+    let seconds = Number(value);
+    if (Number.isNaN(seconds))
+        seconds = (Date.parse(value) - Date.now()) / 1000;
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_RETRY_AFTER_SECONDS) {
+        return undefined;
+    }
+    return seconds * 1000;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function readEnv(name) {
+    const value = globalThis.process?.env?.[name];
+    return value?.trim() || undefined;
+}
+function isBrowser() {
+    return 'window' in globalThis && 'document' in globalThis;
+}

package/dist/cjs/core/api-promise.d.ts

@@ -0,0 +1,25 @@
+/** A response as the client received it, with its body already parsed. */
+export interface RawResponse {
+    response: Response;
+    body: unknown;
+}
+/**
+ * The promise every SDK method returns. Await it for the parsed result, or call
+ * `withResponse()` to also get the HTTP response and its request id.
+ */
+export declare class APIPromise<T> extends Promise<T> {
+    #private;
+    constructor(responsePromise: Promise<RawResponse>, parse: (raw: RawResponse) => T | Promise<T>);
+    static get [Symbol.species](): PromiseConstructor;
+    /** @internal Builds a promise of a value derived from this one's result. */
+    _thenUnwrap<U>(fn: (value: T) => U): APIPromise<U>;
+    /** The parsed result together with the HTTP response it came from. */
+    withResponse(): Promise<{
+        data: T;
+        response: Response;
+        requestId: string | undefined;
+    }>;
+    then<R1 = T, R2 = never>(onfulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: unknown) => R | PromiseLike<R>) | null): Promise<T | R>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+}

package/dist/cjs/core/api-promise.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIPromise = void 0;
+/**
+ * The promise every SDK method returns. Await it for the parsed result, or call
+ * `withResponse()` to also get the HTTP response and its request id.
+ */
+class APIPromise extends Promise {
+    #parsed;
+    #responsePromise;
+    #parse;
+    constructor(responsePromise, parse) {
+        // The value comes from `then` below, never from this executor.
+        super((resolve) => resolve(null));
+        this.#responsePromise = responsePromise;
+        this.#parse = parse;
+    }
+    // Lets `then`, `catch` and `finally` return plain promises.
+    static get [Symbol.species]() {
+        return Promise;
+    }
+    /** @internal Builds a promise of a value derived from this one's result. */
+    _thenUnwrap(fn) {
+        return new APIPromise(this.#responsePromise, async (raw) => fn(await this.#parse(raw)));
+    }
+    /** The parsed result together with the HTTP response it came from. */
+    async withResponse() {
+        const [data, raw] = await Promise.all([this.#value(), this.#responsePromise]);
+        return {
+            data,
+            response: raw.response,
+            requestId: raw.response.headers.get('x-request-id') ?? undefined,
+        };
+    }
+    #value() {
+        this.#parsed ??= this.#responsePromise.then((raw) => this.#parse(raw));
+        return this.#parsed;
+    }
+    then(onfulfilled, onrejected) {
+        return this.#value().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.#value().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.#value().finally(onfinally);
+    }
+}
+exports.APIPromise = APIPromise;

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,78 @@
+import type { ErrorResponse } from '../generated/openapi.js';
+/** Base class for every error the SDK throws. */
+export declare class AfriexError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API answered with a status outside 2xx. Catch a subclass to handle one
+ * status, or this class to handle any of them.
+ */
+export declare class APIError extends AfriexError {
+    /** The HTTP status. */
+    readonly status: number;
+    /** Machine-readable error code from the body, such as `DUPLICATE_REQUEST`. */
+    readonly code: string | undefined;
+    /** The `details` object from the body, when the API sent one. */
+    readonly details: ErrorResponse['details'] | undefined;
+    /** The response body as received, parsed when it was JSON. */
+    readonly body: unknown;
+    readonly headers: Headers;
+    /** The `x-request-id` header. Quote it when you contact support. */
+    readonly requestId: string | undefined;
+    constructor(status: number, body: unknown, headers: Headers);
+    /** Builds the subclass that matches the status. */
+    static from(status: number, body: unknown, headers: Headers): APIError;
+    private static messageFrom;
+}
+/** 400: the request was malformed. Nothing was done. */
+export declare class BadRequestError extends APIError {
+}
+/**
+ * 401: the API key is missing, wrong, revoked, or lacks the permission this
+ * endpoint needs. The API does not say which.
+ */
+export declare class AuthenticationError extends APIError {
+}
+/** 403: the request is not allowed, for example from an address outside your IP allowlist. */
+export declare class PermissionDeniedError extends APIError {
+}
+/** 404: the resource does not exist, or belongs to another business. */
+export declare class NotFoundError extends APIError {
+}
+/**
+ * 409: for a transaction, `DUPLICATE_REQUEST` means its idempotency key or
+ * reference is already taken. Look the transaction up by its reference rather
+ * than sending it again.
+ */
+export declare class ConflictError extends APIError {
+}
+/** 422: the request was well formed but failed validation. Nothing was done. */
+export declare class UnprocessableEntityError extends APIError {
+}
+/** 429: the request was not processed. Retry after `retryAfter` seconds. */
+export declare class RateLimitError extends APIError {
+    /** Seconds to wait, from the `Retry-After` header. */
+    get retryAfter(): number | undefined;
+}
+/** 500 or above. */
+export declare class InternalServerError extends APIError {
+}
+/** No response arrived: DNS, TLS, refused or reset connection. */
+export declare class APIConnectionError extends AfriexError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** No response arrived within the timeout. */
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message?: string);
+}
+/** The request was cancelled through the `signal` you passed. */
+export declare class APIUserAbortError extends AfriexError {
+    constructor(message?: string);
+}
+/** A webhook's signature did not match its body, or no public key was configured. */
+export declare class WebhookVerificationError extends AfriexError {
+}

package/dist/cjs/core/errors.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.APIUserAbortError = exports.APIConnectionTimeoutError = exports.APIConnectionError = exports.InternalServerError = exports.RateLimitError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIError = exports.AfriexError = void 0;
+/** Base class for every error the SDK throws. */
+class AfriexError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+exports.AfriexError = AfriexError;
+/**
+ * The API answered with a status outside 2xx. Catch a subclass to handle one
+ * status, or this class to handle any of them.
+ */
+class APIError extends AfriexError {
+    /** The HTTP status. */
+    status;
+    /** Machine-readable error code from the body, such as `DUPLICATE_REQUEST`. */
+    code;
+    /** The `details` object from the body, when the API sent one. */
+    details;
+    /** The response body as received, parsed when it was JSON. */
+    body;
+    headers;
+    /** The `x-request-id` header. Quote it when you contact support. */
+    requestId;
+    constructor(status, body, headers) {
+        super(APIError.messageFrom(status, body));
+        this.status = status;
+        this.body = body;
+        this.headers = headers;
+        this.requestId = headers.get('x-request-id') ?? undefined;
+        const parsed = isErrorResponse(body) ? body : undefined;
+        this.code = parsed?.code;
+        this.details = parsed?.details;
+    }
+    /** Builds the subclass that matches the status. */
+    static from(status, body, headers) {
+        if (status === 400)
+            return new BadRequestError(status, body, headers);
+        if (status === 401)
+            return new AuthenticationError(status, body, headers);
+        if (status === 403)
+            return new PermissionDeniedError(status, body, headers);
+        if (status === 404)
+            return new NotFoundError(status, body, headers);
+        if (status === 409)
+            return new ConflictError(status, body, headers);
+        if (status === 422) {
+            return new UnprocessableEntityError(status, body, headers);
+        }
+        if (status === 429)
+            return new RateLimitError(status, body, headers);
+        if (status >= 500)
+            return new InternalServerError(status, body, headers);
+        return new APIError(status, body, headers);
+    }
+    static messageFrom(status, body) {
+        if (isErrorResponse(body)) {
+            const message = body.details?.friendlyMessage ?? body.error ?? body.details?.errorMessage;
+            if (message) {
+                return body.code ? `${status} ${body.code}: ${message}` : `${status} ${message}`;
+            }
+        }
+        if (typeof body === 'string' && body)
+            return `${status} ${body}`;
+        return `${status} status code (no body)`;
+    }
+}
+exports.APIError = APIError;
+/** 400: the request was malformed. Nothing was done. */
+class BadRequestError extends APIError {
+}
+exports.BadRequestError = BadRequestError;
+/**
+ * 401: the API key is missing, wrong, revoked, or lacks the permission this
+ * endpoint needs. The API does not say which.
+ */
+class AuthenticationError extends APIError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 403: the request is not allowed, for example from an address outside your IP allowlist. */
+class PermissionDeniedError extends APIError {
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+/** 404: the resource does not exist, or belongs to another business. */
+class NotFoundError extends APIError {
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * 409: for a transaction, `DUPLICATE_REQUEST` means its idempotency key or
+ * reference is already taken. Look the transaction up by its reference rather
+ * than sending it again.
+ */
+class ConflictError extends APIError {
+}
+exports.ConflictError = ConflictError;
+/** 422: the request was well formed but failed validation. Nothing was done. */
+class UnprocessableEntityError extends APIError {
+}
+exports.UnprocessableEntityError = UnprocessableEntityError;
+/** 429: the request was not processed. Retry after `retryAfter` seconds. */
+class RateLimitError extends APIError {
+    /** Seconds to wait, from the `Retry-After` header. */
+    get retryAfter() {
+        const value = Number(this.headers.get('retry-after'));
+        return Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/** 500 or above. */
+class InternalServerError extends APIError {
+}
+exports.InternalServerError = InternalServerError;
+/** No response arrived: DNS, TLS, refused or reset connection. */
+class APIConnectionError extends AfriexError {
+    constructor(message = 'Connection error.', options) {
+        super(message, options);
+    }
+}
+exports.APIConnectionError = APIConnectionError;
+/** No response arrived within the timeout. */
+class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message = 'Request timed out.') {
+        super(message);
+    }
+}
+exports.APIConnectionTimeoutError = APIConnectionTimeoutError;
+/** The request was cancelled through the `signal` you passed. */
+class APIUserAbortError extends AfriexError {
+    constructor(message = 'Request was aborted.') {
+        super(message);
+    }
+}
+exports.APIUserAbortError = APIUserAbortError;
+/** A webhook's signature did not match its body, or no public key was configured. */
+class WebhookVerificationError extends AfriexError {
+}
+exports.WebhookVerificationError = WebhookVerificationError;
+function isErrorResponse(body) {
+    return typeof body === 'object' && body !== null;
+}

package/dist/cjs/core/pagination.d.ts

@@ -0,0 +1,47 @@
+import { APIPromise, type RawResponse } from './api-promise.js';
+/** Fetches one page of a list, given the page number and size. */
+export type PageFetcher<Item> = (page: number, limit: number) => PagePromise<Item>;
+interface PageBody<Item> {
+    data: Item[];
+    total: number;
+    page: number;
+}
+/**
+ * One page of a list endpoint: `{data, total, page}` as the API returns it,
+ * plus helpers to fetch the pages after it. Iterate it with `for await` to
+ * walk every item on this page and the pages after it.
+ */
+export declare class Page<Item> implements AsyncIterable<Item> {
+    #private;
+    /** The items on this page. */
+    readonly data: Item[];
+    /** The number of items that match your filters, across all pages. */
+    readonly total: number;
+    /** This page's number. The first page is `0`. */
+    readonly page: number;
+    /** The page size used to fetch the next page. */
+    readonly limit: number;
+    constructor(body: PageBody<Item>, requested: {
+        page?: number;
+        limit?: number;
+    }, fetchPage: PageFetcher<Item>);
+    /** Whether another page follows this one. The API has no cursor, so this compares against `total`. */
+    hasNextPage(): boolean;
+    /** Fetches the next page. Call `hasNextPage()` first. */
+    getNextPage(): Promise<Page<Item>>;
+    /** Yields this page, then each page after it. */
+    iterPages(): AsyncGenerator<Page<Item>>;
+    [Symbol.asyncIterator](): AsyncGenerator<Item>;
+}
+/**
+ * What a list method returns. Await it for the first `Page`, or iterate it
+ * with `for await` to walk every item across all pages.
+ */
+export declare class PagePromise<Item> extends APIPromise<Page<Item>> implements AsyncIterable<Item> {
+    constructor(responsePromise: Promise<RawResponse>, requested: {
+        page?: number;
+        limit?: number;
+    }, fetchPage: PageFetcher<Item>);
+    [Symbol.asyncIterator](): AsyncGenerator<Item>;
+}
+export {};

package/dist/cjs/core/pagination.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PagePromise = exports.Page = void 0;
+const api_promise_js_1 = require("./api-promise.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * One page of a list endpoint: `{data, total, page}` as the API returns it,
+ * plus helpers to fetch the pages after it. Iterate it with `for await` to
+ * walk every item on this page and the pages after it.
+ */
+class Page {
+    /** The items on this page. */
+    data;
+    /** The number of items that match your filters, across all pages. */
+    total;
+    /** This page's number. The first page is `0`. */
+    page;
+    /** The page size used to fetch the next page. */
+    limit;
+    #fetchPage;
+    constructor(body, requested, fetchPage) {
+        this.data = body.data ?? [];
+        this.total = body.total ?? 0;
+        this.page = body.page ?? requested.page ?? 0;
+        // Without an explicit limit the API used its default, which a full page
+        // reveals. A short page is the last one whatever the limit was.
+        this.limit = requested.limit ?? Math.max(this.data.length, 1);
+        this.#fetchPage = fetchPage;
+    }
+    /** Whether another page follows this one. The API has no cursor, so this compares against `total`. */
+    hasNextPage() {
+        return this.data.length > 0 && (this.page + 1) * this.limit < this.total;
+    }
+    /** Fetches the next page. Call `hasNextPage()` first. */
+    getNextPage() {
+        if (!this.hasNextPage()) {
+            throw new errors_js_1.AfriexError('No next page. Check hasNextPage() before calling getNextPage().');
+        }
+        return this.#fetchPage(this.page + 1, this.limit);
+    }
+    /** Yields this page, then each page after it. */
+    async *iterPages() {
+        let current = this;
+        yield current;
+        while (current.hasNextPage()) {
+            current = await current.getNextPage();
+            yield current;
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const page of this.iterPages()) {
+            yield* page.data;
+        }
+    }
+}
+exports.Page = Page;
+/**
+ * What a list method returns. Await it for the first `Page`, or iterate it
+ * with `for await` to walk every item across all pages.
+ */
+class PagePromise extends api_promise_js_1.APIPromise {
+    constructor(responsePromise, requested, fetchPage) {
+        super(responsePromise, (raw) => new Page(raw.body, requested, fetchPage));
+    }
+    async *[Symbol.asyncIterator]() {
+        const page = await this;
+        yield* page;
+    }
+}
+exports.PagePromise = PagePromise;

package/dist/cjs/core/resource.d.ts

@@ -0,0 +1,18 @@
+import type { Afriex } from '../client.js';
+export declare abstract class APIResource {
+    protected readonly _client: Afriex;
+    constructor(client: Afriex);
+}
+/**
+ * Builds a request path, encoding each interpolated value. An empty id would
+ * otherwise turn `GET /customer/{id}` into `GET /customer`, the list endpoint,
+ * so it throws instead.
+ */
+export declare function path(strings: TemplateStringsArray, ...values: string[]): string;
+/**
+ * Returns a response's `data`. The spec marks `data` optional on most
+ * responses, but a 2xx always carries it, so its type drops `undefined`.
+ */
+export declare function data<T>(response: {
+    data?: T;
+}): Exclude<T, undefined>;