@iteradian/sdk

v1.0.0

Published

4 months ago

Official Iteradian Control Plane SDK for JavaScript/TypeScript

Downloads

0High
0Medium
0Low

andrey-commradian

iteradian rpc blockchain api sdk web3

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

npm install @iteradian/sdk

yarn add @iteradian/sdk

pnpm add @iteradian/sdk

Quick Start

import { IteradianClient } from "@iteradian/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: "[email protected]",
  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)

const { IteradianClient } = require("@iteradian/sdk");

const client = new IteradianClient({
  baseUrl: "https://api.iteradian.com/api/v1",
});

Using API Key Authentication

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

import { IteradianClient, IteradianConfig } from "@iteradian/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

// Set/clear access token at runtime
client.setAccessToken("new-token");
client.clearAccessToken();

Authentication (`client.auth`)

// 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: "[email protected]" });

// Password Reset
await client.auth.forgotPassword({ email: "[email protected]" });
await client.auth.resetPassword({ token: "...", newPassword: "..." });

Organizations (`client.organizations`)

// 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: "[email protected]",
  role: "member",
});
await client.organizations.removeMember(orgId, memberId);

API Keys (`client.apiKeys`)

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`)

// 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

// 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`)

// 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`)

// 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`)

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`)

const plans = await client.plans.list();
const plan = await client.plans.get(planId);

Support (`client.support`)

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

import { IteradianClient } from "@iteradian/sdk";
import { IteradianError } from "@iteradian/sdk/http";

const client = new IteradianClient({ baseUrl: "..." });

try {
  await client.auth.login({ email: "[email protected]", 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}`);
  }
}

Retry Behavior

The SDK automatically retries requests on:

429 Too Many Requests — with exponential backoff
5xx Server Errors — with exponential backoff

Backoff formula: min(1000 * 2^(attempt-1), 10000) ms

Configure via constructor:

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:

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:

import { AuthResource } from "@iteradian/sdk";
import { HttpClient } from "@iteradian/sdk/http";

const http = new HttpClient({ baseUrl: "..." });
const auth = new AuthResource(http);
const tokens = await auth.login({ email: "...", password: "..." });

Pre-Authenticated Client

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

# Build (CJS + ESM + DTS)
npm run build

# Watch mode
npm run dev

# Type check
npm run lint

# Test
npm run test

Built with tsup — outputs:

dist/index.js (CommonJS)
dist/index.mjs (ESM)
dist/index.d.ts (TypeScript declarations)

Project Structure

sdks/typescript/
├── package.json          # @iteradian/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