types: surface IWalletAccount methods on getAccount + resolve protocol class typedefs

index.js

@@ -20,6 +20,7 @@
 /** @typedef {import('./src/wdk.js').MiddlewareFunction} MiddlewareFunction */
 
 /** @typedef {import('./src/wallet-account-with-protocols.js').IWalletAccountWithProtocols} IWalletAccountWithProtocols */
+/** @typedef {import('./src/wdk.js').WdkAccount} WdkAccount */
 
 /** @typedef {import('./src/policy/index.js').Policy} Policy */
 /** @typedef {import('./src/policy/index.js').PolicyRule} PolicyRule */

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetherto/wdk",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "description": "A flexible manager that can register and manage multiple wallet instances for different blockchains dynamically.",
   "keywords": [
     "wdk",

src/wallet-account-with-protocols.js

@@ -17,24 +17,39 @@
 import { IWalletAccount, NotImplementedError } from '@tetherto/wdk-wallet'
 
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ISwapProtocol} ISwapProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').SwapProtocol} SwapProtocolCtor */
 
 /** @typedef {import('@tetherto/wdk-wallet/protocols').IBridgeProtocol} IBridgeProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').BridgeProtocol} BridgeProtocolCtor */
 
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ILendingProtocol} ILendingProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').LendingProtocol} LendingProtocolCtor */
 
 /** @typedef {import('@tetherto/wdk-wallet/protocols').IFiatProtocol} IFiatProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').FiatProtocol} FiatProtocolCtor */
 
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ISwidgeProtocol} ISwidgeProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').SwidgeProtocol} SwidgeProtocolCtor */
 
-/** @interface */
+/**
+ * Interface for wallet accounts that also expose the WDK's protocol-getter
+ * helpers (`registerProtocol`, `getSwapProtocol`, `getBridgeProtocol`,
+ * `getLendingProtocol`, `getFiatProtocol`, `getSwidgeProtocol`). The
+ * concrete shape is materialized at runtime by `wdk.getAccount` /
+ * `getAccountByPath` after middlewares and protocol getters have been
+ * installed. See `WdkAccount` for the consumer-facing type that pairs
+ * this surface with the underlying `IWalletAccount` shape.
+ *
+ * @interface
+ */
 export class IWalletAccountWithProtocols extends IWalletAccount {
   /**
    * Registers a new protocol for this account
    *
    * The label must be unique in the scope of the account and the type of protocol (i.e., there can’t be two protocols of the same
    * type bound to the same account with the same label).
    *
-   * @template {typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol | typeof FiatProtocol | typeof SwidgeProtocol} P
+   * @template {SwapProtocolCtor | BridgeProtocolCtor | LendingProtocolCtor | FiatProtocolCtor | SwidgeProtocolCtor} P
    * @param {string} label - The label.
    * @param {P} Protocol - The protocol class.
    * @param {ConstructorParameters<P>[1]} config - The protocol configuration.

src/wdk.js

@@ -26,6 +26,15 @@ import PolicyEngine from './policy/policy-engine.js'
 
 /** @typedef {import('./wallet-account-with-protocols.js').IWalletAccountWithProtocols} IWalletAccountWithProtocols */
 
+/**
+ * The shape returned by `getAccount` / `getAccountByPath`: the underlying
+ * IWalletAccount (sendTransaction, signTransaction, transfer, approve,
+ * sign, …) plus the protocol-getter surface added by the WDK at account
+ * retrieval time. Concrete wallet packages may further extend this shape.
+ *
+ * @typedef {IWalletAccount & IWalletAccountWithProtocols} WdkAccount
+ */
+
 /** @typedef {<A extends IWalletAccount>(account: A) => Promise<void>} MiddlewareFunction */
 
 /** @typedef {import('./policy/policy-engine.js').Policy} Policy */
@@ -212,7 +221,7 @@ export default class WDK {
    *
    * @param {string} blockchain - The name of the blockchain (e.g., "ethereum").
    * @param {number} [index] - The index of the account to get (default: 0).
-   * @returns {Promise<IWalletAccountWithProtocols>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
+   * @returns {Promise<WdkAccount>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
    * @throws {Error} If no wallet has been registered for the given blockchain.
    * @throws {PolicyConfigurationError} If a registered policy applies but the underlying wallet account does not implement `toReadOnlyAccount()`.
    */
@@ -237,7 +246,7 @@ export default class WDK {
    *
    * @param {string} blockchain - The name of the blockchain (e.g., "ethereum").
    * @param {string} path - The derivation path (e.g., "0'/0/0").
-   * @returns {Promise<IWalletAccountWithProtocols>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
+   * @returns {Promise<WdkAccount>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
    * @throws {Error} If no wallet has been registered for the given blockchain.
    * @throws {PolicyConfigurationError} If a registered policy applies but the underlying wallet account does not implement `toReadOnlyAccount()`.
    */

types/index.d.ts

@@ -4,6 +4,7 @@ export type IWalletAccountReadOnly = import("@tetherto/wdk-wallet").IWalletAccou
 export type FeeRates = import("./src/wdk.js").FeeRates;
 export type MiddlewareFunction = import("./src/wdk.js").MiddlewareFunction;
 export type IWalletAccountWithProtocols = import("./src/wallet-account-with-protocols.js").IWalletAccountWithProtocols;
+export type WdkAccount = import("./src/wdk.js").WdkAccount;
 export type Policy = import("./src/policy/index.js").Policy;
 export type PolicyRule = import("./src/policy/index.js").PolicyRule;
 export type PolicyCondition = import("./src/policy/index.js").PolicyCondition;

types/src/wallet-account-with-protocols.d.ts

@@ -1,23 +1,38 @@
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ISwapProtocol} ISwapProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').SwapProtocol} SwapProtocolCtor */
 /** @typedef {import('@tetherto/wdk-wallet/protocols').IBridgeProtocol} IBridgeProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').BridgeProtocol} BridgeProtocolCtor */
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ILendingProtocol} ILendingProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').LendingProtocol} LendingProtocolCtor */
 /** @typedef {import('@tetherto/wdk-wallet/protocols').IFiatProtocol} IFiatProtocol */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').FiatProtocol} FiatProtocolCtor */
 /** @typedef {import('@tetherto/wdk-wallet/protocols').ISwidgeProtocol} ISwidgeProtocol */
-/** @interface */
+/** @typedef {typeof import('@tetherto/wdk-wallet/protocols').SwidgeProtocol} SwidgeProtocolCtor */
+/**
+ * Interface for wallet accounts that also expose the WDK's protocol-getter
+ * helpers (`registerProtocol`, `getSwapProtocol`, `getBridgeProtocol`,
+ * `getLendingProtocol`, `getFiatProtocol`, `getSwidgeProtocol`). The
+ * concrete shape is materialized at runtime by `wdk.getAccount` /
+ * `getAccountByPath` after middlewares and protocol getters have been
+ * installed. See `WdkAccount` for the consumer-facing type that pairs
+ * this surface with the underlying `IWalletAccount` shape.
+ *
+ * @interface
+ */
 export class IWalletAccountWithProtocols {
     /**
      * Registers a new protocol for this account
      *
      * The label must be unique in the scope of the account and the type of protocol (i.e., there can’t be two protocols of the same
      * type bound to the same account with the same label).
      *
-     * @template {typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol | typeof FiatProtocol | typeof SwidgeProtocol} P
+     * @template {SwapProtocolCtor | BridgeProtocolCtor | LendingProtocolCtor | FiatProtocolCtor | SwidgeProtocolCtor} P
      * @param {string} label - The label.
      * @param {P} Protocol - The protocol class.
      * @param {ConstructorParameters<P>[1]} config - The protocol configuration.
      * @returns {IWalletAccountWithProtocols} The account.
      */
-    registerProtocol<P extends typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol | typeof FiatProtocol | typeof SwidgeProtocol>(label: string, Protocol: P, config: ConstructorParameters<P>[1]): IWalletAccountWithProtocols;
+    registerProtocol<P extends SwapProtocolCtor | BridgeProtocolCtor | LendingProtocolCtor | FiatProtocolCtor | SwidgeProtocolCtor>(label: string, Protocol: P, config: ConstructorParameters<P>[1]): IWalletAccountWithProtocols;
     /**
      * Returns the swap protocol with the given label.
      *
@@ -60,7 +75,12 @@ export class IWalletAccountWithProtocols {
     getSwidgeProtocol(label: string): ISwidgeProtocol;
 }
 export type ISwapProtocol = import("@tetherto/wdk-wallet/protocols").ISwapProtocol;
+export type SwapProtocolCtor = typeof import("@tetherto/wdk-wallet/protocols").SwapProtocol;
 export type IBridgeProtocol = import("@tetherto/wdk-wallet/protocols").IBridgeProtocol;
+export type BridgeProtocolCtor = typeof import("@tetherto/wdk-wallet/protocols").BridgeProtocol;
 export type ILendingProtocol = import("@tetherto/wdk-wallet/protocols").ILendingProtocol;
+export type LendingProtocolCtor = typeof import("@tetherto/wdk-wallet/protocols").LendingProtocol;
 export type IFiatProtocol = import("@tetherto/wdk-wallet/protocols").IFiatProtocol;
+export type FiatProtocolCtor = typeof import("@tetherto/wdk-wallet/protocols").FiatProtocol;
 export type ISwidgeProtocol = import("@tetherto/wdk-wallet/protocols").ISwidgeProtocol;
+export type SwidgeProtocolCtor = typeof import("@tetherto/wdk-wallet/protocols").SwidgeProtocol;

types/src/wdk.d.ts

@@ -1,6 +1,14 @@
 /** @typedef {import('@tetherto/wdk-wallet').IWalletAccount} IWalletAccount */
 /** @typedef {import('@tetherto/wdk-wallet').FeeRates} FeeRates */
 /** @typedef {import('./wallet-account-with-protocols.js').IWalletAccountWithProtocols} IWalletAccountWithProtocols */
+/**
+ * The shape returned by `getAccount` / `getAccountByPath`: the underlying
+ * IWalletAccount (sendTransaction, signTransaction, transfer, approve,
+ * sign, …) plus the protocol-getter surface added by the WDK at account
+ * retrieval time. Concrete wallet packages may further extend this shape.
+ *
+ * @typedef {IWalletAccount & IWalletAccountWithProtocols} WdkAccount
+ */
 /** @typedef {<A extends IWalletAccount>(account: A) => Promise<void>} MiddlewareFunction */
 /** @typedef {import('./policy/policy-engine.js').Policy} Policy */
 /** @typedef {import('./policy/policy-engine.js').PolicyRule} PolicyRule */
@@ -106,21 +114,21 @@ export default class WDK {
      *
      * @param {string} blockchain - The name of the blockchain (e.g., "ethereum").
      * @param {number} [index] - The index of the account to get (default: 0).
-     * @returns {Promise<IWalletAccountWithProtocols>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
+     * @returns {Promise<WdkAccount>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
      * @throws {Error} If no wallet has been registered for the given blockchain.
      * @throws {PolicyConfigurationError} If a registered policy applies but the underlying wallet account does not implement `toReadOnlyAccount()`.
      */
-    getAccount(blockchain: string, index?: number): Promise<IWalletAccountWithProtocols>;
+    getAccount(blockchain: string, index?: number): Promise<WdkAccount>;
     /**
      * Returns the wallet account for a specific blockchain and BIP-44 derivation path.
      *
      * @param {string} blockchain - The name of the blockchain (e.g., "ethereum").
      * @param {string} path - The derivation path (e.g., "0'/0/0").
-     * @returns {Promise<IWalletAccountWithProtocols>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
+     * @returns {Promise<WdkAccount>} The account. When at least one registered policy targets this account, the returned object is a Proxy that throws `PolicyViolationError` from any wrapped write method whose policy evaluation yields a DENY.
      * @throws {Error} If no wallet has been registered for the given blockchain.
      * @throws {PolicyConfigurationError} If a registered policy applies but the underlying wallet account does not implement `toReadOnlyAccount()`.
      */
-    getAccountByPath(blockchain: string, path: string): Promise<IWalletAccountWithProtocols>;
+    getAccountByPath(blockchain: string, path: string): Promise<WdkAccount>;
     /**
      * Returns the current fee rates for a specific blockchain.
      *
@@ -145,6 +153,13 @@ export default class WDK {
 export type IWalletAccount = import("@tetherto/wdk-wallet").IWalletAccount;
 export type FeeRates = import("@tetherto/wdk-wallet").FeeRates;
 export type IWalletAccountWithProtocols = import("./wallet-account-with-protocols.js").IWalletAccountWithProtocols;
+/**
+ * The shape returned by `getAccount` / `getAccountByPath`: the underlying
+ * IWalletAccount (sendTransaction, signTransaction, transfer, approve,
+ * sign, …) plus the protocol-getter surface added by the WDK at account
+ * retrieval time. Concrete wallet packages may further extend this shape.
+ */
+export type WdkAccount = IWalletAccount & IWalletAccountWithProtocols;
 export type MiddlewareFunction = <A extends IWalletAccount>(account: A) => Promise<void>;
 export type Policy = import("./policy/policy-engine.js").Policy;
 export type PolicyRule = import("./policy/policy-engine.js").PolicyRule;