finprodata-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Hopen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# finprodata-sdk
+
+TypeScript SDK for the [finprodata](https://api.finprodata.com) API — verified, never-stale data on finance professionals (PE/VC firms, fund managers, LPs, and the people who work there).
+
+```bash
+npm install finprodata-sdk
+```
+
+```ts
+import { Finprodata } from "finprodata-sdk";
+
+const client = new Finprodata({ apiKey: process.env.FINPRODATA_API_KEY! });
+
+// Search is free; revealing a verified email costs 1 credit.
+const firms = await client.searchFirms({ state: "TX", focusInvestorType: "private_equity" });
+const leads = await client.leads({ firmCreditStrategy: "direct_lending", role: "operations" });
+```
+
+Get a key at https://api.finprodata.com. Full API docs: https://api.finprodata.com/docs

package/dist/index.d.ts

@@ -0,0 +1,338 @@
+export interface Provenanced<T> {
+    value: T;
+    source: string;
+    source_ref?: string | null;
+    last_verified_at: string;
+    confidence: number;
+}
+export interface FocusTag {
+    dimension: "sector" | "stage" | "check_size" | "geography" | "investor_type";
+    value: string;
+    source: string;
+    last_verified_at: string;
+    confidence: number;
+}
+export interface Firm {
+    id: string;
+    crd_number: number | null;
+    name: string;
+    org_type: string;
+    city: string | null;
+    state: string | null;
+    aum: number | null;
+    website: string | null;
+    focus_tags: FocusTag[];
+}
+export interface PersonEmployment {
+    firm_id: string;
+    firm_name: string;
+    title: Provenanced<string | null>;
+}
+export interface ContactPresence {
+    channel: string;
+    available: boolean;
+    status: string;
+    last_verified_at: string;
+}
+export interface Person {
+    id: string;
+    crd_number: number | null;
+    full_name: string;
+    linkedin_url: string | null;
+    employments: PersonEmployment[];
+    contacts: ContactPresence[];
+}
+export interface Page<T> {
+    data: T[];
+    /** True result-set size — trust this, never count visible rows. */
+    total_matches: number;
+    next_cursor: string | null;
+}
+export interface IdentifyQuery {
+    name: string;
+    firm?: string;
+    state?: string;
+    title?: string;
+}
+export interface IdentifyCandidate {
+    person_id: string;
+    full_name: string;
+    crd_number: number | null;
+    firm_name: string | null;
+    firm_state: string | null;
+    title: string | null;
+    confidence: number;
+    data_age_days: number | null;
+}
+export interface IdentifyResult {
+    query: IdentifyQuery;
+    /** false = no acceptable match exists; STOP, do not invent one. */
+    match_found: boolean;
+    /** true = the server judged the top candidate unambiguous. */
+    auto_match: boolean;
+    total_matches: number;
+    best: IdentifyCandidate | null;
+    candidates: IdentifyCandidate[];
+}
+export interface RevealResponse {
+    person_id: string;
+    cached: boolean;
+    /** true only for registry-confirmed employment + deliverable email. */
+    verified: boolean;
+    /** Provenance of the employment behind this contact. */
+    verification_tier: "registry_verified" | "web_confirmed" | "unconfirmed";
+    reason: string | null;
+    email: {
+        value: string;
+        status: string;
+        source: string;
+        last_verified_at: string;
+        confidence: number;
+    } | null;
+    units_spent: number;
+}
+export interface ContributeResponse {
+    accepted: boolean;
+    contribution_id?: string;
+    status?: string;
+    reason?: string;
+    note?: string;
+}
+export interface UsageSummary {
+    period: string;
+    by_cost_class: Record<string, number>;
+    total_units: number;
+    monthly_unit_cap: number | null;
+    units_remaining: number | null;
+    client_version?: string | null;
+}
+export declare class FinprodataError extends Error {
+    readonly status: number;
+    readonly title: string;
+    readonly detail: Record<string, unknown>;
+    constructor(status: number, title: string, detail: Record<string, unknown>);
+    get retryAfterSeconds(): number | null;
+}
+export interface FinprodataOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetchFn?: typeof fetch;
+    /**
+     * Reporting client id + version, sent as the X-Finprodata-Client header on
+     * every request (e.g. "finprodata-mcp/0.2.1"). Lets the server see which
+     * client version each key is on. Optional.
+     */
+    clientVersion?: string;
+}
+export declare class Finprodata {
+    private apiKey;
+    private baseUrl;
+    private fetchFn;
+    private clientVersion?;
+    constructor(opts: FinprodataOptions);
+    private request;
+    searchFirms(params?: {
+        q?: string;
+        state?: string;
+        orgType?: string;
+        focusInvestorType?: string;
+        focusSector?: string;
+        focusStage?: string;
+        focusGeography?: string;
+        aumMin?: number;
+        aumMax?: number;
+        /** Form D raise size — the long-tail sizing signal */
+        offeringMin?: number;
+        offeringMax?: number;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Firm>>;
+    getFirm(idOrCrd: string): Promise<Firm>;
+    searchPeople(params?: {
+        q?: string;
+        firmId?: string;
+        title?: string;
+        /** people AT firms in this state */
+        firmState?: string;
+        /** people AT firms with this investing focus, e.g. venture_capital */
+        firmInvestorType?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Person>>;
+    getPerson(id: string): Promise<Person>;
+    /** Costs credits when not served from cache. Check usage() first. */
+    revealContact(personId: string, opts?: {
+        maxAgeDays?: number;
+    }): Promise<RevealResponse>;
+    /**
+     * Contribute a contact detail you verified that finprodata doesn't have. FREE.
+     * It enters quarantine and is verified before being served; you earn credit
+     * when it is promoted. Only submit details with a clean evidence source.
+     */
+    contribute(input: {
+        entityType: "person" | "firm";
+        entityId: string;
+        field: "email" | "phone" | "linkedin_url" | "title" | "website";
+        value: string;
+        evidenceUrl?: string;
+    }): Promise<ContributeResponse>;
+    /** Smartlead-ready CSV of already-revealed contacts. Never enriches. */
+    exportSmartleadCsv(personIds: string[]): Promise<string>;
+    /**
+     * Batch person resolution (up to 50 queries in ONE call). The server
+     * decides match quality: match_found false means stop; auto_match true
+     * means the top candidate is safe to use without human review.
+     */
+    identifyPeople(queries: IdentifyQuery[]): Promise<{
+        results: IdentifyResult[];
+    }>;
+    /** findLPs-style allocator search: pensions, endowments, family offices, funds. FREE. */
+    searchAllocators(params?: {
+        q?: string;
+        type?: string;
+        state?: string;
+        clientBase?: string;
+        aumMin?: number;
+        aumMax?: number;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        data: unknown[];
+        total_matches: number;
+        next_cursor: string | null;
+    }>;
+    /** Connection graph from a firm or person: {nodes, edges}. FREE. */
+    network(kind: "firm" | "person", id: string, limit?: number): Promise<{
+        seed: string;
+        nodes: Array<{
+            id: string;
+            type: string;
+            label: string;
+        }>;
+        edges: Array<{
+            source: string;
+            target: string;
+            type: string;
+            label?: string;
+        }>;
+    }>;
+    usage(): Promise<UsageSummary>;
+    /**
+     * Composed lead briefs for an ICP: ranked firms each with a rationale, best
+     * contact (verified email + confidence only when already revealed), warm
+     * paths from your imported connections, and categorized intent signals.
+     * FREE; reveal stays the only paid step. Pass format:"csv" (optionally
+     * tab:"signals") to get the deliverable spreadsheet tabs as CSV text.
+     */
+    leads(params?: {
+        role?: string;
+        firmInvestorType?: string;
+        firmStage?: string;
+        firmCreditStrategy?: string;
+        firmSignal?: string;
+        state?: string;
+        aumMin?: number;
+        aumMax?: number;
+        sinceDays?: number;
+        limit?: number;
+        format?: "json" | "csv";
+        tab?: "contacts" | "signals";
+        /** Exclude firms served to this key in the last 30 days — weekly pulls yield NEW leads. */
+        fresh?: boolean;
+        /** Firm ids to exclude (already in your CRM / do-not-contact). */
+        excludeFirmIds?: string[];
+    }): Promise<{
+        data: LeadBrief[];
+    } | string>;
+    /**
+     * Import your LinkedIn connections (parsed rows from the LinkedIn
+     * "Connections" export) as the warm-path substrate for leads(). Scoped to
+     * your API key. mode "merge" (default) is idempotent; "replace" clears the
+     * previous import. FREE.
+     */
+    importConnections(connections: Array<{
+        name: string;
+        company?: string;
+        title?: string;
+    }>, opts?: {
+        mode?: "merge" | "replace";
+    }): Promise<{
+        imported: number;
+        total: number;
+        mode: string;
+    }>;
+    /** Count + last import time of your stored connections. FREE. */
+    connections(): Promise<{
+        total: number;
+        last_imported_at: string | null;
+    }>;
+    /**
+     * On-demand enrichment: research the given firms live (grounded web search)
+     * and write dated, cited intent signals so a thin query becomes a full
+     * answer. Bounded (up to 5 firms/call), skips firms researched in the last
+     * 30 days, time-guarded. Pass firm ids (from a prior search) or a firm-name
+     * query. The freshly written signals then show up in search_people
+     * (firm_signal=), /v1/signals, and get_lead_briefs.
+     */
+    enrich(params: {
+        firmIds?: string[];
+        q?: string;
+        limit?: number;
+    }): Promise<{
+        enriched: Array<{
+            firm_id: string;
+            firm_name: string;
+            signals: number;
+            ai_signals: number;
+        }>;
+        total_signals: number;
+        skipped_fresh: number;
+        not_researched: number;
+    }>;
+}
+/** One composed lead brief from GET /v1/leads. */
+export interface LeadBrief {
+    firm_id: string;
+    firm_name: string;
+    state: string | null;
+    website: string | null;
+    aum: number | null;
+    aum_display: string | null;
+    score: number;
+    rationale: string;
+    contact: {
+        person_id: string;
+        name: string;
+        title: string | null;
+        linkedin_url: string | null;
+        email: string | null;
+        email_status: string | null;
+        email_confidence: number | null;
+    } | null;
+    warm_paths: Array<{
+        name: string;
+        company: string;
+        title: string | null;
+    }>;
+    outreach_hook: string | null;
+    signals: Array<{
+        signal: string;
+        observed_at: string | null;
+        evidence: string | null;
+        source: string;
+        weight: number;
+        section: string;
+        buying_trigger: string;
+        initiative: string;
+    }>;
+    intel: Array<{
+        section: string;
+        title: string;
+        items: Array<{
+            marker: string;
+            evidence: string | null;
+            signal: string;
+            observed_at: string | null;
+        }>;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,216 @@
+// packages/sdk/src/index.ts
+var FinprodataError = class extends Error {
+  constructor(status, title, detail) {
+    super(`${status}: ${title}`);
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.name = "FinprodataError";
+  }
+  status;
+  title;
+  detail;
+  get retryAfterSeconds() {
+    const v = this.detail["retry_after"];
+    return typeof v === "number" ? v : null;
+  }
+};
+var Finprodata = class {
+  apiKey;
+  baseUrl;
+  fetchFn;
+  clientVersion;
+  constructor(opts) {
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.finprodata.com").replace(/\/$/, "");
+    this.fetchFn = opts.fetchFn ?? fetch;
+    this.clientVersion = opts.clientVersion;
+  }
+  async request(method, path, opts = {}) {
+    const url = new URL(`${this.baseUrl}/v1${path}`);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const res = await this.fetchFn(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...opts.body !== void 0 ? { "Content-Type": "application/json" } : {},
+        ...this.clientVersion ? { "X-Finprodata-Client": this.clientVersion } : {}
+      },
+      body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    if (!res.ok) {
+      let detail = {};
+      try {
+        detail = await res.json();
+      } catch {
+      }
+      throw new FinprodataError(
+        res.status,
+        typeof detail["title"] === "string" ? detail["title"] : res.statusText,
+        detail
+      );
+    }
+    if (opts.raw) return await res.text();
+    return await res.json();
+  }
+  searchFirms(params = {}) {
+    return this.request("GET", "/firms", {
+      query: {
+        q: params.q,
+        state: params.state,
+        org_type: params.orgType,
+        "focus.investor_type": params.focusInvestorType,
+        "focus.sector": params.focusSector,
+        "focus.stage": params.focusStage,
+        "focus.geography": params.focusGeography,
+        aum_min: params.aumMin,
+        aum_max: params.aumMax,
+        offering_min: params.offeringMin,
+        offering_max: params.offeringMax,
+        limit: params.limit,
+        cursor: params.cursor
+      }
+    });
+  }
+  getFirm(idOrCrd) {
+    return this.request("GET", `/firms/${encodeURIComponent(idOrCrd)}`);
+  }
+  searchPeople(params = {}) {
+    return this.request("GET", "/people", {
+      query: {
+        q: params.q,
+        firm_id: params.firmId,
+        title: params.title,
+        firm_state: params.firmState,
+        "firm_focus.investor_type": params.firmInvestorType,
+        limit: params.limit,
+        cursor: params.cursor
+      }
+    });
+  }
+  getPerson(id) {
+    return this.request("GET", `/people/${encodeURIComponent(id)}`);
+  }
+  /** Costs credits when not served from cache. Check usage() first. */
+  revealContact(personId, opts = {}) {
+    return this.request("POST", `/people/${personId}/reveal`, {
+      body: { channels: ["email"], max_age_days: opts.maxAgeDays }
+    });
+  }
+  /**
+   * Contribute a contact detail you verified that finprodata doesn't have. FREE.
+   * It enters quarantine and is verified before being served; you earn credit
+   * when it is promoted. Only submit details with a clean evidence source.
+   */
+  contribute(input) {
+    return this.request("POST", "/contributions", {
+      body: {
+        entity_type: input.entityType,
+        entity_id: input.entityId,
+        field: input.field,
+        value: input.value,
+        evidence_url: input.evidenceUrl
+      }
+    });
+  }
+  /** Smartlead-ready CSV of already-revealed contacts. Never enriches. */
+  exportSmartleadCsv(personIds) {
+    return this.request("POST", "/exports/csv", {
+      body: { person_ids: personIds, format: "smartlead" },
+      raw: true
+    });
+  }
+  /**
+   * Batch person resolution (up to 50 queries in ONE call). The server
+   * decides match quality: match_found false means stop; auto_match true
+   * means the top candidate is safe to use without human review.
+   */
+  identifyPeople(queries) {
+    return this.request("POST", "/people/identify", { body: { queries } });
+  }
+  /** findLPs-style allocator search: pensions, endowments, family offices, funds. FREE. */
+  searchAllocators(params = {}) {
+    return this.request("GET", "/allocators", {
+      query: {
+        q: params.q,
+        type: params.type,
+        state: params.state,
+        client_base: params.clientBase,
+        aum_min: params.aumMin,
+        aum_max: params.aumMax,
+        limit: params.limit,
+        cursor: params.cursor
+      }
+    });
+  }
+  /** Connection graph from a firm or person: {nodes, edges}. FREE. */
+  network(kind, id, limit) {
+    return this.request("GET", `/network/${kind}/${id}`, { query: { limit } });
+  }
+  usage() {
+    return this.request("GET", "/usage");
+  }
+  /**
+   * Composed lead briefs for an ICP: ranked firms each with a rationale, best
+   * contact (verified email + confidence only when already revealed), warm
+   * paths from your imported connections, and categorized intent signals.
+   * FREE; reveal stays the only paid step. Pass format:"csv" (optionally
+   * tab:"signals") to get the deliverable spreadsheet tabs as CSV text.
+   */
+  leads(params = {}) {
+    const query = {
+      role: params.role,
+      "firm_focus.investor_type": params.firmInvestorType,
+      "firm_focus.stage": params.firmStage,
+      "firm_focus.credit_strategy": params.firmCreditStrategy,
+      firm_signal: params.firmSignal,
+      state: params.state,
+      aum_min: params.aumMin,
+      aum_max: params.aumMax,
+      since_days: params.sinceDays,
+      limit: params.limit,
+      format: params.format,
+      tab: params.tab,
+      fresh: params.fresh ? "true" : void 0,
+      exclude_firm_ids: params.excludeFirmIds?.length ? params.excludeFirmIds.join(",") : void 0
+    };
+    if (params.format === "csv") {
+      return this.request("GET", "/leads", { query, raw: true });
+    }
+    return this.request("GET", "/leads", { query });
+  }
+  /**
+   * Import your LinkedIn connections (parsed rows from the LinkedIn
+   * "Connections" export) as the warm-path substrate for leads(). Scoped to
+   * your API key. mode "merge" (default) is idempotent; "replace" clears the
+   * previous import. FREE.
+   */
+  importConnections(connections, opts = {}) {
+    return this.request("POST", "/connections/import", {
+      body: { mode: opts.mode, connections }
+    });
+  }
+  /** Count + last import time of your stored connections. FREE. */
+  connections() {
+    return this.request("GET", "/connections");
+  }
+  /**
+   * On-demand enrichment: research the given firms live (grounded web search)
+   * and write dated, cited intent signals so a thin query becomes a full
+   * answer. Bounded (up to 5 firms/call), skips firms researched in the last
+   * 30 days, time-guarded. Pass firm ids (from a prior search) or a firm-name
+   * query. The freshly written signals then show up in search_people
+   * (firm_signal=), /v1/signals, and get_lead_briefs.
+   */
+  enrich(params) {
+    return this.request("POST", "/enrich", {
+      body: { firm_ids: params.firmIds, q: params.q, limit: params.limit }
+    });
+  }
+};
+export {
+  Finprodata,
+  FinprodataError
+};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "finprodata-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the finprodata API — verified, never-stale data on finance professionals (PE/VC firms, fund managers, LPs, and the people who work there).",
+  "license": "MIT",
+  "author": "Brandon Hopen",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "homepage": "https://api.finprodata.com/docs",
+  "repository": { "type": "git", "url": "git+https://github.com/Sliver5/finprodata-js.git" },
+  "keywords": ["finprodata","finance","private-equity","venture-capital","investors","contacts","api","sdk"]
+}