@afriex/sdk 5.0.0 → 6.0.0

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

@@ -0,0 +1,39 @@
+import type { APIPromise } from '../core/api-promise.js';
+import type { PagePromise } from '../core/pagination.js';
+import { APIResource } from '../core/resource.js';
+import type { Body, Data, Item, Query, RequestOptions } from '../core/types.js';
+import type { Transaction, TransactionStatus } from '../generated/openapi.js';
+export type { Transaction, TransactionStatus };
+export type TransactionCreateParams = Body<'createTransaction'>;
+export type TransactionListParams = Query<'listTransactions'>;
+export type TransactionQuoteParams = Query<'getTransactionQuote'>;
+export type TransactionQuote = Data<'getTransactionQuote'>;
+export type TransactionAuthorizeParams = Body<'authorizeTransaction'>;
+export type TransactionSimulateParams = Body<'simulateTransaction'>;
+export type TransactionAdvice = Data<'getTransactionAdvice'>;
+export type PoolAccountProofParams = Body<'submitPoolAccountPaymentProof'>;
+export declare class Transactions extends APIResource {
+    /**
+     * Creates a deposit, withdrawal or swap.
+     *
+     * `meta.idempotencyKey` makes this safe to send again, so the SDK retries it
+     * on timeouts and server errors with the same body. If a retry gets
+     * `409 DUPLICATE_REQUEST` (a `ConflictError`), the first attempt went
+     * through: look the transaction up by `meta.reference`.
+     */
+    create(params: TransactionCreateParams, options?: RequestOptions): APIPromise<Data<'createTransaction'>>;
+    /** Lists transactions, newest first. Iterate the result with `for await` to walk every page. */
+    list(params?: TransactionListParams, options?: RequestOptions): PagePromise<Item<'listTransactions'>>;
+    /** Quotes a withdrawal: the rate, fee and amounts, without creating anything. */
+    quote(params: TransactionQuoteParams, options?: RequestOptions): APIPromise<TransactionQuote>;
+    /** Retrieves a transaction. */
+    get(transactionId: string, options?: RequestOptions): APIPromise<Data<'getTransaction'>>;
+    /** Authorizes a transaction that is waiting for it, for example with an OTP. */
+    authorize(transactionId: string, params: TransactionAuthorizeParams, options?: RequestOptions): APIPromise<Data<'authorizeTransaction'>>;
+    /** Sandbox only: moves a transaction to the outcome you choose. */
+    simulate(transactionId: string, params: TransactionSimulateParams, options?: RequestOptions): APIPromise<Data<'simulateTransaction'>>;
+    /** Retrieves the settlement advice for a completed transaction. */
+    getAdvice(transactionId: string, options?: RequestOptions): APIPromise<TransactionAdvice>;
+    /** Submits proof of a payment into a pool account. */
+    submitPoolAccountProof(params: PoolAccountProofParams, options?: RequestOptions): APIPromise<Data<'submitPoolAccountPaymentProof'>>;
+}

package/dist/cjs/resources/transactions.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transactions = void 0;
+const resource_js_1 = require("../core/resource.js");
+class Transactions extends resource_js_1.APIResource {
+    /**
+     * Creates a deposit, withdrawal or swap.
+     *
+     * `meta.idempotencyKey` makes this safe to send again, so the SDK retries it
+     * on timeouts and server errors with the same body. If a retry gets
+     * `409 DUPLICATE_REQUEST` (a `ConflictError`), the first attempt went
+     * through: look the transaction up by `meta.reference`.
+     */
+    create(params, options) {
+        return this._client
+            .request('post', '/api/v1/transaction', {
+            body: params,
+            idempotent: true,
+            options,
+        })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Lists transactions, newest first. Iterate the result with `for await` to walk every page. */
+    list(params = {}, options) {
+        return this._client.getPage('/api/v1/transaction', params, options);
+    }
+    /** Quotes a withdrawal: the rate, fee and amounts, without creating anything. */
+    quote(params, options) {
+        return this._client
+            .request('get', '/api/v1/transaction/quote', { query: params, options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Retrieves a transaction. */
+    get(transactionId, options) {
+        return this._client
+            .request('get', (0, resource_js_1.path) `/api/v1/transaction/${transactionId}`, { options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Authorizes a transaction that is waiting for it, for example with an OTP. */
+    authorize(transactionId, params, options) {
+        return this._client
+            .request('post', (0, resource_js_1.path) `/api/v1/transaction/${transactionId}/authorize`, { body: params, options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Sandbox only: moves a transaction to the outcome you choose. */
+    simulate(transactionId, params, options) {
+        return this._client
+            .request('post', (0, resource_js_1.path) `/api/v1/transaction/${transactionId}/simulate`, { body: params, options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Retrieves the settlement advice for a completed transaction. */
+    getAdvice(transactionId, options) {
+        return this._client
+            .request('get', (0, resource_js_1.path) `/api/v1/transaction/${transactionId}/advice`, { options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+    /** Submits proof of a payment into a pool account. */
+    submitPoolAccountProof(params, options) {
+        return this._client
+            .request('post', '/api/v1/transaction/pool-account', {
+            body: params,
+            options,
+        })
+            ._thenUnwrap(resource_js_1.data);
+    }
+}
+exports.Transactions = Transactions;

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

@@ -0,0 +1,43 @@
+import type { Afriex } from '../client.js';
+import type { APIPromise } from '../core/api-promise.js';
+import { APIResource } from '../core/resource.js';
+import type { Body, Data, RequestOptions } from '../core/types.js';
+import type { webhooks } from '../generated/openapi.js';
+/** The header that carries a webhook's signature. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
+type WebhookBody<K extends keyof webhooks> = NonNullable<webhooks[K]['post']> extends {
+    requestBody: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : never;
+/** Any event Afriex delivers. Switch on `event` to narrow it. */
+export type WebhookEvent = {
+    [K in keyof webhooks]: WebhookBody<K>;
+}[keyof webhooks];
+export type WebhookEventType = WebhookEvent['event'];
+export type CustomerWebhookEvent = WebhookBody<'customer.events'>;
+export type PaymentMethodWebhookEvent = WebhookBody<'payment_method.events'>;
+export type TransactionWebhookEvent = WebhookBody<'transaction.events'>;
+export type PoolDepositRequestWebhookEvent = WebhookBody<'pool_deposit_request.events'>;
+export type TriggerWebhookParams = Body<'triggerWebhook'>;
+export type TriggerWebhookResult = Data<'triggerWebhook'>;
+export declare class Webhooks extends APIResource {
+    #private;
+    constructor(client: Afriex, publicKey?: string);
+    /**
+     * Whether `signature` is Afriex's signature of `payload`. Pass the raw body
+     * exactly as received: a re-serialized object never matches.
+     */
+    verify(payload: string | Uint8Array, signature: string | string[] | null | undefined): boolean;
+    /**
+     * Verifies a webhook and returns its parsed event.
+     *
+     * @throws WebhookVerificationError when no public key is configured or the signature does not match.
+     */
+    verifyAndParse(payload: string | Uint8Array, signature: string | string[] | null | undefined): WebhookEvent;
+    /** Sandbox only: sends a test webhook for an event and entity to your configured URL. */
+    triggerTestWebhook(params: TriggerWebhookParams, options?: RequestOptions): APIPromise<TriggerWebhookResult>;
+}
+export {};

package/dist/cjs/resources/webhooks.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = exports.WEBHOOK_SIGNATURE_HEADER = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("../core/errors.js");
+const resource_js_1 = require("../core/resource.js");
+/** The header that carries a webhook's signature. */
+exports.WEBHOOK_SIGNATURE_HEADER = 'x-webhook-signature';
+class Webhooks extends resource_js_1.APIResource {
+    #publicKey;
+    constructor(client, publicKey) {
+        super(client);
+        this.#publicKey = publicKey;
+    }
+    /**
+     * Whether `signature` is Afriex's signature of `payload`. Pass the raw body
+     * exactly as received: a re-serialized object never matches.
+     */
+    verify(payload, signature) {
+        const header = Array.isArray(signature) ? signature[0] : signature;
+        if (!this.#publicKey || !header || payload.length === 0)
+            return false;
+        try {
+            // ECDSA P-384 over SHA-256, DER-encoded then base64-encoded.
+            return (0, node_crypto_1.createVerify)('SHA256').update(payload).verify(this.#publicKey, header, 'base64');
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Verifies a webhook and returns its parsed event.
+     *
+     * @throws WebhookVerificationError when no public key is configured or the signature does not match.
+     */
+    verifyAndParse(payload, signature) {
+        if (!this.#publicKey) {
+            throw new errors_js_1.WebhookVerificationError('No webhook public key. Pass `webhookPublicKey` when you create the client.');
+        }
+        if (!this.verify(payload, signature)) {
+            throw new errors_js_1.WebhookVerificationError('The webhook signature does not match its body.');
+        }
+        const text = typeof payload === 'string' ? payload : new TextDecoder().decode(payload);
+        return JSON.parse(text);
+    }
+    /** Sandbox only: sends a test webhook for an event and entity to your configured URL. */
+    triggerTestWebhook(params, options) {
+        return this._client
+            .request('post', '/api/v1/webhooks/trigger', { body: params, options })
+            ._thenUnwrap(resource_js_1.data);
+    }
+}
+exports.Webhooks = Webhooks;

package/dist/cjs/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "6.0.0";

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// Kept equal to package.json's version by a unit test.
+exports.VERSION = '6.0.0';

package/dist/esm/client.d.ts

@@ -0,0 +1,110 @@
+import { APIPromise } from './core/api-promise.js';
+import { PagePromise } from './core/pagination.js';
+import type { RequestOptions } from './core/types.js';
+import { Balance } from './resources/balance.js';
+import { Checkout } from './resources/checkout.js';
+import { Customers } from './resources/customers.js';
+import { Media } from './resources/media.js';
+import { PaymentBatches } from './resources/payment-batches.js';
+import { PaymentMethods } from './resources/payment-methods.js';
+import { Rates } from './resources/rates.js';
+import { SmeRegistration } from './resources/sme-registration.js';
+import { Transactions } from './resources/transactions.js';
+import { Webhooks } from './resources/webhooks.js';
+/** The base URL of each environment. `staging` is the sandbox's older name. */
+export declare const ENVIRONMENTS: {
+    readonly sandbox: "https://sandbox.api.afriex.com";
+    readonly staging: "https://sandbox.api.afriex.com";
+    readonly production: "https://api.afriex.com";
+};
+export type Environment = keyof typeof ENVIRONMENTS;
+/**
+ * The API version this release of the SDK was built against, sent as
+ * `x-api-version`. Each SDK release targets one API version.
+ */
+export declare const API_VERSION = "2026-05-18";
+/** What `signRequest` receives: the request exactly as it will be sent. */
+export interface SignableRequest {
+    method: string;
+    url: string;
+    body: string;
+}
+export interface ClientOptions {
+    /** Your Afriex API key. Defaults to the `AFRIEX_API_KEY` environment variable. */
+    apiKey?: string;
+    /**
+     * `'sandbox'` or `'production'`. Defaults to `'production'`, so set it
+     * explicitly while you integrate. `'staging'` is accepted as the sandbox.
+     */
+    environment?: Environment;
+    /** Overrides the base URL that `environment` selects. */
+    baseURL?: string;
+    /** Sent as `x-api-version`. Defaults to `API_VERSION`. */
+    apiVersion?: string;
+    /** Milliseconds to wait for each attempt. Defaults to 30 seconds. */
+    timeout?: number;
+    /**
+     * How many times to retry a failed request. Defaults to 2. See the README
+     * for which requests are retried.
+     */
+    maxRetries?: number;
+    /**
+     * Returns the `x-api-signature` for a request, if your business has request
+     * signing enabled.
+     */
+    signRequest?: (request: SignableRequest) => string | undefined | Promise<string | undefined>;
+    /** Afriex's public key for webhook signatures, from **Developer → Webhook** in the dashboard. */
+    webhookPublicKey?: string;
+    /** Headers sent with every request. */
+    defaultHeaders?: Record<string, string>;
+    /** A `fetch` implementation to use instead of the global one. */
+    fetch?: typeof fetch;
+    /**
+     * The SDK refuses to run in a browser, where your API key would be visible
+     * to anyone. Set this only if you understand that.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+type Method = 'get' | 'post' | 'patch' | 'delete';
+export interface APIRequestInit {
+    query?: object;
+    body?: unknown;
+    /**
+     * Safe to send twice: retried on timeouts and server errors as well as on
+     * 429. True for every GET; set it for a POST whose body carries an
+     * idempotency key.
+     */
+    idempotent?: boolean;
+    options?: RequestOptions;
+}
+export declare class Afriex {
+    #private;
+    readonly customers: Customers;
+    readonly transactions: Transactions;
+    readonly paymentMethods: PaymentMethods;
+    readonly paymentBatches: PaymentBatches;
+    readonly balance: Balance;
+    readonly rates: Rates;
+    readonly checkout: Checkout;
+    readonly media: Media;
+    readonly smeRegistration: SmeRegistration;
+    readonly webhooks: Webhooks;
+    readonly baseURL: string;
+    readonly apiVersion: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    constructor(options?: ClientOptions);
+    /**
+     * 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<T>(method: Method, path: string, init?: APIRequestInit): APIPromise<T>;
+    /** @internal Fetches one page of a list endpoint. */
+    getPage<Item>(path: string, query?: {
+        page?: number;
+        limit?: number;
+    } & object, options?: RequestOptions): PagePromise<Item>;
+    /** @internal Sends a request with the configured `fetch`, without the API key. For presigned upload URLs. */
+    fetchUnauthenticated(url: string, init: RequestInit): Promise<Response>;
+}
+export {};

package/dist/esm/client.js

@@ -0,0 +1,227 @@
+import { APIPromise } from './core/api-promise.js';
+import { AfriexError, APIConnectionError, APIConnectionTimeoutError, APIError, APIUserAbortError, } from './core/errors.js';
+import { PagePromise } from './core/pagination.js';
+import { Balance } from './resources/balance.js';
+import { Checkout } from './resources/checkout.js';
+import { Customers } from './resources/customers.js';
+import { Media } from './resources/media.js';
+import { PaymentBatches } from './resources/payment-batches.js';
+import { PaymentMethods } from './resources/payment-methods.js';
+import { Rates } from './resources/rates.js';
+import { SmeRegistration } from './resources/sme-registration.js';
+import { Transactions } from './resources/transactions.js';
+import { Webhooks } from './resources/webhooks.js';
+import { VERSION } from './version.js';
+/** The base URL of each environment. `staging` is the sandbox's older name. */
+export const 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.
+ */
+export const API_VERSION = '2026-05-18';
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_RETRY_AFTER_SECONDS = 60;
+export class Afriex {
+    customers = new Customers(this);
+    transactions = new Transactions(this);
+    paymentMethods = new PaymentMethods(this);
+    paymentBatches = new PaymentBatches(this);
+    balance = new Balance(this);
+    rates = new Rates(this);
+    checkout = new Checkout(this);
+    media = new Media(this);
+    smeRegistration = new SmeRegistration(this);
+    webhooks;
+    baseURL;
+    apiVersion;
+    timeout;
+    maxRetries;
+    #apiKey;
+    #signRequest;
+    #defaultHeaders;
+    #fetch;
+    constructor(options = {}) {
+        if (!options.dangerouslyAllowBrowser && isBrowser()) {
+            throw new 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 AfriexError('Missing API key. Pass `apiKey` or set the AFRIEX_API_KEY environment variable.');
+        }
+        const environment = options.environment ?? 'production';
+        if (!(environment in ENVIRONMENTS)) {
+            throw new AfriexError(`Unknown environment "${environment}". Use "sandbox" or "production".`);
+        }
+        this.#apiKey = apiKey;
+        this.baseURL = (options.baseURL ?? ENVIRONMENTS[environment]).replace(/\/+$/, '');
+        this.apiVersion = options.apiVersion ?? 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(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 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 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 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 APIError.from(response.status, raw.body, response.headers);
+        }
+    }
+    async #attempt(url, init, timeout, signal) {
+        if (signal?.aborted)
+            throw new 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 APIUserAbortError();
+            if (timedOut)
+                throw new APIConnectionTimeoutError();
+            throw new 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}`,
+            '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;
+    }
+}
+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/esm/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/esm/core/api-promise.js

@@ -0,0 +1,45 @@
+/**
+ * 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 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);
+    }
+}