@xkova/sdk 0.1.0-alpha.1

package/dist/client.d.ts

@@ -0,0 +1,80 @@
+import { type XKOVARequestSigner } from './request-signing.js';
+import { AccountHoldersResource } from './resources/account-holders.js';
+import { BrandingResource } from './resources/branding.js';
+import { ChainsResource } from './resources/chains.js';
+import { ContactsResource } from './resources/contacts.js';
+import { EscrowsResource } from './resources/escrows.js';
+import { FeeSchedulesResource } from './resources/fee-schedules.js';
+import { IntegrationGatewaysResource } from './resources/integration-gateways.js';
+import { OnboardingResource } from './resources/onboarding.js';
+import { PaymentRequestsResource } from './resources/payment-requests.js';
+import { PaymentsResource } from './resources/payments.js';
+import { RampsResource } from './resources/ramps.js';
+import { RwaResource } from './resources/rwa.js';
+import { TenantResource } from './resources/tenant.js';
+import { TokenizationResource } from './resources/tokenization.js';
+import { TransactionsResource } from './resources/transactions.js';
+import { WalletsResource } from './resources/wallets.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { WorkflowClient } from './resources/workflows.js';
+import { WorkspaceTokensResource } from './resources/workspace-tokens.js';
+import { WorkspacesResource } from './resources/workspaces.js';
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type XKOVAHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface XKOVAClientOptions {
+    /** API origin or versioned base URL, such as https://sandbox-api.xkova.com. */
+    baseUrl: string;
+    /** Tenant API key. Keep this credential in a trusted server process. */
+    apiKey: string;
+    /** Default request deadline in milliseconds. Omit for no SDK deadline. */
+    timeoutMs?: number;
+    /** Defaults to global fetch. Override for tests or custom transport. */
+    fetchImpl?: FetchLike;
+    /**
+     * Customer-owned asymmetric signer for mutation requests. Required for
+     * production workspace keys and optional for sandbox workspace keys.
+     */
+    requestSigner?: XKOVARequestSigner;
+}
+export interface XKOVARequestControl {
+    /** Cancels this request or workflow poll. */
+    signal?: AbortSignal;
+}
+export interface XKOVAMutationOptions extends XKOVARequestControl {
+    /** Reuse this key when retrying the same logical write. */
+    idempotencyKey?: string;
+}
+export declare class XKOVAClient {
+    private readonly config;
+    private readonly memberContext?;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private constructor();
+    private readonly namespaces;
+    get accountHolders(): AccountHoldersResource;
+    get branding(): BrandingResource;
+    get chains(): ChainsResource;
+    get contacts(): ContactsResource;
+    get escrows(): EscrowsResource;
+    get feeSchedules(): FeeSchedulesResource;
+    get integrationGateways(): IntegrationGatewaysResource;
+    get onboarding(): OnboardingResource;
+    get paymentRequests(): PaymentRequestsResource;
+    get payments(): PaymentsResource;
+    get ramps(): RampsResource;
+    get rwa(): RwaResource;
+    get tenant(): TenantResource;
+    get tokenization(): TokenizationResource;
+    get transactions(): TransactionsResource;
+    get wallets(): WalletsResource;
+    get webhooks(): WebhooksResource;
+    get workflows(): WorkflowClient;
+    get workspaceTokens(): WorkspaceTokensResource;
+    get workspaces(): WorkspacesResource;
+    static forTenant(options: XKOVAClientOptions): XKOVAClient;
+    private prepareRequest;
+    private buildUrl;
+    private buildHeaders;
+    private requestSignal;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,251 @@
+import { XKOVAApiError } from './errors.js';
+import { generateIdempotencyKey } from './idempotency.js';
+import { signXKOVARequest, validateXKOVARequestSigner, xkovaContentDigest, } from './request-signing.js';
+import { AccountHoldersResource, } from './resources/account-holders.js';
+import { BrandingResource } from './resources/branding.js';
+import { ChainsResource } from './resources/chains.js';
+import { ContactsResource } from './resources/contacts.js';
+import { EscrowsResource } from './resources/escrows.js';
+import { FeeSchedulesResource } from './resources/fee-schedules.js';
+import { IntegrationGatewaysResource } from './resources/integration-gateways.js';
+import { OnboardingResource } from './resources/onboarding.js';
+import { PaymentRequestsResource } from './resources/payment-requests.js';
+import { PaymentsResource } from './resources/payments.js';
+import { RampsResource } from './resources/ramps.js';
+import { RwaResource } from './resources/rwa.js';
+import { TenantResource } from './resources/tenant.js';
+import { TokenizationResource } from './resources/tokenization.js';
+import { TransactionsResource } from './resources/transactions.js';
+import { WalletsResource } from './resources/wallets.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { WorkflowClient } from './resources/workflows.js';
+import { WorkspaceTokensResource } from './resources/workspace-tokens.js';
+import { WorkspacesResource } from './resources/workspaces.js';
+export class XKOVAClient {
+    config;
+    memberContext;
+    apiBaseUrl;
+    fetchImpl;
+    constructor(config, memberContext) {
+        this.config = config;
+        this.memberContext = memberContext;
+        if (config.timeoutMs !== undefined &&
+            (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0)) {
+            throw new Error('XKOVAClient timeoutMs must be a positive finite number');
+        }
+        if (config.requestSigner !== undefined) {
+            validateXKOVARequestSigner(config.requestSigner);
+        }
+        this.apiBaseUrl = normalizeApiBaseUrl(config.baseUrl);
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    namespaces = {};
+    get accountHolders() {
+        return (this.namespaces.accountHolders ??= new AccountHoldersResource(this, this.fetchImpl));
+    }
+    get branding() {
+        return (this.namespaces.branding ??= new BrandingResource(this));
+    }
+    get chains() {
+        return (this.namespaces.chains ??= new ChainsResource(this));
+    }
+    get contacts() {
+        return (this.namespaces.contacts ??= new ContactsResource(this));
+    }
+    get escrows() {
+        return (this.namespaces.escrows ??= new EscrowsResource(this));
+    }
+    get feeSchedules() {
+        return (this.namespaces.feeSchedules ??= new FeeSchedulesResource(this));
+    }
+    get integrationGateways() {
+        return (this.namespaces.integrationGateways ??= new IntegrationGatewaysResource(this));
+    }
+    get onboarding() {
+        return (this.namespaces.onboarding ??= new OnboardingResource(this));
+    }
+    get paymentRequests() {
+        return (this.namespaces.paymentRequests ??= new PaymentRequestsResource(this));
+    }
+    get payments() {
+        return (this.namespaces.payments ??= new PaymentsResource(this));
+    }
+    get ramps() {
+        return (this.namespaces.ramps ??= new RampsResource(this));
+    }
+    get rwa() {
+        return (this.namespaces.rwa ??= new RwaResource(this));
+    }
+    get tenant() {
+        return (this.namespaces.tenant ??= new TenantResource(this));
+    }
+    get tokenization() {
+        return (this.namespaces.tokenization ??= new TokenizationResource(this));
+    }
+    get transactions() {
+        return (this.namespaces.transactions ??= new TransactionsResource(this));
+    }
+    get wallets() {
+        return (this.namespaces.wallets ??= new WalletsResource(this));
+    }
+    get webhooks() {
+        return (this.namespaces.webhooks ??= new WebhooksResource(this));
+    }
+    get workflows() {
+        return (this.namespaces.workflows ??= new WorkflowClient(this));
+    }
+    get workspaceTokens() {
+        return (this.namespaces.workspaceTokens ??= new WorkspaceTokensResource(this));
+    }
+    get workspaces() {
+        return (this.namespaces.workspaces ??= new WorkspacesResource(this));
+    }
+    static forTenant(options) {
+        return new XKOVAClient(options);
+    }
+    /** @internal Created by the BFF helper after resolving its confidential session store. */
+    static forMemberSession(options, context) {
+        return new XKOVAClient(options, Object.freeze({ ...context }));
+    }
+    /** @internal Resource transport. Use typed namespaces instead. */
+    async requestJson(options) {
+        const prepared = await this.prepareRequest(options);
+        const signal = this.requestSignal(options.signal);
+        const response = await this.fetchImpl(prepared.url, {
+            method: options.method,
+            headers: prepared.headers,
+            cache: 'no-store',
+            redirect: 'error',
+            ...(signal !== undefined && { signal }),
+            ...(prepared.body !== undefined && { body: prepared.body }),
+        });
+        if (!response.ok)
+            throw await XKOVAApiError.fromResponse(response);
+        if (response.status === 204)
+            return undefined;
+        const text = await response.text();
+        if (text.length === 0)
+            return undefined;
+        return JSON.parse(text);
+    }
+    /** @internal Resource transport. Use typed namespaces instead. */
+    async requestText(options) {
+        const prepared = await this.prepareRequest({
+            ...options,
+            accept: options.accept ?? 'text/plain, */*',
+        });
+        const signal = this.requestSignal(options.signal);
+        const response = await this.fetchImpl(prepared.url, {
+            method: options.method,
+            headers: prepared.headers,
+            cache: 'no-store',
+            redirect: 'error',
+            ...(signal !== undefined && { signal }),
+            ...(prepared.body !== undefined && { body: prepared.body }),
+        });
+        if (!response.ok)
+            throw await XKOVAApiError.fromResponse(response);
+        return response.text();
+    }
+    async prepareRequest(options) {
+        const mutation = isMutationMethod(options.method);
+        const signer = this.config.requestSigner;
+        if (mutation && this.config.apiKey.startsWith('xkv_live_') && signer === undefined) {
+            throw new Error('XKOVA production mutations require a configured asymmetric request signer');
+        }
+        const url = this.buildUrl(options);
+        const serializedBody = options.body === undefined ? undefined : JSON.stringify(options.body);
+        if (options.body !== undefined && serializedBody === undefined) {
+            throw new Error('XKOVA request body is not JSON serializable');
+        }
+        const bodyBytes = serializedBody === undefined ? undefined : new TextEncoder().encode(serializedBody);
+        const headers = this.buildHeaders(options);
+        if (mutation && signer !== undefined) {
+            const signatureBody = bodyBytes ?? new Uint8Array();
+            if (bodyBytes !== undefined || headers.has('content-digest')) {
+                headers.set('Content-Digest', xkovaContentDigest(signatureBody));
+            }
+            const fields = await signXKOVARequest({
+                method: options.method,
+                url,
+                headers,
+                body: signatureBody,
+                signer,
+            });
+            headers.set('Signature-Input', fields.signatureInput);
+            headers.set('Signature', fields.signature);
+        }
+        return {
+            url: url.toString(),
+            headers,
+            ...(serializedBody !== undefined && { body: serializedBody }),
+        };
+    }
+    buildUrl(options) {
+        const url = new URL(`${this.apiBaseUrl}${options.path}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value)) {
+                if (value.length > 0)
+                    url.searchParams.set(key, value.join(','));
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        return url;
+    }
+    buildHeaders(options) {
+        const headers = new Headers({
+            Accept: options.accept ?? 'application/json',
+            Authorization: `Bearer ${this.config.apiKey}`,
+        });
+        if (options.body !== undefined)
+            headers.set('Content-Type', 'application/json');
+        if (options.method !== 'GET') {
+            headers.set('Idempotency-Key', options.idempotencyKey ?? generateIdempotencyKey());
+        }
+        for (const [name, value] of Object.entries(options.headers ?? {})) {
+            headers.set(name, value);
+        }
+        if (this.memberContext) {
+            const authority = {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                'X-Member-Session-Id': this.memberContext.memberSessionId,
+                'X-XKOVA-Publishable-Key': this.memberContext.memberAuthPublishableKey,
+                'X-Account-Holder-Id': this.memberContext.accountHolderId,
+            };
+            for (const [name, value] of Object.entries(authority)) {
+                if (headers.has(name) && headers.get(name) !== value) {
+                    throw new TypeError('A member-bound SDK operation cannot replace its session authority');
+                }
+                headers.set(name, value);
+            }
+        }
+        return headers;
+    }
+    requestSignal(signal) {
+        const timeout = this.config.timeoutMs === undefined ? undefined : AbortSignal.timeout(this.config.timeoutMs);
+        if (signal && timeout)
+            return AbortSignal.any([signal, timeout]);
+        return signal ?? timeout;
+    }
+}
+function isMutationMethod(method) {
+    return method !== 'GET';
+}
+function normalizeApiBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.username || url.password || url.search || url.hash) {
+        throw new TypeError('XKOVA SDK baseUrl must be an API origin or /v1 base URL');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
+        throw new TypeError('XKOVA SDK baseUrl must use HTTPS or localhost HTTP');
+    }
+    const pathname = url.pathname.replace(/\/+$/, '');
+    if (pathname !== '' && pathname !== '/v1') {
+        throw new TypeError('XKOVA SDK baseUrl must be an API origin or /v1 base URL');
+    }
+    return `${url.origin}/v1`;
+}

package/dist/cursor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cursors are opaque. Pass each page's `next_cursor` back unchanged until it
+ * is null. Errors stop iteration; use `withRetry` in the page fetcher if needed.
+ */
+export interface CursorPage<T> {
+    items: ReadonlyArray<T>;
+    /** `null` when there's no more data; otherwise pass back as `cursor`. */
+    next_cursor: string | null;
+}
+export interface PaginateCursorOptions<T> {
+    /** Receives undefined on the first call, then the previous page's cursor. */
+    fetchPage: (cursor: string | undefined) => Promise<CursorPage<T>>;
+    /** Hard cap on pages walked (defense against runaway pagination). */
+    maxPages?: number;
+}
+export declare function paginateCursor<T>(opts: PaginateCursorOptions<T>): AsyncGenerator<T, void, void>;
+/**
+ * Collect only bounded lists. Use `for await` on larger results to avoid
+ * holding every item in memory.
+ */
+export declare function collectCursor<T>(opts: PaginateCursorOptions<T>): Promise<T[]>;

package/dist/cursor.js

@@ -0,0 +1,28 @@
+/**
+ * Cursors are opaque. Pass each page's `next_cursor` back unchanged until it
+ * is null. Errors stop iteration; use `withRetry` in the page fetcher if needed.
+ */
+export async function* paginateCursor(opts) {
+    const max = opts.maxPages ?? Infinity;
+    let cursor = undefined;
+    let pages = 0;
+    while (pages < max) {
+        const page = await opts.fetchPage(cursor);
+        for (const item of page.items)
+            yield item;
+        pages += 1;
+        if (page.next_cursor === null)
+            return;
+        cursor = page.next_cursor;
+    }
+}
+/**
+ * Collect only bounded lists. Use `for await` on larger results to avoid
+ * holding every item in memory.
+ */
+export async function collectCursor(opts) {
+    const out = [];
+    for await (const item of paginateCursor(opts))
+        out.push(item);
+    return out;
+}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * API error codes can grow between SDK releases, so `code` remains a string.
+ * Branch on it before narrowing `details` with a runtime guard. Retain the
+ * correlation ID when reporting a failure to support.
+ */
+export declare class XKOVAApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details: Record<string, unknown> | undefined;
+    readonly correlationId: string;
+    readonly retryAfter: string | undefined;
+    constructor(opts: {
+        code: string;
+        message: string;
+        status: number;
+        correlationId: string;
+        details?: Record<string, unknown>;
+        retryAfter?: string;
+    });
+    /**
+     * Rejects malformed responses with a plain Error. A proxy error page has no
+     * XKOVA error code, so callers must handle failures outside the API envelope.
+     */
+    static fromResponse(res: Response): Promise<XKOVAApiError>;
+}
+/** Object-storage stage failure, separate from the API's error namespace. */
+export declare class XKOVAUploadError extends Error {
+    readonly upstreamStatus?: number | undefined;
+    readonly stage = "avatar.object-storage";
+    constructor(message: string, upstreamStatus?: number | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,63 @@
+/**
+ * API error codes can grow between SDK releases, so `code` remains a string.
+ * Branch on it before narrowing `details` with a runtime guard. Retain the
+ * correlation ID when reporting a failure to support.
+ */
+export class XKOVAApiError extends Error {
+    code;
+    status;
+    details;
+    correlationId;
+    retryAfter;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'XKOVAApiError';
+        this.code = opts.code;
+        this.status = opts.status;
+        this.details = opts.details;
+        this.correlationId = opts.correlationId;
+        this.retryAfter = opts.retryAfter;
+    }
+    /**
+     * Rejects malformed responses with a plain Error. A proxy error page has no
+     * XKOVA error code, so callers must handle failures outside the API envelope.
+     */
+    static async fromResponse(res) {
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new Error(`XKOVAApiError.fromResponse: response body wasn't JSON (status ${res.status})`);
+        }
+        if (!isErrorEnvelope(body)) {
+            throw new Error(`XKOVAApiError.fromResponse: response body wasn't an XKOVA error envelope (status ${res.status})`);
+        }
+        return new XKOVAApiError({
+            code: body.code,
+            message: body.message,
+            status: res.status,
+            correlationId: body.correlation_id,
+            ...(res.headers.has('retry-after') && { retryAfter: res.headers.get('retry-after') }),
+            ...(body.details !== undefined && { details: body.details }),
+        });
+    }
+}
+/** Object-storage stage failure, separate from the API's error namespace. */
+export class XKOVAUploadError extends Error {
+    upstreamStatus;
+    stage = 'avatar.object-storage';
+    constructor(message, upstreamStatus) {
+        super(message);
+        this.upstreamStatus = upstreamStatus;
+        this.name = 'XKOVAUploadError';
+    }
+}
+function isErrorEnvelope(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const o = v;
+    return (typeof o['code'] === 'string' &&
+        typeof o['message'] === 'string' &&
+        typeof o['correlation_id'] === 'string');
+}