@atomiqlabs/sdk 8.8.3 → 8.9.0

package/dist/api/ApiTypes.d.ts

@@ -0,0 +1,157 @@
+import { Token } from "../types/Token";
+import { TokenAmount } from "../types/TokenAmount";
+import { LNURLPay, LNURLPayParamsWithUrl } from "../types/lnurl/LNURLPay";
+import { LNURLWithdraw, LNURLWithdrawParamsWithUrl } from "../types/lnurl/LNURLWithdraw";
+import { Swapper } from "../swapper/Swapper";
+/**
+ * Unified amount type for all API responses
+ *
+ * @category API
+ */
+export type ApiAmount = {
+    /** Decimal format of the amount, e.g. "1.5" */
+    amount: string;
+    /** Raw base units as string, e.g. "1500000000000000000" */
+    rawAmount: string;
+    /** Token decimals, e.g. 18 */
+    decimals: number;
+    /** Token ticker, e.g. "STRK" */
+    symbol: string;
+    /** Chain identifier, e.g. "STARKNET", "BITCOIN", "LIGHTNING" */
+    chain: string;
+};
+/**
+ * Serializable token representation for API responses
+ *
+ * @category API
+ */
+export type ApiToken = {
+    /** Canonical token identifier accepted by the API, e.g. "BITCOIN-BTC", "LIGHTNING-BTC", "STARKNET-STRK" */
+    id: string;
+    /** Chain identifier, e.g. "STARKNET", "BITCOIN", "LIGHTNING" */
+    chainId: string;
+    /** Token ticker, e.g. "STRK" */
+    ticker: string;
+    /** Full token name */
+    name: string;
+    /** Decimal places of the token */
+    decimals: number;
+    /** Token contract address, or empty string for BTC on Bitcoin/Lightning */
+    address: string;
+};
+/**
+ * Serializable LNURL-pay representation for API responses
+ *
+ * @category API
+ */
+export type ApiLNURLPay = {
+    /** Marks the LNURL payload as an LNURL-pay response. */
+    type: "pay";
+    /** Minimum payable amount supported by the LNURL-pay endpoint. */
+    min: ApiAmount;
+    /** Maximum payable amount supported by the LNURL-pay endpoint. */
+    max: ApiAmount;
+    /** Maximum comment length accepted by the LNURL-pay endpoint. */
+    commentMaxLength: number;
+    /** Short human-readable description of the payee, when provided by the LNURL service. */
+    shortDescription?: string;
+    /** Longer human-readable description of the payee, when provided by the LNURL service. */
+    longDescription?: string;
+    /** Optional icon for the payee, usually encoded as a data URL. */
+    icon?: string;
+    /** Raw LNURL-pay metadata and callback parameters. */
+    params: LNURLPayParamsWithUrl;
+};
+/**
+ * Serializable LNURL-withdraw representation for API responses
+ *
+ * @category API
+ */
+export type ApiLNURLWithdraw = {
+    /** Marks the LNURL payload as an LNURL-withdraw response. */
+    type: "withdraw";
+    /** Minimum withdrawable amount supported by the LNURL-withdraw endpoint. */
+    min: ApiAmount;
+    /** Maximum withdrawable amount supported by the LNURL-withdraw endpoint. */
+    max: ApiAmount;
+    /** Raw LNURL-withdraw metadata and callback parameters. */
+    params: LNURLWithdrawParamsWithUrl;
+};
+/**
+ * Serializable LNURL representation for API responses
+ *
+ * @category API
+ */
+export type ApiLNURL = ApiLNURLPay | ApiLNURLWithdraw;
+/**
+ * Converts a TokenAmount to the serializable ApiAmount format
+ *
+ * @category API
+ */
+export declare function toApiAmount(tokenAmount: TokenAmount): ApiAmount;
+/**
+ * Converts a Token to the serializable ApiToken format
+ *
+ * @category API
+ */
+export declare function toApiToken(token: Token): ApiToken;
+/**
+ * Converts LNURL data to the serializable API format
+ *
+ * @category API
+ */
+export declare function toApiLNURL(lnurl: LNURLPay | LNURLWithdraw, swapper: Swapper<any>): ApiLNURL;
+/**
+ * Maps a TypeScript type to its schema type string representation
+ *
+ * @category API
+ */
+type TypeToSchemaType<T> = NonNullable<T> extends string ? "string" : NonNullable<T> extends number ? "number" : NonNullable<T> extends bigint ? "bigint" : NonNullable<T> extends boolean ? "boolean" : NonNullable<T> extends any[] ? "array" : "object";
+/**
+ * Schema definition for a single API input field.
+ *
+ * @category API
+ */
+export type InputSchemaField<T = unknown> = {
+    /** Primitive schema type inferred from the TypeScript field type. */
+    type: TypeToSchemaType<T>;
+    /** Whether the field is required by the endpoint input parser. */
+    required: boolean;
+    /** Human-readable description of the field exposed by the API schema. */
+    description: string;
+    /** Nested schema properties for object-like fields. */
+    properties?: T extends readonly any[] ? never : T extends object ? {
+        [K in keyof T]-?: InputSchemaField<T[K]>;
+    } : never;
+    /** Schema definition for array items when the field is an array. */
+    items?: T extends readonly (infer U)[] ? InputSchemaField<U> : never;
+    /** Enumerated allowed values for string, number, or bigint fields when constrained. */
+    allowedValues?: NonNullable<T> extends string | number | bigint ? NonNullable<T>[] : never;
+};
+/**
+ * Schema definition describing the accepted input shape for an API endpoint.
+ *
+ * @category API
+ */
+export type InputSchema<TInput> = {
+    [K in keyof TInput]-?: InputSchemaField<TInput[K]>;
+};
+/**
+ * Typed API endpoint definition for framework-agnostic integration
+ *
+ * @category API
+ */
+export type ApiEndpoint<TInput, TOutput, Type extends "GET" | "POST"> = {
+    /** HTTP method used by the endpoint. */
+    type: Type;
+    /** Human-readable description of what this endpoint does, written for AI agent consumption. */
+    description: string;
+    /** Structured schema describing the accepted input payload. */
+    inputSchema: InputSchema<TInput>;
+    /** Typed endpoint implementation that receives already-validated input. */
+    callback: (input: TInput, abortSignal?: AbortSignal) => Promise<TOutput>;
+    /** Raw endpoint implementation that parses unknown input into the typed callback. */
+    callbackRaw: (input: unknown, abortSignal?: AbortSignal) => Promise<TOutput>;
+};
+export declare function createApiEndpoint<TInput, TOutput, Type extends "GET" | "POST">(type: Type, description: string, callback: (input: TInput, abortSignal?: AbortSignal) => Promise<TOutput>, inputSchema: InputSchema<TInput>): ApiEndpoint<TInput, TOutput, Type>;
+export {};

package/dist/api/ApiTypes.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiEndpoint = exports.toApiLNURL = exports.toApiToken = exports.toApiAmount = void 0;
+const Token_1 = require("../types/Token");
+const TokenAmount_1 = require("../types/TokenAmount");
+const ApiParser_1 = require("./ApiParser");
+/**
+ * Converts a TokenAmount to the serializable ApiAmount format
+ *
+ * @category API
+ */
+function toApiAmount(tokenAmount) {
+    return {
+        amount: tokenAmount.amount,
+        rawAmount: tokenAmount.rawAmount != null ? tokenAmount.rawAmount.toString() : "0",
+        decimals: tokenAmount.token.decimals,
+        symbol: tokenAmount.token.ticker,
+        chain: tokenAmount.token.chainId
+    };
+}
+exports.toApiAmount = toApiAmount;
+/**
+ * Converts a Token to the serializable ApiToken format
+ *
+ * @category API
+ */
+function toApiToken(token) {
+    return {
+        id: `${token.chainId}-${token.ticker}`,
+        chainId: token.chainId,
+        ticker: token.ticker,
+        name: token.name,
+        decimals: token.decimals,
+        address: token.address
+    };
+}
+exports.toApiToken = toApiToken;
+/**
+ * Converts LNURL data to the serializable API format
+ *
+ * @category API
+ */
+function toApiLNURL(lnurl, swapper) {
+    if (lnurl.type === "pay") {
+        return {
+            type: "pay",
+            min: toApiAmount((0, TokenAmount_1.toTokenAmount)(lnurl.min, Token_1.BitcoinTokens.BTCLN, swapper.prices)),
+            max: toApiAmount((0, TokenAmount_1.toTokenAmount)(lnurl.max, Token_1.BitcoinTokens.BTCLN, swapper.prices)),
+            commentMaxLength: lnurl.commentMaxLength,
+            ...(lnurl.shortDescription != null ? { shortDescription: lnurl.shortDescription } : {}),
+            ...(lnurl.longDescription != null ? { longDescription: lnurl.longDescription } : {}),
+            ...(lnurl.icon != null ? { icon: lnurl.icon } : {}),
+            params: lnurl.params
+        };
+    }
+    return {
+        type: "withdraw",
+        min: toApiAmount((0, TokenAmount_1.toTokenAmount)(lnurl.min, Token_1.BitcoinTokens.BTCLN, swapper.prices)),
+        max: toApiAmount((0, TokenAmount_1.toTokenAmount)(lnurl.max, Token_1.BitcoinTokens.BTCLN, swapper.prices)),
+        params: lnurl.params
+    };
+}
+exports.toApiLNURL = toApiLNURL;
+function createApiEndpoint(type, description, callback, inputSchema) {
+    return {
+        type,
+        description,
+        callback,
+        inputSchema,
+        callbackRaw: (input, abortSignal) => {
+            return callback((0, ApiParser_1.parseApiInput)(inputSchema, input), abortSignal);
+        }
+    };
+}
+exports.createApiEndpoint = createApiEndpoint;

package/dist/api/SerializedAction.d.ts

@@ -0,0 +1,40 @@
+import { SwapExecutionAction } from "../types/SwapExecutionAction";
+import { ApiAmount } from "./ApiTypes";
+/**
+ * Strips non-serializable fields (functions, complex objects) from SwapExecutionAction types.
+ * Uses key-remapping to truly omit function keys from the resulting type.
+ *
+ * - SignSmartChainTransaction: functions removed, txs → string[]
+ * - SignPSBT: functions removed, txs[].psbt (Transaction object) omitted
+ * - SendToAddress: functions removed, txs[].amount (TokenAmount) → ApiAmount
+ * - Wait: functions removed, data fields kept as-is
+ *
+ * @category API
+ */
+export type SerializedAction<T extends SwapExecutionAction> = T["type"] extends "SignSmartChainTransaction" ? {
+    [K in keyof T as T[K] extends Function ? never : K]: K extends "txs" ? string[] : T[K];
+} : T["type"] extends "SignPSBT" ? {
+    [K in keyof T as T[K] extends Function ? never : K]: K extends "txs" ? (T extends {
+        txs: (infer U)[];
+    } ? Omit<U, "psbt">[] : never) : T[K];
+} : T["type"] extends "SendToAddress" ? {
+    [K in keyof T as T[K] extends Function ? never : K]: K extends "txs" ? (T extends {
+        txs: (infer U)[];
+    } ? (Omit<U, "amount"> & {
+        amount: ApiAmount;
+    })[] : never) : T[K];
+} : {
+    [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+/**
+ * Runtime serializer that strips non-serializable fields from a SwapExecutionAction.
+ * Matches the compile-time SerializedAction<T> type.
+ *
+ * @param action The swap execution action to serialize
+ * @param txSerializer Optional chain-specific transaction serializer for SignSmartChainTransaction actions.
+ *   Accepts the chain identifier and raw transaction, returns the serialized string.
+ *   Falls back to JSON.stringify if not provided.
+ *
+ * @category API
+ */
+export declare function serializeAction(action: SwapExecutionAction, txSerializer?: (chainId: string, tx: any) => Promise<string>): Promise<SerializedAction<SwapExecutionAction>>;

package/dist/api/SerializedAction.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeAction = void 0;
+const ApiTypes_1 = require("./ApiTypes");
+/**
+ * Runtime serializer that strips non-serializable fields from a SwapExecutionAction.
+ * Matches the compile-time SerializedAction<T> type.
+ *
+ * @param action The swap execution action to serialize
+ * @param txSerializer Optional chain-specific transaction serializer for SignSmartChainTransaction actions.
+ *   Accepts the chain identifier and raw transaction, returns the serialized string.
+ *   Falls back to JSON.stringify if not provided.
+ *
+ * @category API
+ */
+async function serializeAction(action, txSerializer) {
+    switch (action.type) {
+        case "SendToAddress": {
+            const { waitForTransactions, ...rest } = action;
+            return {
+                ...rest,
+                txs: rest.txs.map(tx => ({
+                    type: tx.type,
+                    address: tx.address,
+                    hyperlink: tx.hyperlink,
+                    amount: (0, ApiTypes_1.toApiAmount)(tx.amount)
+                }))
+            };
+        }
+        case "SignPSBT": {
+            const { submitPsbt, txs, ...rest } = action;
+            return {
+                ...rest,
+                txs: txs.map(tx => {
+                    const { psbt, ...txRest } = tx;
+                    return txRest;
+                })
+            };
+        }
+        case "SignSmartChainTransaction": {
+            const { submitTransactions, ...rest } = action;
+            return {
+                ...rest,
+                txs: await Promise.all(rest.txs.map(tx => txSerializer != null
+                    ? txSerializer(rest.chain, tx)
+                    : Promise.resolve(JSON.stringify(tx))))
+            };
+        }
+        case "Wait": {
+            const { wait, ...rest } = action;
+            return rest;
+        }
+        default: {
+            const _exhaustive = action;
+            throw new Error(`Unknown action type: ${_exhaustive.type}`);
+        }
+    }
+}
+exports.serializeAction = serializeAction;

package/dist/api/SwapperApi.d.ts

@@ -0,0 +1,50 @@
+import { MultiChain, Swapper } from "../swapper/Swapper";
+import { ApiEndpoint } from "./ApiTypes";
+import { CreateSwapInput, CreateSwapOutput, GetSpendableBalanceInput, GetSpendableBalanceOutput, GetSupportedTokensInput, GetSupportedTokensOutput, GetSwapCounterTokensInput, GetSwapCounterTokensOutput, GetSwapLimitsInput, GetSwapLimitsOutput, GetSwapStatusInput, GetSwapStatusOutput, ListPendingSwapsInput, ListPendingSwapsOutput, ListSwapsInput, ListSwapsOutput, ParseAddressInput, ParseAddressOutput, SettleWithLnurlInput, SettleWithLnurlOutput, SubmitTransactionInput, SubmitTransactionOutput } from "./ApiEndpoints";
+export type SwapperApiConfig = {
+    syncOnGetStatus?: boolean;
+    idempotentTxSubmission?: boolean;
+};
+export declare class SwapperApi<T extends MultiChain> {
+    private swapper;
+    private readonly config?;
+    readonly endpoints: {
+        createSwap: ApiEndpoint<CreateSwapInput, CreateSwapOutput, "POST">;
+        listSwaps: ApiEndpoint<ListSwapsInput, ListSwapsOutput, "GET">;
+        listPendingSwaps: ApiEndpoint<ListPendingSwapsInput, ListPendingSwapsOutput, "GET">;
+        getSupportedTokens: ApiEndpoint<GetSupportedTokensInput, GetSupportedTokensOutput, "GET">;
+        getSwapCounterTokens: ApiEndpoint<GetSwapCounterTokensInput, GetSwapCounterTokensOutput, "GET">;
+        getSwapLimits: ApiEndpoint<GetSwapLimitsInput, GetSwapLimitsOutput, "GET">;
+        parseAddress: ApiEndpoint<ParseAddressInput, ParseAddressOutput, "GET">;
+        getSpendableBalance: ApiEndpoint<GetSpendableBalanceInput, GetSpendableBalanceOutput, "GET">;
+        getSwapStatus: ApiEndpoint<GetSwapStatusInput, GetSwapStatusOutput, "GET">;
+        submitTransaction: ApiEndpoint<SubmitTransactionInput, SubmitTransactionOutput, "POST">;
+        settleWithLnurl: ApiEndpoint<SettleWithLnurlInput, SettleWithLnurlOutput, "POST">;
+    };
+    constructor(swapper: Swapper<T>, config?: SwapperApiConfig | undefined);
+    private txSerializer;
+    init(): Promise<void>;
+    /**
+     * Should be ran periodically, this synchronizes the swap's state with the on-chain data and also purges
+     *  expired swaps from the persistent storage
+     */
+    sync(): Promise<void>;
+    /**
+     * Optionally good to run this periodically, such that any LPs that are dropped off because they are unresponsive
+     *  can be found again.
+     */
+    reloadLps(): Promise<void>;
+    private createSwap;
+    private validateSwapListInput;
+    private createListedSwapOutputs;
+    private listSwaps;
+    private listPendingSwaps;
+    private getSupportedTokens;
+    private getSwapCounterTokens;
+    private getSwapLimits;
+    private parseAddress;
+    private getSpendableBalance;
+    private getSwapStatus;
+    private submitTransaction;
+    private settleWithLnurl;
+}