@xkova/sdk 0.1.0-alpha.1

package/dist/generated/types.js

@@ -0,0 +1,3 @@
+/** Generated from the XKOVA customer API schema. Do not edit directly. */
+/* eslint-disable */
+export {};

package/dist/idempotency.d.ts

@@ -0,0 +1,25 @@
+/** Reuse one key for every attempt of the same logical write. */
+/**
+ * Save the returned options before the first attempt. With the same key and
+ * body, a retry returns the original result instead of creating another resource.
+ *
+ * ```ts
+ * const opts = withIdempotency();
+ * const created = await client.accountHolders.create(body, opts);
+ * ```
+ *
+ * Without these options, the client generates a new key for each call.
+ */
+export declare function withIdempotency(): {
+    key: string;
+    /** Alias for `key` accepted by client mutation methods. */
+    idempotencyKey: string;
+    headers: {
+        'Idempotency-Key': string;
+    };
+};
+/**
+ * Supported Node runtimes use `crypto.randomUUID()`. Without it, this helper
+ * uses a non-cryptographic generator. Do not use that path for production keys.
+ */
+export declare function generateIdempotencyKey(): string;

package/dist/idempotency.js

@@ -0,0 +1,46 @@
+/** Reuse one key for every attempt of the same logical write. */
+/**
+ * Save the returned options before the first attempt. With the same key and
+ * body, a retry returns the original result instead of creating another resource.
+ *
+ * ```ts
+ * const opts = withIdempotency();
+ * const created = await client.accountHolders.create(body, opts);
+ * ```
+ *
+ * Without these options, the client generates a new key for each call.
+ */
+export function withIdempotency() {
+    const key = generateIdempotencyKey();
+    return { key, idempotencyKey: key, headers: { 'Idempotency-Key': key } };
+}
+/**
+ * Supported Node runtimes use `crypto.randomUUID()`. Without it, this helper
+ * uses a non-cryptographic generator. Do not use that path for production keys.
+ */
+export function generateIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return v4Fallback();
+}
+function v4Fallback() {
+    const hex = '0123456789abcdef';
+    const out = [];
+    for (let i = 0; i < 36; i += 1) {
+        if (i === 8 || i === 13 || i === 18 || i === 23) {
+            out.push('-');
+            continue;
+        }
+        if (i === 14) {
+            out.push('4');
+            continue;
+        }
+        if (i === 19) {
+            out.push(hex[8 + Math.floor(Math.random() * 4)]);
+            continue;
+        }
+        out.push(hex[Math.floor(Math.random() * 16)]);
+    }
+    return out.join('');
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** Server-side TypeScript client for XKOVA customer API operations. */
+export { XKOVAClient, type XKOVAClientOptions, type XKOVAMutationOptions, type XKOVARequestControl, } from './client.js';
+export type { XKOVARequestSigner, XKOVARequestSignInput, XKOVARequestSigningAlgorithm, } from './request-signing.js';
+export { generateIdempotencyKey, withIdempotency } from './idempotency.js';
+export { withRetry, type RetryPolicy } from './retry.js';
+export { collectCursor, paginateCursor, type CursorPage, type PaginateCursorOptions, } from './cursor.js';
+export { XKOVAApiError, XKOVAUploadError } from './errors.js';
+export { type PollOptions } from './resources/workflows.js';
+export { type XKOVAMemberSessionContext } from './resources/account-holders.js';
+export { verifyWebhookSignature, type VerifyWebhookSignatureResult } from './webhook.js';
+export { verifyInclusion, verifyConsistency, verifySth, type VerifyInclusionInput, type VerifyConsistencyInput, type VerifyTreeHeadInput, } from './rwa-verify.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/** Server-side TypeScript client for XKOVA customer API operations. */
+export { XKOVAClient, } from './client.js';
+export { generateIdempotencyKey, withIdempotency } from './idempotency.js';
+export { withRetry } from './retry.js';
+export { collectCursor, paginateCursor, } from './cursor.js';
+export { XKOVAApiError, XKOVAUploadError } from './errors.js';
+export { verifyWebhookSignature } from './webhook.js';
+export { verifyInclusion, verifyConsistency, verifySth, } from './rwa-verify.js';

package/dist/member-action-intents.d.ts

@@ -0,0 +1,72 @@
+import type { XKOVAMemberResources } from './member-resources.js';
+import type { ReqBody } from './resources/base.js';
+export type XKOVAMemberIntentRequest = {
+    readonly operation: 'payment';
+    readonly body: ReqBody<'createPayment'>;
+} | {
+    readonly operation: 'escrow';
+    readonly body: ReqBody<'createEscrow'>;
+} | {
+    readonly operation: 'payment_request_approve';
+    readonly id: string;
+    readonly senderWalletId: string;
+    readonly accountHolderId: string;
+};
+export interface XKOVAMemberPreparedAction {
+    readonly resourceType: 'payment' | 'escrow';
+    readonly resourceId: string;
+    readonly action: 'sign' | 'create';
+    readonly claimUrl?: string;
+}
+export interface StoredXKOVAMemberActionIntent {
+    readonly clientFingerprint: string;
+    readonly sessionReference: string;
+    readonly accountHolderId: string;
+    readonly inputDigest: string;
+    readonly creationIdempotencyKey: string;
+    readonly request: XKOVAMemberIntentRequest;
+    /** Safe application-owned form values, not credentials or authority. */
+    readonly review: Readonly<Record<string, string>>;
+    readonly reviewUri: string;
+    readonly expiresAt: number;
+    /** Retain through the application session so an expired reference cannot create again. */
+    readonly retainUntil: number;
+    readonly prepared?: XKOVAMemberPreparedAction;
+}
+/** Encrypt at rest, serialize per reference across replicas, and retain until retainUntil. */
+export interface XKOVAMemberActionIntentStore {
+    put(reference: string, value: StoredXKOVAMemberActionIntent): Promise<void>;
+    get(reference: string): Promise<StoredXKOVAMemberActionIntent | null>;
+    replace(reference: string, value: StoredXKOVAMemberActionIntent): Promise<void>;
+    runExclusive<T>(reference: string, work: () => Promise<T>): Promise<T>;
+}
+export declare class XKOVAMemberIntentError extends Error {
+    readonly code: 'action_intent_unavailable' | 'action_intent_conflict' | 'action_intent_expired' | 'action_intent_invalid';
+    readonly status: 404 | 409 | 410 | 422;
+    constructor(code: 'action_intent_unavailable' | 'action_intent_conflict' | 'action_intent_expired' | 'action_intent_invalid', status: 404 | 409 | 410 | 422);
+}
+/** Obtain from `resolveActionIntents` so reviews use the current session. */
+export declare class XKOVAMemberActionIntents {
+    private readonly binding;
+    private readonly store;
+    private readonly resources;
+    constructor(binding: {
+        clientFingerprint: string;
+        sessionReference: string;
+        accountHolderId: string;
+        applicationExpiresAt: number;
+    }, store: XKOVAMemberActionIntentStore, resources: XKOVAMemberResources);
+    create(input: {
+        reference: string;
+        browserOrigin: string;
+        reviewUri: string;
+        request: XKOVAMemberIntentRequest;
+        review: Readonly<Record<string, string>>;
+    }): Promise<StoredXKOVAMemberActionIntent>;
+    read(reference: string): Promise<StoredXKOVAMemberActionIntent>;
+    /** Explicit user initiation only. No signing or execution, and no retry with a different key. */
+    prepare(reference: string): Promise<StoredXKOVAMemberActionIntent & {
+        prepared: XKOVAMemberPreparedAction;
+    }>;
+    private assertBound;
+}

package/dist/member-action-intents.js

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+export class XKOVAMemberIntentError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code === 'action_intent_conflict'
+            ? 'This action has different reviewed input. Start a new review.'
+            : code === 'action_intent_expired'
+                ? 'This review expired. Check activity before starting another action.'
+                : code === 'action_intent_invalid'
+                    ? 'The action reference is invalid. Check your device clock and start a new review.'
+                    : 'This action review is unavailable.');
+        this.code = code;
+        this.status = status;
+        this.name = 'XKOVAMemberIntentError';
+    }
+}
+/** Obtain from `resolveActionIntents` so reviews use the current session. */
+export class XKOVAMemberActionIntents {
+    binding;
+    store;
+    resources;
+    constructor(binding, store, resources) {
+        this.binding = binding;
+        this.store = store;
+        this.resources = resources;
+    }
+    async create(input) {
+        const key = intentKey(input.reference);
+        const expiresAt = referenceExpiresAt(input.reference);
+        const location = new URL(input.reviewUri);
+        if (location.origin !== input.browserOrigin ||
+            location.username ||
+            location.password ||
+            location.hash ||
+            (location.protocol !== 'https:' &&
+                !(location.protocol === 'http:' && location.hostname === 'localhost')))
+            throw new TypeError('Action review requires the exact application origin');
+        const snapshot = JSON.parse(canonicalJson({
+            request: input.request,
+            review: input.review,
+            reviewUri: location.toString(),
+        }));
+        if (Object.keys(snapshot.review).length > 20 ||
+            Object.entries(snapshot.review).some(([name, value]) => !/^[a-z][a-z0-9_]{0,63}$/.test(name) || typeof value !== 'string' || value.length > 1024))
+            throw new TypeError('Action review must contain bounded text fields');
+        const inputDigest = digest(canonicalJson(snapshot));
+        return this.store.runExclusive(key, async () => {
+            const existing = await this.store.get(key);
+            if (existing) {
+                this.assertBound(existing);
+                if (existing.inputDigest !== inputDigest)
+                    throw new XKOVAMemberIntentError('action_intent_conflict', 409);
+                return existing;
+            }
+            const intent = {
+                ...snapshot,
+                ...this.binding,
+                inputDigest,
+                creationIdempotencyKey: `member-intent-${digest(`${this.binding.clientFingerprint}:${this.binding.sessionReference}:${input.reference}`)}`,
+                expiresAt: Math.min(expiresAt, this.binding.applicationExpiresAt),
+                retainUntil: this.binding.applicationExpiresAt,
+            };
+            await this.store.put(key, intent);
+            return intent;
+        });
+    }
+    async read(reference) {
+        const value = await this.store.get(intentKey(reference));
+        if (!value)
+            throw new XKOVAMemberIntentError('action_intent_unavailable', 404);
+        this.assertBound(value);
+        return value;
+    }
+    /** Explicit user initiation only. No signing or execution, and no retry with a different key. */
+    async prepare(reference) {
+        return this.store.runExclusive(intentKey(reference), async () => {
+            const value = await this.read(reference);
+            if (value.prepared)
+                return { ...value, prepared: value.prepared };
+            const options = { idempotencyKey: value.creationIdempotencyKey };
+            let prepared;
+            switch (value.request.operation) {
+                case 'payment': {
+                    const resource = await this.resources.payments.create(value.request.body, options);
+                    prepared = { resourceType: 'payment', resourceId: resource.id, action: 'sign' };
+                    break;
+                }
+                case 'escrow': {
+                    const resource = await this.resources.escrows.create(value.request.body, options);
+                    prepared = {
+                        resourceType: 'escrow',
+                        resourceId: resource.escrow.id,
+                        action: 'create',
+                        claimUrl: resource.claim_url_short ?? resource.claim_url,
+                    };
+                    break;
+                }
+                case 'payment_request_approve': {
+                    const resource = await this.resources.paymentRequests.approve(value.request.id, {
+                        accountHolderId: value.request.accountHolderId,
+                        senderWalletId: value.request.senderWalletId,
+                    }, options);
+                    prepared = { resourceType: 'payment', resourceId: resource.id, action: 'sign' };
+                    break;
+                }
+            }
+            const completed = { ...value, prepared };
+            await this.store.replace(intentKey(reference), completed);
+            return completed;
+        });
+    }
+    assertBound(value) {
+        if (value.clientFingerprint !== this.binding.clientFingerprint ||
+            value.sessionReference !== this.binding.sessionReference ||
+            value.accountHolderId !== this.binding.accountHolderId)
+            throw new XKOVAMemberIntentError('action_intent_unavailable', 404);
+        if (value.expiresAt <= Date.now())
+            throw new XKOVAMemberIntentError('action_intent_expired', 410);
+    }
+}
+function intentKey(reference) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(reference))
+        throw new XKOVAMemberIntentError('action_intent_invalid', 422);
+    return digest(reference);
+}
+/**
+ * A public review reference contains a six-byte creation time and 26 random bytes.
+ * The time grants no authority. It caps replay to one hour, even after store loss,
+ * strictly inside the API's 24-hour idempotency retention. Changing the time changes
+ * the reference and is a new intent, never a retry of the old one.
+ */
+function referenceExpiresAt(reference) {
+    const bytes = Buffer.from(reference, 'base64url');
+    if (bytes.length !== 32 || bytes.toString('base64url') !== reference)
+        throw new XKOVAMemberIntentError('action_intent_invalid', 422);
+    const createdAt = bytes.readUIntBE(0, 6);
+    if (createdAt > Date.now() + 5 * 60_000)
+        throw new XKOVAMemberIntentError('action_intent_invalid', 422);
+    const expiresAt = createdAt + 60 * 60_000;
+    if (expiresAt <= Date.now())
+        throw new XKOVAMemberIntentError('action_intent_expired', 410);
+    return expiresAt;
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function canonicalJson(input) {
+    const ancestors = new Set();
+    let nodes = 0;
+    const visit = (value, depth = 0) => {
+        if (++nodes > 4096 || depth > 32)
+            throw new TypeError('Action intent input is too large or deeply nested');
+        if (value === null || typeof value === 'boolean' || typeof value === 'string')
+            return value;
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        if (typeof value === 'object') {
+            if (ancestors.has(value))
+                throw new TypeError('Action intent input must not contain cycles');
+            ancestors.add(value);
+            try {
+                if (Array.isArray(value))
+                    return value.map((child) => visit(child, depth + 1));
+                if (Object.getPrototypeOf(value) === null ||
+                    Object.getPrototypeOf(Object.getPrototypeOf(value)) === null)
+                    return Object.fromEntries(Object.entries(value)
+                        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                        .map(([key, child]) => [key, visit(child, depth + 1)]));
+            }
+            finally {
+                ancestors.delete(value);
+            }
+        }
+        throw new TypeError('Action intent input must contain only JSON values');
+    };
+    const serialized = JSON.stringify(visit(input));
+    if (serialized.length > 16_384)
+        throw new TypeError('Action intent input is too large');
+    return serialized;
+}