@kepler-insights/sdk

Kepler Insights — TypeScript SDK

Official TypeScript / JavaScript SDK for the Kepler Insights API — curated company-scoring intelligence over a 67-signal engine.

Install

npm install @kepler-insights/sdk
# or
pnpm add @kepler-insights/sdk
# or
yarn add @kepler-insights/sdk

Requires Node 18+. Native fetch is the only network dep — no axios, no node-fetch polyfill needed. Works in Node, Deno, Bun, and Cloudflare Workers.

Quickstart

import { Kepler } from "@kepler-insights/sdk";

const client = new Kepler({ apiKey: "ki_live_..." });

const score = await client.score("stripe.com");
console.log(`${score.domain}: ${score.ki_rating} (${score.composite_score.toFixed(1)})`);
console.log(`  team: ${score.buckets.team_structure.toFixed(1)}`);
console.log(`  market: ${score.buckets.market_position.toFixed(1)}`);

Sandbox keys (ki_test_...) accept only the 4 canned domains — acme.test, unicorn.test, struggling.test, cohort.test. See the Sandbox guide.

API surface

Method	Endpoint	Returns
client.score(domain)	POST /v1/score	Score
client.getScore(domain)	GET /v1/score/{domain}	Score
client.startScore(domain)	POST /v1/score?wait=false	Job (Growth+)
client.getJob(jobId)	GET /v1/jobs/{job_id}	JobResponse
client.history(domain, { limit, cursor })	GET /v1/score/{domain}/history	HistoryPage
client.iterHistory(domain, { maxRecords })	(auto-paginates)	AsyncIterable<HistoryRecord>
client.cohort(domain)	GET /v1/company/{domain}/cohort	Cohort
client.confidence(domain)	GET /v1/company/{domain}/confidence	Confidence
client.distribution()	GET /v1/distribution	Distribution
client.movers(window)	GET /v1/movers	Movers
client.signals()	GET /v1/signals	SignalsManifest
client.usage()	GET /v1/usage	Usage

Every response shape is exported as a TypeScript type from the package root.

Async cold scoring

Cold scoring takes 30–60 seconds. On Growth and above, you can start a job and poll without holding an HTTP connection open:

const job = await client.startScore("stripe.com");
const score = await job.wait({ timeoutMs: 180_000 });
console.log(score.composite_score);

If the API short-circuits to a cached-fresh response (no cold work needed), startScore returns a Job already in the complete state — wait() returns instantly. This mirrors Stripe's payment_intent "no action needed" pattern.

Error handling

Every error inherits from KeplerError. Branch with instanceof:

import {
  Kepler,
  AuthError,
  ColdBudgetExhausted,
  FreeTierSandboxOnly,
  NotFound,
  RateLimitError,
  ScoringTimeout,
} from "@kepler-insights/sdk";

try {
  const score = await client.score("stripe.com");
} catch (err) {
  if (err instanceof FreeTierSandboxOnly) {
    console.log("Upgrade to Starter for live scoring.");
  } else if (err instanceof ColdBudgetExhausted) {
    console.log(`Monthly cap hit. Resets in ${err.retryAfter}s.`);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry in ${err.retryAfter}s.`);
  } else if (err instanceof ScoringTimeout) {
    console.log("Cold scoring exceeded sync budget — use startScore() for async.");
  } else if (err instanceof NotFound) {
    console.log("Never scored. Trigger one with score(domain).");
  } else if (err instanceof AuthError) {
    console.log("Invalid or revoked API key.");
  } else {
    throw err;
  }
}

The SDK auto-retries 5xx and network errors with exponential backoff (3 attempts default). It never retries 4xx — those are caller errors.

Configuration

const client = new Kepler({
  apiKey: "ki_live_...",
  baseUrl: "https://api.keplerinsights.us", // override only for testing
  timeoutMs: 70_000,                          // per-request timeout
  retries: 3,                                 // 5xx retry attempts
});

For custom transports (proxies, mTLS, etc.) pass your own fetch:

import { Kepler } from "@kepler-insights/sdk";
import { ProxyAgent } from "undici";

const dispatcher = new ProxyAgent("http://proxy.local:8080");
const customFetch: typeof fetch = (input, init) =>
  fetch(input, { ...init, dispatcher } as RequestInit);

const client = new Kepler({ apiKey: "ki_live_...", fetchImpl: customFetch });

Module compatibility

Dual ESM + CJS published. Use whichever your project prefers:

// ESM
import { Kepler } from "@kepler-insights/sdk";

// CommonJS
const { Kepler } = require("@kepler-insights/sdk");

TypeScript declarations ship in both flavors (.d.ts and .d.cts).

Development

git clone <repo>
cd Ki_dev/sdk-typescript
npm install
npm test                                                   # vitest
npm run typecheck                                          # tsc --noEmit
npm run build                                              # tsup → dist/

License

MIT. The API itself is proprietary; the SDK wrapper is MIT-licensed so you can vendor it freely.