@atomiqlabs/sdk 8.7.7 → 8.9.0

package/src/api/ApiParser.ts

@@ -0,0 +1,138 @@
+import {InputSchema, InputSchemaField} from "./ApiTypes";
+
+// Errors
+function invalidInput(path: string, expected: string, value: unknown): Error {
+    const actualType = value == null ? String(value) : Array.isArray(value) ? "array" : typeof(value);
+    return new Error(`Invalid input "${path}", expected ${expected}, got ${actualType}`);
+}
+
+function missingInput(path: string): Error {
+    return new Error(`Missing required input "${path}"`);
+}
+
+function invalidAllowedValue(path: string, allowedValues: readonly (string | number | bigint)[], value: string | number | bigint): Error {
+    return new Error(
+        `Invalid input "${path}", expected one of: ${allowedValues.map(val => val.toString()).join(", ")}, got ${value.toString()}`
+    );
+}
+
+// Parsers
+function parseNumber(path: string, value: unknown): number {
+    let result: number;
+    if(typeof(value) === "number") {
+        result = value;
+    } else if(typeof(value) === "string") {
+        const trimmedValue = value.trim();
+        if(trimmedValue === "") throw invalidInput(path, "finite number", value);
+        result = Number(trimmedValue);
+    } else throw invalidInput(path, "finite number", value);
+
+    if(!Number.isFinite(result)) throw invalidInput(path, "finite number", value);
+    return result;
+}
+
+function parseBigInt(path: string, value: unknown): bigint {
+    if(typeof(value) === "bigint") return value;
+
+    if(typeof(value) === "number") {
+        if(!Number.isSafeInteger(value)) throw invalidInput(path, "safe integer", value);
+        return BigInt(value);
+    }
+
+    if(typeof(value) === "string") {
+        const trimmedValue = value.trim();
+        if(!/^[+-]?\d+$/.test(trimmedValue)) throw invalidInput(path, "integer", value);
+        return BigInt(trimmedValue);
+    }
+
+    throw invalidInput(path, "integer", value);
+}
+
+function parseBoolean(path: string, value: unknown): boolean {
+    Boolean(value);
+    if(typeof(value) === "boolean") return value;
+    if(value === "true") return true;
+    if(value === "false") return false;
+    throw invalidInput(path, "boolean", value);
+}
+
+// Object type check
+function isObject(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof(value) === "object" && !Array.isArray(value);
+}
+
+// Allowed values for enums
+function applyAllowedValues<T extends string | number | bigint>(path: string, value: T, allowedValues?: readonly T[]): T {
+    if(allowedValues != null && !allowedValues.includes(value)) {
+        throw invalidAllowedValue(path, allowedValues, value);
+    }
+    return value;
+}
+
+function parseField<T>(field: InputSchemaField<T>, value: unknown, path: string): T {
+    switch(field.type) {
+        case "string": {
+            if(typeof(value) !== "string") throw invalidInput(path, "string", value);
+            return applyAllowedValues(path, value, field.allowedValues as readonly string[] | undefined) as T;
+        }
+        case "number": {
+            const parsedValue = parseNumber(path, value);
+            return applyAllowedValues(path, parsedValue, field.allowedValues as readonly number[] | undefined) as T;
+        }
+        case "bigint": {
+            const parsedValue = parseBigInt(path, value);
+            return applyAllowedValues(path, parsedValue, field.allowedValues as readonly bigint[] | undefined) as T;
+        }
+        case "boolean":
+            return parseBoolean(path, value) as T;
+        case "array": {
+            if(!Array.isArray(value)) throw invalidInput(path, "array", value);
+            if(field.items == null) return [...value] as T;
+
+            return value.map((item, index) => parseField(field.items as InputSchemaField, item, `${path}[${index}]`)) as T;
+        }
+        case "object": {
+            if(!isObject(value)) throw invalidInput(path, "object", value);
+            if(field.properties == null) return {...value} as T;
+
+            return _parseApiInput(field.properties as InputSchema<T>, value, path);
+        }
+        default:
+            throw new Error(`Unsupported input schema type for "${path}": ${(field as InputSchemaField).type}`);
+    }
+}
+
+function _parseApiInput<TInput>(inputSchema: InputSchema<TInput>, rawInput: unknown, parentPath: string = ""): TInput {
+    if(!isObject(rawInput)) {
+        throw invalidInput(parentPath || "input", "object", rawInput);
+    }
+
+    const parsedInput: Partial<TInput> = {};
+
+    for(const key in inputSchema) {
+        const field = inputSchema[key];
+        const value = rawInput[key];
+        const path = parentPath === "" ? key : `${parentPath}.${key}`;
+
+        if(value == null) {
+            if(field.required) throw missingInput(path);
+            continue;
+        }
+
+        parsedInput[key] = parseField(field as InputSchemaField<TInput[typeof key]>, value, path);
+    }
+
+    return parsedInput as TInput;
+}
+
+/**
+ * Parses raw input values according to the endpoint schema.
+ *
+ * This accepts untyped transport input such as HTTP query params, JSON request bodies,
+ * or CLI arguments and returns the normalized callback input type.
+ *
+ * @category API
+ */
+export function parseApiInput<TInput>(inputSchema: InputSchema<TInput>, rawInput: unknown): TInput {
+    return _parseApiInput(inputSchema, rawInput);
+}

package/src/api/ApiTypes.ts

@@ -0,0 +1,229 @@
+import {BitcoinTokens, Token} from "../types/Token";
+import {TokenAmount, toTokenAmount} from "../types/TokenAmount";
+import {LNURLPay, LNURLPayParamsWithUrl} from "../types/lnurl/LNURLPay";
+import {LNURLWithdraw, LNURLWithdrawParamsWithUrl} from "../types/lnurl/LNURLWithdraw";
+import {parseApiInput} from "./ApiParser";
+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 function toApiAmount(tokenAmount: TokenAmount): ApiAmount {
+    return {
+        amount: tokenAmount.amount,
+        rawAmount: tokenAmount.rawAmount != null ? tokenAmount.rawAmount.toString() : "0",
+        decimals: tokenAmount.token.decimals,
+        symbol: tokenAmount.token.ticker,
+        chain: tokenAmount.token.chainId
+    };
+}
+
+/**
+ * Converts a Token to the serializable ApiToken format
+ *
+ * @category API
+ */
+export function toApiToken(token: Token): ApiToken {
+    return {
+        id: `${token.chainId}-${token.ticker}`,
+        chainId: token.chainId,
+        ticker: token.ticker,
+        name: token.name,
+        decimals: token.decimals,
+        address: token.address
+    };
+}
+
+/**
+ * Converts LNURL data to the serializable API format
+ *
+ * @category API
+ */
+export function toApiLNURL(lnurl: LNURLPay | LNURLWithdraw, swapper: Swapper<any>): ApiLNURL {
+    if(lnurl.type === "pay") {
+        return {
+            type: "pay",
+            min: toApiAmount(toTokenAmount(lnurl.min, BitcoinTokens.BTCLN, swapper.prices)),
+            max: toApiAmount(toTokenAmount(lnurl.max, 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(toTokenAmount(lnurl.min, BitcoinTokens.BTCLN, swapper.prices)),
+        max: toApiAmount(toTokenAmount(lnurl.max, BitcoinTokens.BTCLN, swapper.prices)),
+        params: lnurl.params
+    };
+}
+
+/**
+ * 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; // Specifies nested object properties
+    /** Schema definition for array items when the field is an array. */
+    items?: T extends readonly (infer U)[] ? InputSchemaField<U> : never; // Specifies type of the array items
+    /** Enumerated allowed values for string, number, or bigint fields when constrained. */
+    allowedValues?: NonNullable<T> extends string | number | bigint ? NonNullable<T>[] : never; // An array of allowed values for a given field
+};
+
+/**
+ * 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 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> {
+    return {
+        type,
+        description,
+        callback,
+        inputSchema,
+        callbackRaw: (input, abortSignal?: AbortSignal) => {
+            return callback(parseApiInput(inputSchema, input), abortSignal);
+        }
+    }
+}

package/src/api/SerializedAction.ts

@@ -0,0 +1,97 @@
+import {
+    SwapExecutionAction,
+    SwapExecutionActionSendToAddress,
+    SwapExecutionActionSignPSBT,
+    SwapExecutionActionSignSmartChainTx,
+    SwapExecutionActionWait
+} from "../types/SwapExecutionAction";
+import {ApiAmount, toApiAmount} 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 async function serializeAction(
+    action: SwapExecutionAction,
+    txSerializer?: (chainId: string, tx: any) => Promise<string>
+): Promise<SerializedAction<SwapExecutionAction>> {
+    switch (action.type) {
+        case "SendToAddress": {
+            const {waitForTransactions, ...rest} = action as SwapExecutionActionSendToAddress<boolean>;
+            return {
+                ...rest,
+                txs: rest.txs.map(tx => ({
+                    type: tx.type,
+                    address: tx.address,
+                    hyperlink: tx.hyperlink,
+                    amount: toApiAmount(tx.amount)
+                }))
+            } as unknown as SerializedAction<SwapExecutionAction>;
+        }
+        case "SignPSBT": {
+            const {submitPsbt, txs, ...rest} = action as SwapExecutionActionSignPSBT<"FUNDED_PSBT" | "RAW_PSBT">;
+            return {
+                ...rest,
+                txs: txs.map(tx => {
+                    const {psbt, ...txRest} = tx;
+                    return txRest;
+                })
+            } as unknown as SerializedAction<SwapExecutionAction>;
+        }
+        case "SignSmartChainTransaction": {
+            const {submitTransactions, ...rest} = action as SwapExecutionActionSignSmartChainTx;
+            return {
+                ...rest,
+                txs: await Promise.all(rest.txs.map(tx =>
+                    txSerializer != null
+                        ? txSerializer(rest.chain, tx)
+                        : Promise.resolve(JSON.stringify(tx))
+                ))
+            } as unknown as SerializedAction<SwapExecutionAction>;
+        }
+        case "Wait": {
+            const {wait, ...rest} = action as SwapExecutionActionWait;
+            return rest as unknown as SerializedAction<SwapExecutionAction>;
+        }
+        default: {
+            const _exhaustive: never = action;
+            throw new Error(`Unknown action type: ${(_exhaustive as any).type}`);
+        }
+    }
+}