@metaflux-dex/client 0.0.2 → 0.0.5

package/src/faucet.ts

@@ -0,0 +1,59 @@
+// Devnet / testnet faucet helper.
+//
+// The node exposes a faucet at `POST <faucetBaseUrl>/faucet` that credits an
+// address with test USDC + MTF. It runs on its OWN origin (devnet node port 8080;
+// production `https://faucet.devnet.mtf.exchange`), SEPARATE from the trading
+// API base URL — so `requestFaucet` takes a dedicated `faucetBaseUrl` rather
+// than reusing a `Client`'s trading base URL.
+//
+// The grant is staged for the NEXT block: a 200 response carries
+// `status: "queued"` and the credited balance lands after ~1 block, not
+// synchronously. Devnet / testnet only — mainnet refuses (surfaced as a
+// `MetaFluxApiError`).
+
+import { httpRequest } from './rest/http.js';
+
+/// Successful faucet response (200). `status` is `"queued"` — the credit is
+/// staged for the next block, so the balance updates after ~1 block rather
+/// than synchronously.
+export interface FaucetResponse {
+  /// Echo of the credited address (`0x`-prefixed 20-byte hex).
+  address: string;
+  /// Whole-USDC cross-collateral granted (capped server-side, default 3000).
+  usdc: number;
+  /// MTF spot tokens granted (fixed, default 10).
+  mtf: number;
+  /// Always `"queued"` — credit staged for the next block.
+  status: string;
+}
+
+/// Request test USDC from a devnet / testnet faucet.
+///
+/// POSTs `{ address, amount? }` to `<faucetBaseUrl>/faucet` (grants both USDC and MTF). `amount` is a
+/// whole-USDC integer; omit it for the faucet's full default grant (capped
+/// server-side).
+///
+/// `faucetBaseUrl` is the faucet's OWN origin (e.g. `http://localhost:8080`
+/// on devnet, `https://faucet.devnet.mtf.exchange` in production) — NOT the
+/// trading API base URL.
+///
+/// On success the credit is `"queued"` for the next block; the balance updates
+/// after ~1 block, not synchronously.
+///
+/// Throws `MetaFluxApiError` on a non-2xx status, surfacing the server's
+/// `{ error }` message — notably 429 (rate-limited: per-address once-ever, per-IP
+/// 1/minute), 400 (bad/zero address), 503 (backlog full), or a mainnet refusal.
+export async function requestFaucet(
+  faucetBaseUrl: string,
+  address: string,
+  amount?: number,
+): Promise<FaucetResponse> {
+  const json: { address: string; amount?: number } = { address };
+  if (amount !== undefined) {
+    json.amount = amount;
+  }
+  return httpRequest<FaucetResponse>(faucetBaseUrl, '/faucet', {
+    method: 'POST',
+    json,
+  });
+}

package/src/index.ts

@@ -1,35 +1,81 @@
 // Public barrel — every export consumers see goes through this file.
 //
 // Pinning the public surface here means we can refactor the internal
-// `client.ts` / `wasm.ts` / `http.ts` split without touching anything
-// import-facing. The npm package `exports` map points at the compiled
+// `client.ts` / `wallet/wasm.ts` / `rest/http.ts` split without touching
+// anything import-facing. The npm package `exports` map points at the compiled
 // `dist/index.js`, so consumers write:
 //
 //     import { Client, type Order } from '@metaflux-dex/client';
 
 export { Client, type ClientOpts } from './client.js';
-export { MetaFluxApiError } from './http.js';
+export { MetaFluxApiError } from './rest/http.js';
+export { requestFaucet, type FaucetResponse } from './faucet.js';
 export {
-  // MTF-native signed-action surface (the path the server now accepts).
-  // Exported so power users can build / sign / inspect actions out-of-band.
+  // MTF-native signed-action signing core. Exported so power users can build /
+  // sign / inspect actions out-of-band.
   MTF_CHAIN_ID,
   MTF_MAINNET_CHAIN_ID,
   MTF_TESTNET_CHAIN_ID,
   nativeActionDigest,
-  buildNativeOrderAction,
-  buildNativeCancelAction,
   signNativeAction,
   recoverNativeSigner,
   nativeRequestBody,
-} from './native.js';
+} from './native/digest.js';
+export {
+  // MTF-native action builders — the full real /exchange surface.
+  buildNativeOrderAction,
+  buildNativeCancelAction,
+  buildNativeCancelByCloidAction,
+  buildNativeModifyAction,
+  buildNativeBatchModifyAction,
+  buildNativeBatchOrderAction,
+  buildNativeBatchCancelAction,
+  buildNativeScheduleCancelAction,
+  buildNativeCancelAllOrdersAction,
+  buildNativeSetPositionModeAction,
+  buildNativeTwapOrderAction,
+  buildNativeTwapCancelAction,
+  buildNativeUpdateLeverageAction,
+  buildNativeUpdateIsolatedMarginAction,
+  buildNativeTopUpIsolatedOnlyMarginAction,
+  buildNativeUserPortfolioMarginAction,
+  buildNativeSetDisplayNameAction,
+  buildNativeSetReferrerAction,
+  buildNativeApproveAgentAction,
+  buildNativeApproveBuilderFeeAction,
+  buildNativeConvertToMultiSigUserAction,
+  buildNativeUserDexAbstractionAction,
+  buildNativeUserSetAbstractionAction,
+  buildNativeAgentSetAbstractionAction,
+  buildNativePriorityBidAction,
+  buildNativeTokenDelegateAction,
+  buildNativeClaimRewardsAction,
+  buildNativeLinkStakingUserAction,
+  buildNativeSubmitEncryptedOrderAction,
+  buildNativeCreateVaultAction,
+  buildNativeVaultTransferAction,
+  buildNativeVaultModifyAction,
+  buildNativeVaultWithdrawAction,
+  buildNativeMbWithdrawAction,
+  buildNativeSetMetaliquidityWhitelistAction,
+  buildNativeRegisterMetaliquidityOperatorAction,
+  // Spot CLOB + spot margin (leveraged spot) + Earn (lending pool).
+  buildNativeSpotOrderAction,
+  buildNativeSpotCancelAction,
+  buildNativeSpotMarginDepositAction,
+  buildNativeSpotMarginWithdrawAction,
+  buildNativeSpotMarginOpenAction,
+  buildNativeSpotMarginCloseAction,
+  buildNativeEarnDepositAction,
+  buildNativeEarnWithdrawAction,
+} from './native/actions.js';
 export {
   // MTF-native `/info` read API + the account-ref union (address | account_id).
   InfoApi,
   type AccountRef,
-} from './info.js';
+} from './rest/info.js';
 export type {
-  // MTF-native `/info` response shapes. Source of truth: the node handlers in
-  // `metaflux/crates/api-node/src/rest/info/{reads,markets,hl_parity}.rs` and
+  // MTF-native `/info` response shapes. Source of truth:
   // the KB spec `metaflux-knowledges/api/rest/info.md`. Every field is the exact
   // snake_case key the node emits inside the `{type, data}` envelope's `data`.
   NodeInfo,
@@ -64,6 +110,7 @@ export type {
   // HL-node parity shapes.
   SpotMeta,
   SpotPair,
+  SpotToken,
   SpotClearinghouseState,
   SpotBalance,
   ExchangeStatus,
@@ -99,7 +146,7 @@ export type {
   WebData2,
   WebData2Clearinghouse,
   WebData2Position,
-} from './info-types.js';
+} from './types/info/index.js';
 export {
   // MTF-native WebSocket client + subscription/channel types.
   WsClient,
@@ -109,7 +156,7 @@ export {
   type WsFrame,
   type WsMessageHandler,
   type WsConfig,
-} from './ws.js';
+} from './ws/ws.js';
 export {
   WasmNotBuiltError,
   WasmCallError,
@@ -122,7 +169,7 @@ export {
   eip712TypedDataHash,
   encodeLimitOrder,
   deriveAddressFromPubkey,
-} from './wasm.js';
+} from './wallet/wasm.js';
 export type {
   Order,
   Builder,
@@ -138,9 +185,63 @@ export type {
   NativeCancel,
   NativeBuilder,
   NativeSide,
+  NativePositionSide,
   NativeOrderKind,
   NativeTif,
   NativeStpMode,
+  NativeSetPositionMode,
+  NativeSpotOrder,
+  NativeSpotCancel,
+  NativeSpotMarginDeposit,
+  NativeSpotMarginWithdraw,
+  NativeSpotMarginOpen,
+  NativeSpotMarginClose,
+  NativeEarnDeposit,
+  NativeEarnWithdraw,
   NativeSignedAction,
   NativeExchangeAck,
-} from './types.js';
+  // Order-management actions.
+  OrderGrouping,
+  Modify,
+  BatchModify,
+  BatchOrder,
+  BatchCancel,
+  CancelByCloid,
+  ScheduleCancel,
+  CancelAllOrders,
+  // Account / margin / agent actions.
+  UpdateLeverage,
+  UpdateIsolatedMargin,
+  TopUpIsolatedOnlyMargin,
+  UserPortfolioMargin,
+  SetDisplayName,
+  SetReferrer,
+  ApproveAgent,
+  ApproveBuilderFee,
+  ConvertToMultiSigUser,
+  UserDexAbstraction,
+  UserSetAbstraction,
+  AgentSetAbstraction,
+  PriorityBid,
+  // TWAP.
+  TwapOrder,
+  TwapCancel,
+  // Staking.
+  TokenDelegate,
+  ClaimRewards,
+  LinkStakingUser,
+  // Encrypted orders.
+  SubmitEncryptedOrder,
+  // Vaults.
+  VaultKind,
+  CreateVault,
+  VaultTransfer,
+  VaultModify,
+  VaultWithdraw,
+  // MetaBridge.
+  MbChain,
+  MbWithdraw,
+  // Governance / operator.
+  SetMetaliquidityWhitelist,
+  RegisterMetaliquidityOperator,
+} from './types/index.js';