@avacuscc/sdk 0.1.0

package/README.md

@@ -0,0 +1,216 @@
+# @avacuscc/sdk
+
+TypeScript SDK for Avacus services.
+
+## Features
+
+- `AvacusClient` as the main entrypoint
+- SNS authentication flow in `client.sns`
+- no lock-in to `ethers`
+- login API based on capability: `walletAddress + signMessage`
+- production endpoint by default
+cp examples/basic-typescript/.env.example examples/basic-typescript/.env
+- optional `env: 'dev' | 'stg' | 'prod'` without exposing raw URLs to SDK consumers
+pnpm install
+```
+
+## Build
+
+```bash
+pnpm build
+```
+
+## Usage
+
+### Create client
+
+```ts
+import { AvacusClient } from '@avacuscc/sdk';
+
+const client = new AvacusClient();
+```
+
+By default, the SDK uses the production endpoint.
+
+You can switch environment without knowing the raw URL:
+
+```ts
+const client = new AvacusClient({ env: 'dev' });
+const stgClient = new AvacusClient({ env: 'stg' });
+```
+
+If you pass `baseUrl`, it takes priority over `env`:
+
+```ts
+const client = new AvacusClient({
+  env: 'prod',
+  baseUrl: 'https://your-custom-host/',
+});
+```
+
+Or install just the SNS-focused client via the subpath entrypoint:
+
+```ts
+import { SnsAuthClient } from '@avacuscc/sdk/sns';
+
+const sns = new SnsAuthClient();
+```
+
+Or target a non-production environment:
+
+```ts
+const sns = new SnsAuthClient({ env: 'dev' });
+```
+
+### SNS login
+
+```ts
+import { AvacusClient } from '@avacuscc/sdk';
+
+const client = new AvacusClient();
+
+const result = await client.sns.login({
+  walletAddress,
+  signMessage,
+});
+```
+
+### SNS create user
+
+```ts
+import { AvacusClient } from '@avacuscc/sdk';
+import { Wallet } from 'ethers';
+
+const wallet = Wallet.createRandom();
+
+const client = new AvacusClient({ env: 'dev' });
+
+const result = await client.sns.createUser({
+  walletAddress: wallet.address,
+  signMessage: (message) => wallet.signMessage(message),
+  displayName: 'sdk-user',
+  description: 'Created from SDK',
+  device: {
+    deviceToken: 'device-token',
+    appName: 'Avacus Wallet',
+    appVersion: '1.0.0',
+    platform: 'ios',
+  },
+});
+```
+
+The SDK handles this flow internally:
+
+1. `getNonce(walletAddress)`
+2. build signed message from `DEFAULT_BASE_SIGNED_MESSAGE + nonce`
+3. `signMessage(message)`
+4. `createUserWithSignature({ walletAddress, message, signature, ...profileFields })`
+
+If the create-user response contains a JWT token, the SDK stores it automatically
+so subsequent authenticated service calls can reuse it.
+
+### SNS public profiles
+
+```ts
+const profiles = await client.sns.getPublicProfiles({
+  wallets: [walletAddress],
+  includeDevices: true,
+});
+```
+
+### SNS-only import
+
+```ts
+import { SnsAuthClient } from '@avacuscc/sdk/sns';
+
+const sns = new SnsAuthClient();
+
+const result = await sns.login({
+  walletAddress,
+  signMessage,
+});
+```
+
+The SDK handles this flow internally:
+
+1. `getNonce(walletAddress)`
+2. build signed message from `DEFAULT_BASE_SIGNED_MESSAGE + nonce`
+3. `signMessage(message)`
+4. `requestAuthToken({ wallet_address, message, signature })`
+
+### Ethers example
+
+```ts
+await client.sns.login({
+  walletAddress: await signer.getAddress(),
+  signMessage: (message) => signer.signMessage(message),
+});
+```
+
+### Viem example
+
+```ts
+await client.sns.login({
+  walletAddress: account.address,
+  signMessage: (message) =>
+    walletClient.signMessage({
+      account,
+      message,
+    }),
+});
+```
+
+### Custom signer / KMS example
+
+```ts
+await client.sns.login({
+  walletAddress: kmsWallet.address,
+  signMessage: async (message) => kmsSigner.signMessage(message),
+});
+```
+
+## Low-level SNS APIs
+
+```ts
+const { nonce } = await client.sns.getNonce({ walletAddress });
+
+const result = await client.sns.requestAuthToken({
+  wallet_address: walletAddress,
+  message,
+  signature,
+});
+```
+
+## Examples
+
+See `examples/README.md`.
+
+### Install from package registry
+
+```bash
+yarn add @avacuscc/sdk
+```
+
+Quick commands from the repository root:
+
+```bash
+cp examples/basic-typescript/.env.example examples/basic-typescript/.env
+pnpm build
+pnpm --dir examples/basic-typescript install
+pnpm --dir examples/basic-typescript start
+pnpm --dir examples/basic-typescript create-user
+```
+
+The example uses production by default. Set `AVACUS_BASE_URL` only if you want to override the endpoint.
+
+## Project structure
+
+- `packages/sdk/src/config.ts` — environment-based endpoint resolution
+- `packages/sdk/src/core/client.ts` — main SDK client
+- `packages/sdk/src/services/sns.ts` — SNS auth service
+- `packages/sdk/src/adapters/http.ts` — shared HTTP transport
+
+## Notes
+
+- build output is generated into `packages/sdk/dist`
+- public exports come from `packages/sdk/src/index.ts`

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@avacuscc/sdk",
+  "version": "0.1.0",
+  "description": "SDK for interacting with services in the Wakumo ecosystem",
+  "main": "./packages/sdk/dist/index.js",
+  "module": "./packages/sdk/dist/index.mjs",
+  "types": "./packages/sdk/dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./packages/sdk/dist/index.d.ts",
+      "import": "./packages/sdk/dist/index.mjs",
+      "require": "./packages/sdk/dist/index.js"
+    },
+    "./sns": {
+      "types": "./packages/sdk/dist/sns.d.ts",
+      "import": "./packages/sdk/dist/sns.mjs",
+      "require": "./packages/sdk/dist/sns.js"
+    }
+  },
+  "files": [
+    "packages/sdk/dist",
+    "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",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "longhoang@wakumo.vn",
+  "license": "MIT",
+  "packageManager": "pnpm@10.33.0",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
+  }
+}

package/packages/sdk/dist/chunk-T5BAFYHX.mjs

@@ -0,0 +1,342 @@
+// packages/sdk/src/adapters/http.ts
+var HttpAdapter = class {
+  /**
+   * Creates a reusable HTTP transport bound to one service base URL.
+   *
+   * @param baseUrl Absolute base URL for the target service namespace.
+   * @param headers Default headers sent with every request.
+   * @param authState Shared mutable auth state so multiple adapters can reuse the same JWT.
+   */
+  constructor(baseUrl, headers = {}, authState = {}) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+    this.authState = authState;
+  }
+  baseUrl;
+  headers;
+  authState;
+  /**
+   * Stores the JWT access token used by authenticated requests.
+   *
+   * @param accessToken JWT returned by the authentication flow.
+   */
+  setAccessToken(accessToken) {
+    this.authState.accessToken = accessToken;
+  }
+  /**
+   * Removes the currently stored JWT access token from shared auth state.
+   */
+  clearAccessToken() {
+    delete this.authState.accessToken;
+  }
+  /**
+   * Returns the currently stored JWT access token, if any.
+   */
+  getAccessToken() {
+    return this.authState.accessToken;
+  }
+  /**
+   * Sends an HTTP GET request to a path relative to this adapter base URL.
+   *
+   * @param path Relative endpoint path.
+   * @param options Request behavior such as auth requirement and extra headers.
+   */
+  async get(path, options = {}) {
+    const response = await fetch(this.buildUrl(path), {
+      method: "GET",
+      headers: this.buildHeaders(options)
+    });
+    return this.parseResponse(response, "GET", path);
+  }
+  /**
+   * Sends an HTTP POST request with a JSON body to a path relative to this adapter base URL.
+   *
+   * @param path Relative endpoint path.
+   * @param body Serializable request payload.
+   * @param options Request behavior such as auth requirement and extra headers.
+   */
+  async post(path, body, options = {}) {
+    const response = await fetch(this.buildUrl(path), {
+      method: "POST",
+      headers: this.buildHeaders({
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          ...options.headers
+        }
+      }),
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    return this.parseResponse(response, "POST", path);
+  }
+  /**
+   * Builds the final request headers by combining default headers, per-request
+   * headers, and an authorization header when the request requires auth.
+   */
+  buildHeaders(options) {
+    const accessToken = this.authState.accessToken;
+    if (options.auth && !accessToken) {
+      throw new Error("This request requires authentication. Call login() first.");
+    }
+    return {
+      ...this.headers,
+      ...options.headers,
+      ...options.auth && accessToken ? {
+        Authorization: `Bearer ${accessToken}`
+      } : {}
+    };
+  }
+  /**
+   * Resolves a relative path against the adapter base URL.
+   */
+  buildUrl(path) {
+    const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+    return new URL(normalizedPath, this.baseUrl);
+  }
+  /**
+   * Parses a JSON response and converts non-2xx responses into descriptive errors.
+   */
+  async parseResponse(response, method, path) {
+    const bodyText = await response.text();
+    if (!response.ok) {
+      throw new Error(
+        `HTTP ${response.status} ${response.statusText} for ${method} ${path}: ${bodyText}`
+      );
+    }
+    try {
+      return JSON.parse(bodyText);
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON response for ${method} ${path}: ${bodyText}`,
+        { cause: error }
+      );
+    }
+  }
+};
+
+// packages/sdk/src/config.ts
+var AVACUS_ENDPOINTS = {
+  prod: "https://apis.avacus.cc/",
+  dev: "https://apis.d.avscc.unit-hosting.net/",
+  stg: "https://apis.avacus.cc/stg/"
+};
+function resolveAvacusBaseUrl(options) {
+  if (options.baseUrl) {
+    return options.baseUrl;
+  }
+  return AVACUS_ENDPOINTS[options.env ?? "prod"];
+}
+function resolveClientSettings(options = {}) {
+  return {
+    env: options.env ?? "prod",
+    baseUrl: resolveAvacusBaseUrl(options),
+    headers: options.headers
+  };
+}
+function isKnownAvacusBaseUrl(baseUrl) {
+  return Object.values(AVACUS_ENDPOINTS).includes(baseUrl);
+}
+function resolveServiceUrl(baseUrl, servicePath) {
+  const normalizedServicePath = servicePath.endsWith("/") ? servicePath : `${servicePath}/`;
+  return new URL(normalizedServicePath, baseUrl).toString();
+}
+
+// packages/sdk/src/services/sns.ts
+var DEFAULT_BASE_SIGNED_MESSAGE = "Hi there from Avacus Wallet! Please sign this message to prove that you can access to secure chat. To stop hackers access to your secure chat, do not sign this message outside Avacus Wallet, and here's a unique message ID they can't guess: ";
+var SNS_SERVICE_PATH = "1/secure-chat/";
+var SnsService = class {
+  /**
+   * Creates the SNS service using a service-scoped HTTP adapter.
+   *
+   * @param http Adapter already configured for the SNS base path.
+   * @param options Optional SNS-specific behavior.
+   */
+  constructor(http, options = {}) {
+    this.http = http;
+    this.options = options;
+  }
+  http;
+  options;
+  /**
+   * Requests a one-time nonce used to construct the login signature message.
+   * This endpoint is public and does not require a JWT token.
+   *
+   * @param params Wallet identity used by the backend to mint a nonce.
+   */
+  async getNonce(params) {
+    const searchParams = new URLSearchParams({
+      wallet_address: params.walletAddress
+    });
+    return this.http.get(`v1/public/users/nonce?${searchParams.toString()}`);
+  }
+  /**
+   * Exchanges a signed message payload for an SNS auth token.
+   * This is the low-level authentication endpoint behind `login()`.
+   *
+   * @param params Payload expected by the SNS auth API.
+   */
+  async requestAuthToken(params) {
+    return this.http.post("v1/public/users/request_auth_token", params);
+  }
+  /**
+   * Returns public user profiles for a batch of wallet addresses and/or user IDs.
+   * This endpoint is public and does not require authentication.
+   *
+   * @param params Query payload with wallet addresses and/or user IDs.
+   */
+  async getPublicProfiles(params) {
+    return this.http.post("v1/public/users/profiles", {
+      wallets: params.wallets,
+      user_ids: params.userIds,
+      include_devices: params.includeDevices
+    });
+  }
+  /**
+   * Creates a new SNS user account using only the inputs the application already knows:
+   * wallet address, signer callback, and optional user profile metadata.
+   * The SDK internally fetches a nonce, builds the canonical message, requests
+   * the signature, and submits the create-user payload.
+   *
+   * @param params User creation payload in SDK-friendly camelCase format.
+   */
+  async createUser(params) {
+    const { walletAddress, signMessage } = params;
+    const { nonce } = await this.getNonce({ walletAddress });
+    const message = this.buildLoginMessage(nonce);
+    const signature = await signMessage(message);
+    return this.createUserWithSignature({
+      walletAddress,
+      message,
+      signature,
+      publicKey: params.publicKey,
+      displayName: params.displayName,
+      description: params.description,
+      device: params.device
+    });
+  }
+  /**
+   * Low-level create-user API for callers that already have a prepared message
+   * and signature and want direct control over the exact payload.
+   *
+   * @param params Signed create-user payload.
+   */
+  async createUserWithSignature(params) {
+    const result = await this.http.post(
+      "v1/public/users",
+      {
+        wallet_address: params.walletAddress,
+        message: params.message,
+        signature: params.signature,
+        public_key: params.publicKey,
+        display_name: params.displayName,
+        description: params.description,
+        device: params.device ? {
+          device_token: params.device.deviceToken,
+          app_name: params.device.appName,
+          app_version: params.device.appVersion,
+          platform: params.device.platform
+        } : void 0
+      }
+    );
+    const accessToken = extractAccessToken(result);
+    if (accessToken) {
+      this.http.setAccessToken(accessToken);
+    }
+    return result;
+  }
+  /**
+   * Adapts camelCase SDK parameters to the snake_case payload expected by the backend.
+   *
+   * @param params Wallet address, signed message, and signature returned by the signer.
+   */
+  async authenticate(params) {
+    return this.requestAuthToken({
+      wallet_address: params.walletAddress,
+      message: params.message,
+      signature: params.signature
+    });
+  }
+  /**
+   * Executes the full SNS login flow:
+   * 1. fetch nonce
+   * 2. build login message
+   * 3. sign message via injected signer callback
+   * 4. exchange signature for JWT
+   * 5. persist token in shared HTTP auth state
+   *
+   * @param params Wallet address and async signing callback.
+   */
+  async login(params) {
+    const { walletAddress, signMessage } = params;
+    const { nonce } = await this.getNonce({ walletAddress });
+    const message = this.buildLoginMessage(nonce);
+    const signature = await signMessage(message);
+    const result = await this.authenticate({
+      walletAddress,
+      message,
+      signature
+    });
+    const accessToken = extractAccessToken(result);
+    if (accessToken) {
+      this.http.setAccessToken(accessToken);
+    }
+    return result;
+  }
+  /**
+   * Builds the exact message string that the wallet must sign during login.
+   */
+  buildLoginMessage(nonce) {
+    return `${this.options.baseSignedMessage ?? DEFAULT_BASE_SIGNED_MESSAGE}${nonce}`;
+  }
+};
+function extractAccessToken(result) {
+  const candidateKeys = ["access_token", "accessToken", "token", "jwt"];
+  for (const key of candidateKeys) {
+    const value = result[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+async function loginWithSns(sns, params) {
+  return sns.login(params);
+}
+
+// packages/sdk/src/sns.ts
+var SnsAuthClient = class extends SnsService {
+  settings;
+  usingCustomBaseUrl;
+  constructor(options = {}) {
+    const settings = resolveClientSettings(options);
+    const http = new HttpAdapter(
+      resolveServiceUrl(settings.baseUrl, "1/secure-chat/"),
+      settings.headers
+    );
+    super(http, {
+      baseSignedMessage: options.baseSignedMessage
+    });
+    this.settings = settings;
+    this.usingCustomBaseUrl = !isKnownAvacusBaseUrl(settings.baseUrl);
+  }
+  getSettings() {
+    return { ...this.settings };
+  }
+  isUsingCustomBaseUrl() {
+    return this.usingCustomBaseUrl;
+  }
+};
+
+export {
+  AVACUS_ENDPOINTS,
+  resolveAvacusBaseUrl,
+  resolveClientSettings,
+  isKnownAvacusBaseUrl,
+  resolveServiceUrl,
+  HttpAdapter,
+  DEFAULT_BASE_SIGNED_MESSAGE,
+  SNS_SERVICE_PATH,
+  SnsService,
+  loginWithSns,
+  SnsAuthClient
+};

package/packages/sdk/dist/index.d.mts

@@ -0,0 +1,53 @@
+import { H as HttpAdapter, S as SnsService, B as BaseClientOptions } from './sns-D0rtlsZp.mjs';
+export { A as AVACUS_ENDPOINTS, a as AuthState, b as AvacusEnvironment, D as DEFAULT_BASE_SIGNED_MESSAGE, R as RequestOptions, c as ResolvedClientSettings, d as SNS_SERVICE_PATH, e as SignMessageFn, f as SnsAuthClient, g as SnsAuthClientOptions, h as SnsAuthTokenPayload, i as SnsAuthenticateParams, j as SnsAvatar, k as SnsCreateUserDeviceParams, l as SnsCreateUserParams, m as SnsCreateUserPayload, n as SnsCreateUserResult, o as SnsCreateUserWithSignatureParams, p as SnsDevice, q as SnsGetNonceParams, r as SnsGetProfilesParams, s as SnsLoginParams, t as SnsLoginResult, u as SnsNonceResponse, v as SnsProfile, w as SnsServiceOptions, x as isKnownAvacusBaseUrl, y as loginWithSns, z as resolveAvacusBaseUrl, C as resolveClientSettings, E as resolveServiceUrl } from './sns-D0rtlsZp.mjs';
+
+declare class BalancerService {
+    private readonly http;
+    constructor(http: HttpAdapter);
+    getPools(): Promise<unknown>;
+}
+
+/**
+ * Base path for gas-account endpoints. The client resolves this path against the
+ * selected environment host before creating the service adapter.
+ */
+declare const GAS_ACCOUNT_SERVICE_PATH = "1/gas-account/";
+declare class GasAccountService {
+    private readonly http;
+    /**
+     * Creates the gas-account service using a service-scoped HTTP adapter.
+     *
+     * @param http Adapter already configured for the gas-account base path.
+     */
+    constructor(http: HttpAdapter);
+    /**
+     * Returns the deposit vault address mapping keyed by chain ID.
+     * Requires a JWT token from a successful SNS login.
+     */
+    getDepositVaults(): Promise<unknown>;
+    /**
+     * Returns the authenticated gas-account service status payload.
+     * Requires a JWT token from a successful SNS login.
+     */
+    getStatus(): Promise<unknown>;
+}
+
+interface AvacusClientOptions extends BaseClientOptions {
+}
+declare class AvacusClient {
+    readonly http: HttpAdapter;
+    readonly gasAccountHttp: HttpAdapter;
+    readonly gasAccount: GasAccountService;
+    readonly sns: SnsService;
+    readonly balancer: BalancerService;
+    /**
+     * Creates the root SDK client and wires all service adapters with a shared
+     * auth state so a token obtained from `sns.login()` is reused automatically by
+     * other authenticated services.
+     *
+     * @param options Environment selection, optional host override, and default headers.
+     */
+    constructor(options?: AvacusClientOptions);
+}
+
+export { AvacusClient, type AvacusClientOptions, BalancerService, BaseClientOptions, GAS_ACCOUNT_SERVICE_PATH, GasAccountService, HttpAdapter, SnsService };

package/packages/sdk/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { H as HttpAdapter, S as SnsService, B as BaseClientOptions } from './sns-D0rtlsZp.js';
+export { A as AVACUS_ENDPOINTS, a as AuthState, b as AvacusEnvironment, D as DEFAULT_BASE_SIGNED_MESSAGE, R as RequestOptions, c as ResolvedClientSettings, d as SNS_SERVICE_PATH, e as SignMessageFn, f as SnsAuthClient, g as SnsAuthClientOptions, h as SnsAuthTokenPayload, i as SnsAuthenticateParams, j as SnsAvatar, k as SnsCreateUserDeviceParams, l as SnsCreateUserParams, m as SnsCreateUserPayload, n as SnsCreateUserResult, o as SnsCreateUserWithSignatureParams, p as SnsDevice, q as SnsGetNonceParams, r as SnsGetProfilesParams, s as SnsLoginParams, t as SnsLoginResult, u as SnsNonceResponse, v as SnsProfile, w as SnsServiceOptions, x as isKnownAvacusBaseUrl, y as loginWithSns, z as resolveAvacusBaseUrl, C as resolveClientSettings, E as resolveServiceUrl } from './sns-D0rtlsZp.js';
+
+declare class BalancerService {
+    private readonly http;
+    constructor(http: HttpAdapter);
+    getPools(): Promise<unknown>;
+}
+
+/**
+ * Base path for gas-account endpoints. The client resolves this path against the
+ * selected environment host before creating the service adapter.
+ */
+declare const GAS_ACCOUNT_SERVICE_PATH = "1/gas-account/";
+declare class GasAccountService {
+    private readonly http;
+    /**
+     * Creates the gas-account service using a service-scoped HTTP adapter.
+     *
+     * @param http Adapter already configured for the gas-account base path.
+     */
+    constructor(http: HttpAdapter);
+    /**
+     * Returns the deposit vault address mapping keyed by chain ID.
+     * Requires a JWT token from a successful SNS login.
+     */
+    getDepositVaults(): Promise<unknown>;
+    /**
+     * Returns the authenticated gas-account service status payload.
+     * Requires a JWT token from a successful SNS login.
+     */
+    getStatus(): Promise<unknown>;
+}
+
+interface AvacusClientOptions extends BaseClientOptions {
+}
+declare class AvacusClient {
+    readonly http: HttpAdapter;
+    readonly gasAccountHttp: HttpAdapter;
+    readonly gasAccount: GasAccountService;
+    readonly sns: SnsService;
+    readonly balancer: BalancerService;
+    /**
+     * Creates the root SDK client and wires all service adapters with a shared
+     * auth state so a token obtained from `sns.login()` is reused automatically by
+     * other authenticated services.
+     *
+     * @param options Environment selection, optional host override, and default headers.
+     */
+    constructor(options?: AvacusClientOptions);
+}
+
+export { AvacusClient, type AvacusClientOptions, BalancerService, BaseClientOptions, GAS_ACCOUNT_SERVICE_PATH, GasAccountService, HttpAdapter, SnsService };