@stellar/typescript-wallet-sdk 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/typescript-wallet-sdk",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "engines": {
     "node": ">=18"
   },
@@ -11,17 +11,22 @@
   "private": false,
   "devDependencies": {
     "@babel/preset-env": "^7.20.2",
-    "@stellar/eslint-config": "^2.1.2",
     "@stellar/prettier-config": "^1.0.1",
     "@stellar/tsconfig": "^1.0.2",
     "@types/jest": "^29.4.0",
     "@types/lodash": "^4.14.194",
     "@types/sinon": "^10.0.15",
+    "@typescript-eslint/eslint-plugin": "^6.7.5",
+    "@typescript-eslint/parser": "^6.7.5",
     "babel-jest": "^29.4.1",
     "crypto-browserify": "^3.12.0",
-    "eslint": "^8.33.0",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.51.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-jsdoc": "^46.8.2",
     "husky": "^8.0.0",
     "jest": "^29.4.1",
+    "lint-staged": "^14.0.1",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.0.5",
     "pretty-quick": "^2.0.1",
@@ -41,18 +46,26 @@
     "jws": "^4.0.0",
     "lodash": "^4.17.21",
     "query-string": "^7.1.3",
-    "stellar-sdk": "^11.0.0-beta.3",
+    "stellar-sdk": "^11.0.0-beta.6",
     "stream-http": "^3.2.0",
     "url": "^0.11.0",
     "util": "^0.12.5",
     "utility-types": "^3.10.0"
   },
   "scripts": {
+    "lint": "eslint . --ext .ts",
     "prepare": "husky install",
     "test": "jest --watchAll",
+    "test:ci": "jest --ci",
+    "test:integration:ci": "jest --config jest.integration.config.js --ci",
     "build:web": "webpack --config webpack.config.js",
     "build:node": "webpack --env NODE=true --config webpack.config.js",
     "build": "run-p build:web build:node",
     "example:sep24": "ts-node examples/sep24/sep24.ts"
+  },
+  "lint-staged": {
+    "**/*.ts": [
+      "eslint --fix --max-warnings 0"
+    ]
   }
 }

package/src/index.ts

@@ -18,10 +18,12 @@ export { Sep24 } from "./walletSdk/Anchor/Sep24";
 export { IssuedAssetId, NativeAssetId, FiatAssetId } from "./walletSdk/Asset";
 export { Sep10, WalletSigner, DefaultSigner } from "./walletSdk/Auth";
 export {
+  AccountKeypair,
   PublicKeypair,
   SigningKeypair,
   AccountService,
   Stellar,
+  CommonTransactionBuilder,
   TransactionBuilder,
   SponsoringBuilder,
 } from "./walletSdk/Horizon";

package/src/walletSdk/Anchor/Sep24.ts

@@ -1,13 +1,10 @@
 import { AxiosInstance } from "axios";
-import queryString from "query-string";
 
 import { Anchor } from "../Anchor";
 import {
   AssetNotSupportedError,
   ServerRequestFailedError,
   MissingTransactionIdError,
-  InvalidTransactionResponseError,
-  InvalidTransactionsResponseError,
 } from "../Exceptions";
 import {
   FLOW_TYPE,
@@ -16,10 +13,14 @@ import {
   AnchorTransaction,
   GetTransactionParams,
   GetTransactionsParams,
-  TransactionStatus,
   AnchorServiceInfo,
+  WatcherSepType,
 } from "../Types";
-import { Watcher } from "../Watcher";
+import {
+  Watcher,
+  _getTransactionsForAsset,
+  _getTransactionBy,
+} from "../Watcher";
 import { camelToSnakeCaseObject } from "../Utils";
 
 // Let's prevent exporting this constructor type as
@@ -29,11 +30,21 @@ type Sep24Params = {
   httpClient: AxiosInstance;
 };
 
-// Do not create this object directly, use the Wallet class.
+/**
+ * Interactive flow for deposit and withdrawal using SEP-24.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md}
+ * Do not create this object directly, use the Anchor class.
+ * @class
+ */
 export class Sep24 {
   private anchor: Anchor;
   private httpClient: AxiosInstance;
 
+  /**
+   * Creates a new instance of the Sep24 class.
+   * @constructor
+   * @param {Sep24Params} params - Parameters to initialize the Sep24 instance.
+   */
   constructor(params: Sep24Params) {
     const { anchor, httpClient } = params;
 
@@ -41,11 +52,21 @@ export class Sep24 {
     this.httpClient = httpClient;
   }
 
+  /**
+   * Initiates a deposit request.
+   * @param {Sep24PostParams} params - The SEP-24 Post params.
+   * @param {string} params.assetCode - The asset to deposit.
+   * @param {AuthToken} params.authToken - Authentication token for the request.
+   * @param {string} [params.lang] - The language for the request (defaults to the Anchor's language).
+   * @param {ExtraFields} [params.extraFields] - Additional fields for the request.
+   * @param {Memo} [params.destinationMemo] - Memo information for the destination account.
+   * @param {string} [params.destinationAccount] - The destination account for the deposit.
+   * @returns {Promise<Sep24PostResponse>} The Sep24 response.
+   * @throws {AssetNotSupportedError} If the asset is not supported for deposit.
+   */
   async deposit({
     assetCode,
-
     authToken,
-
     lang,
     extraFields,
     destinationMemo,
@@ -62,6 +83,17 @@ export class Sep24 {
     });
   }
 
+  /**
+   * Initiates a withdrawal request.
+   * @param {Sep24PostParams} params - The SEP-24 Post params.
+   * @param {string} params.assetCode - The asset to withdraw.
+   * @param {AuthToken} params.authToken - Authentication token for the request.
+   * @param {string} [params.lang] - The language for the request (defaults to the Anchor's language).
+   * @param {ExtraFields} [params.extraFields] - Additional fields for the request.
+   * @param {string} [params.withdrawalAccount] - The withdrawal account.
+   * @returns {Promise<Sep24PostResponse>} The Sep24 response.
+   * @throws {AssetNotSupportedError} If the asset is not supported for withdrawal.
+   */
   async withdraw({
     assetCode,
     authToken,
@@ -106,7 +138,7 @@ export class Sep24 {
     if (!assets.includes(assetCode)) {
       throw new AssetNotSupportedError(type, assetCode);
     }
-    let memoMap = {};
+    const memoMap = {};
     if (destinationMemo) {
       memoMap["memo_type"] = destinationMemo.type;
       memoMap["memo"] = destinationMemo.value;
@@ -125,7 +157,7 @@ export class Sep24 {
         {
           headers: {
             "Content-Type": "application/json",
-            Authorization: `Bearer ${authToken}`,
+            Authorization: `Bearer ${authToken.token}`,
           },
         },
       );
@@ -138,26 +170,35 @@ export class Sep24 {
     }
   }
 
+  /**
+   * Retrieves information about the Anchor.
+   * @returns {Promise<AnchorServiceInfo>} An object containing information about the Anchor.
+   * @throws {ServerRequestFailedError} If the server request to fetch information fails.
+   */
   async getServicesInfo(): Promise<AnchorServiceInfo> {
     return this.anchor.getServicesInfo();
   }
 
+  /**
+   * Creates a new instance of the Watcher class, to watch sep24 transactions.
+   * @returns {Watcher} A new Watcher instance.
+   */
   watcher(): Watcher {
-    return new Watcher(this.anchor);
+    return new Watcher(this.anchor, WatcherSepType.SEP24);
   }
 
   /**
-   * Get single transaction's current status and details. One of the [id], [stellarTransactionId],
-   * [externalTransactionId] must be provided.
-   *
-   * @param authToken auth token of the account authenticated with the anchor
-   * @param id transaction ID
-   * @param stellarTransactionId stellar transaction ID
-   * @param externalTransactionId external transaction ID
-   * @return transaction object
-   * @throws [MissingTransactionIdError] if none of the id params is provided
-   * @throws [InvalidTransactionResponseError] if Anchor returns an invalid transaction
-   * @throws [ServerRequestFailedError] if server request fails
+   * Get single 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<AnchorTransaction>} 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,
@@ -173,53 +214,35 @@ export class Sep24 {
     const toml = await this.anchor.sep1();
     const transferServerEndpoint = toml.transferServerSep24;
 
-    let qs: { [name: string]: string } = {};
-
-    if (id) {
-      qs = { id };
-    } else if (stellarTransactionId) {
-      qs = { stellar_transaction_id: stellarTransactionId };
-    } else if (externalTransactionId) {
-      qs = { external_transaction_id: externalTransactionId };
-    }
-
-    qs = { lang, ...qs };
-
-    try {
-      const resp = await this.httpClient.get(
-        `${transferServerEndpoint}/transaction?${queryString.stringify(qs)}`,
-        {
-          headers: {
-            Authorization: `Bearer ${authToken}`,
-          },
-        },
-      );
-
-      const transaction: AnchorTransaction = resp.data.transaction;
-
-      if (!transaction || Object.keys(transaction).length === 0) {
-        throw new InvalidTransactionResponseError(transaction);
-      }
+    // Let's convert all params to snake case for the API call
+    const apiParams = camelToSnakeCaseObject({
+      id,
+      stellarTransactionId,
+      externalTransactionId,
+      lang,
+    });
 
-      return transaction;
-    } catch (e) {
-      throw new ServerRequestFailedError(e);
-    }
+    return _getTransactionBy<AnchorTransaction>(
+      authToken,
+      apiParams,
+      transferServerEndpoint,
+      this.httpClient,
+    );
   }
 
   /**
    * Get account's transactions specified by asset and other params.
-   *
-   * @param authToken auth token of the account authenticated with the anchor
-   * @param assetCode target asset to query for
-   * @param noOlderThan response should contain transactions starting on or after this date & time
-   * @param limit response should contain at most 'limit' transactions
-   * @param kind kind of transaction that is desired. E.g.: 'deposit', 'withdrawal'
-   * @param pagingId response should contain transactions starting prior to this ID (exclusive)
-   * @param lang desired language (localization), it can also accept locale in the format 'en-US'
-   * @return list of transactions as requested by the client, sorted in time-descending order
-   * @throws [InvalidTransactionsResponseError] if Anchor returns an invalid response
-   * @throws [ServerRequestFailedError] if server request fails
+   * @param {GetTransactionParams} 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'.
+   * @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<AnchorTransaction[]>} 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,
@@ -243,27 +266,11 @@ export class Sep24 {
       lang,
     });
 
-    try {
-      const resp = await this.httpClient.get(
-        `${transferServerEndpoint}/transactions?${queryString.stringify(
-          apiParams,
-        )}`,
-        {
-          headers: {
-            Authorization: `Bearer ${authToken}`,
-          },
-        },
-      );
-
-      const transactions: AnchorTransaction[] = resp.data.transactions;
-
-      if (!transactions || !Array.isArray(transactions)) {
-        throw new InvalidTransactionsResponseError(transactions);
-      }
-
-      return transactions;
-    } catch (e) {
-      throw new ServerRequestFailedError(e);
-    }
+    return _getTransactionsForAsset<AnchorTransaction>(
+      authToken,
+      apiParams,
+      transferServerEndpoint,
+      this.httpClient,
+    );
   }
 }

package/src/walletSdk/Anchor/Sep38.ts

@@ -0,0 +1,180 @@
+import { AxiosInstance } from "axios";
+import queryString from "query-string";
+
+import { Anchor } from "../Anchor";
+import {
+  ServerRequestFailedError,
+  Sep38PriceOnlyOneAmountError,
+} from "../Exceptions";
+import {
+  AuthToken,
+  Sep38Info,
+  Sep38Params,
+  Sep38PricesParams,
+  Sep38PriceParams,
+  Sep38PricesResponse,
+  Sep38PriceResponse,
+  Sep38PostQuoteParams,
+  Sep38PostQuoteResponse,
+  HttpHeaders,
+} from "../Types";
+import { camelToSnakeCaseObject } from "../Utils";
+
+/**
+ * Quote service using SEP-38. It can be used for getting price quotes from an anchor
+ * for exchanging assets.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md}
+ * Do not create this object directly, use the Anchor class.
+ * @class
+ */
+export class Sep38 {
+  private anchor: Anchor;
+  private httpClient: AxiosInstance;
+  private authToken: AuthToken;
+  private headers: HttpHeaders;
+  private sep38Info: Sep38Info;
+
+  /**
+   * Creates a new instance of the Sep38 class.
+   * @constructor
+   * @param {Sep38Params} params - Parameters to initialize the Sep38 instance.
+   */
+  constructor(params: Sep38Params) {
+    const { anchor, httpClient, authToken } = params;
+
+    this.anchor = anchor;
+    this.httpClient = httpClient;
+    this.authToken = authToken;
+    if (authToken) {
+      this.headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.authToken.token}`,
+      };
+    }
+  }
+
+  /**
+   * Get SEP-38 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<Sep38Info>} - SEP-38 information about the anchor.
+   */
+  async info(shouldRefresh?: boolean): Promise<Sep38Info> {
+    if (this.sep38Info && !shouldRefresh) {
+      return this.sep38Info;
+    }
+
+    const { anchorQuoteServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.get(`${anchorQuoteServer}/info`, {
+        headers: this.headers,
+      });
+      this.sep38Info = resp.data;
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Get indicative prices of off-chain assets in exchange for a Stellar asset, or vice versa,
+   * from an anchor using Sep-38.
+   * @param {Sep38PricesParams} params - The parameters for the GET prices request.
+   * if the anchor does not require it.
+   * @returns {Promise<Sep38PricesResponse>} - SEP-38 /prices response.
+   */
+  async prices(params: Sep38PricesParams): Promise<Sep38PricesResponse> {
+    const { anchorQuoteServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.get(
+        `${anchorQuoteServer}/prices?${queryString.stringify(
+          camelToSnakeCaseObject(params),
+        )}`,
+        {
+          headers: this.headers,
+        },
+      );
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Get an indicative price for an an asset pair from and anchor using SEP-38.
+   * @param {Sep38PriceParams} params - The parameters for the GET price request.
+   * if the anchor does not require it.
+   * @throws {Sep38PriceOnlyOneAmountError} Must give only sellAmount or buyAmount, and not both.
+   * @returns {Promise<Sep38PriceResponse>} - SEP-38 /price response.
+   */
+  async price(params: Sep38PriceParams): Promise<Sep38PriceResponse> {
+    if (
+      (params.sellAmount && params.buyAmount) ||
+      (!params.sellAmount && !params.buyAmount)
+    ) {
+      throw new Sep38PriceOnlyOneAmountError();
+    }
+    const { anchorQuoteServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.get(
+        `${anchorQuoteServer}/price?${queryString.stringify(
+          camelToSnakeCaseObject(params),
+        )}`,
+        {
+          headers: this.headers,
+        },
+      );
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Request a firm quote from the anchor.
+   * @param {Sep38PostQuoteParams} params - The parameters for the quote request.
+   * @returns {Promise<Sep38PostQuoteResponse>} - SEP-38 quote response.
+   */
+  async requestQuote(
+    params: Sep38PostQuoteParams,
+  ): Promise<Sep38PostQuoteResponse> {
+    const { anchorQuoteServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.post(
+        `${anchorQuoteServer}/quote`,
+        params,
+        {
+          headers: this.headers,
+        },
+      );
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Get a previously-provided quote from the anchor.
+   * @param {string} quoteId - The id of the quote to fetch.
+   * @returns {Promise<Sep38PostQuoteResponse>} - SEP-38 quote response.
+   */
+  async getQuote(quoteId: string): Promise<Sep38PostQuoteResponse> {
+    const { anchorQuoteServer } = await this.anchor.sep1();
+
+    try {
+      const resp = await this.httpClient.get(
+        `${anchorQuoteServer}/quote/${quoteId}`,
+        {
+          headers: this.headers,
+        },
+      );
+      return resp.data;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+}