@stellar/typescript-wallet-sdk 1.2.0 → 1.3.0

package/src/walletSdk/Anchor/Sep6.ts

@@ -0,0 +1,291 @@
+import { AxiosInstance } from "axios";
+import queryString from "query-string";
+
+import { Anchor } from "../Anchor";
+import {
+  ServerRequestFailedError,
+  MissingTransactionIdError,
+} from "../Exceptions";
+import {
+  Sep6Info,
+  Sep6Params,
+  Sep6DepositParams,
+  Sep6WithdrawParams,
+  Sep6DepositResponse,
+  Sep6WithdrawResponse,
+  Sep6ExchangeParams,
+  Sep6Transaction,
+  GetTransactionParams,
+  GetTransactionsParams,
+  WatcherSepType,
+  AuthToken,
+} from "../Types";
+import {
+  Watcher,
+  _getTransactionsForAsset,
+  _getTransactionBy,
+} from "../Watcher";
+import { camelToSnakeCaseObject } from "../Utils";
+
+/**
+ * Flow for creating deposits and withdrawals with an anchor using SEP-6.
+ * For an interactive flow use Sep24 instead.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md}
+ * Do not create this object directly, use the Anchor class.
+ * @class
+ */
+export class Sep6 {
+  private anchor: Anchor;
+  private httpClient: AxiosInstance;
+  private anchorInfo: Sep6Info;
+
+  /**
+   * Creates a new instance of the Sep6 class.
+   * @constructor
+   * @param {Sep6Params} params - Parameters to initialize the Sep6 instance.
+   */
+  constructor(params: Sep6Params) {
+    const { anchor, httpClient } = params;
+
+    this.anchor = anchor;
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Get SEP-6 anchor information.
+   * If `shouldRefresh` is set to `true`, it fetches fresh values; otherwise, it returns cached values if available.
+   * @param {boolean} [shouldRefresh=false] - Flag to force a refresh of TOML values.
+   * @returns {Promise<Sep6Info>} - SEP-6 information about the anchor.
+   */
+  async info(shouldRefresh?: boolean): Promise<Sep6Info> {
+    if (this.anchorInfo && !shouldRefresh) {
+      return this.anchorInfo;
+    }
+
+    const { transferServer } = await this.anchor.sep1();
+    try {
+      const resp = await this.httpClient.get(`${transferServer}/info`);
+      this.anchorInfo = resp.data;
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Deposits funds using the SEP-6 protocol. Next steps by
+   * the anchor are given in the response.
+   *
+   * @param {object} options - The options for the deposit.
+   * @param {AuthToken} options.authToken - The authentication token.
+   * @param {Sep6DepositParams} options.params - The parameters for the deposit request.
+   *
+   * @returns {Promise<Sep6DepositResponse>} Sep6 deposit response, containing next steps if needed
+   * to complete the deposit.
+   *
+   * @throws {Error} If an unexpected error occurs during the deposit operation.
+   */
+  async deposit({
+    authToken,
+    params,
+  }: {
+    authToken: AuthToken;
+    params: Sep6DepositParams;
+  }): Promise<Sep6DepositResponse> {
+    return this.flow({ type: "deposit", authToken, params });
+  }
+
+  /**
+   * Initiates a withdrawal using SEP-6.
+   *
+   * @param {object} options - The options for the withdrawal operation.
+   * @param {AuthToken} options.authToken - The authentication token.
+   * @param {Sep6WithdrawParams} options.params - The parameters for the withdrawal request.
+   *
+   * @returns {Promise<Sep6WithdrawResponse>} Sep6 withdraw response.
+   */
+  async withdraw({
+    authToken,
+    params,
+  }: {
+    authToken: AuthToken;
+    params: Sep6WithdrawParams;
+  }): Promise<Sep6WithdrawResponse> {
+    return this.flow({ type: "withdraw", authToken, params });
+  }
+
+  /**
+   * Similar to the SEP-6 deposit function, but for non-equivalent assets
+   * that require an exchange.
+   *
+   * @param {object} options - The options for the deposit exchange.
+   * @param {AuthToken} options.authToken - The authentication token.
+   * @param {Sep6ExchangeParams} options.params - The parameters for the deposit request.
+   *
+   * @returns {Promise<Sep6DepositResponse>} Sep6 deposit response, containing next steps if needed
+   * to complete the deposit.
+   *
+   * @throws {Error} If an unexpected error occurs during the deposit operation.
+   */
+  async depositExchange({
+    authToken,
+    params,
+  }: {
+    authToken: AuthToken;
+    params: Sep6ExchangeParams;
+  }): Promise<Sep6DepositResponse> {
+    return this.flow({ type: "deposit-exchange", authToken, params });
+  }
+
+  /**
+   * Similar to the SEP-6 withdraw function, but for non-equivalent assets
+   * that require an exchange.
+   *
+   * @param {object} options - The options for the deposit exchange.
+   * @param {AuthToken} options.authToken - The authentication token.
+   * @param {Sep6ExchangeParams} options.params - The parameters for the deposit request.
+   *
+   * @returns {Promise<Sep6WithdrawResponse>} Sep6 withdraw response, containing next steps if needed
+   * to complete the withdrawal.
+   *
+   * @throws {Error} If an unexpected error occurs during the deposit operation.
+   */
+  async withdrawExchange({
+    authToken,
+    params,
+  }: {
+    authToken: AuthToken;
+    params: Sep6ExchangeParams;
+  }): Promise<Sep6WithdrawResponse> {
+    return this.flow({ type: "withdraw-exchange", authToken, params });
+  }
+
+  private async flow({
+    type,
+    authToken,
+    params,
+  }: {
+    type: "deposit" | "withdraw" | "deposit-exchange" | "withdraw-exchange";
+    authToken: AuthToken;
+    params: Sep6DepositParams | Sep6WithdrawParams | Sep6ExchangeParams;
+  }) {
+    const { transferServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.get(
+        `${transferServer}/${type}?${queryString.stringify(params)}`,
+        {
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${authToken.token}`,
+          },
+        },
+      );
+      return resp.data;
+    } catch (e) {
+      if (e.response?.data?.type === "non_interactive_customer_info_needed") {
+        return e.response?.data;
+      } else if (e.response?.data?.type === "customer_info_status") {
+        return e.response?.data;
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Creates a new instance of the Watcher class, to watch sep6 transactions.
+   * @returns {Watcher} A new Watcher instance.
+   */
+  watcher(): Watcher {
+    return new Watcher(this.anchor, WatcherSepType.SEP6);
+  }
+
+  /**
+   * Get account's sep6 transactions specified by asset and other params.
+   * @param {GetTransactionsParams} params - The Get Transactions params.
+   * @param {AuthToken} params.authToken - The authentication token for the account authenticated with the anchor.
+   * @param {string} params.assetCode - The target asset to query for.
+   * @param {string} [params.noOlderThan] - The response should contain transactions starting on or after this date & time.
+   * @param {string} [params.limit] - The response should contain at most 'limit' transactions.
+   * @param {string} [params.kind] - The kind of transaction that is desired. E.g.: 'deposit', 'withdrawal', 'depo
+   * -exchange', 'withdrawal-exchange'.
+   * @param {string} [params.pagingId] - The response should contain transactions starting prior to this ID (exclusive).
+   * @param {string} [params.lang] - The desired language (localization), it can also accept locale in the format 'en-US'.
+   * @returns {Promise<Sep6Transaction[]>} A list of transactions as requested by the client, sorted in time-descending order.
+   * @throws {InvalidTransactionsResponseError} Anchor returns an invalid response.
+   * @throws {ServerRequestFailedError} If server request fails.
+   */
+  async getTransactionsForAsset({
+    authToken,
+    assetCode,
+    noOlderThan,
+    limit,
+    kind,
+    pagingId,
+    lang = this.anchor.language,
+  }: GetTransactionsParams): Promise<Sep6Transaction[]> {
+    const toml = await this.anchor.sep1();
+    const transferServerEndpoint = toml.transferServer;
+
+    // Let's convert all params to snake case for the API call
+    const apiParams = camelToSnakeCaseObject({
+      assetCode,
+      account: authToken.account,
+      noOlderThan,
+      limit,
+      kind,
+      pagingId,
+      lang,
+    });
+
+    return _getTransactionsForAsset<Sep6Transaction>(
+      authToken,
+      apiParams,
+      transferServerEndpoint,
+      this.httpClient,
+    );
+  }
+
+  /**
+   * Get single sep6 transaction's current status and details from the anchor.
+   * @param {GetTransactionParams} params - The Get Transactions params.
+   * @param {AuthToken} params.authToken - The authentication token for the account authenticated with the anchor.
+   * @param {string} [params.id] - The transaction ID.
+   * @param {string} [params.stellarTransactionId] - The Stellar transaction ID.
+   * @param {string} [params.externalTransactionId] - The external transaction ID.
+   * @param {string} [params.lang] - The language setting.
+   * @returns {Promise<Sep6Transaction>} The transaction object.
+   * @throws {MissingTransactionIdError} If none of the ID parameters is provided.
+   * @throws {InvalidTransactionResponseError} If the anchor returns an invalid transaction response.
+   * @throws {ServerRequestFailedError} If the server request fails.
+   */
+  async getTransactionBy({
+    authToken,
+    id,
+    stellarTransactionId,
+    externalTransactionId,
+    lang = this.anchor.language,
+  }: GetTransactionParams): Promise<Sep6Transaction> {
+    if (!id && !stellarTransactionId && !externalTransactionId) {
+      throw new MissingTransactionIdError();
+    }
+
+    const toml = await this.anchor.sep1();
+    const transferServerEndpoint = toml.transferServer;
+
+    // Let's convert all params to snake case for the API call
+    const apiParams = camelToSnakeCaseObject({
+      id,
+      stellarTransactionId,
+      externalTransactionId,
+      lang,
+    });
+
+    return _getTransactionBy<Sep6Transaction>(
+      authToken,
+      apiParams,
+      transferServerEndpoint,
+      this.httpClient,
+    );
+  }
+}

package/src/walletSdk/Anchor/index.ts

@@ -1,11 +1,17 @@
 import { AxiosInstance } from "axios";
-import { StellarTomlResolver } from "stellar-sdk";
+import { StellarToml } from "stellar-sdk";
 
 import { Config } from "walletSdk";
 import { Sep10 } from "../Auth";
-import { ServerRequestFailedError } from "../Exceptions";
+import { Sep12 } from "../Customer";
+import {
+  ServerRequestFailedError,
+  KYCServerNotFoundError,
+} from "../Exceptions";
+import { Sep6 } from "./Sep6";
 import { Sep24 } from "./Sep24";
-import { AnchorServiceInfo, TomlInfo } from "../Types";
+import { Sep38 } from "./Sep38";
+import { AnchorServiceInfo, TomlInfo, AuthToken } from "../Types";
 import { parseToml } from "../Utils";
 
 // Let's prevent exporting this constructor type as
@@ -17,7 +23,21 @@ type AnchorParams = {
   language: string;
 };
 
-// Do not create this object directly, use the Wallet class.
+export type Transfer = Sep6;
+
+export type Auth = Sep10;
+
+export type Customer = Sep12;
+
+export type Interactive = Sep24;
+
+export type Quote = Sep38;
+
+/**
+ * Build on/off ramps with anchors.
+ * Do not create this object directly, use the Wallet class.
+ * @class
+ */
 export class Anchor {
   public language: string;
 
@@ -26,6 +46,11 @@ export class Anchor {
   private httpClient: AxiosInstance;
   private toml: TomlInfo;
 
+  /**
+   * Creates a new Anchor instance.
+   * @constructor
+   * @param {AnchorParams} params - The parameters to initialize the Anchor.
+   */
   constructor(params: AnchorParams) {
     const { cfg, homeDomain, httpClient, language } = params;
 
@@ -35,6 +60,12 @@ export class Anchor {
     this.language = language;
   }
 
+  /**
+   * Get anchor information from a TOML file.
+   * If `shouldRefresh` is set to `true`, it fetches fresh TOML values; otherwise, it returns cached values if available.
+   * @param {boolean} [shouldRefresh=false] - Flag to force a refresh of TOML values.
+   * @returns {Promise<TomlInfo>} - TOML information about the anchor.
+   */
   async sep1(shouldRefresh?: boolean): Promise<TomlInfo> {
     // return cached TOML values by default
     if (this.toml && !shouldRefresh) {
@@ -42,12 +73,41 @@ export class Anchor {
     }
 
     // fetch fresh TOML values from Anchor domain
-    const stellarToml = await StellarTomlResolver.resolve(this.homeDomain);
+    const stellarToml = await StellarToml.Resolver.resolve(this.homeDomain);
     const parsedToml = parseToml(stellarToml);
     this.toml = parsedToml;
     return parsedToml;
   }
 
+  /**
+   * Retrieves and returns TOML information using the `sep1` method.
+   * @param {boolean} [shouldRefresh=false] - Flag to force a refresh of TOML values.
+   * @returns {Promise<TomlInfo>} - TOML information.
+   */
+  async getInfo(shouldRefresh?: boolean): Promise<TomlInfo> {
+    return this.sep1(shouldRefresh);
+  }
+
+  /**
+   * Creates new transfer flow for given anchor. It can be used for withdrawal or deposit.
+   * @returns {Sep6} - flow service.
+   */
+  sep6(): Sep6 {
+    return new Sep6({ anchor: this, httpClient: this.httpClient });
+  }
+
+  /**
+   * Creates new transfer flow using the `sep6` method.
+   * @returns {Transfer} - transfer flow service.
+   */
+  transfer(): Transfer {
+    return this.sep6();
+  }
+
+  /**
+   * Create new auth object to authenticate account with the anchor using SEP-10.
+   * @returns {Promise<Sep10>} - The SEP-10 authentication manager.
+   */
   async sep10(): Promise<Sep10> {
     const tomlInfo = await this.sep1();
     return new Sep10({
@@ -58,10 +118,83 @@ export class Anchor {
     });
   }
 
+  /**
+   * Create new auth object to authenticate with using the `sep10` method.
+   * @returns {Promise<Auth>} - The SEP-10 authentication manager.
+   */
+  async auth(): Promise<Auth> {
+    return this.sep10();
+  }
+
+  /**
+   * Create new customer object to handle customer records with the anchor using SEP-12.
+   * @param {AuthToken} authToken - The authentication token.
+   * @returns {Promise<Sep12>} - A Sep12 customer instance.
+   * @throws {KYCServerNotFoundError} - If the KYC server information is not available.
+   */
+  async sep12(authToken: AuthToken): Promise<Sep12> {
+    const tomlInfo = await this.sep1();
+    const kycServer = tomlInfo?.kycServer;
+    if (!kycServer) {
+      throw new KYCServerNotFoundError();
+    }
+    return new Sep12(authToken, kycServer, this.httpClient);
+  }
+
+  /**
+   * Create new customer object to handle customer records using the `sep12` method.
+   * @param {AuthToken} authToken - The authentication token.
+   * @returns {Promise<Customer>} - A Customer instance.
+   */
+  async customer(authToken: AuthToken): Promise<Customer> {
+    return this.sep12(authToken);
+  }
+
+  /**
+   * Creates new interactive flow for given anchor. It can be used for withdrawal or deposit.
+   * @returns {Sep24} - interactive flow service.
+   */
   sep24(): Sep24 {
     return new Sep24({ anchor: this, httpClient: this.httpClient });
   }
 
+  /**
+   * Creates new interactive flow using the `sep24` method.
+   * @returns {Interactive} - interactive flow service
+   */
+  interactive(): Interactive {
+    return this.sep24();
+  }
+
+  /**
+   * Creates a new quote service. It can be used for getting price quotes from an anchor
+   * for exchanging assets.
+   * @param {AuthToken} [authToken] - The authentication token.
+   * @returns {Sep38} - quote service.
+   */
+  sep38(authToken?: AuthToken): Sep38 {
+    return new Sep38({
+      anchor: this,
+      httpClient: this.httpClient,
+      authToken,
+    });
+  }
+
+  /**
+   * Creates a new quote service using the `sep38` method.
+   * @param {AuthToken} [authToken] - The authentication token.
+   * @returns {Quote} - quote service.
+   */
+  quote(authToken?: AuthToken): Quote {
+    return this.sep38(authToken);
+  }
+
+  /**
+   * Get information about an Anchor.
+   * @param {string} [lang=this.language] - The language in which to retrieve information.
+   * @returns {Promise<AnchorServiceInfo>} An object containing information about the Anchor.
+   * @throws {ServerRequestFailedError} If the http request fails.
+   */
   async getServicesInfo(
     lang: string = this.language,
   ): Promise<AnchorServiceInfo> {

package/src/walletSdk/Asset/index.ts

@@ -1,4 +1,4 @@
-import StellarSdk from "stellar-sdk";
+import { Asset as StellarAsset } from "stellar-sdk";
 
 const STELLAR_SCHEME = "stellar";
 
@@ -18,11 +18,11 @@ export class StellarAssetId extends AssetId {
   issuer: string;
   scheme = STELLAR_SCHEME;
 
-  toAsset() {
+  toAsset(): StellarAsset {
     if (this.id === "native") {
-      return new StellarSdk.Asset("XLM");
+      return new StellarAsset("XLM");
     }
-    return new StellarSdk.Asset(this.code, this.issuer);
+    return new StellarAsset(this.code, this.issuer);
   }
 }
 
@@ -39,6 +39,8 @@ export class IssuedAssetId extends StellarAssetId {
   }
 }
 
+export type XLM = NativeAssetId;
+
 export class NativeAssetId extends StellarAssetId {
   id = "native";
   code = "XLM";
@@ -56,3 +58,18 @@ export class FiatAssetId extends AssetId {
     return this.sep38;
   }
 }
+
+export const Assets = {
+  Main: {
+    USDC: new IssuedAssetId(
+      "USDC",
+      "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
+    ),
+  },
+  Test: {
+    USDC: new IssuedAssetId(
+      "USDC",
+      "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+    ),
+  },
+};

package/src/walletSdk/Auth/WalletSigner.ts

@@ -1,7 +1,6 @@
 import {
   Transaction,
   TransactionBuilder as StellarTransactionBuilder,
-  FeeBumpTransaction,
 } from "stellar-sdk";
 import { AxiosInstance } from "axios";
 
@@ -10,15 +9,31 @@ import {
   SignWithDomainAccountParams,
   HttpHeaders,
 } from "../Types";
-import { AccountKeypair } from "../Horizon/Account";
 import { DefaultClient } from "../";
 
+/**
+ * A Wallet Signer for signing Stellar transactions.
+ */
 export interface WalletSigner {
+  /**
+   * Sign a transaction with a client keypair.
+   * @param {Transaction} params.transaction - The transaction to sign.
+   * @param {AccountKeypair} params.accountKp - The keypair to sign with.
+   * @returns {Transaction} The signed transaction.
+   */
   signWithClientAccount({
     transaction,
     accountKp,
   }: SignWithClientAccountParams): Transaction;
 
+  /**
+   * Sign a transaction using the domain account's keypair. This method is async in the
+   * case of signing with a different server.
+   * @param {XdrEncodedTransaction} params.transactionXDR - The XDR representation of the transaction to sign.
+   * @param {NetworkPassphrase} params.networkPassphrase - The network passphrase for the Stellar network.
+   * @param {AccountKeypair} params.accountKp - The keypair of the domain account.
+   * @returns {Promise<Transaction>} The signed transaction.
+   */
   signWithDomainAccount({
     transactionXDR,
     networkPassphrase,
@@ -26,11 +41,15 @@ export interface WalletSigner {
   }: SignWithDomainAccountParams): Promise<Transaction>;
 }
 
+/**
+ * A Default signer used if no signer is given.
+ */
 export const DefaultSigner: WalletSigner = {
   signWithClientAccount: ({ transaction, accountKp }) => {
     transaction.sign(accountKp.keypair);
     return transaction;
   },
+  // eslint-disable-next-line @typescript-eslint/require-await
   signWithDomainAccount: async () => {
     throw new Error(
       "The DefaultSigner can't sign transactions with domain account",
@@ -39,8 +58,7 @@ export const DefaultSigner: WalletSigner = {
 };
 
 /**
- * Represents a Domain Signer used for signing Stellar transactions with a domain server.
- *
+ * A Domain Signer used for signing Stellar transactions with a domain server.
  * @class
  * @implements {WalletSigner}
  */
@@ -51,7 +69,6 @@ export class DomainSigner implements WalletSigner {
 
   /**
    * Create a new instance of the DomainSigner class.
-   *
    * @constructor
    * @param {string} url - The URL of the domain server.
    * @param {HttpHeaders} headers - The HTTP headers for requests to the domain server.
@@ -74,6 +91,7 @@ export class DomainSigner implements WalletSigner {
   async signWithDomainAccount({
     transactionXDR,
     networkPassphrase,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     accountKp,
   }: SignWithDomainAccountParams): Promise<Transaction> {
     const response = await this.client.post(

package/src/walletSdk/Auth/index.ts

@@ -30,13 +30,24 @@ type Sep10Params = {
   httpClient: AxiosInstance;
 };
 
-// Do not create this object directly, use the Wallet class.
+/**
+ * Sep-10 used for authentication to an external server.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md}
+ * Do not create this object directly, use the Anchor class.
+ * @class
+ */
 export class Sep10 {
   private cfg: Config;
   private webAuthEndpoint: string;
   private homeDomain: string;
   private httpClient: AxiosInstance;
 
+  /**
+   * Creates a new instance of the Sep10 class.
+   *
+   * @constructor
+   * @param {Sep10Params} params - Parameters to initialize the Sep10 instance.
+   */
   constructor(params: Sep10Params) {
     const { cfg, webAuthEndpoint, homeDomain, httpClient } = params;
 
@@ -46,6 +57,15 @@ export class Sep10 {
     this.httpClient = httpClient;
   }
 
+  /**
+   * Initiates the authentication process using SEP-10.
+   * @param {AuthenticateParams} params - The Authentication params.
+   * @param {AccountKeypair} params.accountKp - Keypair for the Stellar account being authenticated.
+   * @param {WalletSigner} [params.walletSigner] - Signer for signing transactions (defaults to the configuration default signer).
+   * @param {string} [params.memoId] - Memo ID to distinguish the account.
+   * @param {string} [params.clientDomain] - Domain hosting stellar.toml file containing `SIGNING_KEY`.
+   * @returns {Promise<AuthToken>} The authentication token.
+   */
   async authenticate({
     accountKp,
     walletSigner,
@@ -127,17 +147,16 @@ export class Sep10 {
         throw new MissingTokenError();
       }
 
-      const authToken: AuthToken = resp.data.token;
-      validateToken(authToken);
+      validateToken(resp.data.token);
 
-      return authToken;
+      return AuthToken.from(resp.data.token);
     } catch (e) {
       throw new ServerRequestFailedError(e);
     }
   }
 }
 
-const validateToken = (token: AuthToken) => {
+const validateToken = (token: string) => {
   const parsedToken = decode(token);
   if (!parsedToken) {
     throw new InvalidTokenError();