@afriex/sdk 5.1.0 → 6.1.0

package/dist/esm/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/esm/core/errors.js

@@ -0,0 +1,126 @@
+/** Base class for every error the SDK throws. */
+export class AfriexError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The API answered with a status outside 2xx. Catch a subclass to handle one
+ * status, or this class to handle any of them.
+ */
+export 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)`;
+    }
+}
+/** 400: the request was malformed. Nothing was done. */
+export 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 class AuthenticationError extends APIError {
+}
+/** 403: the request is not allowed, for example from an address outside your IP allowlist. */
+export class PermissionDeniedError extends APIError {
+}
+/** 404: the resource does not exist, or belongs to another business. */
+export 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 class ConflictError extends APIError {
+}
+/** 422: the request was well formed but failed validation. Nothing was done. */
+export class UnprocessableEntityError extends APIError {
+}
+/** 429: the request was not processed. Retry after `retryAfter` seconds. */
+export 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;
+    }
+}
+/** 500 or above. */
+export class InternalServerError extends APIError {
+}
+/** No response arrived: DNS, TLS, refused or reset connection. */
+export class APIConnectionError extends AfriexError {
+    constructor(message = 'Connection error.', options) {
+        super(message, options);
+    }
+}
+/** No response arrived within the timeout. */
+export class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message = 'Request timed out.') {
+        super(message);
+    }
+}
+/** The request was cancelled through the `signal` you passed. */
+export class APIUserAbortError extends AfriexError {
+    constructor(message = 'Request was aborted.') {
+        super(message);
+    }
+}
+/** A webhook's signature did not match its body, or no public key was configured. */
+export class WebhookVerificationError extends AfriexError {
+}
+function isErrorResponse(body) {
+    return typeof body === 'object' && body !== null;
+}

package/dist/esm/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/esm/core/pagination.js

@@ -0,0 +1,65 @@
+import { APIPromise } from './api-promise.js';
+import { AfriexError } from './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.
+ */
+export 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 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;
+        }
+    }
+}
+/**
+ * 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 class PagePromise extends APIPromise {
+    constructor(responsePromise, requested, fetchPage) {
+        super(responsePromise, (raw) => new Page(raw.body, requested, fetchPage));
+    }
+    async *[Symbol.asyncIterator]() {
+        const page = await this;
+        yield* page;
+    }
+}

package/dist/esm/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>;

package/dist/esm/core/resource.js

@@ -0,0 +1,30 @@
+import { AfriexError } from './errors.js';
+export class APIResource {
+    _client;
+    constructor(client) {
+        this._client = client;
+    }
+}
+/**
+ * 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 function path(strings, ...values) {
+    return strings.reduce((result, part, index) => {
+        if (index === 0)
+            return part;
+        const value = values[index - 1];
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new AfriexError(`Expected a non-empty string for the path parameter in "${strings.join('{}')}", got ${JSON.stringify(value)}.`);
+        }
+        return result + encodeURIComponent(value) + part;
+    }, '');
+}
+/**
+ * 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 function data(response) {
+    return response.data;
+}

package/dist/esm/core/types.d.ts

@@ -0,0 +1,43 @@
+import type { operations } from '../generated/openapi.js';
+export type OperationId = keyof operations;
+type JSONContent<T> = T extends {
+    content: {
+        'application/json': infer B;
+    };
+} ? B : never;
+/** The JSON request body of an operation. */
+export type Body<K extends OperationId> = operations[K] extends {
+    requestBody?: infer R;
+} ? JSONContent<NonNullable<R>> : never;
+/** The query parameters of an operation. */
+export type Query<K extends OperationId> = operations[K] extends {
+    parameters: {
+        query?: infer Q;
+    };
+} ? NonNullable<Q> : never;
+type SuccessStatus = 200 | 201 | 202;
+/** The JSON body of an operation's success response. */
+export type Response<K extends OperationId> = operations[K] extends {
+    responses: infer R;
+} ? JSONContent<R[Extract<keyof R, SuccessStatus>]> : never;
+/**
+ * The `data` field of an operation's success response. The spec marks `data`
+ * optional on most responses, but a 2xx always carries it.
+ */
+export type Data<K extends OperationId> = Response<K> extends {
+    data?: infer D;
+} ? Exclude<D, undefined> : never;
+/** The item type of a paginated operation. */
+export type Item<K extends OperationId> = Data<K> extends ReadonlyArray<infer I> ? I : never;
+/** Options that apply to a single request, passed as each method's last argument. */
+export interface RequestOptions {
+    /** Milliseconds to wait for a response. Overrides the client's `timeout`. */
+    timeout?: number;
+    /** Overrides the client's `maxRetries` for this request. */
+    maxRetries?: number;
+    /** Extra headers. A value of `null` removes a header the SDK would send. */
+    headers?: Record<string, string | null | undefined>;
+    /** Cancels the request when aborted. */
+    signal?: AbortSignal;
+}
+export {};

package/dist/esm/core/types.js

@@ -0,0 +1 @@
+export {};