@surgecredit/earn-sdk 0.1.1

package/README.md

@@ -0,0 +1,166 @@
+# Surge Earn SDK
+
+TypeScript-first SDK for wallets and web apps that want to integrate Surge Earn markets.
+
+## Install
+
+```bash
+npm install @surgecredit/earn-sdk viem
+```
+
+## Quickstart
+
+```ts
+import { baseSepolia } from "viem/chains";
+import { createWalletClient, custom } from "viem";
+import {
+  SurgeEarnClient,
+  SURGE_BASE_SEPOLIA_CONFIG,
+  createSurgeEarnPublicClient,
+} from "@surgecredit/earn-sdk";
+
+const publicClient = createSurgeEarnPublicClient("https://sepolia.base.org", baseSepolia);
+const walletClient = createWalletClient({
+  chain: baseSepolia,
+  transport: custom(window.ethereum),
+});
+
+const earn = new SurgeEarnClient({
+  publicClient,
+  walletClient,
+  config: SURGE_BASE_SEPOLIA_CONFIG,
+});
+
+const markets = await earn.listMarkets();
+console.log(markets);
+```
+
+## Core API
+
+- `listMarkets({ includeInactive? })`
+- `getUserPosition(address)`
+- `getUserExposures(address)`
+- `getWalletUsdcBalance(address)`
+- `getAllowance(owner, spender?)`
+- `approveMaxUsdc({ account?, waitForReceipt? })`
+- `deposit({ amountUsdc, account?, waitForReceipt? })`
+- `quoteWithdrawLpTokens(account, amountUsdc)`
+- `withdrawByUsdc({ amountUsdc, account, waitForReceipt? })`
+- `withdrawByLpTokens({ lpTokens, account?, waitForReceipt? })`
+- `setExposure({ marketId, exposurePercent, account?, waitForReceipt? })`
+- `listDepositEvents({ user?, fromBlock?, toBlock?, includeTimestamps?, limit? })`
+- `listWithdrawEvents({ user?, fromBlock?, toBlock?, includeTimestamps?, limit? })`
+- `listActivity({ user?, fromBlock?, toBlock?, includeTimestamps?, limit? })`
+- `getUserActivity(user, { fromBlock?, toBlock?, includeTimestamps?, limit? })`
+
+## MetaMask Write Example (UI-ready)
+
+```ts
+import { createWalletClient, custom } from "viem";
+import { baseSepolia } from "viem/chains";
+import {
+  SurgeEarnClient,
+  SURGE_BASE_SEPOLIA_CONFIG,
+  createSurgeEarnPublicClient,
+} from "@surgecredit/earn-sdk";
+
+async function connectMetaMask() {
+  if (!window.ethereum) throw new Error("MetaMask not found");
+  const [address] = await window.ethereum.request({ method: "eth_requestAccounts" });
+
+  const chainIdHex = await window.ethereum.request({ method: "eth_chainId" });
+  if (Number(chainIdHex) !== baseSepolia.id) {
+    await window.ethereum.request({
+      method: "wallet_switchEthereumChain",
+      params: [{ chainId: "0x14a34" }],
+    });
+  }
+
+  const walletClient = createWalletClient({
+    chain: baseSepolia,
+    transport: custom(window.ethereum),
+  });
+
+  return { address, walletClient };
+}
+
+export async function depositFlow(amountUsdc: string) {
+  const { address, walletClient } = await connectMetaMask();
+  const publicClient = createSurgeEarnPublicClient("https://sepolia.base.org", baseSepolia);
+
+  const earn = new SurgeEarnClient({
+    publicClient,
+    walletClient,
+    config: SURGE_BASE_SEPOLIA_CONFIG,
+  });
+
+  const allowance = await earn.getAllowance(address);
+  if (allowance === 0n) {
+    await earn.approveMaxUsdc({ account: address, waitForReceipt: true });
+  }
+
+  await earn.deposit({ amountUsdc, account: address, waitForReceipt: true });
+}
+
+export async function withdrawFlow(amountUsdc: string) {
+  const { address, walletClient } = await connectMetaMask();
+  const publicClient = createSurgeEarnPublicClient("https://sepolia.base.org", baseSepolia);
+
+  const earn = new SurgeEarnClient({
+    publicClient,
+    walletClient,
+    config: SURGE_BASE_SEPOLIA_CONFIG,
+  });
+
+  await earn.withdrawByUsdc({ amountUsdc, account: address, waitForReceipt: true });
+}
+```
+
+## Activity Feed Example
+
+```ts
+const activity = await earn.getUserActivity("0xYourWalletAddress", {
+  fromBlock: 0n,
+  includeTimestamps: true,
+  limit: 25,
+});
+
+// Each item includes: type, amount, lpTokens, txHash, blockNumber, timestamp
+```
+
+## React Hooks
+
+```ts
+import { useEarnActivity, useEarnMarkets, useEarnPortfolio } from "@surgecredit/earn-sdk/react";
+```
+
+- `useEarnMarkets(client, { includeInactive?, pollIntervalMs? })`
+- `useEarnPortfolio(client, address)`
+- `useEarnActivity(client, { user?, fromBlock?, toBlock?, includeTimestamps?, limit?, pollIntervalMs? })`
+
+## Local Example Wallet
+
+Run the local demo wallet:
+
+```bash
+npm install
+npm run build
+cd examples/test-wallet
+npm install
+npm run dev
+```
+
+The example includes:
+
+- Mnemonic create/import for a Base Sepolia account preview
+- Mnemonic persistence across refresh (localStorage)
+- Faucet helper panel (copy address + ETH/USDC faucet links)
+- Base Sepolia USDC balance fetch + invest flow (approve + deposit)
+- Earn position and recent deposit/withdraw activity
+
+## Publishing
+
+Publishing checklist and tag format are documented in `PUBLISHING.md`.
+
+- `prepublishOnly` runs `clean` + full `verify` (test, typecheck, build)
+- Use `vX.Y.Z` for stable tags and `vX.Y.Z-beta.N` for prereleases