@helium/blockchain-api 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @helium/blockchain-api
 
-TypeScript types for the Helium Blockchain API. Provides full type safety when building clients for the Helium blockchain services.
+TypeScript client and schemas for the Helium Blockchain API.
 
 ## Installation
 
@@ -10,76 +10,133 @@ npm install @helium/blockchain-api
 yarn add @helium/blockchain-api
 ```
 
-## Peer Dependencies
+## Quick Start
 
-- `@orpc/server` ^1.12.0
-- `zod` ^4.0.0
+```typescript
+import { createClient } from "@helium/blockchain-api";
+
+const client = createClient({
+  url: "https://api.helium.com",
+  transport: "rpc",
+});
 
-## Usage
+// Get token balances
+const balances = await client.tokens.getBalances({
+  walletAddress: "YOUR_WALLET_ADDRESS",
+});
+
+// Get hotspots
+const hotspots = await client.hotspots.getHotspots({
+  walletAddress: "YOUR_WALLET_ADDRESS",
+  type: "iot",
+  page: 1,
+  limit: 20,
+});
+```
 
-### Setting up a typed client
+## Authentication
+
+For protected endpoints, provide a context factory:
 
 ```typescript
-import type { BlockchainAPIClient } from "@helium/blockchain-api"
-import { createORPCClient } from "@orpc/client"
-import { RPCLink } from "@orpc/client/fetch"
+const client = createClient({
+  url: "https://api.helium.com",
+  transport: "rpc",
+  getContext: () => ({
+    userId: currentUser.id,
+    walletAddress: connectedWallet?.address ?? null,
+    user: privyUser,
+  }),
+});
+```
 
-const link = new RPCLink({
-  url: "https://your-api-url.com/rpc",
-})
+Or use an access token:
 
-const client: BlockchainAPIClient = createORPCClient(link)
+```typescript
+const client = createClient({
+  url: "https://api.helium.com",
+  accessToken: "your-access-token",
+});
 ```
 
-### Example API calls
+## Schema Validation
+
+All Zod schemas are exported for direct use:
 
 ```typescript
-// Get token balances
-const balances = await client.tokens.getBalances({
-  walletAddress: "your-wallet-address"
-})
-
-// Get swap quote
-const quote = await client.swap.getQuote({
-  inputMint: "input-token-mint",
-  outputMint: "output-token-mint",
-  amount: "1000000"
-})
-
-// Claim hotspot rewards
-const { transactionData } = await client.hotspots.claimRewards({
-  walletAddress: "your-wallet-address"
-})
+import { GetBalancesInputSchema, TokenBalanceDataSchema } from "@helium/blockchain-api";
+
+// Validate input
+const input = GetBalancesInputSchema.parse({
+  walletAddress: userInput,
+});
 ```
 
-### With TanStack Query
+## Error Handling
+
+Typed error definitions are available:
 
 ```typescript
-import { createRouterUtils } from "@orpc/tanstack-query"
+import { createClient, INSUFFICIENT_FUNDS, solanaErrors } from "@helium/blockchain-api";
+
+try {
+  await client.tokens.transfer({ ... });
+} catch (error) {
+  if (error.code === INSUFFICIENT_FUNDS.code) {
+    console.error("Not enough SOL:", error.data);
+  }
+}
+```
 
-const orpc = createRouterUtils(client)
+## Testing with Mock Client
 
-// In a React component
-const { data, isLoading } = orpc.tokens.getBalances.useQuery({
-  input: { walletAddress: "your-wallet-address" }
-})
+```typescript
+import { createMockClient } from "@helium/blockchain-api";
+
+const mockClient = createMockClient({
+  tokens: {
+    getBalances: async () => ({
+      totalBalanceUsd: 100,
+      solBalance: 1,
+      solBalanceUsd: 50,
+      tokens: [],
+    }),
+  },
+  health: {
+    check: async () => ({ ok: true }),
+  },
+});
+
+// Use in tests
+const result = await mockClient.tokens.getBalances({ walletAddress: "..." });
 ```
 
-## Available Routers
+## OpenAPI Spec Generation
+
+```typescript
+import { generateOpenAPISpec } from "@helium/blockchain-api";
+
+const spec = generateOpenAPISpec({
+  info: {
+    title: "Helium Blockchain API",
+    version: "1.0.0",
+  },
+  servers: [{ url: "https://api.helium.com" }],
+});
+```
 
-- `hotspots` - Hotspot management, rewards, splits
-- `tokens` - Token balances, transfers
-- `swap` - Jupiter DEX integration
-- `transactions` - Transaction submission/tracking
-- `welcomePacks` - Onboarding rewards
-- `fiat` - Bank accounts, KYC, offramp
-- `health` - Health checks
+## API Reference
 
-## Exports
+### Routers
 
-- `ORPCRouter` - The full router type
-- `BlockchainAPIClient` - Helper type for typed clients
-- `RouterClient` - Re-exported from @orpc/server
+- `health` - Health check
+- `tokens` - Token balances and transfers
+- `hotspots` - Hotspot management and rewards
+- `swap` - Token swaps via Jupiter
+- `transactions` - Transaction submission and tracking
+- `welcomePacks` - Welcome pack management
+- `fiat` - Fiat offramp and bank accounts
+- `webhooks` - Webhook handlers
 
 ## License