@vaultkey/sdk 1.0.0

package/dist/index.mjs

@@ -0,0 +1,454 @@
+// src/signing.ts
+var Signing = class {
+  constructor(client, walletId) {
+    this.client = client;
+    this.walletId = walletId;
+  }
+  /**
+   * Sign an EVM message or typed data (EIP-712).
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.signing("wallet_id").evmMessage({
+   *   payload: { message: "Hello from VaultKey" },
+   * });
+   * // Poll: await vaultkey.jobs.get(data.jobId)
+   */
+  async evmMessage(params) {
+    const { idempotencyKey, ...rest } = params;
+    return this.client.post(
+      `/wallets/${this.walletId}/sign/message/evm`,
+      {
+        payload: rest.payload,
+        idempotency_key: idempotencyKey
+      }
+    );
+  }
+  /**
+   * Sign a Solana message.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.signing("wallet_id").solanaMessage({
+   *   payload: { message: "Hello from VaultKey" },
+   * });
+   */
+  async solanaMessage(params) {
+    const { idempotencyKey, ...rest } = params;
+    return this.client.post(
+      `/wallets/${this.walletId}/sign/message/solana`,
+      {
+        payload: rest.payload,
+        idempotency_key: idempotencyKey
+      }
+    );
+  }
+};
+
+// src/wallets.ts
+var Wallets = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new wallet for a user.
+   *
+   * @example
+   * const { data, error } = await vaultkey.wallets.create({
+   *   userId: "user_123",
+   *   chainType: "evm",
+   *   label: "Primary wallet",
+   * });
+   */
+  async create(params) {
+    const body = {
+      user_id: params.userId,
+      chain_type: params.chainType
+    };
+    if (params.label) body.label = params.label;
+    return this.client.post("/wallets", body);
+  }
+  /**
+   * Retrieve a wallet by its ID.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.get("wallet_abc123");
+   */
+  async get(walletId) {
+    return this.client.get(`/wallets/${walletId}`);
+  }
+  /**
+   * List all wallets belonging to a user.
+   * Results are paginated — use `nextCursor` to fetch the next page.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.listByUser("user_123");
+   * // Next page:
+   * const { data: page2 } = await vaultkey.wallets.listByUser("user_123", {
+   *   after: data.nextCursor,
+   * });
+   */
+  async listByUser(userId, pagination) {
+    const params = new URLSearchParams();
+    if (pagination?.after) params.set("after", pagination.after);
+    if (pagination?.limit) params.set("limit", String(pagination.limit));
+    const qs = params.toString();
+    return this.client.get(
+      `/users/${userId}/wallets${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * Returns a signing interface scoped to the given wallet.
+   * Use this to sign EVM or Solana messages.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets
+   *   .signing("wallet_id")
+   *   .evmMessage({ payload: { message: "Hello" } });
+   */
+  signing(walletId) {
+    return new Signing(this.client, walletId);
+  }
+  /**
+   * Get the native token balance for an EVM wallet.
+   * Provide chainName (preferred) or chainId.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.evmBalance("wallet_id", {
+   *   chainName: "base",
+   * });
+   * console.log(data.balance); // "0.05"
+   */
+  async evmBalance(walletId, chain) {
+    const params = new URLSearchParams();
+    if ("chainName" in chain && chain.chainName) {
+      params.set("chain_name", chain.chainName);
+    } else if ("chainId" in chain && chain.chainId) {
+      params.set("chain_id", chain.chainId);
+    }
+    return this.client.get(
+      `/wallets/${walletId}/balance/evm?${params.toString()}`
+    );
+  }
+  /**
+   * Get the SOL balance for a Solana wallet.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.solanaBalance("wallet_id");
+   * console.log(data.balance); // "1.5"
+   */
+  async solanaBalance(walletId) {
+    return this.client.get(
+      `/wallets/${walletId}/balance/solana`
+    );
+  }
+  /**
+   * Broadcast a pre-signed EVM transaction.
+   * Provide chainName (preferred) or chainId.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.broadcastEVM("wallet_id", {
+   *   signedTx: "0x...",
+   *   chainName: "base",
+   * });
+   * console.log(data.txHash);
+   */
+  async broadcastEVM(walletId, params) {
+    const body = { signed_tx: params.signedTx };
+    if ("chainName" in params && params.chainName) {
+      body.chain_name = params.chainName;
+    } else if ("chainId" in params && params.chainId) {
+      body.chain_id = params.chainId;
+    }
+    return this.client.post(
+      `/wallets/${walletId}/broadcast`,
+      body
+    );
+  }
+  /**
+   * Broadcast a pre-signed Solana transaction.
+   *
+   * @example
+   * const { data } = await vaultkey.wallets.broadcastSolana("wallet_id", {
+   *   signedTx: "base58encodedtx...",
+   * });
+   * console.log(data.signature);
+   */
+  async broadcastSolana(walletId, params) {
+    return this.client.post(
+      `/wallets/${walletId}/broadcast`,
+      { signed_tx: params.signedTx }
+    );
+  }
+  /**
+   * Trigger a sweep — move all funds from this wallet to the configured
+   * master wallet. The operation is asynchronous; poll via `vaultkey.jobs.get`.
+   *
+   * @example
+   * // EVM sweep
+   * const { data } = await vaultkey.wallets.sweep("wallet_id", {
+   *   chainType: "evm",
+   *   chainName: "base",
+   * });
+   *
+   * // Solana sweep
+   * const { data } = await vaultkey.wallets.sweep("wallet_id", {
+   *   chainType: "solana",
+   * });
+   */
+  async sweep(walletId, params) {
+    const body = {
+      chain_type: params.chainType
+    };
+    if (params.chainType === "evm") {
+      if (params.chainName) {
+        body.chain_name = params.chainName;
+      } else if (params.chainId) {
+        body.chain_id = params.chainId;
+      }
+    }
+    return this.client.post(`/wallets/${walletId}/sweep`, body);
+  }
+};
+
+// src/jobs.ts
+var Jobs = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Retrieve the current state of an async job.
+   *
+   * @example
+   * const { data, error } = await vaultkey.jobs.get("job_abc123");
+   * if (data?.status === "completed") {
+   *   console.log("Done!", data.result);
+   * }
+   */
+  async get(jobId) {
+    return this.client.get(`/jobs/${jobId}`);
+  }
+};
+
+// src/stablecoin.ts
+var Stablecoin = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Transfer a stablecoin from a wallet.
+   *
+   * - For EVM: provide chainName (preferred) or chainId.
+   * - For Solana: omit chainName and chainId.
+   * - The operation is async — poll `vaultkey.jobs.get(data.jobId)`.
+   * - Use `idempotencyKey` to safely retry without double-sending.
+   *
+   * @example
+   * // EVM (gasless)
+   * const { data } = await vaultkey.stablecoin.transfer("wallet_id", {
+   *   token: "usdc",
+   *   to: "0xRecipient",
+   *   amount: "100.00",
+   *   chainType: "evm",
+   *   chainName: "base",
+   *   gasless: true,
+   *   speed: "fast",
+   * });
+   *
+   * // Solana
+   * const { data } = await vaultkey.stablecoin.transfer("wallet_id", {
+   *   token: "usdc",
+   *   to: "RecipientBase58",
+   *   amount: "100.00",
+   *   chainType: "solana",
+   * });
+   */
+  async transfer(walletId, params) {
+    const body = {
+      token: params.token,
+      to: params.to,
+      amount: params.amount
+    };
+    if (params.chainType === "evm") {
+      if (params.chainName) {
+        body.chain_name = params.chainName;
+      } else if (params.chainId) {
+        body.chain_id = params.chainId;
+      }
+    }
+    if (params.gasless !== void 0) body.gasless = params.gasless;
+    if (params.speed) body.speed = params.speed;
+    if (params.idempotencyKey) body.idempotency_key = params.idempotencyKey;
+    return this.client.post(
+      `/wallets/${walletId}/stablecoin/transfer/${params.chainType}`,
+      body
+    );
+  }
+  /**
+   * Get the stablecoin balance for a wallet.
+   *
+   * - For EVM: provide chainName (preferred) or chainId.
+   * - For Solana: omit chainName and chainId.
+   *
+   * @example
+   * const { data } = await vaultkey.stablecoin.balance("wallet_id", {
+   *   token: "usdc",
+   *   chainType: "evm",
+   *   chainName: "polygon",
+   * });
+   * console.log(data.balance); // "50.00"
+   */
+  async balance(walletId, params) {
+    const query = { token: params.token };
+    if (params.chainType === "evm") {
+      if (params.chainName) {
+        query.chain_name = params.chainName;
+      } else if (params.chainId) {
+        query.chain_id = params.chainId;
+      }
+    }
+    const qs = new URLSearchParams(
+      Object.entries(query).filter(([, v]) => v !== void 0)
+    ).toString();
+    return this.client.get(
+      `/wallets/${walletId}/stablecoin/balance/${params.chainType}?${qs}`
+    );
+  }
+};
+
+// src/chains.ts
+var Chains = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List all supported EVM chains for the current environment
+   * (testnet or mainnet, determined by your API key).
+   *
+   * @example
+   * const { data, error } = await vaultkey.chains.list();
+   */
+  async list() {
+    return this.client.get("/chains");
+  }
+};
+
+// src/vaultkey.ts
+var MAINNET_BASE_URL = "https://app.vaultkeys.com";
+var TESTNET_BASE_URL = "https://testnet.vaultkeys.com";
+function resolveBaseUrl(apiKey, override) {
+  if (override) return override;
+  return apiKey.startsWith("testnet_") ? TESTNET_BASE_URL : MAINNET_BASE_URL;
+}
+function isVaultKeyErrorResponse(resp) {
+  return typeof resp === "object" && resp !== null && "error" in resp && typeof resp.error === "object";
+}
+var VaultKey = class {
+  apiKey;
+  apiSecret;
+  baseUrl;
+  /** Wallet management — create, retrieve, and list wallets. */
+  wallets;
+  /** Async job polling — check the status of signing and sweep operations. */
+  jobs;
+  /** Stablecoin transfers and balance lookups (USDC, USDT). */
+  stablecoin;
+  /** Chain discovery — list supported EVM chains for the current environment. */
+  chains;
+  constructor(config = {}) {
+    const apiKey = config.apiKey ?? (typeof process !== "undefined" ? process.env?.VAULTKEY_API_KEY : void 0);
+    const apiSecret = config.apiSecret ?? (typeof process !== "undefined" ? process.env?.VAULTKEY_API_SECRET : void 0);
+    if (!apiKey) {
+      throw new Error(
+        'Missing API key. Pass it via config: new VaultKey({ apiKey: "vk_live_..." }) or set the VAULTKEY_API_KEY environment variable.'
+      );
+    }
+    if (!apiSecret) {
+      throw new Error(
+        'Missing API secret. Pass it via config: new VaultKey({ apiSecret: "..." }) or set the VAULTKEY_API_SECRET environment variable.'
+      );
+    }
+    this.apiKey = apiKey;
+    this.apiSecret = apiSecret;
+    this.baseUrl = `${resolveBaseUrl(apiKey, config.baseUrl)}/api/v1/sdk`;
+    this.wallets = new Wallets(this);
+    this.jobs = new Jobs(this);
+    this.stablecoin = new Stablecoin(this);
+    this.chains = new Chains(this);
+  }
+  async fetchRequest(path, options = {}) {
+    const headers = new Headers({
+      "Content-Type": "application/json",
+      "X-API-Key": this.apiKey,
+      "X-API-Secret": this.apiSecret,
+      ...Object.fromEntries(new Headers(options.headers ?? {}))
+    });
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers
+    });
+    const defaultError = {
+      code: "INTERNAL_SERVER_ERROR",
+      message: response.statusText
+    };
+    if (!response.ok) {
+      try {
+        const body = await response.json();
+        if (isVaultKeyErrorResponse(body)) {
+          return { data: null, error: body.error };
+        }
+        if (typeof body?.error === "string") {
+          return {
+            data: null,
+            error: { code: String(response.status), message: body.error }
+          };
+        }
+        return { data: null, error: defaultError };
+      } catch {
+        return { data: null, error: defaultError };
+      }
+    }
+    const data = await response.json();
+    return { data, error: null };
+  }
+  async get(path, options) {
+    return this.fetchRequest(path, {
+      method: "GET",
+      headers: options?.headers
+    });
+  }
+  async post(path, body, options) {
+    return this.fetchRequest(path, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: options?.headers
+    });
+  }
+  async put(path, body, options) {
+    return this.fetchRequest(path, {
+      method: "PUT",
+      body: JSON.stringify(body),
+      headers: options?.headers
+    });
+  }
+  async patch(path, body, options) {
+    return this.fetchRequest(path, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+      headers: options?.headers
+    });
+  }
+  async delete(path, body, options) {
+    return this.fetchRequest(path, {
+      method: "DELETE",
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      headers: options?.headers
+    });
+  }
+};
+export {
+  Chains,
+  Jobs,
+  Signing,
+  Stablecoin,
+  VaultKey,
+  Wallets
+};

package/examples/usage.ts

@@ -0,0 +1,221 @@
+/**
+ * VaultKey SDK — Example Usage
+ *
+ * Run with: npx tsx examples/usage.ts
+ * Make sure VAULTKEY_API_KEY and VAULTKEY_API_SECRET are set in your environment.
+ */
+
+import { VaultKey } from "@vaultkey/sdk";
+
+const vk = new VaultKey({
+  apiKey: process.env.VAULTKEY_API_KEY,
+  apiSecret: process.env.VAULTKEY_API_SECRET,
+});
+
+// ---------------------------------------------------------------------------
+// Helper: poll a job until completed or failed
+// ---------------------------------------------------------------------------
+
+async function pollJob(jobId: string, intervalMs = 1000) {
+  console.log(`  Polling job ${jobId}...`);
+  while (true) {
+    const { data, error } = await vk.jobs.get(jobId);
+    if (error) throw new Error(`Job poll failed: ${error.message}`);
+    console.log(`  status: ${data.status}`);
+    if (data.status === "completed") return data;
+    if (data.status === "failed") throw new Error(`Job failed: ${data.error}`);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Create wallets
+// ---------------------------------------------------------------------------
+
+async function createWallets() {
+  console.log("\n── Create Wallets ──────────────────────────────────────────");
+
+  const { data: evmWallet, error: evmErr } = await vk.wallets.create({
+    userId: "user_123",
+    chainType: "evm",
+    label: "Primary EVM wallet",
+  });
+  if (evmErr) throw new Error(evmErr.message);
+  console.log("EVM wallet created:", evmWallet.id, evmWallet.address);
+
+  const { data: solWallet, error: solErr } = await vk.wallets.create({
+    userId: "user_123",
+    chainType: "solana",
+  });
+  if (solErr) throw new Error(solErr.message);
+  console.log("Solana wallet created:", solWallet.id, solWallet.address);
+
+  return { evmWallet, solWallet };
+}
+
+// ---------------------------------------------------------------------------
+// 2. List wallets for a user
+// ---------------------------------------------------------------------------
+
+async function listWallets(userId: string) {
+  console.log("\n── List Wallets ────────────────────────────────────────────");
+
+  const { data, error } = await vk.wallets.listByUser(userId);
+  if (error) throw new Error(error.message);
+
+  console.log(`Found ${data.wallets.length} wallet(s) for user ${userId}`);
+  for (const w of data.wallets) {
+    console.log(`  ${w.id}  ${w.chainType}  ${w.address}`);
+  }
+
+  if (data.hasMore) {
+    console.log("  (more pages available — use data.nextCursor to fetch)");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 3. Check balances
+// ---------------------------------------------------------------------------
+
+async function checkBalances(evmWalletId: string, solWalletId: string) {
+  console.log("\n── Balances ────────────────────────────────────────────────");
+
+  // EVM — prefer chain name over chain ID
+  const { data: evmBal, error: evmErr } = await vk.wallets.evmBalance(
+    evmWalletId,
+    { chainName: "base-sepolia" }
+  );
+  if (evmErr) throw new Error(evmErr.message);
+  console.log(`EVM balance: ${evmBal.balance} ${evmBal.symbol} on ${evmBal.chainName}`);
+
+  // Solana
+  const { data: solBal, error: solErr } = await vk.wallets.solanaBalance(solWalletId);
+  if (solErr) throw new Error(solErr.message);
+  console.log(`Solana balance: ${solBal.balance} ${solBal.symbol}`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Sign messages
+// ---------------------------------------------------------------------------
+
+async function signMessages(evmWalletId: string, solWalletId: string) {
+  console.log("\n── Sign Messages ───────────────────────────────────────────");
+
+  // EVM message signing
+  const { data: evmJob, error: evmErr } = await vk.wallets
+    .signing(evmWalletId)
+    .evmMessage({
+      payload: { message: "Hello from VaultKey" },
+      idempotencyKey: "sign-evm-001",
+    });
+  if (evmErr) throw new Error(evmErr.message);
+  console.log("EVM sign job created:", evmJob.jobId);
+  const evmResult = await pollJob(evmJob.jobId);
+  console.log("EVM sign result:", evmResult.result);
+
+  // Solana message signing
+  const { data: solJob, error: solErr } = await vk.wallets
+    .signing(solWalletId)
+    .solanaMessage({
+      payload: { data: Buffer.from("Hello from VaultKey").toString("base64") },
+    });
+  if (solErr) throw new Error(solErr.message);
+  console.log("Solana sign job created:", solJob.jobId);
+  await pollJob(solJob.jobId);
+}
+
+// ---------------------------------------------------------------------------
+// 5. Stablecoin transfer
+// ---------------------------------------------------------------------------
+
+async function stablecoinTransfer(evmWalletId: string) {
+  console.log("\n── Stablecoin Transfer ─────────────────────────────────────");
+
+  // EVM USDC transfer (gasless — relayer pays gas)
+  const { data, error } = await vk.stablecoin.transfer(evmWalletId, {
+    token: "usdc",
+    to: "0xRecipientAddress",
+    amount: "10.00",
+    chainType: "evm",
+    chainName: "base-sepolia",
+    gasless: true,
+    speed: "normal",
+    idempotencyKey: "transfer-usdc-001",
+  });
+  if (error) throw new Error(error.message);
+  console.log("Transfer job created:", data.jobId);
+  await pollJob(data.jobId);
+
+  // Check balance after
+  const { data: bal } = await vk.stablecoin.balance(evmWalletId, {
+    token: "usdc",
+    chainType: "evm",
+    chainName: "base-sepolia",
+  });
+  console.log(`USDC balance after transfer: ${bal.balance} ${bal.symbol}`);
+}
+
+// ---------------------------------------------------------------------------
+// 6. Sweep
+// ---------------------------------------------------------------------------
+
+async function sweep(evmWalletId: string, solWalletId: string) {
+  console.log("\n── Sweep ───────────────────────────────────────────────────");
+
+  // EVM sweep
+  const { data: evmJob, error: evmErr } = await vk.wallets.sweep(evmWalletId, {
+    chainType: "evm",
+    chainName: "base-sepolia",
+  });
+  if (evmErr) throw new Error(evmErr.message);
+  console.log("EVM sweep job:", evmJob.jobId);
+  await pollJob(evmJob.jobId);
+
+  // Solana sweep
+  const { data: solJob, error: solErr } = await vk.wallets.sweep(solWalletId, {
+    chainType: "solana",
+  });
+  if (solErr) throw new Error(solErr.message);
+  console.log("Solana sweep job:", solJob.jobId);
+  await pollJob(solJob.jobId);
+}
+
+// ---------------------------------------------------------------------------
+// 7. List supported chains
+// ---------------------------------------------------------------------------
+
+async function listChains() {
+  console.log("\n── Supported Chains ────────────────────────────────────────");
+
+  const { data: chains, error } = await vk.chains.list();
+  if (error) throw new Error(error.message);
+
+  for (const c of chains) {
+    const label = c.testnet ? "(testnet)" : "(mainnet)";
+    console.log(`  ${c.name.padEnd(20)} chain_id=${c.chainId}  ${c.nativeSymbol}  ${label}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Run all examples
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.log("VaultKey SDK — Example Usage");
+  console.log("=".repeat(60));
+
+  const { evmWallet, solWallet } = await createWallets();
+  await listWallets("user_123");
+  await checkBalances(evmWallet.id, solWallet.id);
+  await signMessages(evmWallet.id, solWallet.id);
+  await stablecoinTransfer(evmWallet.id);
+  await sweep(evmWallet.id, solWallet.id);
+  await listChains();
+
+  console.log("\n✓ All examples completed.");
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});