@heliofi/sdk v1.0.3-alpha.0

Helio SDK

Introduction

The Helio SDK is a packaged module to make integrating Helio and our components as easy and as quickly as possible into your front end web site or store so you can start accepting Helio web3 payments.

It wraps and enhances the Helio API away into one NPM package which is easy to install and upgrade.

The Helio SDK is written in Typescript.

Please use the latest production version. Only used ALPHA versions if advised to do so.

Solana is currently supported with Polygon and ETH following soon.

Installation

yarn add @heliofi/sdk

After installing the SDK please import this into your project:

import { Helio } from "@heliofi/sdk";

Helio SDK Services

Detailed below are the methods used via the SDK to interact with the Helio API

Please ensure you select the correct 'Cluster' or network during deployment.

Properties table for the HelioSDK

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

Methods

Properties table for the CurrencyService

import { BlockchainSymbol, Currency, CurrencyType } from '@heliofi/common';

Properties table for the DefaultCurrencyService

Properties table for the SolAvailableBalanceService

import { Connection, PublicKey } from '@solana/web3.js';

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the EthereumAvailableBalanceService

type EVMPublicKey = `0x${string}`;

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the PolygonAvailableBalanceService

type EVMPublicKey = `0x${string}`;

interface AvailableBalance {
    tokenSymbol: string;
    value: number;
}

Properties table for the AvailableBalanceService

import { Connection, PublicKey } from '@solana/web3.js';
import { BlockchainSymbol, Currency } from '@heliofi/common';

type EVMPublicKey = `0x${string}`;

interface TokenSwapQuote {
    paymentRequestId: string;
    routeTokenString: string;
    from: Currency;
    to: Currency;
    slippageBps: number;
    priceImpactPct: number;
    inAmount: number;
    outAmount: number;
    amount: number;
}

interface AvailableBalanceServiceProps {
    publicKey?: PublicKey;
    connection?: Connection;
    evmPublicKey?: EVMPublicKey;
    decimalAmount: number;
    currency?: string;
    canSwapTokens?: boolean;
    swapCurrency?: string;
    quantity?: number;
    tokenSwapQuote?: TokenSwapQuote;
    blockchain?: BlockchainSymbol;
    areCurrenciesDefined: boolean;
}

Properties table for the EthereumExplorerService

Properties table for the PolygonExplorerService

Properties table for the HelioApiAdapter

import {
    FetchifyFindAddress,
    PaymentRequest,
    PaymentRequestType,
    FetchifyRetrieveAddress,
    Currency,
    PrepareTransaction,
    PrepareSwapTransaction,
    TokenQuoting,
    SwapRouteToken,
    PaymentRequestType,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';

Properties table for the SolExplorerService

Properties table for the TokenConversionService

import { BlockchainSymbol, Currency } from '@heliofi/common';

Properties table for the PaylinkSubmitService

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';
import {
    OnlyContentAndSwapTransactionPaylink,
    OnlyContentAndTransactionPaylink,
    CustomerDetails,
    SplitWallet,
} from '@heliofi/common';

type ApproveTransactionResponse = OnlyContentAndTransactionPaylink | OnlyContentAndSwapTransactionPaylink;

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

interface BasePaymentProps<ApproveTransactionResponse> {
    onSuccess: (event: SuccessPaymentEvent<ApproveTransactionResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CreatePaymentProps
    extends BasePaymentProps<ApproveTransactionResponse> {
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    customerDetails?: CustomerDetails;
    quantity?: number;
    productDetails?: {
        name?: string;
        value?: string;
    };
    splitRevenue?: boolean;
    splitWallets?: SplitWallet[];
    wallet: AnchorWallet;
    connection: Connection;
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    rateToken?: string;
}

Properties table for the PolygonPaylinkSubmitService, EthPaylinkSubmitService

import {
    BlockchainSymbol,
    CustomerDetails,
    ProductDetails,
    SplitWallet,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';
import { Web3Provider } from '@ethersproject/providers';

enum LoadingModalStep {
    GET_PERMISSION = 'GET_PERMISSION',
    SIGN_TRANSACTION = 'SIGN_TRANSACTION',
    SUBMIT_TRANSACTION = 'SUBMIT_TRANSACTION',
    DEFAULT = 'DEFAULT',
    CLOSE = 'CLOSE',
}

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

ApproveTransactionResponse = OnlyContentAndTransactionPaylink;

interface SuccessPaymentEvent<ApproveTransactionResponse> extends PaymentEvent {
    data: ApproveTransactionResponse;
    transaction: string;
    paymentPK?: string;
    swapTransactionSignature?: string;
}

interface BasePaymentProps<ApproveTransactionResponse> {
    onSuccess: (event: SuccessPaymentEvent<ApproveTransactionResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    onInitiated?: (event: PaymentEvent) => void;
    setLoadingModalStep: (step: LoadingModalStep) => void;
    onCancel?: () => void;
    symbol: string;
    blockchain?: BlockchainSymbol;
    anchorProvider: Web3Provider;
    rateToken?: string;
    customerDetails?: CustomerDetails;
    productDetails?: ProductDetails;
    mintAddress: string;
    isNativeMintAddress: boolean;
    cluster: ClusterHelioType;
}

interface CreatePaymentProps
    extends BasePaymentProps<ApproveTransactionResponse> {
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    quantity?: number;
    splitRevenue?: boolean;
    splitWallets?: SplitWallet[];
    discountToken?: string;
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    rateToken?: string;
}

Properties table for the PaystreamStartService

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';
import {
    CustomerDetails,
    OnlyContentAndTransactionPaylink,
} from '@heliofi/common';

interface PaymentEvent {
    transaction?: string;
}

interface ErrorPaymentEvent extends PaymentEvent {
    errorMessage: string;
}

interface PendingPaymentEvent extends PaymentEvent {
    transaction: string;
}

interface CreatePaystreamResponse extends OnlyContentAndTransactionPaylink {} {
    document: {
        id: string;
        startedAt: bigint;
        endedAt: bigint;
    };
}

interface BasePaymentProps<CreatePaystreamResponse> {
    onSuccess: (event: SuccessPaymentEvent<CreatePaystreamResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CreatePaystreamProps
    extends BasePaymentProps<CreatePaystreamResponse> {
    interval: number;
    maxTime: number;
    recipientPK: string;
    amount: bigint;
    paymentRequestId: string;
    customerDetails?: CustomerDetails;
    quantity?: number;
    rateToken?: string;
    productDetails?: {
        name?: string;
        value?: string;
    };
    canSwapTokens?: boolean;
    swapRouteToken?: string;
    swapSignedTx?: string;
}

Properties table for the PaystreamCancelService

import { Program } from "@project-serum/anchor";
import { AnchorWallet } from "@solana/wallet-adapter-react";
import { Cluster, Connection } from "@solana/web3.js";
import { HelioIdl } from '@heliofi/solana-adapter';

interface BasePaymentProps<CancelStreamResponse> {
    onSuccess: (event: SuccessPaymentEvent<CancelStreamResponse>) => void;
    onError: (event: ErrorPaymentEvent) => void;
    onPending?: (event: PendingPaymentEvent) => void;
    symbol: string;
    anchorProvider: Program<HelioIdl>;
    wallet: AnchorWallet;
    connection: Connection;
    rateToken?: string;
}

interface CancelStreamResponse extends OnlyContentAndTransactionPaylink {}

interface CancelStreamProps extends BasePaymentProps<CancelStreamResponse> {
    paymentId: string;
}

Properties table for the ConfigService

import { PaymentRequestType } from '@heliofi/common';

type ClusterHelioType = 'devnet' | 'testnet' | 'mainnet';

Example

import { HelioSDK, ClusterHelio } from '@heliofi/sdk';
import { Cluster } from '@solana/web3.js';

const cluster = ClusterHelio.Devnet;

//create object HelioSDK
const helioSDK = new HelioSDK({ cluster });

//get curriences
const currencies = helioSDK.currencyService.getCurrencies();

//get helio asset url
const url = helioSDK.configService.getAssetUrl();

//get mint addresses list
const mintAddresses = await helioSDK.apiService.getTokenSwapMintAddresses('mint address');

//get transaction url
const transactionUrl = helioSDK.solExplorerService.getSolanaExplorerTransactionURL('transaction');

//convert to minimal amount
const amount = helioSDK.tokenConversionService.convertToMinimalUnits('symbol', 100);

//handle transaction paylink for sol blockchain
await helioSDK.paylinkService.handleTransaction({...});

//handle transaction paystream for sol blockchain
await helioSDK.paystreamStartService.handleTransaction({...});

//handle cancel transaction paystream for sol blockchain
await helioSDK.paystreamCancelService.handleTransaction({...});

//handle transaction for evm(polygon, ethereum) blockchain
await helioSDK.polygonPaylinkService.handleTransaction({...});
await helioSDK.ethPaylinkService.handleTransaction({...});