@veilo/sdk-core 0.4.0 → 0.5.0

package/dist/cjs/cloak/client.d.ts

@@ -0,0 +1,28 @@
+import type { CloakCreateOrderOptions, CloakCreateOrderRequest, CloakCreateOrderResponse, CloakDepositRequest, CloakDepositResponse, CloakOrderStatus, CloakOrderStatusResponse, CloakQuoteRequest, CloakQuoteResponse, CloakRefreshTransactionResponse, CloakRequestOptions, CloakTokensResponse, CloakWaitForFinalOptions, VeiloCloakConfig } from "./types.js";
+/**
+ * Typed façade for the Veilo Cloak Partner API.
+ *
+ * The client builds and reads Cloak orders; it never signs or submits a Solana
+ * transaction on the caller's behalf.
+ */
+export declare class VeiloCloakClient {
+    private readonly transport;
+    constructor(config: VeiloCloakConfig);
+    /** List supported assets and their current raw-unit limits. */
+    listTokens(options?: CloakRequestOptions): Promise<CloakTokensResponse>;
+    /** Price a private transfer. This creates no order and does nothing on-chain. */
+    getQuote(input: CloakQuoteRequest, options?: CloakRequestOptions): Promise<CloakQuoteResponse>;
+    /** Build an unsigned v0 deposit transaction for a signed quote. */
+    createOrder(input: CloakCreateOrderRequest, options?: CloakCreateOrderOptions): Promise<CloakCreateOrderResponse>;
+    /** Rebuild an unfunded order with a fresh blockhash. */
+    refreshTransaction(trackingId: string, options?: CloakRequestOptions): Promise<CloakRefreshTransactionResponse>;
+    /** Read the monotone public status of an order. */
+    getOrderStatus(trackingId: string, options?: CloakRequestOptions): Promise<CloakOrderStatusResponse>;
+    /**
+     * Optional latency hint after the user's deposit confirms. Cloak verifies the
+     * signature independently; this acknowledgement is not proof of payment.
+     */
+    notifyDeposit(input: CloakDepositRequest, options?: CloakRequestOptions): Promise<CloakDepositResponse>;
+    /** Poll until Cloak reports a genuinely final, monotone status. */
+    waitForFinalStatus(trackingId: string, options?: CloakWaitForFinalOptions): Promise<CloakOrderStatus>;
+}

package/dist/cjs/cloak/client.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeiloCloakClient = void 0;
+const polling_js_1 = require("./polling.js");
+const transport_js_1 = require("./transport.js");
+/**
+ * Typed façade for the Veilo Cloak Partner API.
+ *
+ * The client builds and reads Cloak orders; it never signs or submits a Solana
+ * transaction on the caller's behalf.
+ */
+class VeiloCloakClient {
+    constructor(config) {
+        this.transport = new transport_js_1.CloakHttpTransport(config);
+    }
+    /** List supported assets and their current raw-unit limits. */
+    async listTokens(options = {}) {
+        return this.transport.request("GET", "/tokens", options);
+    }
+    /** Price a private transfer. This creates no order and does nothing on-chain. */
+    async getQuote(input, options = {}) {
+        return this.transport.request("POST", "/quote", {
+            ...options,
+            body: input,
+        });
+    }
+    /** Build an unsigned v0 deposit transaction for a signed quote. */
+    async createOrder(input, options = {}) {
+        const headers = {};
+        if (options.idempotencyKey?.trim()) {
+            headers["X-Idempotency-Key"] = options.idempotencyKey.trim();
+        }
+        return this.transport.request("POST", "/order", {
+            body: input,
+            headers,
+            signal: options.signal,
+        });
+    }
+    /** Rebuild an unfunded order with a fresh blockhash. */
+    async refreshTransaction(trackingId, options = {}) {
+        return this.transport.request("GET", `/order/${trackingPath(trackingId)}/transaction`, options);
+    }
+    /** Read the monotone public status of an order. */
+    async getOrderStatus(trackingId, options = {}) {
+        return this.transport.request("GET", `/status/${trackingPath(trackingId)}`, options);
+    }
+    /**
+     * Optional latency hint after the user's deposit confirms. Cloak verifies the
+     * signature independently; this acknowledgement is not proof of payment.
+     */
+    async notifyDeposit(input, options = {}) {
+        return this.transport.request("POST", "/deposit", {
+            ...options,
+            body: input,
+        });
+    }
+    /** Poll until Cloak reports a genuinely final, monotone status. */
+    async waitForFinalStatus(trackingId, options = {}) {
+        return (0, polling_js_1.waitForFinalCloakStatus)(this, trackingId, options);
+    }
+}
+exports.VeiloCloakClient = VeiloCloakClient;
+function trackingPath(trackingId) {
+    const value = trackingId.trim();
+    if (!value)
+        throw new TypeError("trackingId must not be empty.");
+    return encodeURIComponent(value);
+}

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

@@ -0,0 +1,13 @@
+import type { CloakErrorCode, CloakErrorResponse } from "./types.js";
+/** Structured error thrown for Cloak HTTP, transport, and response failures. */
+export declare class CloakApiError extends Error {
+    readonly code: CloakErrorCode | (string & {});
+    readonly status: number;
+    readonly details?: CloakErrorResponse;
+    readonly retryAfter?: number;
+    readonly min?: string;
+    readonly max?: string;
+    readonly field?: string;
+    readonly maxBps?: number;
+    constructor(code: CloakErrorCode | (string & {}), message: string, status: number, details?: CloakErrorResponse);
+}

package/dist/cjs/cloak/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloakApiError = void 0;
+/** Structured error thrown for Cloak HTTP, transport, and response failures. */
+class CloakApiError extends Error {
+    constructor(code, message, status, details) {
+        super(message);
+        this.name = "CloakApiError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.retryAfter = numberField(details?.retryAfter);
+        this.min = stringField(details?.min);
+        this.max = stringField(details?.max);
+        this.field = stringField(details?.field);
+        this.maxBps = numberField(details?.maxBps);
+    }
+}
+exports.CloakApiError = CloakApiError;
+function stringField(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/dist/cjs/cloak/helpers.d.ts

@@ -0,0 +1,6 @@
+import { VersionedTransaction } from "@solana/web3.js";
+import type { CloakOrderStatus, CloakOrderTransaction, CloakPartnerStatus } from "./types.js";
+/** True for a terminal public status or a status response carrying one. */
+export declare function isFinalCloakStatus(value: CloakPartnerStatus | Pick<CloakOrderStatus, "status" | "final">): boolean;
+/** Deserialize the API's unsigned base64 transaction for wallet signing. */
+export declare function deserializeCloakTransaction(value: string | Pick<CloakOrderTransaction, "transaction">): VersionedTransaction;

package/dist/cjs/cloak/helpers.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFinalCloakStatus = isFinalCloakStatus;
+exports.deserializeCloakTransaction = deserializeCloakTransaction;
+const web3_js_1 = require("@solana/web3.js");
+const FINAL_STATUSES = new Set([
+    "SUCCESSFUL",
+    "FAILED",
+    "REFUNDED",
+    "EXPIRED",
+]);
+/** True for a terminal public status or a status response carrying one. */
+function isFinalCloakStatus(value) {
+    return typeof value === "string"
+        ? FINAL_STATUSES.has(value)
+        : value.final || FINAL_STATUSES.has(value.status);
+}
+/** Deserialize the API's unsigned base64 transaction for wallet signing. */
+function deserializeCloakTransaction(value) {
+    const encoded = typeof value === "string" ? value : value.transaction;
+    if (!encoded)
+        throw new TypeError("Cloak transaction must not be empty.");
+    return web3_js_1.VersionedTransaction.deserialize(decodeBase64(encoded));
+}
+function decodeBase64(encoded) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(encoded, "base64"));
+    }
+    const binary = atob(encoded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index++) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}

package/dist/cjs/cloak/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./helpers.js";
+export * from "./polling.js";
+export * from "./client.js";
+export { DEFAULT_VEILO_API_BASE_URL } from "./transport.js";

package/dist/cjs/cloak/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_VEILO_API_BASE_URL = void 0;
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./helpers.js"), exports);
+__exportStar(require("./polling.js"), exports);
+__exportStar(require("./client.js"), exports);
+var transport_js_1 = require("./transport.js");
+Object.defineProperty(exports, "DEFAULT_VEILO_API_BASE_URL", { enumerable: true, get: function () { return transport_js_1.DEFAULT_VEILO_API_BASE_URL; } });

package/dist/cjs/cloak/polling.d.ts

@@ -0,0 +1,7 @@
+import type { CloakOrderStatus, CloakOrderStatusResponse, CloakRequestOptions, CloakWaitForFinalOptions } from "./types.js";
+/** Minimal dependency required by the polling helper. */
+export interface CloakStatusReader {
+    getOrderStatus(trackingId: string, options?: CloakRequestOptions): Promise<CloakOrderStatusResponse>;
+}
+/** Poll any compatible status reader until Cloak reaches a final state. */
+export declare function waitForFinalCloakStatus(reader: CloakStatusReader, trackingId: string, options?: CloakWaitForFinalOptions): Promise<CloakOrderStatus>;

package/dist/cjs/cloak/polling.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForFinalCloakStatus = waitForFinalCloakStatus;
+const errors_js_1 = require("./errors.js");
+const helpers_js_1 = require("./helpers.js");
+/** Poll any compatible status reader until Cloak reaches a final state. */
+async function waitForFinalCloakStatus(reader, trackingId, options = {}) {
+    const intervalMs = finiteNonNegative(options.intervalMs ?? 3000, "intervalMs");
+    const timeoutMs = options.timeoutMs === undefined
+        ? undefined
+        : finiteNonNegative(options.timeoutMs, "timeoutMs");
+    const startedAt = Date.now();
+    for (;;) {
+        throwIfAborted(options.signal);
+        const { order } = await reader.getOrderStatus(trackingId, {
+            signal: options.signal,
+        });
+        await options.onStatus?.(order);
+        if ((0, helpers_js_1.isFinalCloakStatus)(order))
+            return order;
+        if (timeoutMs !== undefined) {
+            const elapsed = Date.now() - startedAt;
+            if (elapsed + intervalMs > timeoutMs) {
+                throw new errors_js_1.CloakApiError("POLL_TIMEOUT", `Cloak order ${trackingId} did not reach a final status within ${timeoutMs}ms.`, 0);
+            }
+        }
+        await abortableDelay(intervalMs, options.signal);
+    }
+}
+function finiteNonNegative(value, field) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(`${field} must be a finite, non-negative number.`);
+    }
+    return value;
+}
+function abortError() {
+    const error = new Error("The operation was aborted.");
+    error.name = "AbortError";
+    return error;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError();
+}
+function abortableDelay(ms, signal) {
+    if (ms === 0) {
+        throwIfAborted(signal);
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            reject(abortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/cjs/cloak/transport.d.ts

@@ -0,0 +1,15 @@
+import type { CloakRequestOptions, VeiloCloakConfig } from "./types.js";
+/** Production Veilo API origin. Cloak routes are mounted at `/cloak/v1`. */
+export declare const DEFAULT_VEILO_API_BASE_URL = "https://api.veilo.network";
+export interface CloakTransportRequest extends CloakRequestOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Internal HTTP boundary. Endpoint methods depend on this instead of fetch. */
+export declare class CloakHttpTransport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(config: VeiloCloakConfig);
+    request<T>(method: "GET" | "POST", route: string, options?: CloakTransportRequest): Promise<T>;
+}

package/dist/cjs/cloak/transport.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloakHttpTransport = exports.DEFAULT_VEILO_API_BASE_URL = void 0;
+const errors_js_1 = require("./errors.js");
+/** Production Veilo API origin. Cloak routes are mounted at `/cloak/v1`. */
+exports.DEFAULT_VEILO_API_BASE_URL = "https://api.veilo.network";
+/** Internal HTTP boundary. Endpoint methods depend on this instead of fetch. */
+class CloakHttpTransport {
+    constructor(config) {
+        const baseUrl = config.baseUrl === undefined
+            ? exports.DEFAULT_VEILO_API_BASE_URL
+            : config.baseUrl.trim();
+        const apiKey = config.apiKey?.trim();
+        if (!baseUrl) {
+            throw new TypeError("VeiloCloakClient baseUrl must not be empty.");
+        }
+        if (!apiKey) {
+            throw new TypeError("VeiloCloakClient requires an apiKey.");
+        }
+        const fetchImpl = config.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (!fetchImpl) {
+            throw new TypeError("No fetch implementation is available. Pass `fetch` in the client config.");
+        }
+        this.baseUrl = cloakApiUrl(baseUrl);
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+    async request(method, route, options = {}) {
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${route}`, {
+                method,
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "x-api-key": this.apiKey,
+                    ...options.headers,
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            rethrowAbort(error, options.signal);
+            throw networkError(error, "Network request failed.");
+        }
+        const parsed = await parseResponse(response, options.signal);
+        const success = parsed.success;
+        if (!response.ok || success === false) {
+            throw apiError(response, parsed);
+        }
+        if (success !== true) {
+            throw new errors_js_1.CloakApiError("INVALID_RESPONSE", `Cloak returned a response without a success marker (${response.status}).`, response.status);
+        }
+        return parsed;
+    }
+}
+exports.CloakHttpTransport = CloakHttpTransport;
+function cloakApiUrl(baseUrl) {
+    const normalized = baseUrl.replace(/\/+$/, "");
+    return /\/cloak\/v1$/i.test(normalized)
+        ? normalized
+        : `${normalized}/cloak/v1`;
+}
+async function parseResponse(response, signal) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        rethrowAbort(error, signal);
+        throw networkError(error, "Could not read the Cloak response.");
+    }
+    let parsed = {};
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new errors_js_1.CloakApiError("INVALID_RESPONSE", `Cloak returned a non-JSON response (${response.status}).`, response.status);
+        }
+    }
+    if (!isRecord(parsed)) {
+        throw new errors_js_1.CloakApiError("INVALID_RESPONSE", `Cloak returned an invalid response (${response.status}).`, response.status);
+    }
+    return parsed;
+}
+function apiError(response, body) {
+    const retryAfterHeader = parseRetryAfter(response.headers.get("retry-after"));
+    const details = body.retryAfter === undefined && retryAfterHeader !== undefined
+        ? { ...body, retryAfter: retryAfterHeader }
+        : body;
+    const code = typeof body.error === "string"
+        ? body.error
+        : response.ok
+            ? "INVALID_RESPONSE"
+            : "HTTP_ERROR";
+    const message = typeof body.message === "string"
+        ? body.message
+        : `Cloak request failed (${response.status}).`;
+    return new errors_js_1.CloakApiError(code, message, response.status, details);
+}
+function networkError(error, fallback) {
+    return new errors_js_1.CloakApiError("NETWORK_ERROR", error instanceof Error ? error.message : fallback, 0);
+}
+function rethrowAbort(error, signal) {
+    if ((error instanceof Error && error.name === "AbortError") || signal?.aborted) {
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}

package/dist/cjs/cloak/types.d.ts

@@ -0,0 +1,188 @@
+/** A fetch-compatible transport, injectable for runtimes without global fetch. */
+export type CloakFetch = (input: string, init?: RequestInit) => Promise<Response>;
+export interface VeiloCloakConfig {
+    /** API origin or full Cloak URL. Defaults to https://api.veilo.network/. */
+    baseUrl?: string;
+    /** Partner key issued by Veilo. Sent only in the `x-api-key` header. */
+    apiKey: string;
+    /** Optional fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: CloakFetch;
+}
+export interface CloakRequestOptions {
+    /** Cancels the HTTP request (and polling delay, when used for polling). */
+    signal?: AbortSignal;
+}
+export interface CloakCreateOrderOptions extends CloakRequestOptions {
+    /**
+     * Deduplicates order creation. Strongly recommended even though the API falls
+     * back to the signed quote ID when this is omitted.
+     */
+    idempotencyKey?: string;
+}
+export interface CloakWaitForFinalOptions extends CloakRequestOptions {
+    /** Delay between status reads. Defaults to 3 seconds. */
+    intervalMs?: number;
+    /** Optional total polling deadline. By default polling has no time limit. */
+    timeoutMs?: number;
+    /** Runs after every status read, including the final one. */
+    onStatus?: (order: CloakOrderStatus) => void | Promise<void>;
+}
+export type CloakQuoteMode = "exact_in" | "exact_out";
+export interface CloakToken {
+    /** Veilo asset identifier. Echo this value back in quote requests. */
+    assetId: string;
+    /** Solana mint. Native SOL uses the all-zero system-program address. */
+    mint: string;
+    symbol: string;
+    decimals: number;
+    /** Minimum order amount in raw base units. */
+    minAmount: string;
+    /** Maximum order amount in raw base units. */
+    maxAmount: string;
+}
+export interface CloakTokensResponse {
+    success: true;
+    tokens: CloakToken[];
+    /** True when a usable cached catalogue was served after a refresh failure. */
+    stale?: boolean;
+}
+export interface CloakQuoteRequest {
+    /** Amount in raw base units. Meaning is selected by `mode`. */
+    amount: string;
+    sourceAssetId: string;
+    /** Defaults to `sourceAssetId`; cross-asset Cloak transfers are not yet live. */
+    destinationAssetId?: string;
+    senderAddress: string;
+    recipientAddress: string;
+    /** Defaults to `exact_in`. */
+    mode?: CloakQuoteMode;
+    /** Required when `feeBps` is non-zero. */
+    feeRecipientAddress?: string;
+    /** Partner revenue share in basis points. */
+    feeBps?: number;
+    /** Optional cross-asset slippage band. The relayer clamps it to its supported range. */
+    slippageBps?: number;
+}
+export interface CloakFeeBreakdown {
+    /** Veilo fee in the quote's fee asset (source for sends, destination for swaps). */
+    veiloFee: string;
+    /** Partner fee in the quote's fee asset. */
+    partnerFee: string;
+    /** Relayer-funded on-chain cost in the quote's fee asset. */
+    networkFee: string;
+    /** Accepted when echoing compatibility quote shapes. */
+    partnerBps?: number;
+    /** Destination pool's own swap fee; present only for cross-asset quotes. */
+    poolSwapFee?: string;
+}
+/** Terms cryptographically bound into a cross-asset signed quote. */
+export interface CloakSwapQuoteTerms {
+    minSwapOut: string;
+    destNoteAmount: string;
+    slippageBps: number;
+    quotedOut: string;
+}
+/** Signed quote. Echo this object back unchanged when creating an order. */
+export interface CloakQuote {
+    sourceAssetId: string;
+    destinationAssetId: string;
+    mode: CloakQuoteMode;
+    amountIn: string;
+    amountOut: string;
+    fee: string;
+    protocolFee: string;
+    networkFee: string;
+    feeBreakdown: CloakFeeBreakdown;
+    /** Present only when sourceAssetId and destinationAssetId differ. */
+    swap?: CloakSwapQuoteTerms;
+    /** Extra SOL paid by the sender's wallet, always denominated in lamports. */
+    senderNetworkFeeLamports: string;
+    duration: number;
+    min: string;
+    max: string;
+    quoteId: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export interface CloakQuoteResponse {
+    success: true;
+    quote: CloakQuote;
+}
+export interface CloakCreateOrderRequest {
+    /** The full object returned by `getQuote`; do not modify its values. */
+    quote: CloakQuote;
+    senderAddress: string;
+    recipientAddress: string;
+    /** Repeat the values used for the quote when charging a partner fee. */
+    feeRecipientAddress?: string;
+    feeBps?: number;
+}
+export interface CloakOrderTransaction {
+    trackingId: string;
+    /** Unsigned Solana v0 transaction. */
+    transaction: string;
+    transactionEncoding: "base64";
+    amountIn: string;
+    amountOut: string;
+    expiration: string;
+    blockhashExpiresAtSlot: number;
+}
+export interface CloakCreatedOrder extends CloakOrderTransaction {
+    sourceSymbol: string;
+    destinationSymbol: string;
+    mint: string;
+    decimals: number;
+    /** Estimated seconds until the recipient is paid. */
+    eta: number;
+}
+export interface CloakCreateOrderResponse {
+    success: true;
+    order: CloakCreatedOrder;
+}
+export interface CloakRefreshTransactionResponse {
+    success: true;
+    order: CloakOrderTransaction;
+}
+export type CloakPartnerStatus = "PENDING" | "CONFIRMING" | "EXCHANGING" | "ANONYMIZING" | "SUCCESSFUL" | "FAILED" | "REFUNDED" | "EXPIRED";
+export type CloakDetailedStatus = "awaiting_signature" | "deposit_seen" | "deposit_confirmed" | "swapping" | "swapped" | "queued_payout" | "paying" | "paid" | "refunding" | "refunded" | "expired" | "failed";
+export interface CloakOrderStatus {
+    trackingId: string;
+    status: CloakPartnerStatus;
+    /** Monotone terminal flag. Safe to use for clearing an in-progress UI. */
+    final: boolean;
+    detailedStatus: CloakDetailedStatus;
+    amountIn: string;
+    amountOut: string;
+    sourceSymbol: string;
+    destinationSymbol: string;
+    depositTxSignature?: string | null;
+    payoutTxSignature?: string | null;
+    failureCode?: string;
+    updatedAt: string;
+}
+export interface CloakOrderStatusResponse {
+    success: true;
+    order: CloakOrderStatus;
+}
+export interface CloakDepositRequest {
+    trackingId: string;
+    txSignature: string;
+}
+export interface CloakDepositResponse {
+    success: true;
+    accepted: true;
+}
+/** Known stable error codes. New server codes remain available as plain strings. */
+export type CloakErrorCode = "AMOUNT_BELOW_MIN" | "AMOUNT_ABOVE_MAX" | "QUOTE_FAILED" | "ASSET_NOT_SUPPORTED" | "INVALID_ADDRESS" | "PARTNER_FEE_TOO_HIGH" | "FEE_RECIPIENT_NOT_REGISTERED" | "FEE_RECIPIENT_COOLING_OFF" | "QUOTE_EXPIRED" | "QUOTE_MISMATCH" | "ORDER_IN_PROGRESS" | "IDEMPOTENCY_CONFLICT" | "ORDER_NOT_REFRESHABLE" | "ORDER_NOT_FOUND" | "UNAUTHORIZED" | "LIMIT_EXCEEDED" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "INVALID_RESPONSE" | "POLL_TIMEOUT";
+export interface CloakErrorResponse {
+    success?: false;
+    error?: CloakErrorCode | (string & {});
+    message?: string;
+    min?: string;
+    max?: string;
+    field?: string;
+    maxBps?: number;
+    retryAfter?: number;
+    status?: CloakPartnerStatus;
+    [key: string]: unknown;
+}

package/dist/cjs/cloak/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// =============================================================================
+// Configuration and transport contracts
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/cloak.d.ts

@@ -0,0 +1 @@
+export * from "./cloak/index.js";

package/dist/cjs/cloak.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Stable top-level entry point. Implementation lives in focused Cloak modules.
+__exportStar(require("./cloak/index.js"), exports);