orangeslice 2.1.2 → 2.1.4-beta.0

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

@@ -1,12 +1,14 @@
 ---
-description: Search LinkedIn B2B database for companies by domain, slug, or ID lookup
+description: Search LinkedIn B2B database for companies by domain, slug, or ID lookup. NOT for prospecting — use web search for discovery.
 ---
 
 # Company LinkedIn Search
 
 **Credits: 1/result (per-result). Reserves based on query `LIMIT`.**
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com/company` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 PROSPECTING CHECK:** Are you using this to **discover new companies**? This service is almost never the right choice for prospecting. Use `services.web.search` with `site:linkedin.com/company` patterns for discovery. The only prospecting exception is **trivially simple indexed-column filters** (e.g. `industry_code = 4 AND country_code = 'US'`). Any query with keywords, descriptions, company names, ILIKE, or semantic matching = web search.
+
+> Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search`. **You MUST read `services/web/search` before using web search.**
 
 > **IMPORTANT:** These tables (`linkedin_company`, `linkedin_crunchbase_funding`, etc.) are in an **EXTERNAL B2B database** -- NOT accessible via `ctx.sql()`.
 >

package/docs/services/company/revenue.md

@@ -0,0 +1,74 @@
+# Get Company Revenue
+
+Get company revenue, employee count, and firmographic data from a company domain.
+
+**Credits: 2 (standard). Charged only if a valid result is returned.**
+
+## Input Parameters
+
+| Parameter | Type     | Required | Description                                                               |
+| --------- | -------- | -------- | ------------------------------------------------------------------------- |
+| `domain`  | `string` | Yes      | Company website domain (e.g., `stripe.com`, `https://www.salesforce.com`) |
+
+Accepts any format: bare domain (`stripe.com`), with www (`www.stripe.com`), or full URL (`https://www.stripe.com/about`). The domain is automatically normalized.
+
+## Output
+
+```typescript
+{
+   revenue: number | null; // USD (e.g., 5100000000 for $5.1B). Ranges averaged.
+   employees: number | null; // Count (e.g., 750 for "501-1,000"). Ranges averaged.
+   headquarters: string | null; // e.g., "San Francisco, California, United States"
+   industry: string | null; // e.g., "Business Intelligence (BI) Software, Software"
+   website: string | null; // e.g., "www.stripe.com"
+   funding: number | null; // USD (e.g., 8700000000 for $8.7B)
+   description: string | null; // Company description paragraph
+   sourceUrl: string | null; // The data source URL
+}
+```
+
+## Examples
+
+### Basic Revenue Lookup
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.domain
+});
+return companyData.revenue; // 5100000000
+```
+
+### Extract Multiple Fields
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.website
+});
+return {
+   revenue: companyData.revenue,
+   employees: companyData.employees,
+   industry: companyData.industry,
+   hq: companyData.headquarters
+};
+```
+
+### Filter by Revenue Size
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.domain
+});
+if (companyData.revenue && companyData.revenue > 1_000_000_000) {
+   return "Enterprise";
+} else if (companyData.revenue && companyData.revenue > 100_000_000) {
+   return "Mid-Market";
+}
+return "SMB";
+```
+
+## Key Rules
+
+1. **Domain input only** — pass the company's website domain. URLs, bare domains, and www-prefixed domains all work.
+2. **Numbers are parsed** — revenue, employees, and funding are returned as numbers (not formatted strings). Ranges are averaged.
+3. **All fields nullable** — if the data source doesn't list a field (e.g., funding for a bootstrapped company), it returns `null`.
+4. **Handles normalization** — `https://www.stripe.com/about`, `www.stripe.com`, and `stripe.com` all resolve to the same company.

package/docs/services/ctx/index.md

@@ -0,0 +1,68 @@
+---
+description: Spreadsheet management — create spreadsheets, run SQL, add rows
+---
+
+# ctx — Spreadsheet Context API
+
+Manage Orange Slice spreadsheets programmatically. Create spreadsheets, add sheets and columns via SQL, query data, insert rows.
+
+## Quick start
+
+```typescript
+import { ctx } from "orangeslice";
+
+// Create a spreadsheet
+const ss = await ctx.createSpreadsheet({ name: "Leads" });
+
+// Create a sheet with columns
+await ctx.sql(ss.id, "CREATE TABLE contacts (name, email, website)");
+
+// Insert data
+await ctx.sql(ss.id, "INSERT INTO contacts (name, email) VALUES ('Acme', 'hi@acme.com')");
+
+// Query data
+const result = await ctx.sql(ss.id, "SELECT * FROM contacts WHERE name = 'Acme'");
+console.log(result.rows);
+```
+
+## Methods
+
+### Top-level
+
+- **`ctx.createSpreadsheet({ name })`** — Create a new spreadsheet. The scope (personal vs org) is determined by the API key. Returns `{ id, name }`.
+- **`ctx.listSpreadsheets()`** — List spreadsheets visible to the API key's scope. Returns `{ spreadsheets: [...] }`.
+- **`ctx.deleteSpreadsheet(spreadsheetId)`** — Soft-delete a spreadsheet (must be within the API key's scope).
+- **`ctx.sql(spreadsheetId, sql)`** — Execute EAV-SQL against a spreadsheet within the API key's scope (see SQL reference below).
+
+### Bound spreadsheet
+
+Call `ctx.spreadsheet(id)` to get a handle bound to a specific spreadsheet:
+
+```typescript
+const ss = ctx.spreadsheet("uuid-here");
+await ss.sql("SELECT * FROM contacts");
+await ss.sheet("contacts").addRow({ name: "Corp", email: "corp@example.com" });
+await ss.sheet("contacts").addRows([
+   { name: "Foo", email: "foo@example.com" },
+   { name: "Bar", email: "bar@example.com" }
+]);
+```
+
+- **`ss.sql(sql)`** — Execute EAV-SQL (same as `ctx.sql` but without needing to pass spreadsheetId).
+- **`ss.sheet(name).addRow(row)`** — Insert a single row into the named sheet.
+- **`ss.sheet(name).addRows(rows)`** — Insert multiple rows.
+
+## EAV-SQL Reference
+
+The `sql` method supports a subset of SQL mapped to Orange Slice's EAV storage:
+
+| Statement      | Example                                                    | Description                      |
+| -------------- | ---------------------------------------------------------- | -------------------------------- |
+| `CREATE TABLE` | `CREATE TABLE leads (name, email, website)`                | Creates a new sheet with columns |
+| `SELECT`       | `SELECT name, email FROM leads WHERE email LIKE '%@acme%'` | Query rows                       |
+| `INSERT INTO`  | `INSERT INTO leads (name) VALUES ('Acme')`                 | Add rows                         |
+| `ALTER TABLE`  | `ALTER TABLE leads ADD COLUMN phone`                       | Add/rename/drop columns          |
+| `DELETE FROM`  | `DELETE FROM leads WHERE email IS NULL`                    | Delete rows                      |
+| `DROP TABLE`   | `DROP TABLE leads`                                         | Delete a sheet                   |
+
+> **Note:** `RUN` commands are not supported via the API.

package/docs/services/googleMaps/scrape.ts

@@ -1,4 +1,4 @@
-/** Credits: 1/result (per-result). Reserves up to `limit` or `maxCrawledPlacesPerSearch` (default 100). Settles actual count. */
+/** Credits: 10/result (per-result). Reserves up to `limit` or `maxCrawledPlacesPerSearch` (default 100). Settles actual count. */
 
 interface GoogleMapsScraperInput {
    /** Array of search terms to find places (e.g., ['grocery store', 'pizza restaurant']) */

package/docs/services/index.md

@@ -1,3 +1,4 @@
+- **ctx**: Spreadsheet management — create spreadsheets, run SQL, add sheets/columns/rows programmatically.
 - **ai**: AI helpers (summaries, classifications, scoring).
 - **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.

package/docs/services/ocean/search/companies.ts

@@ -0,0 +1,130 @@
+interface OceanCompaniesFilters {
+  /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
+  lookalikeDomains?: string[];
+  /** Minimum similarity score (0-1) for lookalike matching */
+  minScore?: number;
+  /** Company size ranges to filter by */
+  companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
+  /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
+  countries?: string[];
+  /** Industry categories to filter by */
+  industries?: string[];
+  /** Technology names to filter by (e.g., ["React", "Salesforce"]) */
+  technologies?: string[];
+  /** Technology category names to filter by */
+  technologyCategories?: string[];
+  /** Keywords to search for */
+  keywords?: string[];
+  /** Revenue ranges to filter by (e.g., ["0-1M", "1M-10M"]) */
+  revenueRanges?: string[];
+  /** Filter for e-commerce companies */
+  ecommerce?: boolean;
+}
+
+interface OceanCompanyResult {
+  /** Company domain */
+  domain: string;
+  /** Company name */
+  name?: string;
+  /** Legal company name */
+  legalName?: string;
+  /** Company description */
+  description?: string;
+  /** Two-letter country codes where the company operates */
+  countries?: string[];
+  /** Primary country code */
+  primaryCountry?: string;
+  /** Company size range (e.g., "51-200") */
+  companySize?: string;
+  /** Industry categories */
+  industryCategories?: string[];
+  /** Industries */
+  industries?: string[];
+  /** LinkedIn industry classification */
+  linkedinIndustry?: string;
+  /** Whether the company is an e-commerce business */
+  ecommerce?: boolean;
+  /** Company keywords */
+  keywords?: string[];
+  /** Ocean.io employee count estimate */
+  employeeCountOcean?: number;
+  /** LinkedIn employee count */
+  employeeCountLinkedin?: number;
+  /** Revenue range (e.g., "1M-10M") */
+  revenue?: string;
+  /** Year founded */
+  yearFounded?: number;
+  /** Company email addresses */
+  emails?: string[];
+  /** Phone numbers with country and primary flag */
+  phones?: Array<{ country?: string; number: string; primary?: boolean }>;
+  /** Company logo URL */
+  logo?: string;
+  /** Technologies used */
+  technologies?: string[];
+  /** Technology categories */
+  technologyCategories?: string[];
+  /** Company website root URL */
+  rootUrl?: string;
+  /** Social media profiles */
+  medias?: Record<string, { url?: string; handle?: string; name?: string }>;
+  /** Office locations */
+  locations?: Array<{
+    primary?: boolean;
+    latitude?: number;
+    longitude?: number;
+    country?: string;
+    locality?: string;
+    region?: string;
+    postalCode?: string;
+    streetAddress?: string;
+    state?: string;
+  }>;
+  /** Department sizes */
+  departmentSizes?: Array<{ department: string; size: number }>;
+  /** Headcount growth metrics */
+  headcountGrowth?: {
+    threeMonths?: number;
+    threeMonthsPercentage?: number;
+    sixMonths?: number;
+    sixMonthsPercentage?: number;
+    twelveMonths?: number;
+    twelveMonthsPercentage?: number;
+  };
+  /** Last update timestamp */
+  updatedAt?: string;
+}
+
+/**
+ * Search for lookalike companies using Ocean.io.
+ * Provide seed domains via companiesFilters.lookalikeDomains to find similar companies.
+ * Filter by size, country, industry, technology, revenue, and more.
+ * Returns up to `size` companies per call (default 10). Use `searchAfter` for pagination.
+ */
+type companies = (params: {
+    /** Filters for company search (lookalike domains, size, country, industry, etc.) */
+    companiesFilters?: OceanCompaniesFilters;
+    /** Number of results to return (default 10, max 100) */
+    size?: number;
+    /** Pagination offset (use searchAfter for cursor-based pagination instead) */
+    from?: number;
+    /** Cursor token from a previous response for efficient pagination */
+    searchAfter?: string;
+    /** Domains to always include in results */
+    includeDomains?: string[];
+    /** Domains to exclude from results */
+    excludeDomains?: string[];
+  }) => Promise<{
+  /** Total matching companies */
+  total: number;
+  /** Cursor for next page (pass as searchAfter) */
+  searchAfter?: string;
+  /** Matched companies with relevance scores */
+  companies: Array<{
+    company: OceanCompanyResult;
+    /** Relevance grade (A = best match) */
+    relevance?: string;
+  }>;
+  /** Domains that were redirected to canonical domains */
+  redirectMap?: Record<string, string>;
+}>;

package/docs/services/ocean/search/people.ts

@@ -0,0 +1,120 @@
+interface OceanCompaniesFilters {
+  /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
+  lookalikeDomains?: string[];
+  /** Minimum similarity score (0-1) for lookalike matching */
+  minScore?: number;
+  /** Company size ranges to filter by */
+  companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
+  /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
+  countries?: string[];
+  /** Industry categories to filter by */
+  industries?: string[];
+  /** Technology names to filter by (e.g., ["React", "Salesforce"]) */
+  technologies?: string[];
+  /** Technology category names to filter by */
+  technologyCategories?: string[];
+  /** Keywords to search for */
+  keywords?: string[];
+  /** Revenue ranges to filter by (e.g., ["0-1M", "1M-10M"]) */
+  revenueRanges?: string[];
+  /** Filter for e-commerce companies */
+  ecommerce?: boolean;
+}
+
+interface OceanPeopleFilters {
+  /** Seniority levels to filter by (e.g., ["C-Level", "VP", "Director", "Manager"]) */
+  seniorities?: string[];
+  /** Departments to filter by (e.g., ["Engineering", "Sales", "Marketing"]) */
+  departments?: string[];
+  /** Job title keywords to search for */
+  jobTitleKeywords?: string[];
+  /** Two-letter country codes to filter by */
+  countries?: string[];
+  /** Array of Ocean.io people IDs to find lookalikes for */
+  lookalikePeopleIds?: string[];
+}
+
+interface OceanPersonResult {
+  /** Ocean.io person ID */
+  id: string;
+  /** Company domain */
+  domain?: string;
+  /** Full name */
+  name?: string;
+  /** First name */
+  firstName?: string;
+  /** Last name */
+  lastName?: string;
+  /** Two-letter country code */
+  country?: string;
+  /** State/region */
+  state?: string;
+  /** Location string */
+  location?: string;
+  /** LinkedIn profile URL */
+  linkedinUrl?: string;
+  /** Seniority levels (e.g., ["C-Level", "Manager"]) */
+  seniorities?: string[];
+  /** Departments (e.g., ["Engineering", "Management"]) */
+  departments?: string[];
+  /** Profile photo URL */
+  photo?: string;
+  /** Job title in original language */
+  jobTitle?: string;
+  /** Job title translated to English */
+  jobTitleEnglish?: string;
+  /** Current job description */
+  currentJobDescription?: string;
+  /** Work experience history */
+  experiences?: Array<{
+    dateFrom?: string;
+    dateTo?: string;
+    description?: string;
+    domain?: string;
+    jobTitle?: string;
+  }>;
+  /** Profile summary */
+  summary?: string;
+  /** Skills */
+  skills?: string[];
+  /** Phone numbers with verification status */
+  phone?: { numbers?: string[]; status?: string };
+  /** Email with verification status */
+  email?: { address?: string; status?: string };
+  /** Last update timestamp */
+  updatedAt?: string;
+  /** Company info snapshot */
+  company?: { companySize?: string; logo?: string; name?: string };
+}
+
+/**
+ * Search for people at companies using Ocean.io.
+ * Combine companiesFilters (to target companies) with peopleFilters (to target roles/departments).
+ * Can request verified emails and phone numbers via enableEmailSearch / enablePhoneSearch.
+ * Returns up to `size` people per call (default 10). Use `searchAfter` for pagination.
+ */
+type people = (params: {
+    /** Filters to target companies (lookalike domains, size, country, etc.) */
+    companiesFilters?: OceanCompaniesFilters;
+    /** Filters to target people (seniority, department, title keywords, etc.) */
+    peopleFilters?: OceanPeopleFilters;
+    /** Number of results to return (default 10, max 100) */
+    size?: number;
+    /** Pagination offset */
+    from?: number;
+    /** Cursor token from a previous response for efficient pagination */
+    searchAfter?: string;
+    /** Request verified email addresses (uses additional credits) */
+    enableEmailSearch?: boolean;
+    /** Request verified phone numbers (uses additional credits) */
+    enablePhoneSearch?: boolean;
+  }) => Promise<{
+  /** Total matching people */
+  total: number;
+  /** Cursor for next page (pass as searchAfter) */
+  searchAfter?: string;
+  /** Matched people */
+  people: OceanPersonResult[];
+  /** Domains that were redirected to canonical domains */
+  redirectMap?: Record<string, string>;
+}>;

package/docs/services/person/contact/get.ts

@@ -1,11 +1,11 @@
 /** Credits: up to 275 (custom). Email+Phone=275, Phone=250, Email=25. 0 if not found. */
 
 interface ContactInfoResponse {
-   /** The work emails of the person */
+   /** The work emails of the person. All emails are pre-filtered for deliverability — only verified deliverable addresses are returned. */
    work_emails: string[];
    /** The work phone numbers of the person */
    work_phones: string[];
-   /** The personal emails of the person */
+   /** The personal emails of the person. All emails are pre-filtered for deliverability — only verified deliverable addresses are returned. */
    personal_emails: string[];
    /** The personal phone numbers of the person */
    personal_phones: string[];

package/docs/services/person/linkedin/findUrl.md

@@ -1,4 +1,4 @@
-/\*_ Credits: 2 standard, or 50 when `email` is provided. Charged only if a valid URL is returned. _/
+/\*_ Credits: 2 for the name + company search path, or 50 when reverse-email lookup is used. Charged only if a valid URL is returned. _/
 
 /\*\*
 
@@ -15,6 +15,6 @@
   keyword?: string;
   /\*_ Location string (e.g., city, state, country) to narrow search results _/
   location?: string;
-  /\*_ Email address. If provided, reverse-email lookup runs first, then falls back to search. _/
+  /\*_ Email address. If provided, the service tries name + company search first when possible, then falls back to reverse-email lookup. _/
   email?: string;
   }) => Promise<string | undefined>;

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

@@ -1,12 +1,14 @@
 ---
-description: Search LinkedIn B2B database for people by company ID or slug lookup
+description: Search LinkedIn B2B database for people by company ID or slug lookup. NOT for prospecting — use web search for discovery.
 ---
 
 # Person LinkedIn Search
 
 **Credits: 1/result (per-result). Reserves based on query `LIMIT`.**
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com/in` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 PROSPECTING CHECK:** Are you using this to **discover new people**? This service is almost never the right choice for finding people you don't already have identifiers for. Use `services.web.search` with `site:linkedin.com/in` patterns for discovery. This service is meant for: looking up a person by slug, or listing employees at a single company you already have the ID for.
+
+> Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search`. **You MUST read `services/web/search` before using web search.**
 
 > **IMPORTANT:** These tables (`linkedin_profile`, `linkedin_profile_position3`, etc.) are in an **EXTERNAL B2B database** -- NOT accessible via `ctx.sql()`.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orangeslice",
-  "version": "2.1.2",
+  "version": "2.1.4-beta.0",
   "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",