@fystack/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,611 @@
+import { AbstractSigner, Provider, TransactionResponse, TypedDataDomain, TypedDataField } from 'ethers';
+import { TransactionRequest } from 'ethers/src.ts/providers';
+
+declare class TransactionError extends Error {
+    readonly code: string;
+    readonly transactionId?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, code: string, transactionId?: string | undefined, originalError?: Error | undefined);
+}
+declare enum TxStatus {
+    Pending = "pending",
+    Completed = "completed",
+    Confirmed = "confirmed",
+    Failed = "failed",
+    PendingApproval = "pending_approval",
+    Rejected = "rejected"
+}
+declare enum TxApprovalStatus {
+    Pending = "pending",
+    Approved = "approved",
+    Rejected = "rejected"
+}
+interface APICredentials {
+    apiKey: string;
+    apiSecret: string;
+}
+interface WebhookEvent {
+    webhook_id: string;
+    resource_id: string;
+    url: string;
+    payload: any;
+    event: string;
+}
+interface SignRequestParams {
+    method: string;
+    message: string;
+    chain_id: number;
+    typed_data?: string;
+}
+interface SignResponse {
+    transaction_id: string;
+}
+interface SignatureStatusResponse {
+    status: TxStatus;
+    signature?: string;
+    transaction_id: string;
+    created_at: string;
+    updated_at: string;
+    approvals: Array<{
+        user_id: string;
+        status: TxApprovalStatus;
+    }>;
+}
+interface ApprovalInfo {
+    user_id: string;
+    status: TxApprovalStatus;
+}
+interface TransactionStatusResponse {
+    transaction_id: string;
+    status: TxStatus;
+    method: string;
+    hash?: string;
+    created_at: string;
+    updated_at: string;
+    approvals: ApprovalInfo[];
+    failed_reason?: string;
+}
+declare enum WalletType {
+    Standard = "standard",
+    MPC = "mpc"
+}
+interface CreateWalletOptions {
+    name: string;
+    walletType: WalletType;
+}
+declare enum WalletCreationStatus {
+    Pending = "pending",
+    Success = "success",
+    Error = "error"
+}
+interface CreateWalletResponse {
+    wallet_id: string;
+    status: WalletCreationStatus;
+}
+interface WalletCreationStatusResponse {
+    wallet_id: string;
+    status: WalletCreationStatus;
+}
+interface WalletAssetNetwork {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    name: string;
+    description?: string;
+    is_evm: boolean;
+    chain_id: number;
+    native_currency: string;
+    is_testnet?: boolean;
+    internal_code: string;
+    explorer_tx: string;
+    explorer_address: string;
+    explorer_token: string;
+    confirmation_blocks: number;
+    block_interval_in_seconds: number;
+    disabled: boolean;
+    logo_url: string;
+}
+interface WalletAssetDetail {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    logo_url: string;
+    is_native: boolean;
+    address_type: string;
+    is_whitelisted: boolean;
+    address?: string;
+    network_id: string;
+    network?: WalletAssetNetwork;
+}
+interface WalletAsset {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    wallet_id: string;
+    asset_id: string;
+    deposit_address: string;
+    hidden: boolean;
+    asset: WalletAssetDetail;
+}
+declare enum AddressType {
+    Evm = "evm",
+    Solana = "sol"
+}
+interface DepositAddressResponse {
+    asset_id?: string;
+    address: string;
+    qr_code: string;
+}
+
+declare enum Environment {
+    Local = "local",
+    Sandbox = "sandbox",
+    Production = "production"
+}
+interface APIEndpoints {
+    signTransaction: (walletId: string) => string;
+    requestSign: (walletId: string) => string;
+    getSignStatus: (walletId: string, transactionId: string) => string;
+    getTransactionStatus: (walletId: string, transactionId: string) => string;
+    getWalletDetail: (walletId?: string) => string;
+    createWallet: () => string;
+    createCheckout: () => string;
+    getCheckout: (checkoutId: string) => string;
+    createCheckoutPayment: (checkoutId: string) => string;
+    getCheckoutPayment: (checkoutId: string) => string;
+    getWalletCreationStatus: (walletId: string) => string;
+    getWalletAssets: (walletId: string) => string;
+    getDepositAddress: (walletId: string, addressType: string) => string;
+}
+interface APIConfig {
+    baseURL: string;
+    endpoints: APIEndpoints;
+}
+declare const createAPI: (env: Environment) => APIConfig;
+
+interface SDKOptions {
+    credentials: APICredentials;
+    environment?: Environment;
+    logger?: boolean;
+}
+declare class FystackSDK {
+    private apiService;
+    private enableLogging;
+    constructor(options: SDKOptions);
+    private log;
+    /**
+     * Creates a new wallet
+     * @param options Wallet creation options
+     * @param waitForCompletion Whether to wait for the wallet creation to complete
+     * @returns Promise with wallet ID and status
+     */
+    createWallet(options: CreateWalletOptions, waitForCompletion?: boolean): Promise<CreateWalletResponse>;
+    /**
+     * Gets the current status of a wallet creation process
+     * @param walletId The ID of the wallet being created
+     * @returns Promise with wallet creation status details
+     */
+    getWalletCreationStatus(walletId: string): Promise<WalletCreationStatusResponse>;
+    /**
+     * Waits for a wallet to be created and returns the final status
+     * @param walletId The ID of the wallet being created
+     * @returns Promise with wallet ID and final status
+     */
+    private waitForWalletCreation;
+    /**
+     * Gets assets associated with a wallet
+     * @param walletId The ID of the wallet
+     * @returns Promise with wallet assets
+     */
+    getWalletAssets(walletId: string): Promise<WalletAsset[]>;
+    /**
+     * Gets deposit address for a wallet by address type
+     * @param walletId The wallet ID
+     * @param addressType The type of address (evm, sol)
+     * @returns Promise with deposit address information
+     */
+    getDepositAddress(walletId: string, addressType: AddressType): Promise<DepositAddressResponse>;
+}
+
+interface StatusPollerOptions {
+    maxAttempts?: number;
+    interval?: number;
+    backoffFactor?: number;
+    maxInterval?: number;
+    timeoutMs?: number;
+}
+declare const DEFAULT_POLLER_OPTIONS: StatusPollerOptions;
+declare class StatusPoller {
+    private startTime;
+    private attempts;
+    private currentInterval;
+    private readonly options;
+    constructor(options?: StatusPollerOptions);
+    private wait;
+    private shouldContinue;
+    poll<T>(pollingFn: () => Promise<T>, successCondition: (result: T) => boolean, errorCondition?: (result: T) => boolean | void): Promise<T>;
+}
+
+declare class ApexSigner extends AbstractSigner {
+    private address;
+    private APICredentials;
+    private APIService;
+    private walletDetail;
+    private environment;
+    private pollerOptions?;
+    constructor(credentials: APICredentials, environment: Environment, provider?: null | Provider, pollerOptions?: StatusPollerOptions);
+    setWallet(walletId: string): void;
+    getAddress(): Promise<string>;
+    private getChainId;
+    connect(provider: null | Provider): ApexSigner;
+    private waitForSignature;
+    private waitForTransactonStatus;
+    signTransaction(tx: TransactionRequest): Promise<string>;
+    sendTransaction(tx: TransactionRequest): Promise<TransactionResponse>;
+    signMessage(message: string | Uint8Array): Promise<string>;
+    signTypedData(domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, value: Record<string, any>): Promise<string>;
+}
+
+declare class SolanaSigner {
+    private address;
+    private APIService;
+    private APIKey;
+    private walletDetail;
+    private pollerOptions?;
+    constructor(credentials: APICredentials, environment: Environment, pollerOptions?: StatusPollerOptions);
+    setWallet(walletId: string): void;
+    getAddress(): Promise<string>;
+    private waitForTransactionStatus;
+    /**
+     * Signs a Solana transaction
+     * @param transaction Base64 encoded serialized transaction
+     * @returns Signature as a base58 encoded string
+     */
+    signTransaction(transaction: string): Promise<string>;
+    /**
+     * Signs a Solana message
+     * @param message The message to sign (string or Uint8Array)
+     * @returns Signature as a base58 encoded string
+     */
+    signMessage(message: string | Uint8Array): Promise<string>;
+    /**
+     * Signs and sends a Solana transaction
+     * @param transaction Base64 encoded serialized transaction
+     * @returns Transaction signature
+     */
+    signAndSendTransaction(transaction: string): Promise<string>;
+    /**
+     * Signs multiple Solana transactions
+     * @param transactions Array of base64 encoded serialized transactions
+     * @returns Array of signatures as base58 encoded strings
+     */
+    signAllTransactions(transactions: string[]): Promise<{
+        transactions: string[];
+    }>;
+    private incorporateSignatureIntoTransaction;
+}
+
+interface Network {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    name: string;
+    description: string;
+    is_evm: boolean;
+    chain_id: number;
+    native_currency: string;
+    is_testnet: boolean;
+    internal_code: string;
+    explorer_tx: string;
+    explorer_address: string;
+    explorer_token: string;
+    confirmation_blocks: number;
+    block_interval_in_seconds: number;
+    disabled: boolean;
+    logo_url: string;
+}
+interface Asset {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    logo_url: string;
+    is_native: boolean;
+    address_type: 'evm';
+    is_whitelisted: boolean;
+    address?: string;
+    network_id: string;
+    network?: Network;
+}
+interface CreateCheckoutPayload {
+    price: string;
+    currency: string;
+    supported_assets: string[];
+    underpaid_cover_percent?: number;
+    description?: string;
+    success_url?: string;
+    cancel_url?: string;
+    product_id?: string;
+    customer_id?: string;
+    order_id?: string;
+    enable_localization?: boolean;
+    destination_wallet_id: string;
+    from_address?: string;
+    expiry_duration_seconds: number;
+}
+/**
+ * Represents the payload required to create a checkout payment.
+ */
+interface CreateCheckoutPaymentPayload {
+    /**
+     * Customer's email address.
+     *
+     * - This field is **optional**.
+     * - If provided, it must be a valid email format.
+     */
+    customer_email?: string;
+    /**
+     * Unique identifier of the asset used for payment.
+     *
+     * - This field is **required**.
+     * - Must be a **UUIDv4**.
+     */
+    pay_asset_id: string;
+}
+interface CreateCheckoutResponse {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    currency: string;
+    product_id: string;
+    order_id: string;
+    workspace_id: string;
+    underpaid_cover_percent: number;
+    description: string;
+    price: string;
+    supported_assets: Array<{
+        id: string;
+        created_at: string;
+        updated_at: string;
+        is_native: boolean;
+        is_whitelisted: boolean;
+    }>;
+    customer_id: string;
+    expiry_duration_seconds: number;
+    enable_localization: boolean;
+    success_url: string;
+    cancel_url: string;
+    status: string;
+    outcome: any;
+    from_address: string;
+}
+declare enum PaymentStatus {
+    Pending = "Pending",
+    Confirming = "Confirming",
+    Success = "Success"
+}
+interface SupportedAsset {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    logo_url: string;
+    is_native: boolean;
+    address_type: 'evm';
+    is_whitelisted: boolean;
+    address?: string;
+    network_id: string;
+    network: {
+        id: string;
+        created_at: string;
+        updated_at: string;
+        name: string;
+        description: string;
+        is_evm: boolean;
+        chain_id: number;
+        native_currency: string;
+        is_testnet: boolean;
+        internal_code: string;
+        explorer_tx: string;
+        explorer_address: string;
+        explorer_token: string;
+        confirmation_blocks: number;
+        block_interval_in_seconds: number;
+        disabled: boolean;
+        logo_url: string;
+    };
+}
+interface GetCheckoutResponse {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    currency: string;
+    product_id: string;
+    order_id: string;
+    workspace_id: string;
+    underpaid_cover_percent: number;
+    description: string;
+    price: string;
+    supported_assets: SupportedAsset[];
+    customer_id: string;
+    expiry_duration_seconds: number;
+    enable_localization: boolean;
+    success_url: string;
+    cancel_url: string;
+    status: PaymentStatus;
+    outcome?: string | null;
+    from_address: string;
+}
+/**
+ * Represents the response structure for a checkout payment.
+ */
+interface CreateCheckoutPaymentResponse {
+    /**
+     * Unique identifier of the payment.
+     */
+    id: string;
+    /**
+     * Timestamp when the payment was created (ISO 8601 format).
+     */
+    created_at: string;
+    /**
+     * Timestamp when the payment was last updated (ISO 8601 format).
+     */
+    updated_at: string;
+    /**
+     * Unique identifier of the associated checkout.
+     */
+    checkout_id: string;
+    /**
+     * Details of the associated checkout (if available).
+     * Can be `null` if no data is linked.
+     */
+    checkout: any | null;
+    /**
+     * Customer's email address (if provided).
+     * Can be `null` if not available.
+     */
+    customer_email: string | null;
+    /**
+     * Unique identifier of the asset used for payment.
+     */
+    pay_asset_id: string;
+    /**
+     * Unique identifier of the blockchain network used for the transaction.
+     */
+    network_id: string;
+    /**
+     * Details of the associated blockchain network (if available).
+     * Can be `null` if no data is linked.
+     */
+    network: any | null;
+    /**
+     * Timestamp when the payment expires (ISO 8601 format).
+     */
+    expired_at: string;
+    /**
+     * Blockchain address of the payer (if available).
+     * Can be `null` if not yet provided.
+     */
+    payer_address: string | null;
+    /**
+     * Hash of the blockchain transaction (if completed).
+     * Can be `null` if the transaction has not been broadcasted yet.
+     */
+    tx_hash: string | null;
+    /**
+     * The amount of cryptocurrency required for the payment,
+     * converted to the selected payment asset.
+     */
+    converted_crypto_price: string;
+    /**
+     * The blockchain address where the customer should send the payment.
+     */
+    deposit_address: string;
+    /**
+     * QR code (as a string) representing the deposit address for easy payment.
+     * Could be an empty string if not generated.
+     */
+    deposit_qr: string;
+}
+interface GetCheckoutPaymentResponse {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    checkout_id: string;
+    checkout: GetCheckoutResponse;
+    customer_email?: string | null;
+    pay_asset_id: string;
+    pay_asset: Asset;
+    network_id: string;
+    network: Network;
+    expired_at: string;
+    payer_address?: string | null;
+    tx_hash?: string | null;
+    converted_crypto_price: string;
+    deposit_address: string;
+    deposit_qr: string;
+}
+
+interface APIResponse {
+    data: any;
+    success: boolean;
+    message?: string;
+}
+interface HMACParams {
+    method: string;
+    path: string;
+    timestamp: string;
+    body?: string;
+}
+interface WalletDetail {
+    APIKey: string;
+    WalletID: string;
+    Name: string;
+    AddressType: string;
+    Address: string;
+}
+interface CreateWalletPayload {
+    name: string;
+    walletType: WalletType;
+}
+interface PaymentServiceParams {
+    apiKey: string;
+    environment: Environment;
+}
+declare enum WalletAddressType {
+    Evm = "evm",
+    Sol = "sol"
+}
+declare class APIService {
+    private credentials;
+    Webhook: WebhookService;
+    private API;
+    constructor(credentials: APICredentials, environment: Environment);
+    getWalletDetail(addressType?: WalletAddressType, walletId?: string): Promise<WalletDetail>;
+    requestSign(walletId: string, params: SignRequestParams): Promise<SignResponse>;
+    getSignStatus(walletId: string, transactionId: string): Promise<SignatureStatusResponse>;
+    signTransaction(walletId: string, body: Record<string, any>): Promise<SignResponse>;
+    getTransactionStatus(walletId: string, transactionId: string): Promise<TransactionStatusResponse>;
+    createWallet(payload: CreateWalletPayload): Promise<CreateWalletResponse>;
+    createCheckout(payload: CreateCheckoutPayload): Promise<CreateCheckoutResponse>;
+    getWalletCreationStatus(walletId: string): Promise<WalletCreationStatusResponse>;
+    getWalletAssets(walletId: string): Promise<WalletAsset[]>;
+    /**
+     * Gets deposit address for a wallet by address type
+     * @param walletId The wallet ID
+     * @param addressType The type of address (evm, sol)
+     * @returns Deposit address response
+     */
+    getDepositAddress(walletId: string, addressType: AddressType): Promise<DepositAddressResponse>;
+}
+declare class PaymentService {
+    private apiKey;
+    private API;
+    constructor(params: PaymentServiceParams);
+    createCheckout(payload: CreateCheckoutPayload): Promise<CreateCheckoutResponse>;
+    getCheckout(checkoutId: string): Promise<GetCheckoutResponse>;
+    createCheckoutPayment(checkoutId: string, payload: CreateCheckoutPaymentPayload): Promise<CreateCheckoutPaymentResponse>;
+    getCheckoutPayment(checkoutId: string): Promise<GetCheckoutPaymentResponse>;
+}
+declare class WebhookService {
+    private credentials;
+    constructor(credentials: APICredentials);
+    verifyEvent(event: WebhookEvent, signature: string): Promise<boolean>;
+}
+declare function get(endpoint: string, headers?: Record<string, string>): Promise<APIResponse>;
+declare function post(endpoint: string, body: any, headers?: Record<string, string>): Promise<APIResponse>;
+declare function transformWalletDetail(data: Record<string, string>): WalletDetail;
+declare function transformCreateWalletPayload(data: CreateWalletPayload): {
+    name: string;
+    wallet_type: WalletType;
+};
+
+export { type APIConfig, type APICredentials, type APIEndpoints, APIService, AddressType, ApexSigner, type ApprovalInfo, type CreateWalletOptions, type CreateWalletPayload, type CreateWalletResponse, DEFAULT_POLLER_OPTIONS, type DepositAddressResponse, Environment, FystackSDK, type HMACParams, PaymentService, type PaymentServiceParams, type SDKOptions, type SignRequestParams, type SignResponse, type SignatureStatusResponse, SolanaSigner, StatusPoller, type StatusPollerOptions, TransactionError, type TransactionStatusResponse, TxApprovalStatus, TxStatus, WalletAddressType, type WalletAsset, type WalletAssetDetail, type WalletAssetNetwork, WalletCreationStatus, type WalletCreationStatusResponse, type WalletDetail, WalletType, type WebhookEvent, WebhookService, createAPI, get, post, transformCreateWalletPayload, transformWalletDetail };