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

package/lib/walletSdk/Watcher/Types.d.ts

@@ -0,0 +1,65 @@
+export declare 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;
+}

package/lib/walletSdk/Watcher/index.d.ts

@@ -0,0 +1,54 @@
+import { Anchor } from "walletSdk/Anchor";
+import { WatcherResponse } from "./Types";
+export declare class Watcher {
+    private anchor;
+    private _oneTransactionWatcher;
+    private _allTransactionsWatcher?;
+    private _watchOneTransactionRegistry;
+    private _watchAllTransactionsRegistry;
+    private _transactionsRegistry;
+    private _transactionsIgnoredRegistry;
+    constructor(anchor: Anchor);
+    /**
+    * Watch all transactions returned from a transfer server. When new or
+    * updated transactions come in, run an `onMessage` callback.
+    *
+    * On initial load, it'll return ALL pending transactions via onMessage.
+    * Subsequent messages will be any one of these events:
+    *  - Any new transaction appears
+    *  - Any of the initial pending transactions change any state
+    *
+    * You may also provide an array of transaction ids, `watchlist`, and this
+    * watcher will always react to transactions whose ids are in the watchlist.
+    */
+    watchAllTransactions(params: {
+        authToken: string;
+        assetCode: string;
+        onMessage: (transaction: any) => void;
+        onError: (error: any) => void;
+        watchlist?: string[];
+        timeout?: number;
+        isRetry?: boolean;
+        noOlderThan?: string;
+        kind?: string;
+        lang?: string;
+    }): WatcherResponse;
+    /**
+    * Watch a transaction until it stops pending. Takes three callbacks:
+    * * onMessage - When the transaction comes back as pending_ or incomplete.
+    * * onSuccess - When the transaction comes back as completed / refunded / expired.
+    * * onError - When there's a runtime error, or the transaction comes back as
+    * no_market / too_small / too_large / error.
+    */
+    watchOneTransaction(params: {
+        authToken: string;
+        assetCode: string;
+        id: string;
+        onMessage: (transaction: any) => void;
+        onSuccess: (transaction: any) => void;
+        onError: (error: any) => void;
+        timeout?: number;
+        isRetry?: boolean;
+        lang?: string;
+    }): WatcherResponse;
+}

package/lib/walletSdk/anchor/Types.d.ts

@@ -0,0 +1,76 @@
+import { MemoType } from "stellar-sdk";
+import { Optional } from "utility-types";
+import { TransactionStatus } from "../Watcher/Types";
+export interface AnchorServiceInfo {
+    deposit: {
+        [key: string]: AnchorServiceAsset;
+    };
+    withdraw: {
+        [key: string]: AnchorServiceAsset;
+    };
+    fee: {
+        enabled: boolean;
+    };
+    features: {
+        account_creation: boolean;
+        claimable_balances: boolean;
+    };
+}
+interface BaseTransaction {
+    id: string;
+    kind: string;
+    status: TransactionStatus;
+    more_info_url: string;
+    started_at: string;
+    message?: string;
+}
+interface ProcessingAnchorTransaction extends BaseTransaction {
+    status_eta?: number;
+    kyc_verified?: boolean;
+    amount_in_asset?: string;
+    amount_in: string;
+    amount_out_asset?: string;
+    amount_out: string;
+    amount_fee_asset?: string;
+    amount_fee: string;
+    completed_at?: string;
+    stellar_transaction_id?: string;
+    external_transaction_id?: string;
+    refunds?: Refunds;
+}
+export interface DepositTransaction extends ProcessingAnchorTransaction {
+    from?: string;
+    to?: string;
+    deposit_memo?: string;
+    deposit_memo_type?: MemoType;
+    claimable_balance_id?: string;
+}
+export interface WithdrawTransaction extends ProcessingAnchorTransaction {
+    from: string;
+    to?: string;
+    withdraw_memo?: string;
+    withdraw_memo_type: MemoType;
+    withdraw_anchor_account: string;
+}
+interface ErrorTransaction extends Optional<DepositTransaction & WithdrawTransaction> {
+}
+export type AnchorTransaction = DepositTransaction | WithdrawTransaction | ErrorTransaction;
+interface Payment {
+    id: string;
+    id_type: string;
+    amount: string;
+    fee: string;
+}
+interface Refunds {
+    amount_refunded: string;
+    amount_fee: string;
+    payments: Payment[];
+}
+interface AnchorServiceAsset {
+    enabled: boolean;
+    min_amount: number;
+    max_amount: number;
+    fee_fixed: number;
+    fee_percent: number;
+}
+export {};

package/lib/walletSdk/anchor/index.d.ts

@@ -1,16 +1,87 @@
+import { AxiosInstance } from "axios";
 import { Auth } from "../Auth";
 import { Interactive } from "../interactive";
 import { TomlInfo } from "../toml";
+import { Watcher } from "../Watcher";
+import { Config } from "walletSdk";
+import { AnchorTransaction, AnchorServiceInfo } from "./Types";
+type GetTransactionsParams = {
+    authToken: string;
+    assetCode: string;
+    noOlderThan?: string;
+    limit?: number;
+    kind?: string;
+    pagingId?: string;
+    lang?: string;
+};
 export declare class Anchor {
+    language: string;
+    private cfg;
     private homeDomain;
     private httpClient;
-    private cfg;
-    constructor(cfg: any, homeDomain: string, httpClient: any);
-    getInfo(): Promise<TomlInfo>;
+    private toml;
+    constructor({ cfg, homeDomain, httpClient, language, }: {
+        cfg: Config;
+        homeDomain: string;
+        httpClient: AxiosInstance;
+        language: string;
+    });
+    getInfo(shouldRefresh?: boolean): Promise<TomlInfo>;
     auth(): Promise<Auth>;
     interactive(): Interactive;
-    getServicesInfo(): Promise<any>;
-    getTransaction(): void;
-    getTransactionForAsset(): void;
-    getHistory(): void;
+    watcher(): Watcher;
+    getServicesInfo(lang?: string): Promise<AnchorServiceInfo>;
+    /**
+     * 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
+     */
+    getTransactionBy({ authToken, id, stellarTransactionId, externalTransactionId, lang, }: {
+        authToken: string;
+        id?: string;
+        stellarTransactionId?: string;
+        externalTransactionId?: string;
+        lang?: string;
+    }): Promise<AnchorTransaction>;
+    /**
+     * 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
+     */
+    getTransactionsForAsset(params: GetTransactionsParams): Promise<AnchorTransaction[]>;
+    /**
+     * 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
+     */
+    getHistory(params: GetTransactionsParams): Promise<AnchorTransaction[]>;
 }
+export {};

package/lib/walletSdk/auth/WalletSigner.d.ts

@@ -1,3 +1,6 @@
+import { Keypair, Transaction } from "stellar-sdk";
 export interface WalletSigner {
+    signWithClientAccount(txn: Transaction, account: Keypair): Transaction;
+    signWithDomainAccount(transactionXDR: string, networkPassPhrase: string, account: Keypair): Transaction;
 }
 export declare const DefaultSigner: WalletSigner;

package/lib/walletSdk/auth/index.d.ts

@@ -1,9 +1,12 @@
 import { Keypair } from "stellar-sdk";
+import { WalletSigner } from "./WalletSigner";
 export declare class Auth {
+    private cfg;
     private webAuthEndpoint;
-    constructor(webAuthEndpoint: any);
-    authenticate(accountKp: Keypair, memoId?: string, clientDomain?: string): Promise<any>;
-    challenge(accountKp: Keypair, memoId?: string, clientDomain?: string): Promise<any>;
-    sign(accountKp: Keypair, challengeTx: any, network: any): any;
-    getToken(signedTx: any): Promise<any>;
+    private httpClient;
+    constructor(cfg: any, webAuthEndpoint: any, httpClient: any);
+    authenticate(accountKp: Keypair, walletSigner?: WalletSigner, memoId?: string, clientDomain?: string): Promise<any>;
+    private challenge;
+    private sign;
+    private getToken;
 }

package/lib/walletSdk/exception/index.d.ts

@@ -10,3 +10,12 @@ export declare class InvalidMemoError extends Error {
 export declare class ClientDomainWithMemoError extends Error {
     constructor();
 }
+export declare class MissingTransactionIdError extends Error {
+    constructor();
+}
+export declare class InvalidTransactionResponseError extends Error {
+    constructor(transactionResponse: any);
+}
+export declare class InvalidTransactionsResponseError extends Error {
+    constructor(transactionsResponse: any);
+}

package/lib/walletSdk/horizon/Account.d.ts

@@ -0,0 +1,20 @@
+import { Keypair, Transaction, FeeBumpTransaction } from "stellar-sdk";
+declare class AccountKeypair {
+    keypair: Keypair;
+    constructor(keypair: Keypair);
+    get publicKey(): string;
+    toString(): string;
+}
+export declare class PublicKeypair extends AccountKeypair {
+    keypair: Keypair;
+    constructor(keypair: Keypair);
+    static fromPublicKey: (str: string) => PublicKeypair;
+}
+export declare class SigningKeypair extends AccountKeypair {
+    keypair: Keypair;
+    constructor(keypair: Keypair);
+    static fromSecret: (secret: string) => SigningKeypair;
+    get secretKey(): string;
+    sign(transaction: Transaction | FeeBumpTransaction): Transaction | FeeBumpTransaction;
+}
+export {};

package/lib/walletSdk/horizon/AccountService.d.ts

@@ -0,0 +1,8 @@
+import { SigningKeypair } from "./Account";
+import { Config } from "walletSdk";
+export declare class AccountService {
+    private server;
+    private network;
+    constructor(cfg: Config);
+    createKeypair(): SigningKeypair;
+}

package/lib/walletSdk/horizon/Stellar.d.ts

@@ -1,3 +1,7 @@
+import { AccountService } from "./AccountService";
+import { Config } from "walletSdk";
 export declare class Stellar {
-    constructor(cfg: any);
+    private cfg;
+    constructor(cfg: Config);
+    account(): AccountService;
 }

package/lib/walletSdk/index.d.ts

@@ -1,24 +1,24 @@
 import { Networks, Server } from "stellar-sdk";
+import { AxiosInstance, AxiosRequestConfig } from "axios";
 import { Anchor } from "./Anchor";
 import { WalletSigner } from "./Auth/WalletSigner";
 import { Stellar } from "./horizon/Stellar";
 import { Recovery } from "./recovery/Recovery";
-interface ClientConfigFn {
-}
-interface ClientConfig {
-}
-declare class HttpClient {
+export declare class Config {
+    app: ApplicationConfiguration;
+    stellar: StellarConfiguration;
+    constructor(stellarCfg: any, appCfg: any);
 }
 export declare class Wallet {
     private cfg;
-    private clients;
+    private language;
     static TestNet: () => Wallet;
     static MainNet: () => Wallet;
-    constructor(stellarConfiguration: StellarConfiguration, applicationConfiguration?: ApplicationConfiguration);
-    anchor(homeDomain: string, httpClientConfig?: ClientConfigFn): Anchor;
+    constructor(stellarConfiguration: StellarConfiguration, applicationConfiguration?: ApplicationConfiguration, language?: string);
+    anchor(homeDomain: string, httpClientConfig?: AxiosRequestConfig, language?: string): Anchor;
     stellar(): Stellar;
-    recover(servers: any, httpClientConfig: any): Recovery;
-    getClient(httpClientConfig?: any): any;
+    recover(servers: any, httpClientConfig?: AxiosRequestConfig): Recovery;
+    getClient(httpClientConfig?: AxiosRequestConfig): AxiosInstance;
 }
 export declare class StellarConfiguration {
     server: Server;
@@ -31,7 +31,6 @@ export declare class StellarConfiguration {
 }
 export declare class ApplicationConfiguration {
     defaultSigner: WalletSigner;
-    defaultClient: HttpClient;
-    constructor(defaultSigner?: WalletSigner, defaultCliengConfig?: ClientConfig);
+    defaultClient: AxiosInstance;
+    constructor(defaultSigner?: WalletSigner);
 }
-export {};

package/lib/walletSdk/interactive/index.d.ts

@@ -1,5 +1,13 @@
 type ExtraFields = {
-    [key: string]: string;
+    [api_key: string]: string;
+};
+type InteractiveParams = {
+    accountAddress: string;
+    assetCode: string;
+    authToken: string;
+    lang?: string;
+    extraFields?: ExtraFields;
+    fundsAccountAddress?: string;
 };
 export declare enum FLOW_TYPE {
     DEPOSIT = "deposit",
@@ -8,9 +16,12 @@ export declare enum FLOW_TYPE {
 export declare class Interactive {
     private homeDomain;
     private anchor;
-    constructor(homeDomain: any, anchor: any);
-    deposit(accountAddress: string, assetCode: string, authToken: string, extraFields?: ExtraFields, fundsAccountAddress?: string): Promise<any>;
-    withdraw(accountAddress: string, assetCode: string, authToken: string, extraFields?: ExtraFields, fundsAccountAddress?: string): Promise<any>;
-    flow(accountAddress: string, assetCode: string, authToken: string, type: string, extraFields?: ExtraFields, fundsAccountAddress?: string): Promise<any>;
+    private httpClient;
+    constructor(homeDomain: any, anchor: any, httpClient: any);
+    deposit(params: InteractiveParams): Promise<any>;
+    withdraw(params: InteractiveParams): Promise<any>;
+    flow(params: InteractiveParams & {
+        type: FLOW_TYPE;
+    }): Promise<any>;
 }
 export {};

package/lib/walletSdk/util/camelToSnakeCase.d.ts

@@ -0,0 +1,2 @@
+export declare const camelToSnakeCaseKey: (key: string) => string;
+export declare const camelToSnakeCaseObject: (obj: any) => {};

package/lib/walletSdk/util/sleep.d.ts

@@ -0,0 +1 @@
+export declare function sleep(delay: number): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/typescript-wallet-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.1.0-alpha.1",
   "engines": {
     "node": ">=18"
   },
@@ -14,23 +14,29 @@
     "@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",
     "babel-jest": "^29.4.1",
     "eslint": "^8.33.0",
     "jest": "^29.4.1",
+    "sinon": "^15.1.0",
     "ts-jest": "^29.0.5",
+    "ts-loader": "^9.4.2",
     "tslib": "^2.5.0",
-    "typescript": "^5.0.4"
+    "typescript": "^5.0.4",
+    "webpack": "^5.83.1",
+    "webpack-cli": "^5.1.1"
   },
   "dependencies": {
-    "axios": "^1.3.2",
+    "axios": "^1.4.0",
     "https-browserify": "^1.0.0",
+    "lodash": "^4.17.21",
+    "query-string": "^7.1.3",
     "stellar-sdk": "^10.4.1",
     "stream-http": "^3.2.0",
-    "ts-loader": "^9.4.2",
     "url": "^0.11.0",
     "util": "^0.12.5",
-    "webpack": "^5.83.1",
-    "webpack-cli": "^5.1.1"
+    "utility-types": "^3.10.0"
   },
   "scripts": {
     "prepare": "yarn build",

package/src/walletSdk/Anchor/Types.ts

@@ -0,0 +1,79 @@
+import { MemoType } from "stellar-sdk";
+import { Optional } from "utility-types";
+import { TransactionStatus } from "../Watcher/Types";
+
+export interface AnchorServiceInfo {
+  deposit: { [key: string]: AnchorServiceAsset };
+  withdraw: { [key: string]: AnchorServiceAsset };
+  fee: { enabled: boolean };
+  features: { account_creation: boolean; claimable_balances: boolean };
+}
+
+interface BaseTransaction {
+  id: string;
+  kind: string;
+  status: TransactionStatus;
+  more_info_url: string;
+  started_at: string;
+  message?: string;
+}
+
+interface ProcessingAnchorTransaction extends BaseTransaction {
+  status_eta?: number;
+  kyc_verified?: boolean;
+  amount_in_asset?: string;
+  amount_in: string;
+  amount_out_asset?: string;
+  amount_out: string;
+  amount_fee_asset?: string;
+  amount_fee: string;
+  completed_at?: string;
+  stellar_transaction_id?: string;
+  external_transaction_id?: string;
+  refunds?: Refunds;
+}
+
+export interface DepositTransaction extends ProcessingAnchorTransaction {
+  from?: string;
+  to?: string;
+  deposit_memo?: string;
+  deposit_memo_type?: MemoType;
+  claimable_balance_id?: string;
+}
+
+export interface WithdrawTransaction extends ProcessingAnchorTransaction {
+  from: string;
+  to?: string;
+  withdraw_memo?: string;
+  withdraw_memo_type: MemoType;
+  withdraw_anchor_account: string;
+}
+
+interface ErrorTransaction
+  extends Optional<DepositTransaction & WithdrawTransaction> {}
+
+export type AnchorTransaction =
+  | DepositTransaction
+  | WithdrawTransaction
+  | ErrorTransaction;
+
+interface Payment {
+  id: string;
+  id_type: string;
+  amount: string;
+  fee: string;
+}
+
+interface Refunds {
+  amount_refunded: string;
+  amount_fee: string;
+  payments: Payment[];
+}
+
+interface AnchorServiceAsset {
+  enabled: boolean;
+  min_amount: number;
+  max_amount: number;
+  fee_fixed: number;
+  fee_percent: number;
+}