sheeply 0.0.0-stage → 0.1.0

package/dist/dealroom/schemas.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+/**
+ * Validation for the Dealroom responses Sheeply reads, checked against the OpenAPI spec for
+ * API version 2026-10-22. Only fields the analysis uses are declared; unknown fields pass through
+ * untouched because the raw body is stored separately. See docs/dealroom-field-mapping.md.
+ */
+export const partialDate = z.string().regex(/^\d{4}(-\d{2}(-\d{2})?)?$/, "expected YYYY, YYYY-MM or YYYY-MM-DD");
+export const entityRef = z.object({
+    uuid: z.string().min(1),
+    type: z.enum(["organization", "person"]),
+    subtype: z.string().nullable().optional(),
+    name: z.string(),
+    dealroom_url: z.string().nullable().optional(),
+});
+export const taxonomyTerm = z.object({
+    id: z.number(),
+    name: z.string(),
+    type: z.string(),
+});
+const location = z.object({
+    role: z.string(),
+    city: z.object({ id: z.number(), name: z.string() }).nullable().optional(),
+    country: z.object({ id: z.number(), name: z.string() }).nullable().optional(),
+});
+export const organizationSummary = z.object({
+    uuid: z.string().min(1),
+    name: z.string(),
+    type: z.string().optional(),
+    subtype: z.string().nullable().optional(),
+    launch_date: partialDate.nullable().optional(),
+    dealroom_url: z.string().nullable().optional(),
+    taxonomy: z.array(taxonomyTerm).optional(),
+    locations: z.array(location).optional(),
+});
+export const page = z.object({
+    next_cursor: z.string().nullable().optional(),
+    total: z.number().nullable().optional(),
+    tier: z.string().nullable().optional(),
+    capped: z.boolean().nullable().optional(),
+    result_cap: z.number().nullable().optional(),
+});
+export const roundInvestor = z.object({
+    is_lead: z.boolean().nullable(),
+    investor: entityRef,
+});
+/** One row of `/data/companies/{id}/funding-rounds`: a transaction without its `company`. */
+export const companyRound = z.object({
+    id: z.number().int(),
+    amount: z.number().nullable(),
+    announced_date: partialDate.nullable(),
+    round_type: z.string().nullable(),
+    standardized_round: z.string().nullable(),
+    round_label: z.string().nullable().optional(),
+    valuation: z.number().nullable().optional(),
+    is_vc_round: z.boolean().nullable(),
+    is_exit: z.boolean().nullable().optional(),
+    investors: z.array(roundInvestor).nullable(),
+    source_url: z.string().nullable().optional(),
+});
+/** One row of `/data/transactions`. */
+export const transaction = companyRound.extend({
+    company: organizationSummary,
+    deleted_at: z.string().nullable().optional(),
+});
+export const searchResponse = z.object({
+    data: z.array(z.object({
+        uuid: z.string().min(1),
+        type: z.string(),
+        name: z.string(),
+        tagline: z.string().nullable().optional(),
+        investor_rank: z.number().nullable().optional(),
+        website_domain: z.string().nullable().optional(),
+        hq_city: z.string().nullable().optional(),
+        hq_country: z.string().nullable().optional(),
+    })),
+});
+const namedCode = z.object({ id: z.number(), name: z.string(), code: z.string().optional() });
+/** `/data/investors/{id}` returns either an investor firm or a person who invests. */
+export const investorDetailResponse = z.object({
+    data: z.object({
+        uuid: z.string().min(1),
+        name: z.string(),
+        type: z.enum(["organization", "person"]),
+        subtype: z.string().nullable().optional(),
+        domain: z.string().nullable().optional(),
+        dealroom_url: z.string().nullable().optional(),
+        launch_date: partialDate.nullable().optional(),
+        roles: z.array(z.string()).optional(),
+        types: z.array(namedCode).optional(),
+        locations: z.array(location).optional(),
+        investments: z
+            .object({
+            count: z.number().nullable().optional(),
+            preferred_round: z.string().nullable().optional(),
+            last_round_date: partialDate.nullable().optional(),
+        })
+            .nullable()
+            .optional(),
+        portfolio: z
+            .object({
+            rounds_count: z.number().nullable().optional(),
+            companies: z.object({ total: z.number().nullable().optional() }).nullable().optional(),
+        })
+            .nullable()
+            .optional(),
+    }),
+});
+export const portfolioResponse = z.object({
+    data: z.array(z.object({
+        is_lead: z.boolean(),
+        rounds_count: z.number().int(),
+        last_round_date: partialDate.nullable(),
+        company: organizationSummary,
+    })),
+    page,
+});
+export const transactionsResponse = z.object({ data: z.array(transaction), page, currency: z.string().optional() });
+export const companyRoundsResponse = z.object({ data: z.array(companyRound), page, currency: z.string().optional() });
+export const errorEnvelope = z.object({
+    error: z.object({ code: z.string(), message: z.string() }),
+});

package/dist/ingest/extract.js

@@ -0,0 +1,137 @@
+import { resetDerivedTables, transaction } from "../db/database.js";
+import { companyRoundsResponse, investorDetailResponse, portfolioResponse, transactionsResponse } from "../dealroom/schemas.js";
+import { nameKey } from "../util.js";
+import { EXTRACTION_VERSION } from "../version.js";
+const bool = (value) => (value == null ? null : value ? 1 : 0);
+function parse(schema, row) {
+    const parsed = schema.safeParse(JSON.parse(row.body_json));
+    if (!parsed.success)
+        throw new Error(`Stored response ${row.id} (${row.kind}) no longer matches its schema: ${parsed.error.message}`);
+    return parsed.data;
+}
+/**
+ * Derives the normalised tables from one complete run's raw responses. Global records (companies,
+ * rounds, entities) are upserted, so each holds the newest version observed; the investor's own
+ * portfolio and round scope are replaced wholesale, so records Dealroom dropped disappear too.
+ */
+export function extractRun(db, runId) {
+    const run = db.prepare("SELECT investor_id, status FROM ingestion_runs WHERE id = ?").get(runId);
+    if (!run || run.status !== "complete")
+        throw new Error(`Run ${runId} is not a complete ingestion run`);
+    const investorId = String(run.investor_id);
+    const rows = db
+        .prepare("SELECT id, kind, subject_id, retrieved_at, body_json FROM raw_responses WHERE run_id = ? ORDER BY kind, subject_id, page_index, id")
+        .all(runId);
+    const upsertEntity = db.prepare(`INSERT INTO entities (uuid, name, type, subtype, dealroom_url, source_response_id) VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT (uuid) DO UPDATE SET name = excluded.name, type = excluded.type, subtype = excluded.subtype,
+       dealroom_url = excluded.dealroom_url, source_response_id = excluded.source_response_id`);
+    const upsertCompany = db.prepare(`INSERT INTO companies (uuid, name, subtype, launch_date, dealroom_url, taxonomy_known, source_response_id, retrieved_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT (uuid) DO UPDATE SET name = excluded.name, subtype = excluded.subtype, launch_date = excluded.launch_date,
+       dealroom_url = excluded.dealroom_url, taxonomy_known = excluded.taxonomy_known,
+       source_response_id = excluded.source_response_id, retrieved_at = excluded.retrieved_at`);
+    const insertCompanyIfMissing = db.prepare(`INSERT OR IGNORE INTO companies (uuid, name, subtype, launch_date, dealroom_url, taxonomy_known, source_response_id, retrieved_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    const clearTaxonomy = db.prepare("DELETE FROM company_taxonomy WHERE company_id = ?");
+    const upsertTerm = db.prepare("INSERT INTO taxonomy_terms (id, name, type) VALUES (?, ?, ?) ON CONFLICT (id) DO UPDATE SET name = excluded.name, type = excluded.type");
+    const insertCompanyTerm = db.prepare("INSERT OR IGNORE INTO company_taxonomy (company_id, term_id, source_response_id) VALUES (?, ?, ?)");
+    const upsertRound = db.prepare(`INSERT INTO funding_rounds (id, company_id, announced_date, round_type, standardized_round, round_label, amount, valuation,
+       currency, is_vc_round, is_exit, investors_disclosed, source_url, source_response_id, retrieved_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT (id) DO UPDATE SET company_id = excluded.company_id, announced_date = excluded.announced_date,
+       round_type = excluded.round_type, standardized_round = excluded.standardized_round, round_label = excluded.round_label,
+       amount = excluded.amount, valuation = excluded.valuation, currency = excluded.currency, is_vc_round = excluded.is_vc_round,
+       is_exit = excluded.is_exit, investors_disclosed = excluded.investors_disclosed, source_url = excluded.source_url,
+       source_response_id = excluded.source_response_id, retrieved_at = excluded.retrieved_at`);
+    const clearParticipants = db.prepare("DELETE FROM round_participants WHERE round_id = ?");
+    // A participant listed twice on one round keeps the most informative lead flag: true over false over unknown.
+    const insertParticipant = db.prepare(`INSERT INTO round_participants (round_id, entity_id, is_lead, position) VALUES (?, ?, ?, ?)
+     ON CONFLICT (round_id, entity_id) DO UPDATE SET is_lead = CASE
+       WHEN excluded.is_lead IS NULL THEN round_participants.is_lead
+       WHEN round_participants.is_lead IS NULL THEN excluded.is_lead
+       ELSE max(round_participants.is_lead, excluded.is_lead) END`);
+    const insertScope = db.prepare("INSERT OR IGNORE INTO investor_round_scope (investor_id, round_id) VALUES (?, ?)");
+    const writeCompany = (company, row, overwrite) => {
+        const args = [
+            company.uuid,
+            company.name,
+            company.subtype ?? null,
+            company.launch_date ?? null,
+            company.dealroom_url ?? null,
+            company.taxonomy === undefined ? 0 : 1,
+            row.id,
+            row.retrieved_at,
+        ];
+        const changed = overwrite ? upsertCompany.run(...args).changes : insertCompanyIfMissing.run(...args).changes;
+        if (!changed || company.taxonomy === undefined)
+            return;
+        clearTaxonomy.run(company.uuid);
+        for (const term of company.taxonomy) {
+            upsertTerm.run(term.id, term.name, term.type);
+            insertCompanyTerm.run(company.uuid, term.id, row.id);
+        }
+    };
+    const writeEntity = (ref, sourceId) => upsertEntity.run(ref.uuid, ref.name, ref.type, ref.subtype ?? null, ref.dealroom_url ?? null, sourceId);
+    const writeRound = (round, companyId, currency, row) => {
+        upsertRound.run(round.id, companyId, round.announced_date, round.round_type, round.standardized_round, round.round_label ?? null, round.amount, round.valuation ?? null, currency, bool(round.is_vc_round), bool(round.is_exit), round.investors === null ? 0 : 1, round.source_url ?? null, row.id, row.retrieved_at);
+        clearParticipants.run(round.id);
+        (round.investors ?? []).forEach((participant, position) => {
+            writeEntity(participant.investor, row.id);
+            insertParticipant.run(round.id, participant.investor.uuid, bool(participant.is_lead), position);
+        });
+        insertScope.run(investorId, round.id);
+    };
+    transaction(db, () => {
+        db.prepare("DELETE FROM portfolio_relationships WHERE investor_id = ?").run(investorId);
+        db.prepare("DELETE FROM investor_round_scope WHERE investor_id = ?").run(investorId);
+        const insertPortfolio = db.prepare(`INSERT OR REPLACE INTO portfolio_relationships
+         (investor_id, company_id, company_subtype, is_lead_any, rounds_count, last_round_date, source_response_id, retrieved_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const row of rows.filter((r) => r.kind === "investor")) {
+            const investor = parse(investorDetailResponse, row).data;
+            db.prepare(`INSERT INTO investors (uuid, name, name_key, type, subtype, firm_types_json, launch_date, domain, hq_country, dealroom_url,
+           reported_portfolio_total, reported_rounds_count, source_response_id, retrieved_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (uuid) DO UPDATE SET name = excluded.name, name_key = excluded.name_key, type = excluded.type,
+           subtype = excluded.subtype, firm_types_json = excluded.firm_types_json, launch_date = excluded.launch_date,
+           domain = excluded.domain, hq_country = excluded.hq_country, dealroom_url = excluded.dealroom_url,
+           reported_portfolio_total = excluded.reported_portfolio_total, reported_rounds_count = excluded.reported_rounds_count,
+           source_response_id = excluded.source_response_id, retrieved_at = excluded.retrieved_at`).run(investor.uuid, investor.name, nameKey(investor.name), investor.type, investor.subtype ?? null, JSON.stringify((investor.types ?? []).map((t) => t.name).sort()), investor.launch_date ?? null, investor.domain ?? null, investor.locations?.find((l) => l.role === "hq")?.country?.name ?? null, investor.dealroom_url ?? null, investor.portfolio?.companies?.total ?? null, investor.portfolio?.rounds_count ?? null, row.id, row.retrieved_at);
+            writeEntity({ uuid: investor.uuid, name: investor.name, type: investor.type, subtype: investor.subtype }, row.id);
+        }
+        for (const row of rows.filter((r) => r.kind === "portfolio")) {
+            for (const item of parse(portfolioResponse, row).data) {
+                writeCompany(item.company, row, true);
+                insertPortfolio.run(investorId, item.company.uuid, item.company.subtype ?? null, item.is_lead ? 1 : 0, item.rounds_count, item.last_round_date, row.id, row.retrieved_at);
+            }
+        }
+        for (const row of rows.filter((r) => r.kind === "transactions")) {
+            const body = parse(transactionsResponse, row);
+            for (const round of body.data) {
+                if (round.deleted_at)
+                    continue;
+                writeCompany(round.company, row, false);
+                writeRound(round, round.company.uuid, body.currency ?? null, row);
+            }
+        }
+        for (const row of rows.filter((r) => r.kind === "company_rounds")) {
+            const body = parse(companyRoundsResponse, row);
+            for (const round of body.data)
+                writeRound(round, row.subject_id, body.currency ?? null, row);
+        }
+        db.prepare(`INSERT INTO extraction_state (investor_id, run_id, extraction_version) VALUES (?, ?, ?)
+       ON CONFLICT (investor_id) DO UPDATE SET run_id = excluded.run_id, extraction_version = excluded.extraction_version`).run(investorId, runId, EXTRACTION_VERSION);
+        db.prepare("INSERT INTO meta (key, value) VALUES ('extraction_version', ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(EXTRACTION_VERSION);
+    });
+}
+/** Drops every derived table and replays the latest complete run of each investor, oldest first. */
+export function rebuildDerivedTables(db) {
+    resetDerivedTables(db);
+    const runs = db
+        .prepare(`SELECT max(id) AS id FROM ingestion_runs WHERE status = 'complete' GROUP BY investor_id ORDER BY max(id)`)
+        .all()
+        .map((row) => Number(row.id));
+    for (const runId of runs)
+        extractRun(db, runId);
+    return runs;
+}

package/dist/ingest/fetch.js

@@ -0,0 +1,80 @@
+import { DealroomApiError } from "../dealroom/client.js";
+import { companyRoundPages, getInvestor, portfolioPages, portfolioTransactionPages } from "../dealroom/endpoints.js";
+import { sha256 } from "../util.js";
+import { TOOL_VERSION } from "../version.js";
+import { extractRun } from "./extract.js";
+/** Statuses where the transactions filter itself is unavailable, so per-company calls may still work. */
+const FALLBACK_STATUS = new Set([400, 403, 404]);
+/**
+ * Fetches everything one analysis needs and stores each response verbatim, then derives the
+ * normalised tables from those responses. A failed run is kept for debugging but never analysed.
+ */
+export async function ingestInvestor(db, client, investorId, options = {}) {
+    const log = options.log ?? (() => { });
+    const now = options.now ?? (() => new Date());
+    const runId = Number(db
+        .prepare(`INSERT INTO ingestion_runs (investor_id, status, started_at, api_base_url, api_version, tool_version)
+         VALUES (?, 'running', ?, ?, ?, ?)`)
+        .run(investorId, now().toISOString(), client.config.baseUrl, client.config.apiVersion, TOOL_VERSION).lastInsertRowid);
+    const insertRaw = db.prepare(`INSERT INTO raw_responses
+       (run_id, kind, subject_id, page_index, endpoint, params_json, retrieved_at, api_version, credits_used, body_sha256, body_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const store = (kind, subjectId, pageIndex, response) => {
+        const body = JSON.stringify(response.raw);
+        insertRaw.run(runId, kind, subjectId, pageIndex, response.meta.endpoint, JSON.stringify(response.meta.params), response.meta.retrievedAt, response.meta.apiVersion, response.meta.creditsUsed, sha256(body), body);
+    };
+    const before = client.usage;
+    try {
+        const detail = await getInvestor(client, investorId);
+        store("investor", investorId, 0, detail);
+        const investor = detail.body.data;
+        const expected = investor.portfolio?.companies?.total;
+        log(`Fetching portfolio of ${investor.name}${expected == null ? "" : ` (${expected} companies reported)`}`);
+        const roundCompanies = [];
+        let portfolioRows = 0;
+        for await (const page of portfolioPages(client, investorId)) {
+            store("portfolio", investorId, page.pageIndex, page);
+            portfolioRows += page.body.data.length;
+            for (const row of page.body.data)
+                if (row.rounds_count > 0)
+                    roundCompanies.push(row.company.uuid);
+            if (page.body.page.tier && page.body.page.tier !== "premium") {
+                log(`Warning: Dealroom served the "${page.body.page.tier}" tier, so some fields may be redacted`);
+            }
+        }
+        log(`Portfolio: ${portfolioRows} rows`);
+        let strategy = "portfolio_transactions";
+        try {
+            let rounds = 0;
+            for await (const page of portfolioTransactionPages(client, investorId)) {
+                store("transactions", investorId, page.pageIndex, page);
+                rounds += page.body.data.length;
+                const total = page.body.page.total;
+                log(`Funding rounds: ${rounds}${total == null ? "" : ` of ${total}`}`);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof DealroomApiError) || !FALLBACK_STATUS.has(error.status))
+                throw error;
+            strategy = "per_company_funding_rounds";
+            db.prepare("DELETE FROM raw_responses WHERE run_id = ? AND kind = 'transactions'").run(runId);
+            log(`The portfolio transactions filter is unavailable (${error.status} ${error.code}); fetching rounds per company`);
+            let done = 0;
+            for (const companyId of [...new Set(roundCompanies)].sort()) {
+                for await (const page of companyRoundPages(client, companyId))
+                    store("company_rounds", companyId, page.pageIndex, page);
+                if (++done % 25 === 0)
+                    log(`Funding rounds: ${done} of ${roundCompanies.length} companies`);
+            }
+        }
+        const after = client.usage;
+        db.prepare(`UPDATE ingestion_runs SET status = 'complete', finished_at = ?, rounds_strategy = ?, requests = ?, credits_used = ? WHERE id = ?`).run(now().toISOString(), strategy, after.requests - before.requests, after.credits - before.credits, runId);
+    }
+    catch (error) {
+        const after = client.usage;
+        db.prepare(`UPDATE ingestion_runs SET status = 'failed', finished_at = ?, requests = ?, credits_used = ?, error = ? WHERE id = ?`).run(now().toISOString(), after.requests - before.requests, after.credits - before.credits, error instanceof Error ? error.message : String(error), runId);
+        throw error;
+    }
+    extractRun(db, runId);
+    return runId;
+}

package/dist/ingest/resolve.js

@@ -0,0 +1,74 @@
+import { searchInvestors } from "../dealroom/endpoints.js";
+import { nameKey } from "../util.js";
+export class InvestorResolutionError extends Error {
+    name = "InvestorResolutionError";
+    candidates;
+    constructor(message, candidates = []) {
+        super(message);
+        this.candidates = candidates;
+    }
+}
+const fromHit = (hit) => ({
+    id: hit.uuid,
+    name: hit.name,
+    location: [hit.hq_city, hit.hq_country].filter(Boolean).join(", ") || null,
+    domain: hit.website_domain ?? null,
+    rank: hit.investor_rank ?? null,
+});
+/**
+ * Only an exact name match is ever chosen automatically. Anything else is ambiguous: the caller
+ * either asks the user or fails with the candidate list, never guesses from relevance order.
+ */
+export function matchCandidates(query, candidates) {
+    const key = nameKey(query);
+    const exact = candidates.filter((candidate) => nameKey(candidate.name) === key);
+    if (exact.length === 1)
+        return { match: exact[0] };
+    return { ambiguous: exact.length > 1 ? exact : candidates };
+}
+export function localCandidates(db, query) {
+    return db
+        .prepare("SELECT uuid, name, hq_country, domain FROM investors WHERE name_key = ? ORDER BY name, uuid")
+        .all(nameKey(query))
+        .map((row) => ({
+        id: String(row.uuid),
+        name: String(row.name),
+        location: row.hq_country == null ? null : String(row.hq_country),
+        domain: row.domain == null ? null : String(row.domain),
+        rank: null,
+    }));
+}
+export async function resolveInvestor(options) {
+    const { db, query, investorId, offline } = options;
+    if (investorId) {
+        const local = db.prepare("SELECT name FROM investors WHERE uuid = ?").get(investorId);
+        return { id: investorId, name: local ? String(local.name) : investorId, via: "investor_id" };
+    }
+    if (!query?.trim())
+        throw new InvestorResolutionError("Give an investor name or --investor-id <uuid>.");
+    const local = localCandidates(db, query);
+    if (local.length === 1)
+        return { id: local[0].id, name: local[0].name, via: "local_exact_name" };
+    if (offline) {
+        if (local.length === 0) {
+            throw new InvestorResolutionError(`No stored investor is named "${query}". Run once without --offline to fetch it.`);
+        }
+        return choose(options, query, local);
+    }
+    if (!options.client)
+        throw new InvestorResolutionError("No Dealroom client available for investor search.");
+    const { body } = await searchInvestors(options.client(), query);
+    const hits = body.data.filter((hit) => hit.type === "investor").map(fromHit);
+    if (hits.length === 0)
+        throw new InvestorResolutionError(`Dealroom has no investor matching "${query}".`);
+    const result = matchCandidates(query, hits);
+    if ("match" in result)
+        return { id: result.match.id, name: result.match.name, via: "search_exact_name" };
+    return choose(options, query, result.ambiguous);
+}
+async function choose(options, query, candidates) {
+    const chosen = options.choose ? await options.choose(query, candidates) : null;
+    if (chosen)
+        return { id: chosen.id, name: chosen.name, via: "interactive_choice" };
+    throw new InvestorResolutionError(`"${query}" matches more than one investor, or none exactly. Rerun with --investor-id <uuid>.`, candidates);
+}

package/dist/reports/json.js

@@ -0,0 +1,97 @@
+import { THRESHOLDS } from "../analysis/interpretation.js";
+import { leadStatus } from "../analysis/leadership.js";
+import { stageBucket } from "../analysis/stages.js";
+import { canonicalJson, sha256 } from "../util.js";
+import { ALGORITHM_VERSION, EXTRACTION_VERSION, REPORT_SCHEMA_VERSION, TOOL_NAME, TOOL_VERSION } from "../version.js";
+/** Hash of exactly the records the analysis read, so two reports can be checked for the same input. */
+export function datasetFingerprint(dataset) {
+    const { provenance: _provenance, ...records } = dataset;
+    return `sha256:${sha256(canonicalJson(records))}`;
+}
+function roundView(round, investorId) {
+    return {
+        round_id: round.id,
+        announced_date: round.announcedDate,
+        round_label: round.roundLabel,
+        stage_bucket: stageBucket(round.roundLabel),
+        standardized_round: round.standardizedRound,
+        round_type: round.roundType,
+        amount: round.amount,
+        currency: round.currency,
+        lead_status: leadStatus(round, investorId),
+        leads: round.participants.filter((p) => p.isLead === true && p.id !== investorId).map((p) => ({ id: p.id, name: p.name })),
+        participants: round.investorsDisclosed ? round.participants.length : null,
+    };
+}
+function contribution(company, investorId) {
+    const entry = company.entry;
+    return {
+        company_id: company.companyId,
+        company_name: company.companyName,
+        status: company.status,
+        rounds_count_reported: company.roundsCountReported,
+        company_rounds_observed: company.companyRoundsObserved,
+        initial_round: company.initial ? roundView(company.initial, investorId) : null,
+        entry_context: entry && {
+            company_first_known_vc_round_id: entry.companyFirstVcRoundId,
+            prior_vc_rounds: entry.priorVcRounds,
+            uncertain_vc_rounds: entry.uncertainVcRounds,
+            prior_vc_capital: entry.priorVcCapital,
+            prior_vc_rounds_without_amount: entry.priorVcRoundsWithoutAmount,
+            company_age_at_entry_years: entry.companyAgeAtEntryYears,
+        },
+        follow_on_rounds: company.followOns.map((round) => roundView(round, investorId)),
+        flags: company.flags,
+    };
+}
+export function buildReport(dataset, analysis, blackSheep, options) {
+    const { investor, provenance } = dataset;
+    const report = {
+        report_schema_version: REPORT_SCHEMA_VERSION,
+        tool: { name: TOOL_NAME, version: TOOL_VERSION, algorithm_version: ALGORITHM_VERSION, extraction_version: EXTRACTION_VERSION },
+        source: {
+            provider: "Dealroom",
+            api_base_url: provenance.apiBaseUrl,
+            api_version: provenance.apiVersion,
+            ingestion_run_id: provenance.runId,
+            retrieval_started_at: provenance.startedAt,
+            retrieval_finished_at: provenance.finishedAt,
+            rounds_strategy: provenance.roundsStrategy,
+            responses_stored: provenance.responsesStored,
+            requests: provenance.requests,
+            credits_used: provenance.creditsUsed,
+            dataset_fingerprint: datasetFingerprint(dataset),
+        },
+        investor: {
+            id: investor.id,
+            name: investor.name,
+            entity_type: investor.type,
+            entity_subtype: investor.subtype,
+            firm_types: investor.firmTypes,
+            launch_date: investor.launchDate,
+            hq_country: investor.hqCountry,
+            dealroom_url: investor.dealroomUrl,
+            analysis_level: investor.type === "person" ? "person" : "firm",
+        },
+        coverage: {
+            portfolio_companies_returned: analysis.dataQuality.portfolio.rows_returned,
+            portfolio_companies_reported: analysis.dataQuality.portfolio.reported_by_dealroom,
+            first_investments_identified: analysis.entryMaturity.first_investments,
+            first_investments_with_known_stage: analysis.entryMaturity.known_stage,
+            first_investments_with_usable_lead_status: analysis.investmentLeadership.initial_investments.usable_lead_status,
+            funding_rounds_analysed: dataset.rounds.length,
+        },
+        black_sheep_score: blackSheep,
+        entry_maturity: analysis.entryMaturity,
+        investment_leadership: analysis.investmentLeadership,
+        sector_exposure: analysis.sectorExposure,
+        syndicate_relationships: analysis.syndicateRelationships,
+        data_quality: analysis.dataQuality,
+        interpretation: { thresholds: THRESHOLDS, statements: analysis.interpretation },
+        ...(options.verbose
+            ? { contributions: analysis.history.companies.map((company) => contribution(company, investor.id)) }
+            : {}),
+    };
+    return report;
+}
+export const renderJson = (report) => `${JSON.stringify(report, null, 2)}\n`;

package/dist/reports/sheep.js

@@ -0,0 +1,63 @@
+const SHEEP = [
+    "          .-~~-.-~~-.-~~-.",
+    "  ,--.  .(@@@@@@@@@@@@@@@).",
+    " ( o  \\(@@@@@@@@@@@@@@@@@@@)",
+    "  \\   /(@@@@@@@@@@@@@@@@@@@)",
+    "   `-'  `(@@@@@@@@@@@@@@@)'",
+    "          `-~~-'-~~-'-~~-'",
+    "            ||        ||",
+    "            ^^        ^^",
+];
+const WOOL = "@";
+const WOOL_ROWS = SHEEP.flatMap((text, line) => text.includes(WOOL) ? [{ line, start: text.indexOf(WOOL), width: text.lastIndexOf(WOOL) - text.indexOf(WOOL) + 1 }] : []);
+export const WOOL_SLOTS = WOOL_ROWS.reduce((sum, row) => sum + row.width, 0);
+const TIERS = [
+    [15, "Pure white sheep. Baaa-sically the whole flock."],
+    [35, "Follows the flock"],
+    [55, "Grey area. Shear indecision."],
+    [75, "Ewe-nique taste"],
+    [90, "Ram-pant contrarian"],
+    [100, "True Blaaaaack Sheep"],
+];
+export const clampScore = (score) => Math.round(Math.min(100, Math.max(0, score)));
+export const tierLabel = (score) => TIERS.find(([max]) => clampScore(score) <= max)[1];
+export const woolCount = (score) => Math.round((WOOL_SLOTS * (100 - clampScore(score))) / 100);
+function fleece(wool) {
+    let slot = 0;
+    return WOOL_ROWS.map((row) => Array.from({ length: row.width }, () => {
+        const filled = Math.floor(((slot + 1) * wool) / WOOL_SLOTS) > Math.floor((slot * wool) / WOOL_SLOTS);
+        slot++;
+        return filled;
+    }));
+}
+const offsetAlternateRows = (rows) => rows.map((slots, r) => (r % 2 === 1 ? [slots.at(-1), ...slots.slice(0, -1)] : slots));
+/** Counts screen columns where the sparser mark sits directly above itself in the next row. */
+function stripes(rows, sparse) {
+    let count = 0;
+    for (let r = 1; r < rows.length; r++) {
+        const shift = WOOL_ROWS[r].start - WOOL_ROWS[r - 1].start;
+        rows[r].forEach((slot, s) => {
+            if (slot === sparse && rows[r - 1][s + shift] === sparse)
+                count++;
+        });
+    }
+    return count;
+}
+export function renderSheep(score) {
+    const wool = woolCount(score);
+    const sparse = wool * 2 < WOOL_SLOTS;
+    const even = fleece(wool);
+    const offset = offsetAlternateRows(even);
+    const rows = stripes(offset, sparse) < stripes(even, sparse) ? offset : even;
+    const lines = [...SHEEP];
+    WOOL_ROWS.forEach(({ line, start, width }, r) => {
+        const text = lines[line];
+        const fill = rows[r].map((filled) => (filled ? WOOL : " ")).join("");
+        lines[line] = text.slice(0, start) + fill + text.slice(start + width);
+    });
+    return lines.join("\n");
+}
+export function renderBlackSheep(investorName, score) {
+    const clamped = clampScore(score);
+    return `Investor: ${investorName}\n${renderSheep(clamped)}\n${clamped}% black sheep: ${tierLabel(clamped)}\n`;
+}

package/dist/util.js

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+/** Case-, accent- and punctuation-insensitive key, so "LocalGlobe" matches "Local Globe". */
+export function nameKey(name) {
+    return name
+        .normalize("NFKD")
+        .replace(/\p{Diacritic}/gu, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, "");
+}
+export function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** JSON with object keys sorted, so equal data always serialises to equal bytes. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, inner) => inner && typeof inner === "object" && !Array.isArray(inner)
+        ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : inner);
+}
+export const compareStrings = (a, b) => (a < b ? -1 : a > b ? 1 : 0);

package/dist/version.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+export const TOOL_NAME = "sheeply";
+export const TOOL_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** Bump when the raw-response to table mapping changes; `sheeply db rebuild` re-derives tables. */
+export const EXTRACTION_VERSION = "1";
+/** Bump when any metric, threshold or interpretation rule changes. */
+export const ALGORITHM_VERSION = "0.3.0";
+/** Bump when the JSON report shape changes incompatibly. */
+export const REPORT_SCHEMA_VERSION = "2";

package/docs/api-limitations.md

@@ -0,0 +1,36 @@
+# Dealroom API limitations and open questions
+
+Checked against the docs and live API on 2026-10-28, API version `2026-10-22`, with a beta-issued key.
+
+## Limitations Sheeply works around
+
+1. **`is_lead: false` does not mean a confirmed non-lead.** The spec documents `is_lead` as nullable ("Whether this investor led the round, when known"), but all 4,652 participant flags on Seedcamp's portfolio rounds came back `true` or `false`. Only 37% of rounds with participants flag anyone as lead; 591 rounds list a single investor flagged `false`; lead coverage rises from 14% of pre-2015 rounds to 53% from 2023. Sheeply treats `false` as a non-lead only when another participant is flagged as lead, and reports the other reading as a sensitivity. See [methodology](methodology.md#metric-b-investment-leadership).
+2. **Many rounds have no stage label.** `round_label` was null on 825 of 1,777 rounds (46%), including 324 rounds standardised as Seed (279 of them with an amount). Those first investments are excluded from entry maturity and broken down by `standardized_round` instead.
+3. **`standardized_round` is not strictly standardised.** Where `round_label` exists, `standardized_round` is a coarser copy of it (952 of 952 rounds agreed). Where it is missing, `standardized_round` is the self-reported `round_type` mapped across, as the filter docs say ("falls back to the reported round type when Dealroom left a round unlabelled"). Sheeply uses `round_label` and never fills a missing label.
+4. **No exclusive sector classification.** The API exposes overlapping taxonomy families only. The top level, `industry` (31 values), allows two per company (182 of 513 Seedcamp companies have two). Sector exposure is therefore multi-label, with shares that can exceed 100%.
+5. **Portfolio stakes without rounds.** 47 of Seedcamp's 523 portfolio companies have `rounds_count: 0` and no rounds at all. They are counted and excluded, not guessed.
+6. **Partial dates.** Rounds carry `announced_date` at source precision (`YYYY` or `YYYY-MM`). Order inside an overlapping span is a tie-break and is flagged.
+7. **Funds are not linked to deals.** `/investors/{id}/funds` lists vehicles (name, size, date) with no round or company link, so fund-level attribution is impossible. Analysis is firm-level.
+8. **Credits.** Each returned record costs a credit (portfolio row, transaction row); investor detail costs 2; search and `/reference` are free. A full Seedcamp fetch cost 2,302 credits; Ada Ventures cost 278. `402 CREDITS_EXHAUSTED` stops the run without retrying, and the cost of each run is stored and reported.
+9. **Rate limit.** 5 requests per second per key. Sheeply spaces requests at 4 per second and honours `Retry-After` on 429.
+10. **Intermittent gateway errors.** `include_total=true` on `/portfolio` returned a Cloudflare 504 during testing, so Sheeply never asks the portfolio for a total and reads the count from the investor profile instead. 5xx and network errors are retried with backoff.
+11. **Production vs beta host.** The docs name `https://api.dealroom.app` with audience `https://api.dealroom.app`. A key issued during the open beta is refused by that audience (403) and works only with `DEALROOM_API_BASE_URL=https://api.beta.dealroom.app`.
+12. **Short version support.** During the open beta a pinned version is supported for 30 days after it is superseded. Sheeply pins `2026-10-22` and warns on stderr when Dealroom sends a `Sunset` header.
+13. **Redaction.** Callers without the premium tier get `investors: null` on rounds. API keys report `premium`; Sheeply still stores `investors_disclosed` and counts redacted rounds under data quality.
+
+## Open questions for Dealroom
+
+1. Does `is_lead: false` mean "confirmed not lead" or "not recorded"? Is `null` ever returned? Is there a way to tell a round with no lead from a round whose lead is unknown?
+2. Is `round_label` computed from information available at the time of the round, or recomputed with later data (for example, a company's later funding history)? If the latter, it is mild look-ahead for entry maturity.
+3. Why do labelled-looking seed rounds with amounts have no `round_label`? Which definition do they miss?
+4. Are rounds ever re-attributed between investor entities (for example, from a fund vehicle entity to the firm), and does `company_investor_id` follow those links?
+5. Does the portfolio include every company where the firm appears on a round, or only ones curated onto the profile? (For Seedcamp the two agreed exactly: zero `rounds_not_matched`.)
+6. One Seedcamp portfolio round is dated 2006, before Seedcamp's 2007 launch date. Are pre-founding rounds expected (for example, partners investing before the fund existed)?
+7. Is the 18-sector exclusive classification available through the API, or planned?
+8. What does the Dealroom licence allow for local caching of raw responses? Sheeply keeps them only in the user's local SQLite file and never ships them.
+
+## Unverified in this build
+
+- The per-company fallback (`/companies/{id}/funding-rounds`) is covered by mocked tests only; the live key never needed it.
+- `--refresh` against the live API was not re-run, to save credits. Refresh idempotency is covered by mocked integration tests.
+- Windows and Linux were not run. SQLite comes from Node's built-in `node:sqlite`, so there is no native module to compile on any platform.