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,
    });

    console.log('Aggregate call response:', response);
    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.