@iteradian-rpc/sdk 1.0.1 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@
 <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/version-1.2.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" />
@@ -57,11 +57,15 @@ const client = new IteradianClient({
 });
 
 // Login — sets the access token automatically
-const tokens = await client.auth.login({
+const login = await client.auth.login({
   email: "user@example.com",
   password: "password123",
 });
-console.log(`Logged in as ${tokens.user.email}`);
+if (login.requires2FA) {
+  // Two-factor auth is on: log in again with a code (see Authentication).
+  throw new Error("2FA code required");
+}
+console.log(`Logged in as ${login.user?.email}`);
 
 // List organizations
 const orgs = await client.organizations.list();
@@ -81,12 +85,13 @@ if (orgs.length > 0) {
     name: "Production Key",
     environment: "live",
   });
-  console.log(`Created key: ${key.prefix}`);
+  // The full key is shown once, in `secret`.
+  console.log(`Created key: ${key.prefix} (${key.secret})`);
 
   // Query logs
   const logs = await client.logs.query(orgId, {
     status: "error",
-    pageSize: 50,
+    limit: 50,
   });
   console.log(`Total logs: ${logs.total}`);
 }
@@ -163,14 +168,26 @@ client.clearAccessToken();
 ### Authentication (`client.auth`)
 
 ```typescript
-// Login (token set automatically)
-const tokens = await client.auth.login({ email: "...", password: "..." });
+// Login (the access token is set automatically when the answer has one)
+const login = await client.auth.login({ email: "...", password: "..." });
+
+// With two-factor auth on, a login without a code answers
+// { requires2FA: true } and no tokens. Log in again with a code:
+if (login.requires2FA) {
+  await client.auth.login({ email: "...", password: "...", twoFactorCode: "123456" });
+  // or, with a one-time backup code:
+  // await client.auth.login({ email: "...", password: "...", backupCode: "..." });
+}
 
-// Register
-const tokens = await client.auth.register({
+// Register — does NOT sign in. Answers { message, email } and emails a
+// confirmation link; log in once the address is confirmed.
+// acceptedTerms is required: pass true only after the user agreed to the
+// Terms of Service, Privacy Policy and DPA (https://iteradian.com/terms,
+// /privacy, /dpa). The server rejects registration (400) otherwise.
+const { message } = await client.auth.register({
   email: "...",
   password: "...",
-  name: "...",
+  acceptedTerms: true,
 });
 
 // Refresh token
@@ -179,19 +196,25 @@ const tokens = await client.auth.refresh(refreshToken);
 // Logout
 await client.auth.logout();
 
+// Email verification
+await client.auth.verifyEmail(token);
+await client.auth.resendVerification("user@example.com");
+
 // Two-Factor Authentication
-const setup = await client.auth.enable2FA({ password: "..." });
+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" });
+const { backupCodes } = await client.auth.verify2FA("123456");
+const fresh = await client.auth.regenerateBackupCodes("password");
+await client.auth.disable2FA("password", "123456"); // password + current 6-digit TOTP code
 
 // Magic Link
-await client.auth.sendMagicLink({ email: "user@example.com" });
+await client.auth.requestMagicLink("user@example.com");
+await client.auth.loginWithMagicLink(tokenFromEmail);
 
 // Password Reset
-await client.auth.forgotPassword({ email: "user@example.com" });
-await client.auth.resetPassword({ token: "...", newPassword: "..." });
+await client.auth.forgotPassword("user@example.com");
+await client.auth.resetPassword(tokenFromEmail, "new-password");
 ```
 
 ### Organizations (`client.organizations`)
@@ -199,20 +222,40 @@ await client.auth.resetPassword({ token: "...", newPassword: "..." });
 ```typescript
 // CRUD
 const orgs = await client.organizations.list();
-const org = await client.organizations.create({
+// `name`, `planId` and `acceptedTerms` are required; `slug` and
+// `billingInterval` ("month" | "year") are optional.
+const created = await client.organizations.create({
   name: "My Org",
+  planId: "plan_free",
+  acceptedTerms: true,
   slug: "my-org",
 });
 const org = await client.organizations.get(orgId);
+await client.organizations.update(orgId, { name: "Renamed" });
 await client.organizations.delete(orgId);
+await client.organizations.leave(orgId);
+const perms = await client.organizations.getMyPermissions(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.updateMemberRole(orgId, memberId, "viewer");
 await client.organizations.removeMember(orgId, memberId);
+
+// Invitations — inviting creates a pending invite; the invitee becomes a
+// member only after accepting it (signed in, verified email).
+const invite = await client.organizations.inviteMember(orgId, {
+  email: "user@example.com",
+  role: "developer",
+}); // { id, email, role, status: "pending", expiresAt, createdAt }
+const open = await client.organizations.listInvites(orgId);
+await client.organizations.revokeInvite(orgId, invite.id);
+
+// As the invitee
+const { invites } = await client.organizations.listMyInvites();
+await client.organizations.acceptInvite(invites[0].id); // or declineInvite()
+// A user who has not accepted the current terms version gets 403
+// (TERMS_ACCEPTANCE_REQUIRED); once they agree, accept with:
+await client.organizations.acceptInvite(invites[0].id, { acceptedTerms: true });
 ```
 
 ### API Keys (`client.apiKeys`)
@@ -223,9 +266,12 @@ 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);
+// The full key is shown once, in `secret`. `key.key` is a deprecated alias.
+console.log(key.secret);
+await client.apiKeys.update(orgId, key.id, { name: "Renamed" });
+const newKey = await client.apiKeys.rotate(orgId, key.id); // new key in newKey.secret
+const analytics = await client.apiKeys.getAnalytics(orgId, key.id, "7d");
+await client.apiKeys.revoke(orgId, key.id);
 ```
 
 ### Endpoints (`client.endpoints`)
@@ -233,95 +279,135 @@ const analytics = await client.apiKeys.getAnalytics(orgId, keyId);
 ```typescript
 // Networks
 const networks = await client.endpoints.getNetworks();
+const network = await client.endpoints.getNetwork(networkId);
 
 // Endpoint management
 const endpoints = await client.endpoints.list(orgId);
 const endpoint = await client.endpoints.create(orgId, {
-  name: "...",
+  name: "My endpoint",
   networkId: "...",
-  region: "us-east-1",
+  region: "eu_central",
 });
-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);
+await client.endpoints.update(orgId, endpoint.id, { name: "Renamed" });
+await client.endpoints.delete(orgId, endpoint.id);
+const paused = await client.endpoints.pause(orgId, endpoint.id);
+const resumed = await client.endpoints.resume(orgId, endpoint.id);
+await client.endpoints.updatePriorities(orgId, [{ id: endpoint.id, priority: 2 }]);
+
+// Health and metrics
+const check = await client.endpoints.checkHealth(orgId, endpoint.id); // runs a check now
+const health = await client.endpoints.getHealth(orgId, endpoint.id); // current health
+const summary = await client.endpoints.getHealthOverview(orgId);
+const metrics = await client.endpoints.getMetrics(orgId, endpoint.id);
+const ranged = await client.endpoints.getMetrics(
+  orgId,
+  endpoint.id,
+  "2026-01-01T00:00:00Z",
+  "2026-01-02T00:00:00Z",
+);
 ```
 
+Decimal fields such as `avgLatencyMs`, `successRate` and `uptime` can arrive as
+numeric strings; they are typed `number | string`, so use `Number(value)`.
+
 ### 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" });
+// Usage: a list of rows (one per key per day)
+const rows = await client.usage.get(orgId, "2026-01-01", "2026-01-31");
+const usage = await client.usage.getSummary(orgId);
+
+// Dashboard. The optional second argument is the API timeRange:
+// last_hour, last_24_hours (default), last_7_days, last_30_days or custom.
+// The short forms "1h", "24h", "7d" and "30d" are translated.
+const data = await client.dashboard.get(orgId, "7d");
+const custom = await client.dashboard.get(orgId, "custom", { from: "2026-01-01", to: "2026-01-07" });
 const health = await client.dashboard.getHealth(orgId);
-const stats = await client.dashboard.getQuickStats(orgId, { period: "24h" });
+const stats = await client.dashboard.getQuickStats(orgId, "24h");
+const requestRate = await client.dashboard.getRequestRate(orgId); // { currentRate, timeSeries, ... }
+const errorRate = await client.dashboard.getErrorRate(orgId);
+const latency = await client.dashboard.getLatency(orgId); // { p50, p95, p99, ... }
+const perf = await client.dashboard.getPerformance(orgId);
 ```
 
 ### Alerts (`client.alerts`)
 
 ```typescript
-// Alerts
+// Alerts. list() returns the alerts array; overview() also has the counters,
+// rules and channels.
 const alerts = await client.alerts.list(orgId);
+const overview = await client.alerts.overview(orgId);
 const ack = await client.alerts.acknowledge(orgId, alertId);
 const resolved = await client.alerts.resolve(orgId, alertId);
+await client.alerts.evaluate(orgId);
 
-// Alert Rules
+// Alert Rules. type is one of high_error_rate, high_latency,
+// rate_limit_exceeded, quota_warning, service_down, key_expiring,
+// unusual_traffic; config holds the thresholds for that type.
 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",
+  name: "High error rate",
+  type: "high_error_rate",
+  config: { threshold: 5 },
+  severity: "warning", // info | warning | error | critical
+  cooldownSeconds: 900, // at least 60
   isEnabled: true,
-  cooldownMinutes: 15,
 });
-await client.alerts.deleteRule(orgId, ruleId);
-
-// Channels
-const channels = await client.alerts.getChannels(orgId);
-await client.alerts.testChannel(orgId, channelId);
+await client.alerts.updateRule(orgId, rule.id, { name: "Renamed" });
+await client.alerts.toggleRule(orgId, rule.id);
+await client.alerts.seedDefaults(orgId);
+await client.alerts.deleteRule(orgId, rule.id);
+
+// Channels. type is email | webhook | slack.
+const channels = await client.alerts.listChannels(orgId);
+const channel = await client.alerts.createChannel(orgId, {
+  name: "Ops webhook",
+  type: "webhook",
+  config: { url: "https://example.com/hook" },
+});
+await client.alerts.updateChannel(orgId, channel.id, { isEnabled: false });
+await client.alerts.testChannel(orgId, channel.id);
+await client.alerts.deleteChannel(orgId, channel.id);
 ```
 
 ### Logs (`client.logs`)
 
 ```typescript
-// Query with filters
+// Query with filters. Page with limit (1-200) and offset.
 const logs = await client.logs.query(orgId, {
-  page: 1,
-  pageSize: 50,
+  limit: 50,
+  offset: 0,
   status: "error",
   method: "eth_call",
-  network: "ethereum",
+  network: "eth-mainnet",
+  minLatencyMs: 100,
   sortBy: "timestamp",
   sortOrder: "desc",
 });
-console.log(`Page ${logs.page}/${logs.totalPages}`);
+console.log(`${logs.logs.length} of ${logs.total}`);
 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);
+const log = await client.logs.get(orgId, logs.logs[0].id);
 
 // Filter options
 const filters = await client.logs.getFilterOptions(orgId);
 
 // Stats
-const stats = await client.logs.getStats(orgId, { period: "24h" });
+const stats = await client.logs.getStats(orgId);
 ```
 
 ### Subscriptions (`client.subscriptions`)
 
 ```typescript
 const sub = await client.subscriptions.get(orgId);
-const updated = await client.subscriptions.changePlan(orgId, { planId: "pro" });
+// The caller confirms the user accepted the plan-change billing terms; the
+// server rejects the change (400) unless acceptedTerms is true.
+const updated = await client.subscriptions.changePlan(orgId, "plan_builder", {
+  acceptedTerms: true,
+});
 const cancelled = await client.subscriptions.cancel(orgId);
 const reactivated = await client.subscriptions.reactivate(orgId);
 const invoices = await client.subscriptions.getInvoices(orgId);
@@ -337,22 +423,41 @@ const plan = await client.plans.get(planId);
 ### Support (`client.support`)
 
 ```typescript
+// listTickets() returns the tickets array.
 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...",
+  body: "Detailed description...",
+  category: "technical", // optional
+  priority: "high", // optional: low | medium | high | urgent
 });
-const detail = await client.support.getTicket(orgId, ticketId);
-await client.support.addMessage(orgId, ticketId, {
-  content: "Follow-up message...",
+const stats = await client.support.getStats(orgId);
+const detail = await client.support.getTicket(orgId, ticket.id);
+await client.support.addMessage(orgId, ticket.id, "Follow-up message...");
+await client.support.updateStatus(orgId, ticket.id, "resolved");
+```
+
+### RPC (`client.rpc`)
+
+```typescript
+const gateway = new IteradianClient({ apiKey: "itrd_live_..." });
+const networks = await gateway.rpc.networks();
+const res = await gateway.rpc.call("eth-mainnet", {
+  jsonrpc: "2.0",
+  method: "eth_blockNumber",
+  params: [],
+  id: 1,
 });
+const batch = await gateway.rpc.batch("eth-mainnet", [
+  { jsonrpc: "2.0", method: "eth_blockNumber", params: [], id: 1 },
+  { jsonrpc: "2.0", method: "eth_chainId", params: [], id: 2 },
+]);
 ```
 
 ## Type Definitions
 
-All types are exported from the package and defined in `src/types.ts` (538 lines):
+All types are exported from the package and defined in `src/types.ts`. Response fields are optional except `id`; decimal
+fields are typed `number | string` (`Numeric`):
 
 ### Configuration
 
@@ -362,66 +467,75 @@ All types are exported from the package and defined in `src/types.ts` (538 lines
 
 ### Auth Types
 
-| Type              | Fields                                |
-| ----------------- | ------------------------------------- |
-| `LoginRequest`    | `email`, `password`, `twoFactorCode?` |
-| `RegisterRequest` | `email`, `password`, `name`           |
-| `AuthTokens`      | `accessToken`, `refreshToken`, `user` |
-| `TwoFASetup`      | `secret`, `qrCode`                    |
+| Type               | Fields                                                              |
+| ------------------ | ------------------------------------------------------------------- |
+| `LoginRequest`     | `email`, `password`, `twoFactorCode?`, `backupCode?`                  |
+| `RegisterRequest`  | `email`, `password`, `acceptedTerms`                                  |
+| `RegisterResponse` | `message`, `email` (no tokens)                                      |
+| `LoginResult`      | `accessToken?`, `refreshToken?`, `user?`, `requires2FA?`                 |
+| `AuthTokens`       | `accessToken`, `refreshToken`, `user?` (refresh)                      |
+| `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`                                |
+| Type                        | Fields                                                                  |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `Organization`              | `id`, `name?`, `slug?`, `role?`, `subscription?`, `members?`               |
+| `OrgMember`                 | `id`, `userId?`, `email?`, `role?`, `joinedAt?`                           |
+| `CreateOrganizationRequest` | `name`, `planId`, `acceptedTerms`, `slug?`, `billingInterval?`            |
+| `OrgInvite`                 | `id`, `email?`, `role?`, `status?`, `expiresAt?`, `createdAt?`, `invitedBy?` |
+| `MyInvites`                 | `emailVerified?`, `invites` (`MyInvite[]`)                              |
+| `InviteAcceptance`          | `organizationId?`, `membershipId?`, `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?`                                                                            |
+| Type                  | Fields                                                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `ApiKey`              | `id`, `name?`, `prefix?`, `environment?`, `status?`, `ipAllowlist?`, `allowedNetworks?`, `rateLimit?`, `dailyLimit?`, `expiresAt?`, `lastUsedAt?`, `createdAt?` |
+| `ApiKeyWithSecret`    | `ApiKey` plus `secret` (create and rotate) and `key` (deprecated alias of `secret`)                                                  |
+| `CreateApiKeyRequest` | `name`, `environment`, `ipAllowlist?`, `allowedNetworks?`, `rateLimit?`, `dailyLimit?`, `expiresAt?`, `walletUrlAuth?`                      |
 
 ### 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?`                                                      |
+| Type                    | Fields                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `Network`               | `id`, `name?`, `chainId?`, `type?`, `environment?`, `nativeCurrency?`, `isActive?`                               |
+| `Endpoint`              | `id`, `networkId?`, `region?`, `name?`, `priority?`, `status?`, `isEnabled?`, `timeoutMs?`, `retryCount?`, metrics   |
+| `CreateEndpointRequest` | `name`, `networkId`, `region`, `priority?`, `timeoutMs?`, `retryCount?`, `rateLimitOverride?`                       |
+| `EndpointHealth`        | `status?`, `nodeCount?`, `healthyNodeCount?`, `latencyMs?`, `lastCheck?`                                          |
 
 ### 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?`  |
+| Type             | Fields                                                                                                                                                   |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RequestLog`     | `id`, `method?`, `status?`, `statusCode?`, `latencyMs?`, `network?`, `region?`, `timestamp?`                                                        |
+| `LogsResponse`   | `logs`, `total?`, `stats?`                                                                                                                              |
+| `LogQueryParams` | `limit?`, `offset?`, `status?`, `method?`, `apiKeyId?`, `network?`, `region?`, `search?`, `statusCode?`, `minLatencyMs?`, `maxLatencyMs?`, `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`                         |
+| Type                       | Fields                                                                                       |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| `Alert`                    | `id`, `ruleId?`, `type?`, `severity?`, `status?`, `title?`, `message?`, `firedAt?`, `metadata?`  |
+| `AlertRule`                | `id`, `name?`, `type?`, `severity?`, `isEnabled?`, `config?`, `cooldownSeconds?`           |
+| `CreateAlertRuleRequest`   | `name`, `type`, `config`, `severity?`, `cooldownSeconds?`, `isEnabled?`                       |
+| `AlertChannel`             | `id`, `name?`, `type?`, `isEnabled?`, `config?`                                           |
+| `CreateAlertChannelRequest` | `name`, `type`, `config`, `isEnabled?`                                                    |
 
 ### Billing Types
 
-| Type           | Fields                                                                                  |
-| -------------- | --------------------------------------------------------------------------------------- |
-| `Plan`         | `id`, `name`, `slug`, `price`, `currency`, `interval`, `features`, `limits`, `isActive` |
-| `Subscription` | `id`, `organizationId`, `planId`, `status`, `cancelAtPeriodEnd`, `plan?`                |
+| Type           | Fields                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------- |
+| `Plan`         | `id`, `name?`, `displayName?`, `priceMonthly?`, `limits?`, `features?`, `isActive?`                      |
+| `Subscription` | `id`, `status?`, `plan?`, `billingInterval?`, `currentPeriodEnd?`, `cancelAtPeriodEnd?`, `recentInvoices?` |
 
 ### Support Types
 
-| Type                  | Fields                                                              |
-| --------------------- | ------------------------------------------------------------------- |
-| `SupportTicket`       | `id`, `organizationId`, `subject`, `category`, `priority`, `status` |
-| `CreateTicketRequest` | `subject`, `category`, `priority`, `message`                        |
+| Type                  | Fields                                                                         |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `SupportTicket`       | `id`, `subject?`, `category?`, `priority?`, `status?`, `messages?`, `createdBy?`  |
+| `CreateTicketRequest` | `subject`, `body`, `category?`, `priority?`                                       |
+| `TicketMessage`       | `id`, `body?`, `isStaff?`, `author?`, `createdAt?`                                |
 
 ### Error Types
 
@@ -441,7 +555,7 @@ try {
 } catch (err) {
   if (err instanceof IteradianError) {
     console.log(`Status: ${err.statusCode}`); // 401
-    console.log(`Message: ${err.message}`); // "Invalid credentials"
+    console.log(`Message: ${err.message}`); // "Invalid credentials" (validation errors: messages joined with ", ")
     console.log(`Error: ${err.error}`); // Error code
   } else {
     console.log(`Unexpected error: ${err}`);
@@ -449,6 +563,16 @@ try {
 }
 ```
 
+### Terms acceptance (403 `TERMS_ACCEPTANCE_REQUIRED`)
+
+After Iteradian publishes a new version of the Terms of Service, Privacy
+Policy or DPA, any write (POST/PUT/PATCH/DELETE) made with a user JWT may
+answer `IteradianError` with `statusCode` 403 until the user accepts the new
+version in the dashboard (the response body carries
+`code: "TERMS_ACCEPTANCE_REQUIRED"`, `termsVersion` and `termsUrl`). API keys
+and agent tokens are unaffected. `organizations.acceptInvite(id, {
+acceptedTerms: true })` records the acceptance as part of joining.
+
 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":
@@ -465,6 +589,9 @@ try {
   if (err instanceof IteradianError) {
     if (err.isRateLimited) {
       // -32005. Wait err.retryAfter seconds and try again.
+    } else if (err.isDailyLimitReached) {
+      // -32008. This API key's daily limit is used up. err.data carries
+      // { dailyLimit, used, cost, resetsAt }; resetsAt is the next 00:00 UTC.
     } 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.
@@ -489,8 +616,9 @@ 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.
+  recover until the billing period rolls over, and `-32008` (per-API-key daily
+  limit) not until `error.data.resetsAt` (the next 00:00 UTC), 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.
@@ -622,10 +750,61 @@ This SDK takes both, and defaults the gateway to `https://rpc.iteradian.com`.
   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.
+  quota exhausted, `-32007` overage spend cap reached, `-32008` the API key's
+  own daily limit reached (`error.data = { dailyLimit, used, cost, resetsAt }`).
+  None of the last three recover before `resetsAt` (the billing period roll-over,
+  or the next 00:00 UTC for `-32008`), so retrying them is wasted work.
+
+Plans (defaults; an admin can change them): Free 25 rps / 3M per month with no
+overage (requests stop at the quota, no card needed), Developer 100 rps / 5M
+with overage at $6 per million, Professional 500 rps / 30M at $4.50 per million,
+Dedicated per contract from $4 per million. Trials are offered on Developer
+only; a trial that ends unpaid falls back to Free. See `sdks/SDK_CONTRACT.md`
+for the full table.
+
+### WebSocket
+
+The gateway also serves JSON-RPC over WebSocket at
+`wss://rpc.iteradian.com/ws/v1/{network}`. This SDK does not wrap it on
+purpose: connect with any WebSocket client, such as ethers
+`WebSocketProvider`, viem's `webSocket()` transport, or the built-in
+`WebSocket` in browsers and Node 22+. Authenticate with the
+`X-Api-Key` header, `Authorization: Bearer <key>`, or `?apiKey=<key>` on the
+URL (browsers cannot set headers on a WebSocket).
 
-Plans: Developer 20 rps / 5M per month, Professional 100 rps / 30M, Dedicated
-per contract. See `sdks/SDK_CONTRACT.md` for the full table.
+```typescript
+const ws = new WebSocket(
+  "wss://rpc.iteradian.com/ws/v1/eth-mainnet?apiKey=itrd_live_...",
+);
+
+ws.addEventListener("open", () => {
+  ws.send(JSON.stringify({
+    jsonrpc: "2.0", id: 1, method: "eth_subscribe", params: ["newHeads"],
+  }));
+});
+
+ws.addEventListener("message", (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.method === "eth_subscription") {
+    console.log("new head", msg.params.result.number);
+  }
+});
+
+ws.addEventListener("close", (event) => {
+  // 1012: node restarted, reconnect and re-subscribe. 4003: key revoked, stop.
+  console.log("closed", event.code);
+});
+```
 
-**WebSocket is not available.** The gateway serves HTTPS JSON-RPC only.
+- Each message you send is charged like an HTTP request (a batch of N costs N).
+  Subscription notifications pushed to you are not charged.
+- A message refused by a limit gets an ordinary JSON-RPC error under that
+  call's `id`, with the same codes as above (`-32005` to `-32008`). The socket
+  stays open.
+- An organization can hold `max(5, floor(concurrency / 4))` streams at once;
+  past that the upgrade is refused with HTTP 429. Other upgrade failures: 400
+  bad path, 401/403 bad key, 404 unknown network, 503 no WebSocket-capable node.
+- Close code `1012` means the upstream node restarted: reconnect and
+  re-subscribe. `4003` means the key was revoked or the organization suspended
+  (keys are re-checked every 60 s): do not reconnect.
+- The server pings every 30 s. Messages are limited to 1 MB.