xplore-sdk

JavaScript/TypeScript SDK for interacting with the Xplore Aggregator service for cross-chain operations in browser environments.

Installation

npm install xplore-sdk

or

yarn add xplore-sdk

Features

• Type-safe client for the Xplore Aggregator gRPC-Web service
• Support for cross-chain token operations in browsers
• Comprehensive error handling
• Promise-based API
• TypeScript support
• Automatic environment detection for browser and Node.js compatibility

Environment Adaptability

The SDK intelligently identifies its execution context (browser or Node.js) and optimizes its behavior accordingly:

• When running in web applications (React, Next.js, etc.), it leverages the standard gRPC-Web transport
• When operating in Node.js environments, it automatically utilizes NodeHttpTransport when available

This smart adaptation eliminates the common "Dynamic require of http is not supported" error that typically occurs in browser-based applications like Next.js.

Usage

Basic Usage

import { AggregatorClient } from 'xplore-sdk';

// Create a client instance
const client = new AggregatorClient({
  endpoint: 'https://xplore.blinq.fi',
  timeoutMs: 30000,
});

// Make an aggregation call
async function makeAggregateCall() {
  try {
    const response = await client.aggregateCall({
      inputToken: {
        chainId: 'ethereum',
        address: '0x1234...',
        isNative: false,
      },
      outputToken: {
        chainId: 'solana',
        address: 'So11111...',
        isNative: true,
      },
      amountIn: '1000000000000000000', // 1 ETH in wei
      amountOutMin: '0',
      slippageTolerance: 1,
      recipientAddress: 'recipient-address',
      senderAddress: 'sender-address',
      exactOut: false,
      timeoutMs: 30000,
      generateDepositAddress: false,
    });

    // Summarize key fields including new fees
    console.log('Aggregate call response:', {
      amountIn: response.amountIn,
      amountOut: response.amountOut,
      amountInWithFee: response.amountInWithFee,
      protocolFee: response.protocolFee,
      bridgeFee: response.bridgeFee,
      depositAddress: response.depositAddress,
    });

    // Optional: inspect route steps for node type
    response.routes?.forEach((step, i) => {
      console.log(`step #${i + 1}:`, {
        nodeId: step.nodeId,
        nodeType: step.nodeType, // enum value from server
        amountIn: step.amountIn,
        amountOut: step.amountOut,
      });
    });
    return response;
  } catch (error) {
    console.error('Error making aggregate call:', error);
    throw error;
  }
}

Getting Transaction Records

import { AggregatorClient } from 'xplore-sdk';

const client = new AggregatorClient({
  endpoint: 'https://xplore.blinq.fi',
  timeoutMs: 30000,
});

async function getTransaction(txHash: string) {
  try {
    const record = await client.getTransactionRecord(txHash);
    console.log('Transaction record:', record);
    return record;
  } catch (error) {
    console.error('Error getting transaction record:', error);
    throw error;
  }
}

API Reference

AggregatorClient

The main client for interacting with the Xplore Aggregator service in browser environments.

Constructor

constructor(config: AggregatorClientConfig)

AggregatorClientConfig

| Property | Type | Required | Description | | ------------- | -------------------------- | -------- | ----------------------------------------------- | | endpoint | string | Yes | The gRPC-Web endpoint to connect to | | timeoutMs | number | No | Timeout in milliseconds for calls | | credentials | { [index: string]: string }| No | Credentials to include with each request | | options | { [index: string]: any } | No | Additional options for the client |

Methods

aggregateCall

async aggregateCall(params: AggregateCallParams): Promise<XploreResponse>

Makes an aggregate call to the service for cross-chain operations.

getTransactionRecord

async getTransactionRecord(txHash: string): Promise<TransactionRecord>

Retrieves a transaction record by its hash.

Error Handling

The SDK provides enhanced error handling with the GrpcError class:

import { AggregatorClient, GrpcError } from 'xplore-sdk';

const client = new AggregatorClient({
  endpoint: 'https://your-endpoint.example.com',
});

try {
  const response = await client.aggregateCall(/* ... */);
} catch (error) {
  if (error instanceof GrpcError) {
    console.error(`gRPC error: [${error.code}] ${error.message}`);
    // Handle specific error codes
    switch (error.code) {
      case 4: // DEADLINE_EXCEEDED
        console.error('Operation timed out');
        break;
      case 14: // UNAVAILABLE
        console.error('Service unavailable');
        break;
      // Handle other error codes...
    }
  } else {
    console.error('Unknown error:', error);
  }
}

Development

Prerequisites

• Node.js 18.x or higher
• npm, pnpm, or yarn

Setup

1. Clone the repository

   git clone https://github.com/blinq-fi/xplore-sdk.git
   cd xplore-sdk

2. Install dependencies

   npm install   # Using npm
   # or: pnpm install   # Using pnpm

3. Build the SDK

   npm run build   # Using npm
   # or: pnpm run build   # Using pnpm

License

This project is licensed under the MIT License - see the LICENSE file for details.