@kepler-insights/sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,351 @@
+/**
+ * Response type definitions matching Ki_dev/docs/openapi.yaml.
+ *
+ * Hand-written for clarity. Every type uses non-readonly fields so callers
+ * can spread or modify freely. Unknown server-added fields pass through
+ * unmolested — we don't validate at runtime (the API contract is enforced
+ * server-side; clients trust it).
+ */
+interface Buckets {
+    team_structure: number;
+    market_position: number;
+    momentum_tailwinds: number;
+    financial_health: number;
+}
+interface Rank {
+    percentile: number;
+    cohort_size: number;
+}
+type CacheStatus = "cached" | "cold";
+interface XKeplerMeta {
+    tier: string;
+    cache_status: CacheStatus;
+    freshness_window_hours: number;
+}
+interface Score {
+    mode?: string;
+    domain: string;
+    scored_at: string;
+    ki_rating: string;
+    composite_score: number;
+    scale_premium: number;
+    buckets: Buckets;
+    rank?: Rank;
+    x_kepler?: XKeplerMeta;
+}
+interface HistoryRecord {
+    scored_at: string;
+    composite_score: number;
+    scale_premium: number;
+    ki_rating: string;
+    momentum_index?: number;
+    buckets: Buckets;
+    data_completeness_pct?: number;
+}
+interface HistoryPage {
+    mode?: string;
+    domain: string;
+    records: HistoryRecord[];
+    next_cursor?: string;
+}
+interface CohortContext {
+    sector?: string;
+    geo_scope?: string;
+}
+interface CohortTarget {
+    domain: string;
+    company_name?: string;
+    composite_score: number;
+    ki_rating: string;
+    business_profile?: string;
+    context?: CohortContext;
+}
+interface CohortStats {
+    count: number;
+    mean: number;
+    p50: number;
+    p90: number;
+    stddev: number;
+    min: number;
+    max: number;
+    rank: number;
+    percentile: number;
+}
+interface BucketDelta {
+    target: number;
+    cohort: number;
+    delta: number;
+}
+interface CohortMember {
+    domain: string;
+    company_name?: string;
+    composite_score: number;
+    ki_rating: string;
+    business_profile?: string;
+}
+interface Cohort {
+    mode?: string;
+    target: CohortTarget;
+    cohort: CohortStats;
+    bucket_means: Record<string, BucketDelta>;
+    members: CohortMember[];
+}
+type ConfidenceBand = "high" | "medium" | "directional";
+interface Confidence {
+    mode?: string;
+    domain: string;
+    scored_at: string;
+    band: ConfidenceBand;
+    completeness_pct: number;
+    failed_fetchers: string[];
+    data_warnings: string[];
+    missing_signals: string[];
+}
+interface HistBin {
+    range: string;
+    count: number;
+}
+interface Universe {
+    count: number;
+    mean: number;
+    p50: number;
+    p90: number;
+    stddev: number;
+    min: number;
+    max: number;
+    composite_hist: HistBin[];
+    scale_premium_hist: HistBin[];
+    rating_dist: Record<string, number>;
+    profile_split: Record<string, number>;
+}
+interface Distribution {
+    mode?: string;
+    pipeline_version: string;
+    universe: Universe;
+}
+type Window = "7d" | "30d" | "90d";
+interface MoverRow {
+    domain: string;
+    company_name?: string;
+    composite_now: number;
+    composite_then: number;
+    delta: number;
+    ki_rating_now: string;
+    ki_rating_then: string;
+}
+interface Movers {
+    mode?: string;
+    window: Window;
+    window_start: string;
+    window_end: string;
+    gainers: MoverRow[];
+    decliners: MoverRow[];
+}
+type Actionability = "actionable" | "slow_actionable" | "immutable";
+interface Signal {
+    key: string;
+    label: string;
+    bucket: string;
+    category: string;
+    weight: number;
+    actionability: Actionability;
+    description: string;
+}
+interface SignalsManifest {
+    version: string;
+    signals: Signal[];
+}
+interface TierLimits {
+    cached_calls_included: number | null;
+    cold_calls_included: number | null;
+    freshness_window_hours: number;
+}
+interface Usage {
+    mode?: string;
+    user_id: string;
+    period: string;
+    tier: string;
+    total_calls: number;
+    cold_calls: number;
+    cached_calls: number;
+    last_reset: string;
+    next_reset: string;
+    tier_limits: TierLimits;
+}
+type JobStatus = "pending" | "complete" | "failed";
+interface JobResultRef {
+    domain: string;
+    scored_at: string;
+}
+interface JobResponse {
+    mode?: string;
+    job_id: string;
+    status: JobStatus;
+    domain: string;
+    created_at?: string;
+    completed_at?: string | null;
+    result_ref?: JobResultRef | null;
+    score_url?: string | null;
+    failure_reason?: string | null;
+}
+
+/**
+ * High-level Kepler Insights API client.
+ *
+ * Usage
+ * -----
+ *
+ *   import { Kepler } from "@kepler-insights/sdk";
+ *   const client = new Kepler({ apiKey: "ki_live_..." });
+ *   const score = await client.score("stripe.com");
+ *   console.log(score.ki_rating, score.composite_score);
+ *
+ * Async cold scoring
+ * ------------------
+ *
+ *   const job = await client.startScore("stripe.com");
+ *   const score = await job.wait({ timeoutMs: 180_000 });
+ */
+
+interface KeplerOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    retries?: number;
+    /** Inject a custom fetch (e.g. for proxies, custom TLS). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+interface JobWaitOptions {
+    /** Total wait budget in milliseconds. Default 180_000 (3 min). */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds. Default 5_000. */
+    intervalMs?: number;
+}
+declare class Kepler {
+    private readonly transport;
+    constructor(opts: KeplerOptions);
+    /**
+     * Score a company. Blocks up to ~70s on cold scoring.
+     * Returns a cached record if one exists within the tier's freshness window.
+     */
+    score(domain: string, opts?: {
+        forceFresh?: boolean;
+    }): Promise<Score>;
+    /**
+     * Read the latest cached score. Never triggers a cold run.
+     * Throws {@link NotFound} if the domain has never been scored.
+     */
+    getScore(domain: string): Promise<Score>;
+    /**
+     * Start an async cold-scoring job (Growth+ tiers). Returns a Job handle.
+     * Use {@link Job.wait} to block until completion.
+     */
+    startScore(domain: string, opts?: {
+        forceFresh?: boolean;
+    }): Promise<Job>;
+    /** Single poll of an async scoring job. */
+    getJob(jobId: string): Promise<JobResponse>;
+    history(domain: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<HistoryPage>;
+    /** Auto-paginating async iterator over every history record. */
+    iterHistory(domain: string, opts?: {
+        pageSize?: number;
+        maxRecords?: number;
+    }): AsyncIterable<HistoryRecord>;
+    cohort(domain: string): Promise<Cohort>;
+    confidence(domain: string): Promise<Confidence>;
+    distribution(): Promise<Distribution>;
+    movers(window?: Window): Promise<Movers>;
+    signals(): Promise<SignalsManifest>;
+    usage(): Promise<Usage>;
+}
+/** Handle to an async scoring job started via {@link Kepler.startScore}. */
+declare class Job {
+    private response;
+    private readonly client;
+    /** Set when the API short-circuits to a sync 200 (no cold work needed). */
+    private cachedScore;
+    constructor(client: Kepler, response: JobResponse);
+    /** Internal: wrap a sync-200 cached score response as a Job in `complete` state. */
+    static _fromCachedScore(client: Kepler, score: Score): Job;
+    get id(): string;
+    get status(): string;
+    get domain(): string;
+    get raw(): JobResponse;
+    /** One-shot poll. Updates the cached `raw` in place. */
+    refresh(): Promise<JobResponse>;
+    /**
+     * Poll until the job settles, then return the resulting {@link Score}.
+     * Throws {@link JobFailed} on a `failed` status, or {@link JobTimeout}
+     * if the job is still `pending` after `timeoutMs`.
+     */
+    wait(opts?: JobWaitOptions): Promise<Score>;
+}
+
+/**
+ * Exception hierarchy for the Kepler Insights SDK.
+ *
+ * Branch with `instanceof` or on the stable `code` string. Error messages
+ * may be tightened over time; the codes are stable.
+ *
+ *   try {
+ *     const score = await client.score("stripe.com");
+ *   } catch (err) {
+ *     if (err instanceof FreeTierSandboxOnly) { ... }
+ *     if (err instanceof ColdBudgetExhausted) { ... }
+ *   }
+ */
+interface KeplerErrorOptions {
+    statusCode?: number;
+    response?: unknown;
+}
+/** Base class for every error raised by the SDK. */
+declare class KeplerError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    constructor(code: string, message?: string, opts?: KeplerErrorOptions);
+}
+/** 401: missing, invalid, or revoked API key. */
+declare class AuthError extends KeplerError {
+}
+/** 403: live key on Free tier attempted a real-domain score. */
+declare class FreeTierSandboxOnly extends KeplerError {
+}
+/** 403: catch-all forbidden (e.g. polling someone else's job_id). */
+declare class Forbidden extends KeplerError {
+}
+/** 404: domain has no score on file, or job_id expired/unknown. */
+declare class NotFound extends KeplerError {
+}
+/** 400: malformed request (bad domain, unsupported window, etc.). */
+declare class ValidationError extends KeplerError {
+}
+/** 429: rate-limited. `retryAfter` carries the Retry-After header in seconds. */
+declare class RateLimitError extends KeplerError {
+    readonly retryAfter?: number;
+    constructor(code: string, message?: string, opts?: KeplerErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** 429 cold_budget_exhausted: monthly cold-call cap hit. `retryAfter` points at the next monthly reset (UTC). */
+declare class ColdBudgetExhausted extends RateLimitError {
+}
+/** 5xx: server-side error. Retry once; if persistent, contact support. */
+declare class ServerError extends KeplerError {
+}
+/** 504: cold scoring exceeded sync budget. Poll GET /v1/score/{domain} in ~30s, or use startScore for async. */
+declare class ScoringTimeout extends ServerError {
+}
+/** `Job.wait()` exceeded the caller's timeout while the job was still pending. */
+declare class JobTimeout extends KeplerError {
+}
+/** Async scoring job ended in `failed`. `code` carries the failure_reason. */
+declare class JobFailed extends KeplerError {
+}
+
+declare const VERSION = "1.0.0";
+
+export { type Actionability, AuthError, type BucketDelta, type Buckets, type CacheStatus, type Cohort, type CohortMember, type CohortStats, type CohortTarget, ColdBudgetExhausted, type Confidence, type ConfidenceBand, type Distribution, Forbidden, FreeTierSandboxOnly, type HistBin, type HistoryPage, type HistoryRecord, Job, JobFailed, type JobResponse, type JobResultRef, type JobStatus, JobTimeout, type JobWaitOptions, Kepler, KeplerError, type KeplerOptions, type MoverRow, type Movers, NotFound, type Rank, RateLimitError, type Score, ScoringTimeout, ServerError, type Signal, type SignalsManifest, type TierLimits, type Universe, type Usage, VERSION, ValidationError, type Window, type XKeplerMeta };

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Response type definitions matching Ki_dev/docs/openapi.yaml.
+ *
+ * Hand-written for clarity. Every type uses non-readonly fields so callers
+ * can spread or modify freely. Unknown server-added fields pass through
+ * unmolested — we don't validate at runtime (the API contract is enforced
+ * server-side; clients trust it).
+ */
+interface Buckets {
+    team_structure: number;
+    market_position: number;
+    momentum_tailwinds: number;
+    financial_health: number;
+}
+interface Rank {
+    percentile: number;
+    cohort_size: number;
+}
+type CacheStatus = "cached" | "cold";
+interface XKeplerMeta {
+    tier: string;
+    cache_status: CacheStatus;
+    freshness_window_hours: number;
+}
+interface Score {
+    mode?: string;
+    domain: string;
+    scored_at: string;
+    ki_rating: string;
+    composite_score: number;
+    scale_premium: number;
+    buckets: Buckets;
+    rank?: Rank;
+    x_kepler?: XKeplerMeta;
+}
+interface HistoryRecord {
+    scored_at: string;
+    composite_score: number;
+    scale_premium: number;
+    ki_rating: string;
+    momentum_index?: number;
+    buckets: Buckets;
+    data_completeness_pct?: number;
+}
+interface HistoryPage {
+    mode?: string;
+    domain: string;
+    records: HistoryRecord[];
+    next_cursor?: string;
+}
+interface CohortContext {
+    sector?: string;
+    geo_scope?: string;
+}
+interface CohortTarget {
+    domain: string;
+    company_name?: string;
+    composite_score: number;
+    ki_rating: string;
+    business_profile?: string;
+    context?: CohortContext;
+}
+interface CohortStats {
+    count: number;
+    mean: number;
+    p50: number;
+    p90: number;
+    stddev: number;
+    min: number;
+    max: number;
+    rank: number;
+    percentile: number;
+}
+interface BucketDelta {
+    target: number;
+    cohort: number;
+    delta: number;
+}
+interface CohortMember {
+    domain: string;
+    company_name?: string;
+    composite_score: number;
+    ki_rating: string;
+    business_profile?: string;
+}
+interface Cohort {
+    mode?: string;
+    target: CohortTarget;
+    cohort: CohortStats;
+    bucket_means: Record<string, BucketDelta>;
+    members: CohortMember[];
+}
+type ConfidenceBand = "high" | "medium" | "directional";
+interface Confidence {
+    mode?: string;
+    domain: string;
+    scored_at: string;
+    band: ConfidenceBand;
+    completeness_pct: number;
+    failed_fetchers: string[];
+    data_warnings: string[];
+    missing_signals: string[];
+}
+interface HistBin {
+    range: string;
+    count: number;
+}
+interface Universe {
+    count: number;
+    mean: number;
+    p50: number;
+    p90: number;
+    stddev: number;
+    min: number;
+    max: number;
+    composite_hist: HistBin[];
+    scale_premium_hist: HistBin[];
+    rating_dist: Record<string, number>;
+    profile_split: Record<string, number>;
+}
+interface Distribution {
+    mode?: string;
+    pipeline_version: string;
+    universe: Universe;
+}
+type Window = "7d" | "30d" | "90d";
+interface MoverRow {
+    domain: string;
+    company_name?: string;
+    composite_now: number;
+    composite_then: number;
+    delta: number;
+    ki_rating_now: string;
+    ki_rating_then: string;
+}
+interface Movers {
+    mode?: string;
+    window: Window;
+    window_start: string;
+    window_end: string;
+    gainers: MoverRow[];
+    decliners: MoverRow[];
+}
+type Actionability = "actionable" | "slow_actionable" | "immutable";
+interface Signal {
+    key: string;
+    label: string;
+    bucket: string;
+    category: string;
+    weight: number;
+    actionability: Actionability;
+    description: string;
+}
+interface SignalsManifest {
+    version: string;
+    signals: Signal[];
+}
+interface TierLimits {
+    cached_calls_included: number | null;
+    cold_calls_included: number | null;
+    freshness_window_hours: number;
+}
+interface Usage {
+    mode?: string;
+    user_id: string;
+    period: string;
+    tier: string;
+    total_calls: number;
+    cold_calls: number;
+    cached_calls: number;
+    last_reset: string;
+    next_reset: string;
+    tier_limits: TierLimits;
+}
+type JobStatus = "pending" | "complete" | "failed";
+interface JobResultRef {
+    domain: string;
+    scored_at: string;
+}
+interface JobResponse {
+    mode?: string;
+    job_id: string;
+    status: JobStatus;
+    domain: string;
+    created_at?: string;
+    completed_at?: string | null;
+    result_ref?: JobResultRef | null;
+    score_url?: string | null;
+    failure_reason?: string | null;
+}
+
+/**
+ * High-level Kepler Insights API client.
+ *
+ * Usage
+ * -----
+ *
+ *   import { Kepler } from "@kepler-insights/sdk";
+ *   const client = new Kepler({ apiKey: "ki_live_..." });
+ *   const score = await client.score("stripe.com");
+ *   console.log(score.ki_rating, score.composite_score);
+ *
+ * Async cold scoring
+ * ------------------
+ *
+ *   const job = await client.startScore("stripe.com");
+ *   const score = await job.wait({ timeoutMs: 180_000 });
+ */
+
+interface KeplerOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    retries?: number;
+    /** Inject a custom fetch (e.g. for proxies, custom TLS). Defaults to globalThis.fetch. */
+    fetchImpl?: typeof fetch;
+}
+interface JobWaitOptions {
+    /** Total wait budget in milliseconds. Default 180_000 (3 min). */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds. Default 5_000. */
+    intervalMs?: number;
+}
+declare class Kepler {
+    private readonly transport;
+    constructor(opts: KeplerOptions);
+    /**
+     * Score a company. Blocks up to ~70s on cold scoring.
+     * Returns a cached record if one exists within the tier's freshness window.
+     */
+    score(domain: string, opts?: {
+        forceFresh?: boolean;
+    }): Promise<Score>;
+    /**
+     * Read the latest cached score. Never triggers a cold run.
+     * Throws {@link NotFound} if the domain has never been scored.
+     */
+    getScore(domain: string): Promise<Score>;
+    /**
+     * Start an async cold-scoring job (Growth+ tiers). Returns a Job handle.
+     * Use {@link Job.wait} to block until completion.
+     */
+    startScore(domain: string, opts?: {
+        forceFresh?: boolean;
+    }): Promise<Job>;
+    /** Single poll of an async scoring job. */
+    getJob(jobId: string): Promise<JobResponse>;
+    history(domain: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<HistoryPage>;
+    /** Auto-paginating async iterator over every history record. */
+    iterHistory(domain: string, opts?: {
+        pageSize?: number;
+        maxRecords?: number;
+    }): AsyncIterable<HistoryRecord>;
+    cohort(domain: string): Promise<Cohort>;
+    confidence(domain: string): Promise<Confidence>;
+    distribution(): Promise<Distribution>;
+    movers(window?: Window): Promise<Movers>;
+    signals(): Promise<SignalsManifest>;
+    usage(): Promise<Usage>;
+}
+/** Handle to an async scoring job started via {@link Kepler.startScore}. */
+declare class Job {
+    private response;
+    private readonly client;
+    /** Set when the API short-circuits to a sync 200 (no cold work needed). */
+    private cachedScore;
+    constructor(client: Kepler, response: JobResponse);
+    /** Internal: wrap a sync-200 cached score response as a Job in `complete` state. */
+    static _fromCachedScore(client: Kepler, score: Score): Job;
+    get id(): string;
+    get status(): string;
+    get domain(): string;
+    get raw(): JobResponse;
+    /** One-shot poll. Updates the cached `raw` in place. */
+    refresh(): Promise<JobResponse>;
+    /**
+     * Poll until the job settles, then return the resulting {@link Score}.
+     * Throws {@link JobFailed} on a `failed` status, or {@link JobTimeout}
+     * if the job is still `pending` after `timeoutMs`.
+     */
+    wait(opts?: JobWaitOptions): Promise<Score>;
+}
+
+/**
+ * Exception hierarchy for the Kepler Insights SDK.
+ *
+ * Branch with `instanceof` or on the stable `code` string. Error messages
+ * may be tightened over time; the codes are stable.
+ *
+ *   try {
+ *     const score = await client.score("stripe.com");
+ *   } catch (err) {
+ *     if (err instanceof FreeTierSandboxOnly) { ... }
+ *     if (err instanceof ColdBudgetExhausted) { ... }
+ *   }
+ */
+interface KeplerErrorOptions {
+    statusCode?: number;
+    response?: unknown;
+}
+/** Base class for every error raised by the SDK. */
+declare class KeplerError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    constructor(code: string, message?: string, opts?: KeplerErrorOptions);
+}
+/** 401: missing, invalid, or revoked API key. */
+declare class AuthError extends KeplerError {
+}
+/** 403: live key on Free tier attempted a real-domain score. */
+declare class FreeTierSandboxOnly extends KeplerError {
+}
+/** 403: catch-all forbidden (e.g. polling someone else's job_id). */
+declare class Forbidden extends KeplerError {
+}
+/** 404: domain has no score on file, or job_id expired/unknown. */
+declare class NotFound extends KeplerError {
+}
+/** 400: malformed request (bad domain, unsupported window, etc.). */
+declare class ValidationError extends KeplerError {
+}
+/** 429: rate-limited. `retryAfter` carries the Retry-After header in seconds. */
+declare class RateLimitError extends KeplerError {
+    readonly retryAfter?: number;
+    constructor(code: string, message?: string, opts?: KeplerErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/** 429 cold_budget_exhausted: monthly cold-call cap hit. `retryAfter` points at the next monthly reset (UTC). */
+declare class ColdBudgetExhausted extends RateLimitError {
+}
+/** 5xx: server-side error. Retry once; if persistent, contact support. */
+declare class ServerError extends KeplerError {
+}
+/** 504: cold scoring exceeded sync budget. Poll GET /v1/score/{domain} in ~30s, or use startScore for async. */
+declare class ScoringTimeout extends ServerError {
+}
+/** `Job.wait()` exceeded the caller's timeout while the job was still pending. */
+declare class JobTimeout extends KeplerError {
+}
+/** Async scoring job ended in `failed`. `code` carries the failure_reason. */
+declare class JobFailed extends KeplerError {
+}
+
+declare const VERSION = "1.0.0";
+
+export { type Actionability, AuthError, type BucketDelta, type Buckets, type CacheStatus, type Cohort, type CohortMember, type CohortStats, type CohortTarget, ColdBudgetExhausted, type Confidence, type ConfidenceBand, type Distribution, Forbidden, FreeTierSandboxOnly, type HistBin, type HistoryPage, type HistoryRecord, Job, JobFailed, type JobResponse, type JobResultRef, type JobStatus, JobTimeout, type JobWaitOptions, Kepler, KeplerError, type KeplerOptions, type MoverRow, type Movers, NotFound, type Rank, RateLimitError, type Score, ScoringTimeout, ServerError, type Signal, type SignalsManifest, type TierLimits, type Universe, type Usage, VERSION, ValidationError, type Window, type XKeplerMeta };