@stellar/typescript-wallet-sdk 1.0.0-alpha.2 → 1.1.0-alpha.1

package/src/walletSdk/Anchor/index.ts

@@ -1,57 +1,257 @@
+import { AxiosInstance } from "axios";
+import queryString from "query-string";
 import { StellarTomlResolver } from "stellar-sdk";
-import axios from "axios";
 
 import { Auth } from "../Auth";
 import { Interactive } from "../interactive";
 import { TomlInfo, parseToml } from "../toml";
-import { ServerRequestFailedError } from "../exception";
+import { Watcher } from "../Watcher";
+import {
+  MissingTransactionIdError,
+  ServerRequestFailedError,
+  InvalidTransactionResponseError,
+  InvalidTransactionsResponseError,
+  AssetNotSupportedError,
+} from "../exception";
+import { camelToSnakeCaseObject } from "../util/camelToSnakeCase";
+import { Config } from "walletSdk";
+import { TransactionStatus } from "../Watcher/Types";
+import { AnchorTransaction, AnchorServiceInfo } from "./Types";
+
+type GetTransactionsParams = {
+  authToken: string;
+  assetCode: string;
+  noOlderThan?: string;
+  limit?: number;
+  kind?: string;
+  pagingId?: string;
+  lang?: string;
+};
 
 // Do not create this object directly, use the Wallet class.
 export class Anchor {
-  private homeDomain = "";
-  private httpClient = null;
-  private cfg;
+  public language: string;
+
+  private cfg: Config;
+  private homeDomain: string;
+  private httpClient: AxiosInstance;
+  private toml: TomlInfo;
 
-  constructor(cfg, homeDomain: string, httpClient) {
+  constructor({
+    cfg,
+    homeDomain,
+    httpClient,
+    language,
+  }: {
+    cfg: Config;
+    homeDomain: string;
+    httpClient: AxiosInstance;
+    language: string;
+  }) {
+    this.cfg = cfg;
     this.homeDomain = homeDomain;
     this.httpClient = httpClient;
-    this.cfg = cfg;
+    this.language = language;
   }
 
-  async getInfo(): Promise<TomlInfo> {
-    const toml = await StellarTomlResolver.resolve(this.homeDomain);
-    return parseToml(toml);
+  async getInfo(shouldRefresh?: boolean): Promise<TomlInfo> {
+    // return cached TOML values by default
+    if (this.toml && !shouldRefresh) {
+      return this.toml;
+    }
+
+    // fetch fresh TOML values from Anchor domain
+    const stellarToml = await StellarTomlResolver.resolve(this.homeDomain);
+    const parsedToml = parseToml(stellarToml);
+    this.toml = parsedToml;
+    return parsedToml;
   }
 
-  async auth() {
+  async auth(): Promise<Auth> {
     const tomlInfo = await this.getInfo();
-    return new Auth(tomlInfo.webAuthEndpoint);
+    return new Auth(this.cfg, tomlInfo.webAuthEndpoint, this.httpClient);
   }
 
-  interactive() {
-    return new Interactive(this.homeDomain, this);
+  interactive(): Interactive {
+    return new Interactive(this.homeDomain, this, this.httpClient);
   }
 
-  async getServicesInfo() {
+  watcher(): Watcher {
+    return new Watcher(this);
+  }
+
+  async getServicesInfo(
+    lang: string = this.language
+  ): Promise<AnchorServiceInfo> {
     const toml = await this.getInfo();
     const transferServerEndpoint = toml.transferServerSep24;
 
     try {
-      // TODO - use httpClient
-      const resp = await axios.get(`${transferServerEndpoint}/info`, {
-        headers: {
-          "Content-Type": "application/json",
-        },
-      });
+      const resp = await this.httpClient.get(
+        `${transferServerEndpoint}/info?lang=${lang}`,
+        {
+          headers: {
+            "Content-Type": "application/json",
+          },
+        }
+      );
       return resp.data;
     } catch (e) {
       throw new ServerRequestFailedError(e);
     }
   }
 
-  getTransaction() {}
+  /**
+   * 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
+   */
+  async getTransactionBy({
+    authToken,
+    id,
+    stellarTransactionId,
+    externalTransactionId,
+    lang = this.language,
+  }: {
+    authToken: string;
+    id?: string;
+    stellarTransactionId?: string;
+    externalTransactionId?: string;
+    lang?: string;
+  }): Promise<AnchorTransaction> {
+    if (!id && !stellarTransactionId && !externalTransactionId) {
+      throw new MissingTransactionIdError();
+    }
+
+    const toml = await this.getInfo();
+    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 = resp.data?.transaction;
+
+      if (!transaction || Object.keys(transaction).length === 0) {
+        throw new InvalidTransactionResponseError(transaction);
+      }
+
+      return transaction;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * 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
+   */
+  async getTransactionsForAsset(
+    params: GetTransactionsParams
+  ): Promise<AnchorTransaction[]> {
+    const { authToken, lang = this.language, ...otherParams } = params;
+
+    const toml = await this.getInfo();
+    const transferServerEndpoint = toml.transferServerSep24;
+
+    // Let's convert all params to snake case for the API call
+    const apiParams = camelToSnakeCaseObject({ lang, ...otherParams });
+
+    try {
+      const resp = await this.httpClient.get(
+        `${transferServerEndpoint}/transactions?${queryString.stringify(
+          apiParams
+        )}`,
+        {
+          headers: {
+            Authorization: `Bearer ${authToken}`,
+          },
+        }
+      );
+
+      const transactions = resp.data?.transactions;
 
-  getTransactionForAsset() {}
+      if (!transactions || !Array.isArray(transactions)) {
+        throw new InvalidTransactionsResponseError(transactions);
+      }
 
-  getHistory() {}
+      return transactions;
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+  }
+
+  /**
+   * Get all successfully finished (either completed or refunded) account transactions for specified
+   * asset. Optional field implementation depends on anchor.
+   *
+   * @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 filtered transactions that achieved a final state (completed or refunded)
+   * @throws [AssetNotSupportedError] if asset is not supported by the anchor 
+   * @throws [InvalidTransactionsResponseError] if Anchor returns an invalid response
+   * @throws [ServerRequestFailedError] if server request fails
+   */
+
+  async getHistory(
+    params: GetTransactionsParams
+  ): Promise<AnchorTransaction[]> {
+    const { assetCode } = params;
+
+    const toml = await this.getInfo();
+    if (!toml.currencies?.find(({ code }) => code === assetCode)) {
+      throw new AssetNotSupportedError(null, assetCode);
+    }
+
+    const transactions = await this.getTransactionsForAsset(params);
+
+    const finishedTransactions = transactions
+      .filter(({ status }) => [
+        TransactionStatus.completed, 
+        TransactionStatus.refunded
+      ].includes(status));
+
+    return finishedTransactions;
+  }
 }

package/src/walletSdk/Auth/WalletSigner.ts

@@ -1,4 +1,19 @@
-// TODO - https://stellarorg.atlassian.net/browse/WAL-813?atlOrigin=eyJpIjoiODBkZTQ1MDMzYTJmNDFjOWI0NDM3MTQ2YWYxNTEzNTgiLCJwIjoiaiJ9
+import StellarSdk, { Keypair, Transaction } from "stellar-sdk";
 
-export interface WalletSigner {}
-export const DefaultSigner: WalletSigner = {};
+export interface WalletSigner {
+  signWithClientAccount(txn: Transaction, account: Keypair): Transaction;
+  signWithDomainAccount(
+    transactionXDR: string,
+    networkPassPhrase: string,
+    account: Keypair
+  ): Transaction;
+}
+export const DefaultSigner: WalletSigner = {
+  signWithClientAccount: (txn, account) => {
+    txn.sign(account);
+    return txn;
+  },
+  signWithDomainAccount: (transactionXDR, networkPassPhrase, account) => {
+    throw new Error("The DefaultSigner can't sign transactions with domain");
+  },
+};

package/src/walletSdk/Auth/index.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import StellarSdk, { Keypair } from "stellar-sdk";
 
 import {
@@ -6,18 +5,23 @@ import {
   ClientDomainWithMemoError,
   ServerRequestFailedError,
 } from "../exception";
+import { WalletSigner } from "./WalletSigner";
 
 // Do not create this object directly, use the Wallet class.
 export class Auth {
+  private cfg;
   private webAuthEndpoint = "";
+  private httpClient;
 
-  // TODO - add config and custom httpClient functionality
-  constructor(webAuthEndpoint) {
+  constructor(cfg, webAuthEndpoint, httpClient) {
+    this.cfg = cfg;
     this.webAuthEndpoint = webAuthEndpoint;
+    this.httpClient = httpClient;
   }
 
   async authenticate(
     accountKp: Keypair,
+    walletSigner?: WalletSigner,
     memoId?: string,
     clientDomain?: string
   ) {
@@ -28,13 +32,17 @@ export class Auth {
     );
     const signedTx = this.sign(
       accountKp,
-      challengeResponse.transaction,
-      challengeResponse.network_passphrase
+      challengeResponse,
+      walletSigner ?? this.cfg.app.defaultSigner
     );
     return await this.getToken(signedTx);
   }
 
-  async challenge(accountKp: Keypair, memoId?: string, clientDomain?: string) {
+  private async challenge(
+    accountKp: Keypair,
+    memoId?: string,
+    clientDomain?: string
+  ) {
     if (memoId && parseInt(memoId) < 0) {
       throw new InvalidMemoError();
     }
@@ -45,26 +53,44 @@ export class Auth {
       memoId ? `&memo=${memoId}` : ""
     }${clientDomain ? `&client_domain=${clientDomain}` : ""}`;
     try {
-      const auth = await axios.get(url);
+      const auth = await this.httpClient.get(url);
       return auth.data;
     } catch (e) {
       throw new ServerRequestFailedError(e);
     }
   }
 
-  // TODO - add signing with client account functionality
-  sign(accountKp: Keypair, challengeTx, network) {
-    const transaction = StellarSdk.TransactionBuilder.fromXDR(
-      challengeTx,
-      network
+  private sign(
+    accountKp: Keypair,
+    challengeResponse: {
+      transaction: string;
+      network_passphrase: string;
+    },
+    walletSigner: WalletSigner
+  ) {
+    let transaction = StellarSdk.TransactionBuilder.fromXDR(
+      challengeResponse.transaction,
+      challengeResponse.network_passphrase
     );
-    transaction.sign(accountKp);
+
+    // check if verifying client domain as well
+    for (const op of transaction.operations) {
+      if (op.type === "manageData" && op.name === "client_domain") {
+        transaction = walletSigner.signWithDomainAccount(
+          challengeResponse.transaction,
+          challengeResponse.network_passphrase,
+          accountKp
+        );
+      }
+    }
+
+    walletSigner.signWithClientAccount(transaction, accountKp);
     return transaction;
   }
 
-  async getToken(signedTx) {
+  private async getToken(signedTx) {
     try {
-      const resp = await axios.post(this.webAuthEndpoint, {
+      const resp = await this.httpClient.post(this.webAuthEndpoint, {
         transaction: signedTx.toXDR(),
       });
       return resp.data.token;

package/src/walletSdk/Watcher/Types.ts

@@ -0,0 +1,81 @@
+export enum TransactionStatus {
+  /**
+   * There is not yet enough information for this transaction to be initiated. Perhaps the user has
+   * not yet entered necessary info in an interactive flow
+   */
+  incomplete = "incomplete",
+
+  /**
+   * The user has not yet initiated their transfer to the anchor. This is the next necessary step in
+   * any deposit or withdrawal flow after transitioning from `incomplete`
+   */
+  pending_user_transfer_start = "pending_user_transfer_start",
+
+  /**
+   * The Stellar payment has been successfully received by the anchor and the off-chain funds are
+   * available for the customer to pick up. Only used for withdrawal transactions.
+   */
+  pending_user_transfer_complete = "pending_user_transfer_complete",
+  
+  /**
+   * Pending External deposit/withdrawal has been submitted to external network, but is not yet
+   * confirmed. This is the status when waiting on Bitcoin or other external crypto network to
+   * complete a transaction, or when waiting on a bank transfer.
+   */  
+  pending_external = "pending_external",
+  
+  /**
+   * Deposit/withdrawal is being processed internally by anchor. This can also be used when the
+   * anchor must verify KYC information prior to deposit/withdrawal.
+   */
+  pending_anchor = "pending_anchor",
+  
+  /**
+   * Deposit/withdrawal operation has been submitted to Stellar network, but is not yet confirmed.
+   */
+  pending_stellar = "pending_stellar",
+  
+  /** The user must add a trustline for the asset for the deposit to complete. */
+  pending_trust = "pending_trust",
+  
+  /**
+   * The user must take additional action before the deposit / withdrawal can complete, for example
+   * an email or 2fa confirmation of a withdrawal.
+   */
+  pending_user = "pending_user",
+  
+  /** Deposit/withdrawal fully completed */
+  completed = "completed",
+  
+  /** The deposit/withdrawal is fully refunded */
+  refunded = "refunded",
+  
+  /**
+   * Funds were never received by the anchor and the transaction is considered abandoned by the
+   * user. Anchors are responsible for determining when transactions are considered expired.
+   */
+  expired = "expired",
+  
+  /**
+   * Could not complete deposit because no satisfactory asset/XLM market was available to create the
+   * account
+   */
+  no_market = "no_market",
+  
+  /** Deposit/withdrawal size less than min_amount. */
+  too_small = "too_small",
+  
+  /** Deposit/withdrawal size exceeded max_amount. */
+  too_large = "too_large",
+  
+  /** Catch-all for any error not enumerated above. */
+  error = "error",
+}
+
+export type WatcherRefreshFunction = () => void;
+export type WatcherStopFunction = () => void;
+
+export interface WatcherResponse {
+  refresh: WatcherRefreshFunction;
+  stop: WatcherStopFunction;
+}