@avacuscc/sdk 0.1.0 → 0.2.1

package/README.md

@@ -72,9 +72,29 @@ const client = new AvacusClient();
 const result = await client.sns.login({
   walletAddress,
   signMessage,
+  serviceName: 'connect', // optional: 'connect' | 'redirect' | 'gas-sponsor'
 });
+
+`client.sns.login()` now uses `POST /v2/public/users/request_auth_token` and,
+when `serviceName` is provided, builds the signed message with the matching base
+message:
+
+- omitted `serviceName`: Avacus Wallet message (`DEFAULT_BASE_SIGNED_MESSAGE`)
+- `connect`: `BASE_CONNECT_SIGNED_MSG`
+- `redirect`: `BASE_REDIRECT_SIGNED_MSG`
+- `gas-sponsor`: `BASE_GAS_SPONSOR_SIGNED_MSG`
 ```
 
+## Services
+
+`AvacusClient` exposes these service clients:
+
+- `client.sns`
+- `client.gasAccount`
+- `client.balancer`
+
+Most `gasAccount` APIs require a JWT token from `client.sns.login()` first.
+
 ### SNS create user
 
 ```ts
@@ -118,6 +138,253 @@ const profiles = await client.sns.getPublicProfiles({
 });
 ```
 
+## Gas Account service
+
+### Gas Account login prerequisite
+
+Authenticated gas-account APIs require SNS login first:
+
+```ts
+await client.sns.login({
+  walletAddress,
+  signMessage,
+});
+```
+
+### Gas Account summary
+
+```ts
+const summary = await client.gasAccount.getSummary();
+```
+
+### Gas Account stable tokens
+
+```ts
+const tokens = await client.gasAccount.getStableTokens();
+const bscTestnetTokens = await client.gasAccount.getStableTokens(97);
+```
+
+### Gas Account deposit vaults
+
+```ts
+const vaults = await client.gasAccount.getDepositVaults();
+```
+
+### Gas Account whitelist spenders
+
+Get current whitelist and nonce:
+
+```ts
+const whitelist = await client.gasAccount.getWhitelistSpenders();
+```
+
+Recommended helper for register flow:
+
+```ts
+await client.gasAccount.registerWhitelistSpendersWithEthers({
+  owner: wallet.address,
+  spenders: [
+    {
+      address: '0x9876543210987654321098765432109876543210',
+      expiresAt: 0,
+    },
+  ],
+  signer: wallet,
+});
+```
+
+Generic signer helper when you do not want to couple app code to `ethers`:
+
+```ts
+await client.gasAccount.registerWhitelistSpendersWithSignature({
+  owner: wallet.address,
+  spenders: [
+    {
+      address: '0x9876543210987654321098765432109876543210',
+      expiresAt: 0,
+    },
+  ],
+  signTypedData: (typedData) =>
+    wallet.signTypedData(
+      typedData.domain,
+      typedData.types,
+      typedData.message,
+    ),
+});
+```
+
+Low-level flow when you want full control:
+
+```ts
+const { data } = await client.gasAccount.getWhitelistSpenders();
+
+const typedData = client.gasAccount.buildRegisterWhitelistSpendersTypedData({
+  owner: wallet.address,
+  spenders: [
+    {
+      address: '0x9876543210987654321098765432109876543210',
+      expiresAt: 0,
+    },
+  ],
+  nonce: data.nonce,
+  deadline: Math.floor(Date.now() / 1000) + 600,
+});
+
+const signature = await wallet.signTypedData(
+  typedData.domain,
+  typedData.types,
+  typedData.message,
+);
+
+await client.gasAccount.registerWhitelistSpenders({
+  spenders: typedData.message.spenders,
+  nonce: typedData.message.nonce,
+  deadline: typedData.message.deadline,
+  signature,
+});
+```
+
+Remove spenders:
+
+```ts
+await client.gasAccount.removeWhitelistSpenders({
+  spenders: ['0x9876543210987654321098765432109876543210'],
+});
+```
+
+### Gas Account balances
+
+```ts
+const balance = await client.gasAccount.getBalance();
+const detailedBalance = await client.gasAccount.getDetailedBalance();
+const stats = await client.gasAccount.getBalanceStats();
+```
+
+Public batch balances:
+
+```ts
+const balances = await client.gasAccount.getBalances({
+  addresses: [
+    '0x3a0430580303f4De9C5320aC013f14cd92192bfA',
+    '0x610b463d2f57d2e0d9e785a7ff423fbae36f0624',
+  ],
+});
+```
+
+### Gas Account transactions
+
+List transactions:
+
+```ts
+const transactions = await client.gasAccount.listTransactions({
+  page: 1,
+  per: 10,
+  type: 'DEPOSIT',
+  status: 'CONFIRMED',
+});
+```
+
+Get transaction by ID:
+
+```ts
+const transaction = await client.gasAccount.getTransactionById(transactionId);
+```
+
+Create deposit:
+
+```ts
+await client.gasAccount.createDeposit({
+  chainId: 97,
+  amount: '100.00000000',
+  tokenAddress: '0x5bF5121A17e3329D07Ba43f758dEC271D9105132',
+  txHash: '0xe3844e7bc420b2d409058e6bf5534fdba69b917907d691abf65862654df749d7',
+  actor: walletAddress,
+  notes: 'Deposit from wallet',
+});
+```
+
+Use balance for gas:
+
+```ts
+await client.gasAccount.useBalance({
+  toAddress: '0x9876543210987654321098765432109876543210',
+  chainId: 97,
+  gasLimit: 21000,
+  gasPrice: 5,
+  notes: 'Gas for token transfer',
+});
+```
+
+Use balance from another owner's gas account via delegated spender permission:
+
+```ts
+await client.gasAccount.useBalance({
+  toAddress: '0x9876543210987654321098765432109876543210',
+  chainId: 97,
+  gasLimit: 21000,
+  gasPrice: 5,
+  sourceAddress: '0x610b463d2f57d2e0d9e785a7ff423fbae36f0624',
+  notes: 'Use gas from delegated source account',
+});
+```
+
+`sourceAddress` is important for delegated spending flows:
+
+- omit `sourceAddress` to spend from the currently authenticated user's own gas account
+- provide `sourceAddress` to spend from another owner's gas account
+- to make that possible, the owner must first authorize the caller with `registerWhitelistSpenders(...)` or one of the helper methods
+- the logged-in user must already be whitelisted as a spender for that `sourceAddress`
+- when `sourceAddress` is used, the returned balance payload reflects the source owner's balance
+
+Create sponsored transfer:
+
+```ts
+await client.gasAccount.createSponsoredTransfer({
+  transactions: [
+    {
+      tokenAddress: '0x409E7b65eF7B243529e3F97be2A122123c55DE63',
+      from: '0x1234567890123456789012345678901234567890',
+      to: '0x9876543210987654321098765432109876543210',
+      value: '1000000000000000000',
+      validBefore: 1735689600,
+      validAfter: 0,
+      nonce: '0x0000000000000000000000000000000000000000000000000000000000000001',
+      signature: '0x...',
+    },
+  ],
+  chainId: 97,
+  type: 'ADMIN',
+  notes: 'JPYC transfer sponsorship',
+});
+```
+
+Cancel pending transaction:
+
+```ts
+await client.gasAccount.cancelTransaction(transactionId);
+```
+
+Internal funding request:
+
+```ts
+await client.gasAccount.createFundingRequest({
+  sourceAddress: '0x610b463d2f57d2e0d9e785a7ff423fbae36f0624',
+  toAddress: '0x9876543210987654321098765432109876543210',
+  chainId: 97,
+  gasLimit: 21000,
+  gasPrice: 5,
+  notes: 'Gas for token transfer',
+});
+```
+
+## Balancer service
+
+### Get balancer pools
+
+```ts
+const pools = await client.balancer.getPools();
+```
+
 ### SNS-only import
 
 ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@avacuscc/sdk",
-  "version": "0.1.0",
-  "description": "SDK for interacting with services in the Wakumo ecosystem",
+  "version": "0.2.1",
+  "description": "SDK for interacting with Avacuscc services",
   "main": "./packages/sdk/dist/index.js",
   "module": "./packages/sdk/dist/index.mjs",
   "types": "./packages/sdk/dist/index.d.ts",
@@ -22,8 +22,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup packages/sdk/src/index.ts packages/sdk/src/sns.ts --format cjs,esm --dts --clean --out-dir packages/sdk/dist",
-    "dev": "tsup packages/sdk/src/index.ts packages/sdk/src/sns.ts --format cjs,esm --dts --watch --out-dir packages/sdk/dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [],