@stellar-broker/client 0.4.1 → 0.6.0

package/src/errors.js

@@ -1,54 +1,56 @@
-export class StellarBrokerError extends Error {
-    constructor(code, message) {
-        super(message)
-        this.code = code
-    }
-
-    /**
-     * Numeric error code
-     * @type {number}
-     * @readonly
-     */
-    code = 0
-}
-
-const errors = {
-    invalidInitParam(param) {
-        return new StellarBrokerError(1, `Invalid parameter value: "${param}"`)
-    },
-    invalidAuthorizationParam() {
-        return new StellarBrokerError(2, 'Invalid authorization secret key or callback provided')
-    },
-    notConnected() {
-        return new StellarBrokerError(3, 'Client not connected to the server')
-    },
-    quoteNotSet() {
-        return new StellarBrokerError(11, 'Price quote not available')
-    },
-    quoteExpired() {
-        return new StellarBrokerError(12, 'Price quote expired')
-    },
-    quoteError(message) {
-        return new StellarBrokerError(13, 'Price quotation error: ' + message)
-    },
-    invalidQuoteParam(invalidParamName = 'asset', details) {
-        return new StellarBrokerError(14, `Invalid quote request parameter: "${invalidParamName}". ${details}`)
-    },
-    tradeInProgress() {
-        return new StellarBrokerError(20, 'Cannot change quote while trade is in progress')
-    },
-    invalidSwapTx() {
-        return new StellarBrokerError(21, 'Invalid swap transaction received from the server')
-    },
-    failedToSignTx() {
-        return new StellarBrokerError(22, 'Failed to sign received transaction')
-    },
-    unsupportedEventType(type) {
-        return new StellarBrokerError(31, 'Unknown event type: ' + type)
-    },
-    serverError(message) {
-        return new StellarBrokerError(101, message)
-    }
-}
-
+export class StellarBrokerError extends Error {
+    constructor(code, message) {
+        super(message)
+        this.code = code
+    }
+
+    /**
+     * Numeric error code
+     * @type {number}
+     * @readonly
+     */
+    code = 0
+}
+
+const errors = {
+    invalidInitParam(param) {
+        return new StellarBrokerError(1, `Invalid parameter value: "${param}"`)
+    },
+    invalidAuthorizationParam() {
+        return new StellarBrokerError(2, 'Invalid authorization secret key or callback provided')
+    },
+    notConnected() {
+        return new StellarBrokerError(3, 'Client not connected to the server')
+    },
+    quoteNotSet() {
+        return new StellarBrokerError(11, 'Price quote not available')
+    },
+    quoteExpired() {
+        return new StellarBrokerError(12, 'Price quote expired')
+    },
+    quoteError(message) {
+        return new StellarBrokerError(13, 'Price quotation error: ' + message)
+    },
+    invalidQuoteParam(invalidParamName = 'asset', details) {
+        return new StellarBrokerError(14, `Invalid quote request parameter: "${invalidParamName}". ${details}`)
+    },
+    tradeInProgress() {
+        return new StellarBrokerError(20, 'Cannot change quote while trade is in progress')
+    },
+    invalidSwapTx() {
+        return new StellarBrokerError(21, 'Invalid swap transaction received from the server')
+    },
+    failedToSignTx() {
+        return new StellarBrokerError(22, 'Failed to sign received transaction')
+    },
+    unsupportedEventType(type) {
+        return new StellarBrokerError(31, 'Unknown event type: ' + type)
+    },
+
+
+    serverError(message) {
+        return new StellarBrokerError(101, message)
+    }
+}
+
 export default errors

package/src/estimate.js

@@ -1,10 +1,11 @@
 import errors, {StellarBrokerError} from './errors.js'
 import {validateQuoteRequest} from './quote-request.js'
+import {QuoteResult} from './quote-result.js'
 
 /**
  * Request single swap quote estimate without trading
- * @param {SwapQuoteParams} params
- * @return {Promise<SwapQuoteResult>}
+ * @param {QuoteParams} params
+ * @return {Promise<QuoteResult>}
  */
 export async function estimateSwap(params) {
     const query = Object.entries(validateQuoteRequest(params))
@@ -15,7 +16,7 @@ export async function estimateSwap(params) {
         const res = await fetch(url).then(r => r.json())
         if (res.status !== 'success')
             throw errors.quoteError(res.error || 'Quote not available')
-        return res
+        return new QuoteResult(res)
     } catch (e) {
         if (e instanceof StellarBrokerError)
             throw e

package/src/index.d.ts

@@ -1,6 +1,9 @@
-import {FeeBumpTransaction} from "@stellar/stellar-sdk";
+import {Asset, TransactionI} from "@stellar/stellar-sdk";
 
-export default class StellarBrokerClient {
+/**
+ * Client for StellarBroker service
+ */
+export class StellarBrokerClient {
     /**
      * @param {ClientInitializationParams} params
      */
@@ -10,16 +13,16 @@ export default class StellarBrokerClient {
      * Trader account public key
      * @type {string}
      */
-    readonly source: string;
+    readonly trader: string;
     /**
      * Stellar network passphrase
      * @type {string}
      */
     readonly network: string;
     /**
-     * @type {ClientStatus}
+     * @type {ClientSessionStatus}
      */
-    readonly status: ClientStatus;
+    readonly status: ClientSessionStatus;
 
     /**
      * Connect to the StellarBroker server
@@ -29,9 +32,9 @@ export default class StellarBrokerClient {
 
     /**
      * Request swap quote
-     * @param {SwapQuoteParams} params - Quote parameters
+     * @param {QuoteParams} params - Quote parameters
      */
-    quote(params: SwapQuoteParams): void;
+    quote(params: QuoteParams): void;
 
     /**
      * Stop quotation/trading
@@ -40,10 +43,8 @@ export default class StellarBrokerClient {
 
     /**
      * Confirm current quote and start trading
-     * @param {string} account - Trader account address
-     * @param {string|ClientAuthorizationCallback} authorization - Authorization method, either account secret key or an authorization callback
      */
-    confirmQuote(account: string, authorization: string | ClientAuthorizationCallback): void;
+    confirmQuote(): void;
 
     /**
      * Add event listener
@@ -75,9 +76,12 @@ export default class StellarBrokerClient {
 /**
  * Request single swap quote estimate without trading
  */
-export function estimateSwap(params: SwapQuoteParams): Promise<SwapQuoteResult>;
+export function estimateSwap(params: QuoteParams): Promise<QuoteResult>;
 
-export interface SwapQuoteParams {
+/**
+ * Quote request parameters provided by the client
+ */
+export interface QuoteParams {
     /**
      * Asset to sell
      */
@@ -91,53 +95,102 @@ export interface SwapQuoteParams {
      */
     sellingAmount?: string
     /**
-     * Amount of buying asset
-     */
-    buyingAmount?: string
-    /**
-     * Swap slippage tolerance (2% by default)
+     * Swap slippage tolerance (0.02 by default - 2%)
      */
     slippageTolerance?: number
 }
 
-
 export interface ClientInitializationParams {
     /**
-     * Partner key
+     * Trader account address
      */
-    partnerKey?: string;
+    account: string;
     /**
-     * Swap flow mode
+     * Partner key
      */
-    flow?: SwapFlowMode;
+    partnerKey?: string;
     /**
-     * Stellar network identifier or passphrase (pubnet by default)
+     * Authorization method, either account secret key or an authorization callback
      */
-    network?: string;
+    authorization: ClientAuthorizationParams;
 }
 
-export type ClientStatus = "disconnected" | "ready" | "quote" | "trade";
+/**
+ * Current client session status
+ */
+export type ClientSessionStatus = "disconnected" | "ready" | "quote" | "trade";
 
-export type StellarBrokerClientEvent = "quote" | "finished" | "progress" | "error";
+/**
+ * Event type generated by the client
+ */
+export type StellarBrokerClientEvent = "quote" | "progress" | "paused" | "finished" | "error";
 
-export type SwapFlowMode = "direct";
+/**
+ * Result status code returned by the server
+ */
+export type QuoteResultStatus = "unfeasible" | "rejected" | "success";
 
-export interface SwapQuoteResult {
-    sellingAsset: string;
-    buyingAsset: string;
-    slippageTolerance: number;
-    destination: string;
-    ledger: number;
-    sellingAmount?: string;
-    estimatedBuyingAmount?: string;
-    buyingAmount?: string;
-    estimatedSellingAmount?: string;
-    directTrade?: SwapQuoteDirectTradeResult;
+/**
+ * Quote received from the server
+ */
+export interface QuoteResult {
+    /**
+     * Quote timestamp
+     */
+    readonly ts: Date,
+    /**
+     * Quote status code
+     */
+    readonly status: QuoteResultStatus;
+    /**
+     * Asset to sell
+     */
+    readonly sellingAsset: string;
+    /**
+     * Asset to buy
+     */
+    readonly buyingAsset: string;
+    /**
+     * Swap slippage tolerance
+     */
+    readonly slippageTolerance: number;
+    /**
+     * Amount of the selling asset
+     */
+    readonly sellingAmount: string;
+    /**
+     * Estimated amount of buyingAsset to receive
+     */
+    readonly estimatedBuyingAmount?: string;
+    /**
+     * Equivalent direct path_payment trade estimate
+     */
+    readonly directTrade?: QuoteDirectTradeResult;
+    /**
+     * Difference between quoted price and estimated direct trade
+     */
+    readonly profit: string;
+    /**
+     * Error details from the server (for failed quotes)
+     */
+    readonly error?: string;
 }
 
-export interface SwapQuoteDirectTradeResult {
+/**
+ * Emulated single `path_payment` trades result corresponding to the quote
+ */
+export interface QuoteDirectTradeResult {
+    /**
+     * Estimated amount to sell
+     */
     selling: string;
+    /**
+     * Estimated amount to buy
+     */
     buying: string;
+    /**
+     * Conversion path
+     */
     path: string[];
 }
 
@@ -150,4 +203,57 @@ export class StellarBrokerError extends Error {
     readonly code: number;
 }
 
-export type ClientAuthorizationCallback = (arg0: FeeBumpTransaction) => Promise<FeeBumpTransaction>;
+/**
+ * Async authorization callback for transactions and simulated auth entries
+ */
+export type ClientAuthorizationCallback = (txOrAuthEntry: TransactionI | Buffer) => Promise<TransactionI | Buffer>;
+
+/**
+ * Authorization method, either account secret key or an authorization callback
+ */
+export type ClientAuthorizationParams = string | ClientAuthorizationCallback;
+
+/**
+ * Trader mediator account wrapper
+ */
+export class Mediator {
+    /**
+     * Create a trader mediator account instance for a given source account
+     * @param source - Source account
+     * @param sellingAsset - Asset to sell
+     * @param buyingAsset - Asset to buy
+     * @param sellingAmount - Amount to sell
+     * @param authorization - Authorization callback or secret key
+     */
+    constructor(source: string, sellingAsset: string | Asset, buyingAsset: string | Asset, sellingAmount: string, authorization: ClientAuthorizationParams)
+
+    readonly source: string;
+
+    readonly sellingAsset: Asset;
+
+    readonly buyingAsset: Asset;
+
+    readonly sellingAmount: bigint;
+
+    readonly mediatorAddress: string;
+
+    /**
+     * Check if there are any non-disposed mediators that belong to lost swap sessions
+     */
+    get hasObsoleteMediators(): boolean;
+
+    /**
+     * Retrieve funds from mediator accounts that belong to lost swap sessions
+     */
+    disposeObsoleteMediators(): Promise<void>;
+
+    /**
+     * Create mediator account and deposit tokens to sell
+     */
+    init(): Promise<string>;
+
+    /**
+     * Dispose mediator account
+     */
+    dispose(address: string): Promise<void>;
+}

package/src/index.js

@@ -1,4 +1,5 @@
-import StellarBrokerClient from './client.js'
-export * from './estimate.js'
-
-export default StellarBrokerClient
+import {StellarBrokerClient} from './client.js'
+export * from './estimate.js'
+export * from './mediator.js'
+
+export {StellarBrokerClient}