Skip to main content
How It Works→Sandbox→Pricing→
← Back to Docs

SDK Reference

Node.js SDK

Full reference for the @rankigi/sdk package.

Installation

bash
npm install @rankigi/sdk

Requires Node.js 18+ and TypeScript 5+ (recommended).

Configuration

typescript
import { Rankigi } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:  process.env.RANKIGI_API_KEY,
  agentId: process.env.RANKIGI_AGENT_ID,
});

Get your API key from the Dashboard → API Keys page. The agent ID is the UUID of the agent you want to track.

Methods

trackToolCall()

Record an agent tool invocation with input/output.

typescript
await rankigi.trackToolCall({
  tool: "stripe_refund",
  input: { amount: 100, reason: "duplicate_charge" },
  output: { success: true, refund_id: "re_abc123" },
});

trackAgentOutput()

Record a general agent action or output.

typescript
await rankigi.trackAgentOutput({
  action: "generate_report",
  output: { report_id: "rpt_456", pages: 12 },
  severity: "info",
});

trackError()

Record an error during agent operation.

typescript
await rankigi.trackError({
  tool: "database_query",
  error: "Connection timeout after 30s",
  severity: "critical",
});

trackCustomEvent()

Record any custom event with arbitrary payload.

typescript
await rankigi.trackCustomEvent({
  action: "policy_decision",
  tool: "approval_engine",
  payload: {
    decision: "approved",
    amount: 5000,
    approver: "agent_7b2f",
  },
  severity: "warn",
});

initiateHandshake() / completeHandshake() / verifyHandshake()

Establish and verify cryptographic handshakes between agents.

typescript
// Agent A initiates a handshake with Agent B
const handshake = await rankigi.initiateHandshake({
  targetAgentId: "agent-b-uuid",
  purpose: "data_exchange",
  metadata: { dataset: "customer_records" },
});

// Agent B completes the handshake
await rankigi.completeHandshake({
  handshakeId: handshake.id,
  accepted: true,
});

// Either party can verify
const result = await rankigi.verifyHandshake({
  handshakeId: handshake.id,
});

flush() / close()

Force flush buffered events or gracefully shut down the client.

typescript
// Force flush all buffered events immediately
await rankigi.flush();

// Gracefully close the client (flushes + stops background timer)
await rankigi.close();

Buffer and Retry Behavior

The SDK buffers events in memory and flushes them to the RANKIGI API in batches. This minimizes network overhead and ensures the sidecar does not block your agent's critical path.

Flush interval5,000ms (configurable)
Max buffer size100 events (configurable)
Retry strategyExponential backoff, 3 retries
Failure behaviorSilent drop (sidecar principle)

TypeScript Types

typescript
interface TrackToolCallParams {
  tool: string;
  input?: Record<string, unknown>;
  output?: Record<string, unknown>;
  severity?: "info" | "warn" | "critical";
}

interface TrackAgentOutputParams {
  action: string;
  output?: Record<string, unknown>;
  severity?: "info" | "warn" | "critical";
}

interface TrackErrorParams {
  tool: string;
  error: string;
  severity?: "info" | "warn" | "critical";
}

interface TrackCustomEventParams {
  action: string;
  tool?: string;
  payload?: Record<string, unknown>;
  severity?: "info" | "warn" | "critical";
}

interface RankigiConfig {
  apiKey: string;
  agentId: string;
  baseUrl?: string;       // default: "https://rankigi.com"
  flushIntervalMs?: number; // default: 5000
  maxBufferSize?: number;   // default: 100
  maxRetries?: number;      // default: 3
}

Full Example

typescript
import { Rankigi } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:  process.env.RANKIGI_API_KEY,
  agentId: process.env.RANKIGI_AGENT_ID,
});

async function processRefund(chargeId: string, amount: number) {
  try {
    // Your business logic
    const result = await stripe.refunds.create({
      charge: chargeId,
      amount,
    });

    // Track the action with RANKIGI
    await rankigi.trackToolCall({
      tool: "stripe_refund",
      input: { charge_id: chargeId, amount },
      output: { success: true, refund_id: result.id },
    });

    return result;
  } catch (error) {
    // Track errors too
    await rankigi.trackError({
      tool: "stripe_refund",
      error: error instanceof Error ? error.message : "Unknown error",
      severity: "critical",
    });
    throw error;
  }
}

// Graceful shutdown
process.on("SIGTERM", async () => {
  await rankigi.close();
  process.exit(0);
});

Error Handling

typescript
import { Rankigi, RankigiError } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:  process.env.RANKIGI_API_KEY,
  agentId: process.env.RANKIGI_AGENT_ID,
});

// The SDK is designed to never throw — it logs errors
// and continues silently (sidecar principle).
// If you need to handle errors explicitly:

rankigi.on("error", (error: RankigiError) => {
  console.error("[rankigi]", error.message);
  // error.code: "AUTH_FAILED" | "RATE_LIMITED" | "NETWORK_ERROR"
  // error.statusCode: HTTP status code (if applicable)
});

// Track calls are fire-and-forget by default.
// The SDK buffers events and retries on failure.
// If the buffer is full, oldest events are dropped.