@bosonprotocol/core-sdk 1.11.0-alpha.8 → 1.11.0

package/src/core-sdk.ts

@@ -29,6 +29,10 @@ export class CoreSDK {
   private _subgraphUrl: string;
   private _protocolDiamond: string;
 
+  /**
+   * Creates an instance of `CoreSDK`
+   * @param args - Constructor args
+   */
   constructor(opts: {
     web3Lib: Web3LibAdapter;
     subgraphUrl: string;
@@ -43,6 +47,22 @@ export class CoreSDK {
     this._theGraphStorage = opts.theGraphStorage;
   }
 
+  /**
+   * Creates an instance of `CoreSDK` by using default values derived either from
+   * `args.envName` or `args.chainId`.
+   *
+   * @example
+   * Instance which uses the default contract address and subgraph url of mainnet:
+   * ```ts
+   * const coreSdk = CoreSDK.fromDefaultConfig({
+   *   ...otherArgs,
+   *   chainId: 137
+   * })
+   * ```
+   *
+   * @param args - Constructor args.
+   * @returns CoreSDK instance with default values.
+   */
   static fromDefaultConfig(args: {
     web3Lib: Web3LibAdapter;
     envName?: string;
@@ -64,6 +84,16 @@ export class CoreSDK {
     });
   }
 
+  /* -------------------------------------------------------------------------- */
+  /*                          Metadata related methods                          */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Stores supported offer metadata via the MetadataStorage instance which was passed in
+   * at construction.
+   * @param metadata - Offer metadata of type `BASE` or `PRODUCT_V1`.
+   * @returns Metadata hash / identifier.
+   */
   public async storeMetadata(metadata: AnyMetadata): Promise<string> {
     if (!this._metadataStorage) {
       throw new Error("No metadata storage set");
@@ -72,6 +102,12 @@ export class CoreSDK {
     return this._metadataStorage.storeMetadata(metadata);
   }
 
+  /**
+   * Returns supported offer metadata from passed in `MetadataStorage` instance.
+   * @param metadataHashOrUri - Metadata hash or uri that can be handled by the
+   * storage instance.
+   * @returns Metadata hash / identifier.
+   */
   public async getMetadata(metadataHashOrUri: string): Promise<AnyMetadata> {
     if (!this._metadataStorage) {
       throw new Error("No metadata storage set");
@@ -80,6 +116,11 @@ export class CoreSDK {
     return this._metadataStorage.getMetadata(metadataHashOrUri);
   }
 
+  /**
+   * Returns `BASE` type offer metadata entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns BaseMetadataEntities from subgraph.
+   */
   public async getBaseMetadataEntities(
     queryVars?: subgraph.GetBaseMetadataEntitiesQueryQueryVariables
   ): Promise<subgraph.BaseMetadataEntityFieldsFragment[]> {
@@ -89,6 +130,11 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns `PRODUCT_V1` type offer metadata entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns ProductV1MetadataEntities from subgraph.
+   */
   public async getProductV1MetadataEntities(
     queryVars?: subgraph.GetProductV1MetadataEntitiesQueryQueryVariables
   ): Promise<subgraph.ProductV1MetadataEntityFieldsFragment[]> {
@@ -98,6 +144,18 @@ export class CoreSDK {
     );
   }
 
+  /* -------------------------------------------------------------------------- */
+  /*                           Account related methods                          */
+  /* -------------------------------------------------------------------------- */
+
+  /* --------------------------------- Seller --------------------------------- */
+
+  /**
+   * Returns seller entity from subgraph.
+   * @param sellerId - ID of seller entity to query for.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entity from subgraph.
+   */
   public async getSellerById(
     sellerId: BigNumberish,
     queryVars?: accounts.subgraph.SingleSellerQueryVariables
@@ -109,6 +167,12 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns seller entity from subgraph.
+   * @param operator - Operator address of seller entity to query for.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entity from subgraph.
+   */
   public async getSellerByOperator(
     operator: string,
     queryVars?: subgraph.GetSellersQueryQueryVariables
@@ -120,6 +184,12 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns seller entity from subgraph.
+   * @param clerk - Clerk address of seller entity to query for.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entity from subgraph.
+   */
   public async getSellerByClerk(
     clerk: string,
     queryVars?: subgraph.GetSellersQueryQueryVariables
@@ -131,6 +201,12 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns seller entity from subgraph. Matches `operator`, `clerk`, `admin` or `treasury`.
+   * @param address - Address of seller entity to query for.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entity from subgraph.
+   */
   public async getSellerByAddress(
     address: string,
     queryVars?: subgraph.GetSellersQueryQueryVariables
@@ -142,12 +218,23 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns seller entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entities from subgraph.
+   */
   public async getSellers(
     queryVars?: subgraph.GetSellersQueryQueryVariables
   ): Promise<subgraph.SellerFieldsFragment[]> {
     return accounts.subgraph.getSellers(this._subgraphUrl, queryVars);
   }
 
+  /**
+   * Creates seller account by calling the `AccountHandlerFacet` contract.
+   * @param sellerToCreate - Addresses to set in the seller account.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
   public async createSeller(
     sellerToCreate: accounts.CreateSellerArgs,
     overrides: Partial<{
@@ -161,6 +248,14 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Creates seller account and offer by calling the `OrchestrationHandlerFacet` contract.
+   * This transaction only succeeds if there is no existing seller account for the connected signer.
+   * @param sellerToCreate - Addresses to set in the seller account.
+   * @param offerToCreate - Offer arguments.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
   public async createSellerAndOffer(
     sellerToCreate: accounts.CreateSellerArgs,
     offerToCreate: offers.CreateOfferArgs,
@@ -178,6 +273,47 @@ export class CoreSDK {
     });
   }
 
+  /* ---------------------------------- Buyer --------------------------------- */
+
+  /**
+   * Returns buyer entity from subgraph.
+   * @param buyerId - ID of buyer entity to query for.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Buyer entity from subgraph.
+   */
+  public async getBuyerById(
+    buyerId: BigNumberish,
+    queryVars?: accounts.subgraph.SingleBuyerQueryVariables
+  ): Promise<subgraph.BuyerFieldsFragment> {
+    return accounts.subgraph.getBuyerById(
+      this._subgraphUrl,
+      buyerId,
+      queryVars
+    );
+  }
+
+  /**
+   * Returns buyer entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Seller entities from subgraph.
+   */
+  public async getBuyers(
+    queryVars?: subgraph.GetBuyersQueryQueryVariables
+  ): Promise<subgraph.BuyerFieldsFragment[]> {
+    return accounts.subgraph.getBuyers(this._subgraphUrl, queryVars);
+  }
+
+  /* -------------------------------------------------------------------------- */
+  /*                            Offer related methods                           */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Creates offer by calling the `OfferHandlerFacet` contract.
+   * This transaction only succeeds if there is an existing seller account for connected signer.
+   * @param offerToCreate - Offer arguments.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
   public async createOffer(
     offerToCreate: offers.CreateOfferArgs,
     overrides: Partial<{
@@ -193,6 +329,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Utility method to retrieve the created `offerId` from logs after calling `createOffer`
+   * or `createOfferAndSeller`.
+   * @param logs - Logs to search in.
+   * @returns Created offer id.
+   */
   public getCreatedOfferIdFromLogs(logs: Log[]): string | null {
     const offerId = getValueFromLogs({
       iface: offers.iface.bosonOfferHandlerIface,
@@ -212,6 +354,13 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Voids an existing offer by calling the `OfferHandlerFacet` contract.
+   * This transaction only succeeds if the connected signer is the `operator`.
+   * @param offerId - ID of offer to void.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
   public async voidOffer(
     offerId: BigNumberish,
     overrides: Partial<{
@@ -226,6 +375,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Returns offer from subgraph.
+   * @param offerId - ID of offer.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Offer entity from subgraph.
+   */
   public async getOfferById(
     offerId: BigNumberish,
     queryVars?: offers.subgraph.SingleOfferQueryVariables
@@ -233,36 +388,27 @@ export class CoreSDK {
     return offers.subgraph.getOfferById(this._subgraphUrl, offerId, queryVars);
   }
 
+  /**
+   * Returns offers from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Offer entities from subgraph.
+   */
   public async getOffers(
     queryVars?: subgraph.GetOffersQueryQueryVariables
   ): Promise<subgraph.OfferFieldsFragment[]> {
     return offers.subgraph.getOffers(this._subgraphUrl, queryVars);
   }
 
-  public async commitToOffer(
-    offerId: BigNumberish,
-    overrides: Partial<{
-      buyer: string;
-    }> = {}
-  ): Promise<TransactionResponse> {
-    return exchanges.handler.commitToOffer({
-      buyer: overrides.buyer || (await this._web3Lib.getSignerAddress()),
-      offerId,
-      web3Lib: this._web3Lib,
-      subgraphUrl: this._subgraphUrl,
-      contractAddress: this._protocolDiamond
-    });
-  }
-
-  public getCommittedExchangeIdFromLogs(logs: Log[]): string | null {
-    return getValueFromLogs({
-      iface: exchanges.iface.bosonExchangeHandlerIface,
-      logs,
-      eventArgsKey: "exchangeId",
-      eventName: "BuyerCommitted"
-    });
-  }
+  /* -------------------------------------------------------------------------- */
+  /*                   ERC20 / Exchange Token related methods                   */
+  /* -------------------------------------------------------------------------- */
 
+  /**
+   * Returns the current allowance of the given token by calling the contract.
+   * @param exchangeToken - Address of exchange token.
+   * @param overrides - Optional overrides.
+   * @returns Allowance for given signer.
+   */
   public async getExchangeTokenAllowance(
     exchangeToken: string,
     overrides: Partial<{
@@ -278,6 +424,11 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Returns `name`, `decimals` and `symbol` of the given token by calling the contract.
+   * @param exchangeToken - Address exchange token.
+   * @returns Decimals, name and symbol.
+   */
   public async getExchangeTokenInfo(exchangeToken: string): Promise<{
     name: string;
     decimals: number;
@@ -296,6 +447,13 @@ export class CoreSDK {
     return { decimals, name, symbol };
   }
 
+  /**
+   * Approves the given amount for the main protocol contract.
+   * @param exchangeToken - Address of token to approve.
+   * @param value - Amount of allowance.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
   public async approveExchangeToken(
     exchangeToken: string,
     value: BigNumberish,
@@ -311,6 +469,17 @@ export class CoreSDK {
     });
   }
 
+  /* -------------------------------------------------------------------------- */
+  /*                            Funds related methods                           */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Deposit funds by calling the `FundsHandlerFacet` contract.
+   * @param sellerId - ID of seller account to deposit funds for.
+   * @param fundsAmount - Amount of funds.
+   * @param fundsTokenAddress - Address of funds token.
+   * @returns Transaction response.
+   */
   public async depositFunds(
     sellerId: BigNumberish,
     fundsAmount: BigNumberish,
@@ -325,6 +494,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Returns funds entity from subgraph.
+   * @param fundsId - ID of funds entity.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Funds entity from subgraph.
+   */
   public async getFundsById(
     fundsId: BigNumberish,
     queryVars?: subgraph.GetFundsByIdQueryVariables
@@ -332,12 +507,24 @@ export class CoreSDK {
     return funds.subgraph.getFundsById(this._subgraphUrl, fundsId, queryVars);
   }
 
+  /**
+   * Returns funds entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Funds entities from subgraph.
+   */
   public async getFunds(
     queryVars?: subgraph.GetFundsQueryVariables
   ): Promise<subgraph.FundsEntityFieldsFragment[]> {
     return funds.subgraph.getFunds(this._subgraphUrl, queryVars);
   }
 
+  /**
+   * Withdraw selected funds by calling the `FundsHandlerFacet` contract.
+   * @param sellerId - ID of seller account to withdraw funds for.
+   * @param tokensToWithdraw - Addresses of funds tokens to withdraw.
+   * @param amountsToWithdraw - Amounts of funds token to withdraw.
+   * @returns Transaction response.
+   */
   public async withdrawFunds(
     sellerId: BigNumberish,
     tokensToWithdraw: Array<string>,
@@ -352,6 +539,11 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Withdraw all available funds by calling the `FundsHandlerFacet` contract.
+   * @param sellerId - ID of seller account to withdraw funds for.
+   * @returns Transaction response.
+   */
   public async withdrawAllAvailableFunds(
     sellerId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -363,6 +555,16 @@ export class CoreSDK {
     });
   }
 
+  /* -------------------------------------------------------------------------- */
+  /*                          Exchange related methods                          */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Returns exchange entity from subgraph.
+   * @param exchangeId - ID of exchange entity.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Exchange entity from subgraph.
+   */
   public async getExchangeById(
     exchangeId: BigNumberish,
     queryVars?: subgraph.GetExchangeByIdQueryQueryVariables
@@ -374,12 +576,59 @@ export class CoreSDK {
     );
   }
 
+  /**
+   * Returns exchange entities from subgraph.
+   * @param queryVars - Optional query variables to skip, order or filter.
+   * @returns Exchange entities from subgraph.
+   */
   public async getExchanges(
     queryVars?: subgraph.GetExchangesQueryQueryVariables
   ): Promise<subgraph.ExchangeFieldsFragment[]> {
     return exchanges.subgraph.getExchanges(this._subgraphUrl, queryVars);
   }
 
+  /**
+   * Commits to an offer by calling the `ExchangeHandlerContract`.
+   * This transaction only succeeds if the seller has deposited funds.
+   * @param offerId - ID of offer to commit to.
+   * @param overrides - Optional overrides.
+   * @returns Transaction response.
+   */
+  public async commitToOffer(
+    offerId: BigNumberish,
+    overrides: Partial<{
+      buyer: string;
+    }> = {}
+  ): Promise<TransactionResponse> {
+    return exchanges.handler.commitToOffer({
+      buyer: overrides.buyer || (await this._web3Lib.getSignerAddress()),
+      offerId,
+      web3Lib: this._web3Lib,
+      subgraphUrl: this._subgraphUrl,
+      contractAddress: this._protocolDiamond
+    });
+  }
+
+  /**
+   * Utility method to retrieve the created `exchangeId` from logs after calling `commitToOffer`.
+   * @param logs - Logs to search in.
+   * @returns Created exchange id.
+   */
+  public getCommittedExchangeIdFromLogs(logs: Log[]): string | null {
+    return getValueFromLogs({
+      iface: exchanges.iface.bosonExchangeHandlerIface,
+      logs,
+      eventArgsKey: "exchangeId",
+      eventName: "BuyerCommitted"
+    });
+  }
+
+  /**
+   * Revokes an existing voucher by calling the `ExchangeHandlerContract`.
+   * Callable by seller `operator`.
+   * @param exchangeId - ID of exchange to revoke.
+   * @returns Transaction response.
+   */
   public async revokeVoucher(
     exchangeId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -391,6 +640,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Cancels an existing voucher by calling the `ExchangeHandlerContract`.
+   * Callable by buyer.
+   * @param exchangeId - ID of exchange to cancel.
+   * @returns Transaction response.
+   */
   public async cancelVoucher(
     exchangeId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -402,6 +657,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Redeems an existing voucher by calling the `ExchangeHandlerContract`.
+   * Callable by buyer.
+   * @param exchangeId - ID of exchange to redeem.
+   * @returns Transaction response.
+   */
   public async redeemVoucher(
     exchangeId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -413,6 +674,12 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Completes an existing voucher by calling the `ExchangeHandlerContract`.
+   * Callable by buyer or seller operator.
+   * @param exchangeId - ID of exchange to complete.
+   * @returns Transaction response.
+   */
   public async completeExchange(
     exchangeId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -424,6 +691,11 @@ export class CoreSDK {
     });
   }
 
+  /**
+   * Expires an existing voucher by calling the `ExchangeHandlerContract`.
+   * @param exchangeId - ID of exchange to expire.
+   * @returns Transaction response.
+   */
   public async expireVoucher(
     exchangeId: BigNumberish
   ): Promise<TransactionResponse> {
@@ -435,6 +707,15 @@ export class CoreSDK {
     });
   }
 
+  /* -------------------------------------------------------------------------- */
+  /*                           Meta Tx related methods                          */
+  /* -------------------------------------------------------------------------- */
+
+  /**
+   * Encodes and signs a meta transaction that can be relayed.
+   * @param args - Meta transaction args.
+   * @returns Signature.
+   */
   public async signExecuteMetaTx(
     args: Omit<
       Parameters<typeof metaTx.handler.signExecuteMetaTx>[0],