@iteradian-rpc/sdk 1.0.1

package/README.md

@@ -0,0 +1,631 @@
+<p align="center">
+  <h1 align="center">Iteradian TypeScript SDK</h1>
+  <p align="center">Official TypeScript/JavaScript client library for the Iteradian Control Plane API</p>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/node-%3E%3D16.0.0-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node 16+" />
+  <img src="https://img.shields.io/badge/version-1.0.0-green?style=flat-square" alt="Version" />
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License" />
+  <img src="https://img.shields.io/badge/npm-%40iteradian%2Fsdk-CB3837?style=flat-square&logo=npm&logoColor=white" alt="npm" />
+  <img src="https://img.shields.io/badge/deps-zero-brightgreen?style=flat-square" alt="Zero Dependencies" />
+  <img src="https://img.shields.io/badge/formats-ESM%20%2B%20CJS-blue?style=flat-square" alt="ESM + CJS" />
+</p>
+
+---
+
+## Features
+
+- **Zero runtime dependencies** — uses native `fetch` API only
+- **TypeScript-first** — comprehensive type definitions included (`.d.ts`)
+- **Dual module format** — ships ESM (`.mjs`) and CommonJS (`.js`)
+- **Resource-based API** — clean `client.auth`, `client.organizations`, `client.endpoints` access pattern
+- **Full API coverage** — Auth, Organizations, API Keys, Endpoints, Usage, Dashboard, Alerts, Logs, Subscriptions, Plans, Support
+- **Automatic retry** — exponential backoff on 429 / 5xx responses (configurable)
+- **Timeout support** — via `AbortController` (configurable, default 30s)
+- **Dual auth** — supports both Bearer tokens and `X-API-Key` headers
+- **Tree-shakeable** — individual resource classes can be imported directly
+- **Browser & Node.js** — works anywhere `fetch` is available
+
+## Requirements
+
+- **Node.js 16** or later (for native `fetch`)
+- **TypeScript 5.3+** (recommended, for type checking)
+
+## Installation
+
+```bash
+npm install @iteradian-rpc/sdk
+```
+
+```bash
+yarn add @iteradian-rpc/sdk
+```
+
+```bash
+pnpm add @iteradian-rpc/sdk
+```
+
+## Quick Start
+
+```typescript
+import { IteradianClient } from "@iteradian-rpc/sdk";
+
+const client = new IteradianClient({
+  baseUrl: "https://api.iteradian.com/api/v1",
+});
+
+// Login — sets the access token automatically
+const tokens = await client.auth.login({
+  email: "user@example.com",
+  password: "password123",
+});
+console.log(`Logged in as ${tokens.user.email}`);
+
+// List organizations
+const orgs = await client.organizations.list();
+console.log(`Organizations: ${orgs.length}`);
+
+if (orgs.length > 0) {
+  const orgId = orgs[0].id;
+
+  // List endpoints
+  const endpoints = await client.endpoints.list(orgId);
+  for (const ep of endpoints) {
+    console.log(`  ${ep.name}: ${ep.status} (${ep.region})`);
+  }
+
+  // Create API key
+  const key = await client.apiKeys.create(orgId, {
+    name: "Production Key",
+    environment: "live",
+  });
+  console.log(`Created key: ${key.prefix}`);
+
+  // Query logs
+  const logs = await client.logs.query(orgId, {
+    status: "error",
+    pageSize: 50,
+  });
+  console.log(`Total logs: ${logs.total}`);
+}
+```
+
+### JavaScript (CommonJS)
+
+```javascript
+const { IteradianClient } = require("@iteradian-rpc/sdk");
+
+const client = new IteradianClient({
+  baseUrl: "https://api.iteradian.com/api/v1",
+});
+```
+
+### Using API Key Authentication
+
+```typescript
+const client = new IteradianClient({
+  baseUrl: "https://api.iteradian.com/api/v1",
+  apiKey: "itrd_live_abc123...",
+});
+
+const endpoints = await client.endpoints.list("org-id");
+```
+
+### Configuration Options
+
+```typescript
+import { IteradianClient, IteradianConfig } from "@iteradian-rpc/sdk";
+
+const config: IteradianConfig = {
+  baseUrl: "https://api.iteradian.com/api/v1", // API base URL
+  accessToken: "existing-token", // Pre-set Bearer token
+  apiKey: "itrd_live_...", // API key for X-API-Key header
+  timeout: 60_000, // Request timeout in ms (default: 30000)
+  retry: true, // Enable auto-retry (default: true)
+  maxRetries: 5, // Max retry attempts (default: 3)
+  headers: {
+    // Custom headers
+    "X-Custom-Header": "value",
+  },
+};
+
+const client = new IteradianClient(config);
+```
+
+## API Reference
+
+### Resource Accessors
+
+| Resource      | Property               | Type                    | Description                         |
+| ------------- | ---------------------- | ----------------------- | ----------------------------------- |
+| Auth          | `client.auth`          | `AuthResource`          | Authentication & account management |
+| Organizations | `client.organizations` | `OrganizationsResource` | Organization CRUD & members         |
+| API Keys      | `client.apiKeys`       | `ApiKeysResource`       | API key management                  |
+| Endpoints     | `client.endpoints`     | `EndpointsResource`     | Endpoint & network management       |
+| Usage         | `client.usage`         | `UsageResource`         | Usage analytics                     |
+| Dashboard     | `client.dashboard`     | `DashboardResource`     | Dashboard data & health             |
+| Alerts        | `client.alerts`        | `AlertsResource`        | Alert management & rules            |
+| Logs          | `client.logs`          | `LogsResource`          | Request log querying                |
+| Subscriptions | `client.subscriptions` | `SubscriptionsResource` | Subscription & billing              |
+| Plans         | `client.plans`         | `PlansResource`         | Plan catalog                        |
+| Support       | `client.support`       | `SupportResource`       | Support ticket management           |
+
+### Client Methods
+
+```typescript
+// Set/clear access token at runtime
+client.setAccessToken("new-token");
+client.clearAccessToken();
+```
+
+### Authentication (`client.auth`)
+
+```typescript
+// Login (token set automatically)
+const tokens = await client.auth.login({ email: "...", password: "..." });
+
+// Register
+const tokens = await client.auth.register({
+  email: "...",
+  password: "...",
+  name: "...",
+});
+
+// Refresh token
+const tokens = await client.auth.refresh(refreshToken);
+
+// Logout
+await client.auth.logout();
+
+// Two-Factor Authentication
+const setup = await client.auth.enable2FA({ password: "..." });
+console.log(`Secret: ${setup.secret}`);
+console.log(`QR Code: ${setup.qrCode}`);
+await client.auth.verify2FA({ code: "123456" });
+await client.auth.disable2FA({ password: "...", code: "123456" });
+
+// Magic Link
+await client.auth.sendMagicLink({ email: "user@example.com" });
+
+// Password Reset
+await client.auth.forgotPassword({ email: "user@example.com" });
+await client.auth.resetPassword({ token: "...", newPassword: "..." });
+```
+
+### Organizations (`client.organizations`)
+
+```typescript
+// CRUD
+const orgs = await client.organizations.list();
+const org = await client.organizations.create({
+  name: "My Org",
+  slug: "my-org",
+});
+const org = await client.organizations.get(orgId);
+await client.organizations.delete(orgId);
+
+// Members
+const members = await client.organizations.listMembers(orgId);
+const member = await client.organizations.inviteMember(orgId, {
+  email: "user@example.com",
+  role: "member",
+});
+await client.organizations.removeMember(orgId, memberId);
+```
+
+### API Keys (`client.apiKeys`)
+
+```typescript
+const keys = await client.apiKeys.list(orgId);
+const key = await client.apiKeys.create(orgId, {
+  name: "Key Name",
+  environment: "live",
+});
+await client.apiKeys.revoke(orgId, keyId);
+const newKey = await client.apiKeys.rotate(orgId, keyId);
+const analytics = await client.apiKeys.getAnalytics(orgId, keyId);
+```
+
+### Endpoints (`client.endpoints`)
+
+```typescript
+// Networks
+const networks = await client.endpoints.getNetworks();
+
+// Endpoint management
+const endpoints = await client.endpoints.list(orgId);
+const endpoint = await client.endpoints.create(orgId, {
+  name: "...",
+  networkId: "...",
+  region: "us-east-1",
+});
+await client.endpoints.delete(orgId, endpointId);
+const paused = await client.endpoints.pause(orgId, endpointId);
+const resumed = await client.endpoints.resume(orgId, endpointId);
+const health = await client.endpoints.checkHealth(orgId, endpointId);
+const metrics = await client.endpoints.getMetrics(orgId, endpointId);
+```
+
+### Usage & Dashboard
+
+```typescript
+// Usage
+const usage = await client.usage.get(orgId, {
+  from: "2024-01-01",
+  to: "2024-01-31",
+});
+
+// Dashboard
+const data = await client.dashboard.get(orgId, { period: "7d" });
+const health = await client.dashboard.getHealth(orgId);
+const stats = await client.dashboard.getQuickStats(orgId, { period: "24h" });
+```
+
+### Alerts (`client.alerts`)
+
+```typescript
+// Alerts
+const alerts = await client.alerts.list(orgId);
+const ack = await client.alerts.acknowledge(orgId, alertId);
+const resolved = await client.alerts.resolve(orgId, alertId);
+
+// Alert Rules
+const rules = await client.alerts.listRules(orgId);
+const rule = await client.alerts.createRule(orgId, {
+  name: "High Latency",
+  metric: "latency_p95",
+  condition: "greater_than",
+  threshold: 500,
+  severity: "warning",
+  isEnabled: true,
+  cooldownMinutes: 15,
+});
+await client.alerts.deleteRule(orgId, ruleId);
+
+// Channels
+const channels = await client.alerts.getChannels(orgId);
+await client.alerts.testChannel(orgId, channelId);
+```
+
+### Logs (`client.logs`)
+
+```typescript
+// Query with filters
+const logs = await client.logs.query(orgId, {
+  page: 1,
+  pageSize: 50,
+  status: "error",
+  method: "eth_call",
+  network: "ethereum",
+  sortBy: "timestamp",
+  sortOrder: "desc",
+});
+console.log(`Page ${logs.page}/${logs.totalPages}`);
+for (const log of logs.logs) {
+  console.log(`  [${log.status}] ${log.method} (${log.latencyMs}ms)`);
+}
+
+// Get single log
+const log = await client.logs.get(orgId, logId);
+
+// Filter options
+const filters = await client.logs.getFilterOptions(orgId);
+
+// Stats
+const stats = await client.logs.getStats(orgId, { period: "24h" });
+```
+
+### Subscriptions (`client.subscriptions`)
+
+```typescript
+const sub = await client.subscriptions.get(orgId);
+const updated = await client.subscriptions.changePlan(orgId, { planId: "pro" });
+const cancelled = await client.subscriptions.cancel(orgId);
+const reactivated = await client.subscriptions.reactivate(orgId);
+const invoices = await client.subscriptions.getInvoices(orgId);
+```
+
+### Plans (`client.plans`)
+
+```typescript
+const plans = await client.plans.list();
+const plan = await client.plans.get(planId);
+```
+
+### Support (`client.support`)
+
+```typescript
+const tickets = await client.support.listTickets(orgId);
+const ticket = await client.support.createTicket(orgId, {
+  subject: "API returning 500 errors",
+  category: "technical",
+  priority: "high",
+  message: "Detailed description...",
+});
+const detail = await client.support.getTicket(orgId, ticketId);
+await client.support.addMessage(orgId, ticketId, {
+  content: "Follow-up message...",
+});
+```
+
+## Type Definitions
+
+All types are exported from the package and defined in `src/types.ts` (538 lines):
+
+### Configuration
+
+| Type              | Fields                                                                                 |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `IteradianConfig` | `baseUrl?`, `accessToken?`, `apiKey?`, `timeout?`, `retry?`, `maxRetries?`, `headers?` |
+
+### Auth Types
+
+| Type              | Fields                                |
+| ----------------- | ------------------------------------- |
+| `LoginRequest`    | `email`, `password`, `twoFactorCode?` |
+| `RegisterRequest` | `email`, `password`, `name`           |
+| `AuthTokens`      | `accessToken`, `refreshToken`, `user` |
+| `TwoFASetup`      | `secret`, `qrCode`                    |
+
+### Organization Types
+
+| Type                  | Fields                                         |
+| --------------------- | ---------------------------------------------- |
+| `Organization`        | `id`, `name`, `slug`, `createdAt`, `updatedAt` |
+| `OrgMember`           | `id`, `userId`, `email`, `role`, `joinedAt`    |
+| `CreateOrgRequest`    | `name`, `slug`                                 |
+| `InviteMemberRequest` | `email`, `role`                                |
+
+### API Key Types
+
+| Type                  | Fields                                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ApiKey`              | `id`, `name`, `prefix`, `key?`, `environment`, `status`, `ipAllowlist?`, `allowedNetworks?`, `rateLimit?`, `dailyLimit?`, `createdAt`, `updatedAt`, `expiresAt?`, `lastUsedAt?` |
+| `CreateApiKeyRequest` | `name`, `environment`, `ipAllowlist?`, `allowedNetworks?`, `rateLimit?`, `dailyLimit?`, `expiresAt?`                                                                            |
+
+### Network & Endpoint Types
+
+| Type                    | Fields                                                                                                                       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `Network`               | `id`, `slug`, `name`, `chainId`, `type`, `environment`, `isActive`                                                           |
+| `Endpoint`              | `id`, `organizationId`, `networkId`, `region`, `name`, `priority`, `status`, `isEnabled`, `timeoutMs`, `retryCount`, metrics |
+| `CreateEndpointRequest` | `name`, `networkId`, `region`, `priority?`, `timeoutMs?`, `retryCount?`                                                      |
+
+### Logging Types
+
+| Type             | Fields                                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `RequestLog`     | `id`, `organizationId`, `method`, `status`, `statusCode?`, `latencyMs?`, `network?`, `region?`, `timestamp` |
+| `LogsResponse`   | `logs`, `total`, `page`, `pageSize`, `totalPages`                                                           |
+| `LogQueryParams` | `page?`, `pageSize?`, `status?`, `method?`, `network?`, `region?`, `from?`, `to?`, `sortBy?`, `sortOrder?`  |
+
+### Alert Types
+
+| Type                     | Fields                                                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `Alert`                  | `id`, `organizationId`, `ruleId?`, `severity`, `status`, `title`, `message`, `metadata?`                       |
+| `AlertRule`              | `id`, `organizationId`, `name`, `metric`, `condition`, `threshold`, `severity`, `isEnabled`, `cooldownMinutes` |
+| `CreateAlertRuleRequest` | `name`, `metric`, `condition`, `threshold`, `severity`, `isEnabled`, `cooldownMinutes`                         |
+
+### Billing Types
+
+| Type           | Fields                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------- |
+| `Plan`         | `id`, `name`, `slug`, `price`, `currency`, `interval`, `features`, `limits`, `isActive` |
+| `Subscription` | `id`, `organizationId`, `planId`, `status`, `cancelAtPeriodEnd`, `plan?`                |
+
+### Support Types
+
+| Type                  | Fields                                                              |
+| --------------------- | ------------------------------------------------------------------- |
+| `SupportTicket`       | `id`, `organizationId`, `subject`, `category`, `priority`, `status` |
+| `CreateTicketRequest` | `subject`, `category`, `priority`, `message`                        |
+
+### Error Types
+
+| Type       | Fields                            |
+| ---------- | --------------------------------- |
+| `ApiError` | `message`, `statusCode`, `error?` |
+
+## Error Handling
+
+```typescript
+import { IteradianClient, IteradianError } from "@iteradian-rpc/sdk";
+
+const client = new IteradianClient({ baseUrl: "..." });
+
+try {
+  await client.auth.login({ email: "user@example.com", password: "wrong" });
+} catch (err) {
+  if (err instanceof IteradianError) {
+    console.log(`Status: ${err.statusCode}`); // 401
+    console.log(`Message: ${err.message}`); // "Invalid credentials"
+    console.log(`Error: ${err.error}`); // Error code
+  } else {
+    console.log(`Unexpected error: ${err}`);
+  }
+}
+```
+
+On a gateway call the same error also carries the JSON-RPC detail, which is how
+you tell "wait a second" from "you are out of quota until the period rolls
+over":
+
+```typescript
+try {
+  await client.rpc.call("tao-mainnet", {
+    jsonrpc: "2.0",
+    method: "system_health",
+    params: [],
+    id: 1,
+  });
+} catch (err) {
+  if (err instanceof IteradianError) {
+    if (err.isRateLimited) {
+      // -32005. Wait err.retryAfter seconds and try again.
+    } else if (err.isQuotaExhausted) {
+      // -32006 or -32007. Retrying will not help: err.data.resetsAt says when
+      // the allowance returns, and the cap needs a plan change.
+    }
+  }
+}
+```
+
+Pass an `AbortSignal` to cancel a call:
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 1000);
+
+await client.rpc.call("tao-mainnet", request, { signal: controller.signal });
+```
+
+### Retry Behavior
+
+The SDK automatically retries:
+
+- **5xx Server Errors** — with exponential backoff
+- **429 Too Many Requests**, but **only** `-32005` (rate or concurrency limit).
+  `-32006` (monthly quota exhausted) and `-32007` (overage spend cap) do not
+  recover until the billing period rolls over, so retrying them burns your time
+  for a guaranteed 429.
+
+Backoff formula: `min(1000 * 2^(attempt-1), 10000)` ms, or the gateway's own
+`retryAfter` hint when it gives one — capped at 30 seconds either way.
+
+**Transaction submissions are never retried.** A request whose JSON-RPC method
+submits a transaction (`eth_sendRawTransaction`, `author_submitExtrinsic`,
+`sendTransaction`, and the rest) is sent exactly once: a timeout says nothing
+about whether the node already accepted and gossiped it, and a retry could
+double-submit. The gateway applies the same rule when failing over between
+nodes.
+
+**Redirects are not followed.** Neither host redirects, and following one would
+resend your API key to whatever origin the redirect named. A 3xx raises
+`IteradianError` with `error: "UNEXPECTED_REDIRECT"`.
+
+Configure via constructor:
+
+```typescript
+const client = new IteradianClient({
+  baseUrl: "...",
+  retry: true, // Enable retry (default: true)
+  maxRetries: 5, // Max retry attempts (default: 3)
+  timeout: 60_000, // Timeout per request (default: 30000ms)
+});
+```
+
+To disable retries:
+
+```typescript
+const client = new IteradianClient({
+  baseUrl: "...",
+  retry: false,
+});
+```
+
+## Advanced Usage
+
+### Importing Individual Resources
+
+For tree-shaking or advanced use cases, you can import resource classes directly:
+
+```typescript
+import { AuthResource } from "@iteradian-rpc/sdk";
+import { HttpClient } from "@iteradian-rpc/sdk/http";
+
+const http = new HttpClient({ baseUrl: "..." });
+const auth = new AuthResource(http);
+const tokens = await auth.login({ email: "...", password: "..." });
+```
+
+### Pre-Authenticated Client
+
+```typescript
+const client = new IteradianClient({
+  baseUrl: "https://api.iteradian.com/api/v1",
+  accessToken: "existing-jwt-token",
+});
+
+// No login needed — use the API directly
+const orgs = await client.organizations.list();
+```
+
+## Build & Development
+
+```bash
+# Build (CJS + ESM + DTS)
+npm run build
+
+# Watch mode
+npm run dev
+
+# Type check
+npm run lint
+
+# Test
+npm run test
+```
+
+Built with [tsup](https://github.com/egoist/tsup) — outputs:
+
+- `dist/index.js` (CommonJS)
+- `dist/index.mjs` (ESM)
+- `dist/index.d.ts` (TypeScript declarations)
+
+## Project Structure
+
+```
+sdks/typescript/
+├── package.json          # @iteradian-rpc/sdk, zero runtime deps
+├── tsconfig.json         # TypeScript config (ES2020, strict)
+├── README.md             # This file
+└── src/
+    ├── index.ts          # Re-exports everything
+    ├── client.ts         # IteradianClient class (110 lines)
+    ├── http.ts           # HttpClient + IteradianError (155 lines)
+    ├── types.ts          # All TypeScript interfaces (538 lines)
+    └── resources/
+        ├── auth.ts       # AuthResource
+        ├── organizations.ts
+        ├── api-keys.ts   # ApiKeysResource
+        ├── endpoints.ts  # EndpointsResource
+        ├── usage.ts      # UsageResource
+        ├── dashboard.ts  # DashboardResource
+        ├── alerts.ts     # AlertsResource
+        ├── logs.ts       # LogsResource
+        ├── subscriptions.ts
+        ├── plans.ts      # PlansResource
+        └── support.ts    # SupportResource
+```
+
+## License
+
+MIT © [Iteradian](https://iteradian.com)
+
+## RPC gateway, rate limits and quotas
+
+The RPC gateway is a **different host** from the control-plane API:
+
+| Surface | Base URL |
+| --- | --- |
+| Control plane | `https://api.iteradian.com/api/v1` |
+| RPC gateway | `https://rpc.iteradian.com` |
+
+This SDK takes both, and defaults the gateway to `https://rpc.iteradian.com`.
+
+- A **batch of N calls costs N** against your per-second rate limit and your
+  monthly quota. Batching saves round trips, not allowance.
+- Limits are **per subscription**, aggregated over every API key your
+  organization holds. Creating more keys does not raise them.
+- The gateway returns HTTP 429 with a JSON-RPC error body:
+  `-32005` rate limited (retry after `error.data.retryAfter`), `-32006` monthly
+  quota exhausted, `-32007` overage spend cap reached. The last two do not
+  recover until the billing period rolls over, so retrying them is wasted work.
+
+Plans: Developer 20 rps / 5M per month, Professional 100 rps / 30M, Dedicated
+per contract. See `sdks/SDK_CONTRACT.md` for the full table.
+
+**WebSocket is not available.** The gateway serves HTTPS JSON-RPC only.