@helium/blockchain-api 0.1.3 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @helium/blockchain-api
 
-TypeScript types and Zod schemas 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,98 +10,133 @@ npm install @helium/blockchain-api
 yarn add @helium/blockchain-api
 ```
 
-## Peer Dependencies
+## Quick Start
 
-- `@orpc/client` ^1.12.0
-- `zod` ^4.0.0
+```typescript
+import { createClient } from "@helium/blockchain-api";
 
-## Usage
+const client = createClient({
+  url: "https://api.helium.com",
+  transport: "rpc",
+});
 
-### Setting up a typed client
+// 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,
+});
+```
 
-```typescript
-import type { BlockchainAPIClient } from "@helium/blockchain-api"
-import { createORPCClient } from "@orpc/client"
-import { RPCLink } from "@orpc/client/fetch"
+## Authentication
 
-const link = new RPCLink({
-  url: "https://your-api-url.com/rpc",
-})
+For protected endpoints, provide a context factory:
 
-const client: BlockchainAPIClient = createORPCClient(link)
+```typescript
+const client = createClient({
+  url: "https://api.helium.com",
+  transport: "rpc",
+  getContext: () => ({
+    userId: currentUser.id,
+    walletAddress: connectedWallet?.address ?? null,
+    user: privyUser,
+  }),
+});
 ```
 
-### Example API calls
+Or use an access token:
 
 ```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"
-})
+const client = createClient({
+  url: "https://api.helium.com",
+  accessToken: "your-access-token",
+});
 ```
 
-### Using Zod schemas for validation
+## Schema Validation
+
+All Zod schemas are exported for direct use:
 
 ```typescript
-import { HotspotSchema, TokenAccountSchema } from "@helium/blockchain-api"
+import { GetBalancesInputSchema, TokenBalanceDataSchema } from "@helium/blockchain-api";
 
-// Validate data
-const hotspot = HotspotSchema.parse(rawData)
+// Validate input
+const input = GetBalancesInputSchema.parse({
+  walletAddress: userInput,
+});
+```
+
+## Error Handling
 
-// Type inference
-type Hotspot = z.infer<typeof HotspotSchema>
+Typed error definitions are available:
+
+```typescript
+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);
+  }
+}
 ```
 
-### With TanStack Query
+## Testing with Mock Client
 
 ```typescript
-import { createRouterUtils } from "@orpc/tanstack-query"
+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: "..." });
+```
 
-const orpc = createRouterUtils(client)
+## OpenAPI Spec Generation
 
-// In a React component
-const { data, isLoading } = orpc.tokens.getBalances.useQuery({
-  input: { walletAddress: "your-wallet-address" }
-})
+```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" }],
+});
 ```
 
-## Available Routers
-
-- `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
-
-## Exports
-
-### Types
-- `ORPCRouter` - The full router type
-- `BlockchainAPIClient` - Helper type for typed clients
-- `RouterClient` - Re-exported from @orpc/server
-
-### Zod Schemas
-- `HotspotSchema`, `HotspotsDataSchema` - Hotspot data validation
-- `TokenAccountSchema`, `TokenBalanceDataSchema` - Token data validation
-- `TransactionDataSchema`, `TransactionItemSchema` - Transaction validation
-- `QuoteResponseSchema` - Swap quote validation
-- `WelcomePackSchema` - Welcome pack validation
-- `BankAccountSchema`, `KycStatusOutputSchema` - Fiat/KYC validation
-- And many more input/output schemas for each router
+## API Reference
+
+### Routers
+
+- `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