orangeslice 2.1.0 → 2.1.1

package/README.md

@@ -64,11 +64,21 @@ const [companies, searchPage, ai] = await Promise.all([
       }
    })
 ]);
+
+const startups = await services.crunchbase.search({
+   sql: `
+      SELECT name, website_url, linkedin_url
+      FROM public.crunchbase_scraper_lean
+      WHERE operating_status = 'Active'
+      LIMIT 10
+   `
+});
 ```
 
 ## Service map
 
 - `services.company.linkedin.search/enrich`
+- `services.crunchbase.search` (returns rows array directly)
 - `services.company.getEmployeesFromLinkedin` (database-only B2B path)
 - `services.person.linkedin.search/enrich`
 - `services.web.search/batchSearch`

package/dist/cli.js

@@ -100,6 +100,19 @@ Use these docs as the source of truth. If there is any conflict between your pri
 - Be concise, factual, and deterministic.
 - Ask a clarifying question only when a missing detail blocks progress.
 
+## Package Setup (Do Not Guess)
+- Import from the package name, not a local file path:
+  - \`import { services } from "orangeslice"\`
+  - \`import { configure, services } from "orangeslice"\` when setting API key programmatically
+- Do NOT use \`import { services } from "./orangeslice"\` unless the user explicitly has a local wrapper file at that path.
+- \`npx orangeslice\` is a setup/bootstrap command (docs sync, package install, auth). It does NOT execute user app scripts.
+
+## Runtime Requirements
+- If writing standalone scripts that use top-level \`await\`, use ESM:
+  - Set \`"type": "module"\` in \`package.json\`, or
+  - Use \`.mjs\` files.
+- If the project is CommonJS and cannot switch to ESM, avoid top-level \`await\` and wrap async code in an async function.
+
 ## Mandatory Read Order (Before writing code)
 1. \`./services/index.md\` - service map and capabilities
 2. Relevant docs under \`./services/**\` for every service you plan to call

package/dist/crunchbase.d.ts

@@ -0,0 +1,10 @@
+export interface CrunchbaseSearchParams {
+    sql: string;
+    userId?: string;
+}
+/**
+ * Search the Crunchbase lean table using SQL.
+ *
+ * Returns rows directly (no envelope).
+ */
+export declare function crunchbaseSearch<T = Record<string, unknown>>(params: CrunchbaseSearchParams): Promise<T[]>;

package/dist/crunchbase.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crunchbaseSearch = crunchbaseSearch;
+const api_1 = require("./api");
+/**
+ * Search the Crunchbase lean table using SQL.
+ *
+ * Returns rows directly (no envelope).
+ */
+async function crunchbaseSearch(params) {
+    const data = await (0, api_1.post)("/execute/crunchbase-sql", { sql: params.sql });
+    return data.rows ?? [];
+}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { configure } from "./api";
 export type { OrangesliceConfig } from "./api";
 export { linkedinSearch } from "./b2b";
 export type { LinkedInSearchParams, LinkedInSearchResponse } from "./b2b";
+export { crunchbaseSearch } from "./crunchbase";
+export type { CrunchbaseSearchParams } from "./crunchbase";
 export { webSearch, webBatchSearch } from "./serp";
 export type { WebSearchQuery, WebSearchResult, WebSearchResponse, BatchWebSearchParams } from "./serp";
 export { generateObject } from "./generateObject";
@@ -21,12 +23,16 @@ export type { PersonLinkedinFindUrlParams, CompanyLinkedinFindUrlParams, PersonC
 import { runApifyActor } from "./apify";
 import { linkedinSearch } from "./b2b";
 import { browserExecute } from "./browser";
+import { crunchbaseSearch } from "./crunchbase";
 import { personLinkedinEnrich, personLinkedinFindUrl, personContactGet, companyLinkedinEnrich, companyLinkedinFindUrl, companyGetEmployeesFromLinkedin, geoParseAddress, builtWithLookupDomain, builtWithRelationships, builtWithSearchByTech } from "./expansion";
 import { scrapeWebsite } from "./firecrawl";
 import { generateObject } from "./generateObject";
 import { googleMapsScrape } from "./googleMaps";
 import { webBatchSearch, webSearch } from "./serp";
 export declare const services: {
+    crunchbase: {
+        search: typeof crunchbaseSearch;
+    };
     company: {
         linkedin: {
             findUrl: typeof companyLinkedinFindUrl;

package/dist/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.linkedinSearch = exports.configure = void 0;
+exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.crunchbaseSearch = exports.linkedinSearch = exports.configure = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return api_1.configure; } });
 var b2b_1 = require("./b2b");
 Object.defineProperty(exports, "linkedinSearch", { enumerable: true, get: function () { return b2b_1.linkedinSearch; } });
+var crunchbase_1 = require("./crunchbase");
+Object.defineProperty(exports, "crunchbaseSearch", { enumerable: true, get: function () { return crunchbase_1.crunchbaseSearch; } });
 var serp_1 = require("./serp");
 Object.defineProperty(exports, "webSearch", { enumerable: true, get: function () { return serp_1.webSearch; } });
 Object.defineProperty(exports, "webBatchSearch", { enumerable: true, get: function () { return serp_1.webBatchSearch; } });
@@ -36,6 +38,7 @@ Object.defineProperty(exports, "builtWithSearchByTech", { enumerable: true, get:
 const apify_2 = require("./apify");
 const b2b_2 = require("./b2b");
 const browser_2 = require("./browser");
+const crunchbase_2 = require("./crunchbase");
 const expansion_2 = require("./expansion");
 const firecrawl_2 = require("./firecrawl");
 const generateObject_2 = require("./generateObject");
@@ -43,6 +46,9 @@ const googleMaps_2 = require("./googleMaps");
 const predictLeads_2 = require("./predictLeads");
 const serp_2 = require("./serp");
 exports.services = {
+    crunchbase: {
+        search: crunchbase_2.crunchbaseSearch
+    },
     company: {
         linkedin: {
             findUrl: expansion_2.companyLinkedinFindUrl,

package/docs/integrations/gmail/index.md

@@ -9,4 +9,4 @@ Typed functions for Gmail actions powered by Orange Slice Google integrations.
 ## Email
 
 - `integrations.gmail.sendEmail(input)` - Send an email through the connected Gmail account
-- Heavy rate limit: `sendEmail` is capped at **20 calls/day** per connected Gmail account
+- Heavy rate limit: `sendEmail` is capped at **40 calls/day** per connected Gmail account

package/docs/integrations/gmail/sendEmail.md

@@ -2,7 +2,7 @@
 
 Send an email from the connected Gmail account.
 
-> Rate limit note for AI: `integrations.gmail.sendEmail(...)` is heavily rate-limited to **20 calls/day** per connected Gmail account. Use sparingly and batch/aggregate where possible.
+> Rate limit note for AI: `integrations.gmail.sendEmail(...)` is heavily rate-limited to **40 calls/day** per connected Gmail account. Use sparingly and batch/aggregate where possible.
 
 ```typescript
 // Basic email
@@ -25,18 +25,18 @@ await integrations.gmail.sendEmail({
 
 ## Input
 
-| Parameter          | Type        | Required | Description |
-| ------------------ | ----------- | -------- | ----------- |
-| `recipient_email`  | `string`    | No\*     | Primary `To` recipient |
-| `extra_recipients` | `string[]`  | No       | Additional `To` recipients |
-| `cc`               | `string[]`  | No       | CC recipients |
-| `bcc`              | `string[]`  | No       | BCC recipients |
-| `subject`          | `string`    | No\*     | Email subject |
-| `body`             | `string`    | No\*     | Email body (plain text or HTML) |
-| `is_html`          | `boolean`   | No       | Set to `true` when body is HTML |
-| `from_email`       | `string`    | No       | Optional verified send-as alias |
-| `attachment`       | `object`    | No       | Optional attachment payload |
-| `user_id`          | `string`    | No       | Gmail user id (`"me"` by default) |
+| Parameter          | Type       | Required | Description                       |
+| ------------------ | ---------- | -------- | --------------------------------- |
+| `recipient_email`  | `string`   | No\*     | Primary `To` recipient            |
+| `extra_recipients` | `string[]` | No       | Additional `To` recipients        |
+| `cc`               | `string[]` | No       | CC recipients                     |
+| `bcc`              | `string[]` | No       | BCC recipients                    |
+| `subject`          | `string`   | No\*     | Email subject                     |
+| `body`             | `string`   | No\*     | Email body (plain text or HTML)   |
+| `is_html`          | `boolean`  | No       | Set to `true` when body is HTML   |
+| `from_email`       | `string`   | No       | Optional verified send-as alias   |
+| `attachment`       | `object`   | No       | Optional attachment payload       |
+| `user_id`          | `string`   | No       | Gmail user id (`"me"` by default) |
 
 \*Gmail requires at least one recipient (`recipient_email`, `cc`, or `bcc`) and at least one of `subject` or `body`.
 

package/docs/prospecting/index.md

@@ -16,6 +16,7 @@ description: Strategies for searching or finding people and companies. This is a
 Run queries with built-in filters when the criteria is searchable:
 
 - **Web search (`services.web.search`)** — **Default for LinkedIn**. Use for keywords, niche queries, fuzzy matching, anything descriptive.
+- **Crunchbase (`services.crunchbase.search`)** — **Default for funding data**. Use for funding-stage, round type, amount, date windows, and investor-backed company discovery.
 - **LinkedIn B2B DB** — **Indexed lookups ONLY:** company by domain/slug/ID, employees at a known company (by company_id), basic funding (2-table join). Everything else = web search. See [QUICK_REF](./linkedin_data/QUICK_REF.md).
 - **Google Maps** — industry, location, ratings
 - **LinkedIn job search** — job filters, titles
@@ -83,11 +84,11 @@ When using qualification columns, think Circle & Star:
 | Source                   | Use When                                                    | Limitations                                              |
 | ------------------------ | ----------------------------------------------------------- | -------------------------------------------------------- |
 | **Web Search (Default)** | **Everything else** — keywords, niche, fuzzy, specific      | Requires verification columns for false positives.       |
+| **Crunchbase (Funding Default)** | Funding-focused prospecting: stage, round type, amount, recency, investors | Best for funding intelligence; use other sources for non-funding discovery criteria. |
 | **PredictLeads**         | Company intelligence, buying signals, and structured company events at scale | Coverage varies by company/market; use web search for very niche long-tail discovery. |
 | **Niche Directory Scrape** | Well-defined categories with existing lists (see below)   | Requires finding the right directory first.              |
 | **LinkedIn B2B DB**      | **Indexed lookups ONLY:** company by domain/slug/ID, employees at known company, basic 2-table funding. | **3s hard max. No keyword search, no LATERAL, no 3+ table joins.** Everything else = web search. |
 | **Google Maps**          | Local/SMB, physical locations, restaurants, retail          | Limited to businesses with physical presence.            |
-| **NPI Database**         | Healthcare providers                                        | Healthcare only. Free.                                   |
 | **Apify Actors**         | Platform-specific scraping (Instagram, TikTok, job boards)  | Per-platform setup. May break with platform changes.     |
 
 ### PredictLeads: When It Is Better Than Everything Else
@@ -105,6 +106,12 @@ Prefer other sources when:
 - You need local storefront/SMB discovery -> use Google Maps
 - You need fast indexed LinkedIn lookups by known IDs/domain/company -> use LinkedIn B2B DB
 
+### Funding Prospecting Standard: Use Crunchbase First
+
+For any request centered on funding data (for example: "Series A fintech companies", "companies that raised in the last 12 months", "recently funded startups"), use `services.crunchbase.search` as the **standard/default source**.
+
+Use LinkedIn B2B DB funding joins only when the user explicitly needs a LinkedIn-only workflow or a narrow lookup tied to existing LinkedIn records. Otherwise, Crunchbase should be the first choice for funding-oriented discovery.
+
 ### Niche Directory Scraping — For Well-Defined Categories
 
 When users ask for companies in a **specific, well-defined niche** (e.g., "fast food chains", "Fortune 500 companies", "Y Combinator startups"), the best approach is often to **find and scrape a curated directory or list**.
@@ -260,27 +267,28 @@ Don't overthink it — just create 2-3 views that match the columns you built. S
 
 ## Examples
 
-| User Request                                 | Approach         | Why                                                                 |
-| -------------------------------------------- | ---------------- | ------------------------------------------------------------------- |
-| "AI CRM companies"                           | Web search       | Keyword query → `"AI CRM" site:linkedin.com/company`                |
-| "Fintech startups"                           | Web search       | Fuzzy/descriptive → `"fintech" "startup" site:linkedin.com/company` |
-| "SDRs at Series A companies"                 | Web search       | Specific criteria → `"SDR" "Series A" site:linkedin.com/in`         |
-| "Companies using Kubernetes"                 | Web search       | Technology match → `"Kubernetes" site:linkedin.com/company`         |
-| "VPs who worked at Google"                   | Web search       | Fuzzy history match → `"VP" "Google" site:linkedin.com/in`          |
-| "1000 software engineers in Bay Area"        | B2B DB           | Simple title + location + high volume                               |
-| "All healthcare companies 100-500 employees" | B2B DB           | Industry + size + high volume                                       |
-| "Fast food chains that..."                   | Directory scrape | Scrape Wikipedia list → `browser.execute`                           |
-| "Restaurants in Austin"                      | Google Maps      | Local/SMB with physical presence                                    |
-| "Companies hiring SDRs"                      | LinkedIn Jobs    | Job search with title filter                                        |
-| "Warehouses implementing WMS"                | Circle + columns | Pull logistics companies → add "WMS Score" column                   |
-| "Companies that recently switched CRMs"      | Circle + columns | Pull SaaS companies → add "CRM Change Signals" column               |
+| User Request                                 | Approach         | Why                                                                         |
+| -------------------------------------------- | ---------------- | --------------------------------------------------------------------------- |
+| "AI CRM companies"                           | Web search       | Keyword query → `"AI CRM" site:linkedin.com/company`                        |
+| "Fintech startups"                           | Web search       | Fuzzy/descriptive → `"fintech" "startup" site:linkedin.com/company`         |
+| "SDRs at Series A companies"                 | Web search       | Specific criteria → `"SDR" "Series A" site:linkedin.com/in`                 |
+| "Series A/B companies raised last year"      | Crunchbase       | Funding-specific discovery is best handled via `services.crunchbase.search` |
+| "Companies using Kubernetes"                 | Web search       | Technology match → `"Kubernetes" site:linkedin.com/company`                 |
+| "VPs who worked at Google"                   | Web search       | Fuzzy history match → `"VP" "Google" site:linkedin.com/in`                  |
+| "1000 software engineers in Bay Area"        | B2B DB           | Simple title + location + high volume                                       |
+| "All healthcare companies 100-500 employees" | B2B DB           | Industry + size + high volume                                               |
+| "Fast food chains that..."                   | Directory scrape | Scrape Wikipedia list → `browser.execute`                                   |
+| "Restaurants in Austin"                      | Google Maps      | Local/SMB with physical presence                                            |
+| "Companies hiring SDRs"                      | LinkedIn Jobs    | Job search with title filter                                                |
+| "Warehouses implementing WMS"                | Circle + columns | Pull logistics companies → add "WMS Score" column                           |
+| "Companies that recently switched CRMs"      | Circle + columns | Pull SaaS companies → add "CRM Change Signals" column                       |
 
 ---
 
 ## Tools
 
 - **LinkedIn:** `services.company.linkedin.search({ sql: "SELECT ... FROM linkedin_company ..." })`, `services.person.linkedin.search({ sql: "SELECT ... FROM linkedin_profile ..." })` — **Lookup tool only, 3s max, 2-table joins max. Use web search for anything else.**
-- **Healthcare:** `healthcare.npi`
+- **Funding:** `services.crunchbase.search({ sql: "SELECT ... FROM ... WHERE ..." })` — **Default for funding search and screening.**
 - **Local/SMB:** `googleMaps.scrape`
 - **Web:** `web.search` + `browser.execute`
 - **Platforms:** `services.apify.runActor`

package/docs/services/company/linkedin/search.md

@@ -390,6 +390,38 @@ WHERE lc.company_size = '51-200 employees'
 - **Use `lc` alias** for company tables
 - **Default to US**: `lc.country_code = 'US'`
 
+## Return Type
+
+`services.company.linkedin.search()` returns an object envelope:
+
+```typescript
+{
+   rows: (Record < string, unknown > []);
+   count: number;
+}
+```
+
+- `rows`: Result rows from your SQL query, with exactly the columns you selected.
+- `count`: Number of rows returned in `rows`.
+
+Example:
+
+```typescript
+const searchResult = await services.company.linkedin.search({
+   sql: `
+    SELECT
+      lc.company_name,
+      lc.domain,
+      'https://www.linkedin.com/company/' || lc.universal_name AS lc_linkedin_url
+    FROM linkedin_company lc
+    WHERE lc.domain = 'stripe.com'
+    LIMIT 1
+  `
+});
+
+return searchResult.rows; // Most spreadsheet snippets should return rows
+```
+
 ---
 
 ## Table Aliases

package/docs/services/crunchbase/search.md

@@ -0,0 +1,337 @@
+---
+description: Search Crunchbase with SQL
+---
+
+# Crunchbase Search
+
+Run SQL against `public.crunchbase_scraper_lean` for startup/company prospecting.
+
+```typescript
+const rows = await services.crunchbase.search({
+   sql: `
+      SELECT name, website_url, linkedin_url
+      FROM public.crunchbase_scraper_lean
+      WHERE operating_status = 'active'
+      LIMIT 25
+   `
+});
+
+// rows: Record<string, unknown>[]
+return rows;
+```
+
+## Contract (Hard Rules)
+
+- Query **only** `public.crunchbase_scraper_lean`.
+- **Only one statement** is allowed.
+- **Only SELECT** queries are allowed (`WITH ... SELECT` is fine).
+- Always include `LIMIT` (recommended `<= 100`).
+- This is an external service path, not `ctx.sql()`.
+- Credits are 1 credit per returned row (reserve estimate is derived from `LIMIT`).
+
+## Return Type
+
+`services.crunchbase.search()` returns rows directly:
+
+```typescript
+(Record < string, unknown > []);
+```
+
+No `{ rows, count }` envelope.
+
+```typescript
+const rows = await services.crunchbase.search({ sql: "SELECT name FROM public.crunchbase_scraper_lean LIMIT 10" });
+const count = rows.length;
+```
+
+## Live Schema (Verified)
+
+Source of truth: live DB introspection of `public.crunchbase_scraper_lean`.
+
+| Column                       | Type          | Nullable |
+| ---------------------------- | ------------- | -------- |
+| `id`                         | `bigint`      | no       |
+| `uuid`                       | `text`        | yes      |
+| `name`                       | `text`        | yes      |
+| `link`                       | `text`        | yes      |
+| `type`                       | `text`        | yes      |
+| `operating_status`           | `text`        | yes      |
+| `company_type`               | `text`        | yes      |
+| `short_description`          | `text`        | yes      |
+| `description`                | `text`        | yes      |
+| `website_url`                | `text`        | yes      |
+| `linkedin_url`               | `text`        | yes      |
+| `twitter_url`                | `text`        | yes      |
+| `facebook_url`               | `text`        | yes      |
+| `contact_email`              | `text`        | yes      |
+| `phone_number`               | `text`        | yes      |
+| `hq_postal_code`             | `text`        | yes      |
+| `primary_category`           | `text`        | yes      |
+| `categories`                 | `jsonb`       | no       |
+| `category_groups`            | `jsonb`       | no       |
+| `location_identifiers`       | `jsonb`       | no       |
+| `location_group_identifiers` | `jsonb`       | no       |
+| `num_employees_enum`         | `integer`     | yes      |
+| `revenue_range`              | `text`        | yes      |
+| `funding_stage`              | `text`        | yes      |
+| `funding_total_usd`          | `numeric`     | yes      |
+| `last_funding_total_usd`     | `numeric`     | yes      |
+| `last_funding_type`          | `text`        | yes      |
+| `last_funding_date`          | `date`        | yes      |
+| `num_funding_rounds`         | `integer`     | yes      |
+| `num_investors`              | `integer`     | yes      |
+| `num_lead_investors`         | `integer`     | yes      |
+| `rank_org_company`           | `integer`     | yes      |
+| `rank_org`                   | `integer`     | yes      |
+| `rank_delta_d7`              | `integer`     | yes      |
+| `rank_delta_d30`             | `integer`     | yes      |
+| `rank_delta_d90`             | `integer`     | yes      |
+| `growth_score_tier`          | `text`        | yes      |
+| `heat_score_tier`            | `text`        | yes      |
+| `ipo_status`                 | `text`        | yes      |
+| `went_public_on`             | `date`        | yes      |
+| `imported_at`                | `timestamptz` | no       |
+
+## Enum Catalog (Verified Distinct Values)
+
+These are observed live values, in production data.
+
+### `operating_status`
+
+- `active`
+- `closed`
+
+### `company_type`
+
+- `for_profit`
+- `non_profit`
+
+### `type`
+
+- `organization`
+
+### `funding_stage`
+
+- `seed`
+- `early_stage_venture`
+- `m_and_a`
+- `late_stage_venture`
+- `ipo`
+
+### `last_funding_type`
+
+- `seed`
+- `series_a`
+- `series_b`
+- `series_c`
+
+### `revenue_range`
+
+- `r_00000000`
+- `r_00001000`
+- `r_00010000`
+- `r_00050000`
+- `r_00100000`
+- `r_00500000`
+- `r_01000000`
+- `r_10000000`
+
+### `growth_score_tier`
+
+- `c100_high`
+- `c200_medium`
+- `c300_low`
+
+### `heat_score_tier`
+
+- `c100_high`
+- `c200_medium`
+- `c300_low`
+
+### `ipo_status`
+
+- `private`
+- `public`
+- `delisted`
+
+### `num_employees_enum`
+
+Column exists, but currently sparse/null in this dataset.
+
+## JSONB Array Fields
+
+`categories`, `category_groups`, `location_identifiers`, and `location_group_identifiers` are `jsonb` arrays.
+
+Do **not** treat them as `text[]` with `&& ARRAY[...]::text[]`.
+Use `jsonb_array_elements_text(...)` with `EXISTS`, for example:
+
+```sql
+AND EXISTS (
+  SELECT 1
+  FROM jsonb_array_elements_text(categories) AS c(category)
+  WHERE category IN ('Health Care', 'Biotechnology')
+)
+```
+
+## Recommended Query Patterns
+
+| Pattern                                                 | Why                                |
+| ------------------------------------------------------- | ---------------------------------- |
+| Equality / `IN` filters on enum columns                 | Fast and stable                    |
+| Date windows on `last_funding_date`                     | Strong recency control             |
+| Numeric ranges on `funding_total_usd`                   | Good segmentation                  |
+| `EXISTS + jsonb_array_elements_text` for tags/locations | Works with current schema          |
+| Explicit narrow column lists                            | Lower payload and faster execution |
+
+## Banned / Avoided Patterns
+
+| Pattern                                                                      | Why                                 | Better Alternative                                  |
+| ---------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------- |
+| Missing `LIMIT`                                                              | Unbounded scans + excessive credits | Always add `LIMIT`                                  |
+| `SELECT *` for production pulls                                              | Larger payload and cost             | Select only needed columns                          |
+| Leading-wildcard scans on long text (`ILIKE '%term%'`) across broad dataset  | Expensive text scans                | Use enum/date/range filters first, then narrow text |
+| Heavy aggregations (`COUNT(*)`, `DISTINCT`, wide `GROUP BY`) on large slices | Slow and expensive                  | Pull scoped rows, aggregate in code                 |
+| Unscoped global sorts on large sets                                          | Expensive sort operations           | Filter first, sort smaller result sets              |
+| Multi-table joins for routine prospecting                                    | More planner risk and latency       | Stay on lean table only                             |
+
+## Canonical Prospecting Queries
+
+### 1) US early-stage SaaS/AI, currently active
+
+```sql
+SELECT
+   name,
+   website_url,
+   linkedin_url,
+   funding_stage,
+   num_employees_enum,
+   last_funding_date
+FROM public.crunchbase_scraper_lean
+WHERE operating_status = 'active'
+  AND funding_stage IN ('seed', 'early_stage_venture')
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(categories) AS c(category)
+      WHERE category IN ('SaaS', 'Artificial Intelligence (AI)')
+  )
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(location_identifiers) AS l(location)
+      WHERE location = 'United States'
+  )
+LIMIT 100;
+```
+
+### 2) Recently funded (last 12 months)
+
+```sql
+SELECT
+   name,
+   website_url,
+   last_funding_type,
+   last_funding_date,
+   last_funding_total_usd,
+   funding_total_usd
+FROM public.crunchbase_scraper_lean
+WHERE operating_status = 'active'
+  AND last_funding_date >= CURRENT_DATE - INTERVAL '12 months'
+  AND last_funding_type IN ('seed', 'series_a', 'series_b')
+ORDER BY last_funding_date DESC NULLS LAST
+LIMIT 100;
+```
+
+### 3) Bay Area fintech companies with meaningful funding
+
+```sql
+SELECT
+   name,
+   website_url,
+   funding_stage,
+   funding_total_usd,
+   num_employees_enum
+FROM public.crunchbase_scraper_lean
+WHERE operating_status = 'active'
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(categories) AS c(category)
+      WHERE category IN ('FinTech', 'Financial Services')
+  )
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(location_group_identifiers) AS g(location_group)
+      WHERE location_group = 'San Francisco Bay Area'
+  )
+  AND funding_total_usd >= 5000000
+LIMIT 75;
+```
+
+### 4) Non-profits with health focus
+
+```sql
+SELECT
+   name,
+   website_url,
+   company_type,
+   categories,
+   location_identifiers
+FROM public.crunchbase_scraper_lean
+WHERE company_type = 'non_profit'
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(categories) AS c(category)
+      WHERE category ILIKE ANY (ARRAY['%health%', '%medical%', '%biotech%', '%pharma%', '%telemedicine%'])
+  )
+LIMIT 100;
+```
+
+### 5) Healthtech seed to series B (safe column set)
+
+```sql
+SELECT
+   name,
+   website_url,
+   linkedin_url,
+   short_description,
+   funding_stage,
+   last_funding_type,
+   last_funding_date,
+   funding_total_usd,
+   num_employees_enum,
+   categories,
+   location_identifiers,
+   num_investors,
+   num_funding_rounds
+FROM public.crunchbase_scraper_lean
+WHERE operating_status = 'active'
+  AND last_funding_type IN ('seed', 'series_a', 'series_b')
+  AND EXISTS (
+      SELECT 1
+      FROM jsonb_array_elements_text(categories) AS c(category)
+      WHERE category ILIKE ANY (ARRAY['%health%', '%medical%', '%biotech%', '%pharma%', '%telemedicine%'])
+  )
+ORDER BY last_funding_date DESC NULLS LAST
+LIMIT 100;
+```
+
+## Usage Pattern (Spreadsheet Code)
+
+```typescript
+const rows = await services.crunchbase.search({
+   sql: `
+      SELECT name, website_url, linkedin_url
+      FROM public.crunchbase_scraper_lean
+      WHERE operating_status = 'active'
+      LIMIT 20
+   `
+});
+
+// rows is already an array of objects
+return rows;
+```
+
+## Troubleshooting
+
+- `column "...\" does not exist` -> you are using an old/nonexistent column name; check "Known Bad Column Names".
+- `only public.crunchbase_scraper_lean is allowed` -> query references a disallowed table.
+- `only SELECT queries are allowed` -> remove `INSERT/UPDATE/DELETE`, keep read-only SQL.
+- Empty results with no error -> usually value casing mismatch (use lowercase enum values like `active`, `series_a`).

package/docs/services/index.md

@@ -2,12 +2,12 @@
 - **apify**: Run any of 10,000+ Apify actors for web scraping, social media, e-commerce, and more.
 - **browser**: Kernel browser automation - spin up cloud browsers, execute Playwright code, take screenshots. **Use this for scraping structured lists of repeated data** (e.g., product listings, search results, table rows) where you know the DOM structure. Also ideal for **intercepting network requests** to discover underlying APIs, then paginate those APIs directly in your code (faster & cheaper than clicking through pages). Perfect for JS-heavy sites that don't work with simple HTTP scraping.
 - **company**: company data (getting employees at the company, getting company data, getting open jobs).
+- **crunchbase**: SQL search over the lean Crunchbase company table (`public.crunchbase_scraper_lean`) for startup prospecting.
 - **person**: finding a persons linkedin url, enriching it from linkedin, contact info, and searching for specific people / groups on linkedin
 - **geo**: parsing address
 - **googleMaps**: search businesses via Google Maps.
 - **email**: send transactional notification emails through Orange Slice's managed sender.
 - **scrape**: website scraper, sitemap scraper
 - **web**: SERP
-- **healthcare**: Query the NPI (National Provider Identifier) database for healthcare organizations by specialty, location, or name. Contains 1.8M+ providers.
 - **predictLeads**: company intelligence datasets (financing events, technologies, products, job openings, news, and related company data).
 - **guides**: agent notes & operational docs (see [Error Handling Cheatsheet](../error-handling-cheatsheet.md))