refactor: refine decorated client API

Author: cesarenaldi

packages/client/src/actions/account.ts

@@ -55,6 +55,11 @@ export type FetchClosedOnlyModeError =
  * Fetches whether the account is restricted to closed-only trading.
  *
  * @throws {@link FetchClosedOnlyModeError}
+ *
+ * @example
+ * ```ts
+ * const closedOnly = await fetchClosedOnlyMode(client);
+ * ```
  */
 export async function fetchClosedOnlyMode(
   client: SecureClient,
@@ -164,6 +169,13 @@ export type FetchOrderError =
  * Fetches a single order for the authenticated account.
  *
  * @throws {@link FetchOrderError}
+ *
+ * @example
+ * ```ts
+ * const order = await fetchOrder(client, {
+ *   orderId: '123',
+ * });
+ * ```
  */
 export async function fetchOrder(
   client: SecureClient,
@@ -283,6 +295,11 @@ export type DropNotificationsRequest = z.input<
  * Fetches notifications for the authenticated account.
  *
  * @throws {@link FetchNotificationsError}
+ *
+ * @example
+ * ```ts
+ * const notifications = await fetchNotifications(client);
+ * ```
  */
 export async function fetchNotifications(
   client: SecureClient,
@@ -470,6 +487,13 @@ export type FetchOrderScoringError =
  * Fetches whether a single order is currently scoring.
  *
  * @throws {@link FetchOrderScoringError}
+ *
+ * @example
+ * ```ts
+ * const scoring = await fetchOrderScoring(client, {
+ *   orderId: '123',
+ * });
+ * ```
  */
 export async function fetchOrderScoring(
   client: SecureClient,
@@ -506,6 +530,13 @@ export type FetchOrdersScoringError =
  * Fetches scoring state for multiple orders.
  *
  * @throws {@link FetchOrdersScoringError}
+ *
+ * @example
+ * ```ts
+ * const scoring = await fetchOrdersScoring(client, {
+ *   orderIds: ['1', '2'],
+ * });
+ * ```
  */
 export async function fetchOrdersScoring(
   client: SecureClient,
@@ -623,6 +654,13 @@ export type FetchTotalEarningsForUserForDayError =
  * Fetches total earnings for the authenticated account on a given day.
  *
  * @throws {@link FetchTotalEarningsForUserForDayError}
+ *
+ * @example
+ * ```ts
+ * const earnings = await fetchTotalEarningsForUserForDay(client, {
+ *   date: '2026-04-16',
+ * });
+ * ```
  */
 export async function fetchTotalEarningsForUserForDay(
   client: SecureClient,
@@ -746,6 +784,11 @@ export type FetchRewardPercentagesError =
  * Fetches reward percentages for the authenticated account.
  *
  * @throws {@link FetchRewardPercentagesError}
+ *
+ * @example
+ * ```ts
+ * const percentages = await fetchRewardPercentages(client);
+ * ```
  */
 export async function fetchRewardPercentages(
   client: SecureClient,

packages/client/src/actions/approvals.ts

@@ -54,11 +54,15 @@ export type PrepareErc20ApprovalError = UserInputError;
  *
  * @example
  * ```ts
- * const result = await prepareErc20Approval(client, {
+ * const handle = await prepareErc20Approval(client, {
  *   amount: 'max',
  *   spenderAddress: '0x1234…',
  *   tokenAddress: '0x5678…',
- * }).then(completeWith(walletClient));
+ * }).then(completeWith(wallet));
+ *
+ * const outcome = await handle.wait();
+ *
+ * // outcome.transactionHash: TxHash
  * ```
  *
  * @throws {@link PrepareErc20ApprovalError}
@@ -124,10 +128,14 @@ export type PrepareErc1155ApprovalForAllError = UserInputError;
  *
  * @example
  * ```ts
- * const result = await prepareErc1155ApprovalForAll(client, {
+ * const handle = await prepareErc1155ApprovalForAll(client, {
  *   operatorAddress: '0x1234…',
  *   tokenAddress: '0x5678…',
- * }).then(completeWith(walletClient));
+ * }).then(completeWith(wallet));
+ *
+ * const outcome = await handle.wait();
+ *
+ * // outcome.transactionHash: TxHash
  * ```
  *
  * @throws {@link PrepareErc1155ApprovalForAllError}
@@ -193,7 +201,11 @@ export type PrepareTradingApprovalsError = UserInputError;
  *
  * @example
  * ```ts
- * const result = await prepareTradingApprovals(client).then(completeWith(walletClient));
+ * const handle = await prepareTradingApprovals(client).then(completeWith(wallet));
+ *
+ * const outcome = await handle.wait();
+ *
+ * // outcome.transactionHash: TxHash
  * ```
  *
  * @throws {@link PrepareTradingApprovalsError}

packages/client/src/actions/clob.test.ts

@@ -13,13 +13,13 @@ import {
   fetchOrderBook,
   fetchOrderBooks,
   fetchPrice,
+  fetchPriceHistory,
   fetchPrices,
   fetchSpread,
   fetchSpreads,
   fetchTickSize,
   listCurrentRewards,
   listMarketRewards,
-  listPriceHistory,
 } from './clob';
 import { listMarkets } from './markets';
 
@@ -201,11 +201,11 @@ describe('CLOB', () => {
     });
   });
 
-  describe('listPriceHistory', () => {
+  describe('fetchPriceHistory', () => {
     it('lists historical price points for a token', async () => {
       const tokenId = await selectLiquidClobTokenId();
 
-      const result = await listPriceHistory(publicClient, {
+      const result = await fetchPriceHistory(publicClient, {
         tokenId,
         interval: PriceHistoryInterval.ONE_DAY,
         fidelity: 60,

packages/client/src/actions/clob.ts

@@ -690,39 +690,39 @@ const ListPriceHistoryRequestSchema = z.object({
   interval: PriceHistoryIntervalSchema.optional(),
 });
 
-export type ListPriceHistoryRequest = z.input<
+export type FetchPriceHistoryRequest = z.input<
   typeof ListPriceHistoryRequestSchema
 >;
 
-export type ListPriceHistoryError =
+export type FetchPriceHistoryError =
   | RateLimitError
   | RequestRejectedError
   | TransportError
   | UnexpectedResponseError
   | UserInputError;
 
 /**
- * Lists historical price points for a token.
+ * Fetches historical price points for a token.
  *
- * @throws {@link ListPriceHistoryError}
+ * @throws {@link FetchPriceHistoryError}
  * Thrown on failure.
  *
  * @example
  * ```ts
- * const history = await listPriceHistory(client, {
+ * const history = await fetchPriceHistory(client, {
  *   tokenId:
  *     '8501497159083948713316135768103773293754490207922884688769443031624417212426',
  *   interval: PriceHistoryInterval.ONE_DAY,
  *   fidelity: 60,
  * });
  *
- * // history[0] === { t: 1775653225, p: 0.535 }
+ * // history === PriceHistoryPoint[]
  * ```
  *
  */
-export async function listPriceHistory(
+export async function fetchPriceHistory(
   client: Client,
-  request: ListPriceHistoryRequest,
+  request: FetchPriceHistoryRequest,
 ): Promise<PriceHistoryPoint[]> {
   const params = parseUserInput(request, ListPriceHistoryRequestSchema);
   const response = await unwrap(

packages/client/src/actions/gasless.ts

@@ -148,6 +148,13 @@ export type IsGaslessReadyError =
  *
  * @throws {@link IsGaslessReadyError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const ready = await isGaslessReady(client, {
+ *   wallet: '0x1234...',
+ * });
+ * ```
  */
 export async function isGaslessReady(
   client: Client,
@@ -192,6 +199,15 @@ export type PrepareGaslessWalletError =
  *
  * @throws {@link PrepareGaslessWalletError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const handle = await prepareGaslessWallet(client).then(completeWith(wallet));
+ *
+ * const outcome = await handle.wait();
+ *
+ * // outcome.transactionHash: TxHash
+ * ```
  */
 export async function prepareGaslessWallet(
   client: Client,

packages/client/src/actions/orders/cancel.ts

@@ -52,6 +52,15 @@ export type CancelOrderError =
  *
  * @throws {@link CancelOrderError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const response = await cancelOrder(client, {
+ *   orderId: '123',
+ * });
+ *
+ * // response.canceled: string[]
+ * ```
  */
 export async function cancelOrder(
   client: SecureClient,
@@ -78,6 +87,15 @@ export type CancelOrdersError =
  *
  * @throws {@link CancelOrdersError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const response = await cancelOrders(client, {
+ *   orderIds: ['1', '2'],
+ * });
+ *
+ * // response.canceled: string[]
+ * ```
  */
 export async function cancelOrders(
   client: SecureClient,
@@ -100,6 +118,13 @@ export type CancelAllError =
  *
  * @throws {@link CancelAllError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const response = await cancelAll(client);
+ *
+ * // response.canceled: string[]
+ * ```
  */
 export async function cancelAll(
   client: SecureClient,
@@ -124,6 +149,15 @@ export type CancelMarketOrdersError =
  *
  * @throws {@link CancelMarketOrdersError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const response = await cancelMarketOrders(client, {
+ *   market: '0x0000000000000000000000000000000000000000000000000000000000000001',
+ * });
+ *
+ * // response.canceled: string[]
+ * ```
  */
 export async function cancelMarketOrders(
   client: SecureClient,

packages/client/src/actions/orders/prepare.ts

@@ -53,6 +53,19 @@ export type PrepareMarketOrderError =
  *
  * @throws {@link PrepareMarketOrderError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const order = await prepareMarketOrder(client, {
+ *   amount: 10,
+ *   side: OrderSide.BUY,
+ *   tokenId: '123',
+ * }).then(completeWith(wallet));
+ *
+ * const response = await postOrder(client, order);
+ *
+ * // response: OrderResponse
+ * ```
  */
 export async function prepareMarketOrder(
   client: SecureClient,
@@ -88,6 +101,20 @@ export type PrepareLimitOrderError =
  *
  * @throws {@link PrepareLimitOrderError}
  * Thrown on failure.
+ *
+ * @example
+ * ```ts
+ * const order = await prepareLimitOrder(client, {
+ *   price: 0.52,
+ *   side: OrderSide.BUY,
+ *   size: 10,
+ *   tokenId: '123',
+ * }).then(completeWith(wallet));
+ *
+ * const response = await postOrder(client, order);
+ *
+ * // response: OrderResponse
+ * ```
  */
 export async function prepareLimitOrder(
   client: SecureClient,