orangeslice 2.1.5 → 2.3.0-beta.0

package/docs/services/company/findCareersPage.ts

@@ -0,0 +1,37 @@
+interface FindCareersPageResult {
+  /** The original website or URL input */
+  inputUrl: string;
+  /** Canonical homepage/base URL used during discovery */
+  normalizedWebsiteUrl: string;
+  /** Best careers page URL found, or null when none was found */
+  careerPageUrl: string | null;
+  /** Whether the result points to an ATS board, an official careers page, or nothing */
+  pageType: "ats" | "official" | "not_found";
+  /** ATS provider when pageType is "ats" */
+  atsProvider: string | null;
+  /** How the page was discovered */
+  detectionMethod:
+    | "input-ats"
+    | "homepage-ats-link"
+    | "homepage-careers-link"
+    | "deterministic-candidate"
+    | "candidate-ats-link"
+    | "embedded-ats"
+    | "candidate-redirect"
+    | "ats-unverified"
+    | "not-found";
+  /** URLs checked while searching */
+  checkedUrls: string[];
+}
+
+/**
+ * Find the best careers page for a company website.
+ * Accepts a homepage URL/domain and returns either a canonical ATS board URL
+ * or an official careers page on the company site.
+ */
+type findCareersPage = (params: {
+    /** Company website or homepage URL */
+    website?: string;
+    /** Alias for website. Provide website or url. */
+    url?: string;
+  }) => Promise<FindCareersPageResult>;

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

@@ -56,7 +56,15 @@ interface B2BCompany {
 }
 ```
 
-> Note: company industry coverage in the LinkedIn B2B DB can be sparse. `industry` and `industries` may be `null`, generic, or missing even when the company record exists, so do not rely on them as the only company classification signal.
+> Important: LinkedIn company `industry` / `industries` coverage in the B2B DB is very sparse and often too weak for enrichment. These fields may be `null`, generic, stale, or missing even when the company record exists. Treat them as lookup metadata only, not as a high-confidence classification source for enrichment workflows.
+>
+> Preferred pattern for enrichment/classification:
+>
+> 1. Start from the company `domain` when available
+> 2. `services.scrape.website(...)` the company site or a relevant subpage
+> 3. `services.ai.generateObject(...)` to classify the company from the scraped content
+>
+> Use LinkedIn enrich primarily for fast lookup fields like company identity, URL, headcount, location, and description. Do **not** build industry enrichment pipelines that depend mainly on LinkedIn `industry`.
 
 ### Extended (`extended: true`) - `B2BCompanyExtended`
 
@@ -282,6 +290,44 @@ return {
 };
 ```
 
+### Classify Industry from Domain, Not LinkedIn
+
+If your goal is enrichment or categorization, prefer the company website over LinkedIn `industry`:
+
+```typescript
+const company = await services.company.linkedin.enrich({
+   domain: row.domain
+});
+
+const { markdown } = await services.scrape.website({
+   url: `https://${row.domain}`
+});
+
+const { object } = await services.ai.generateObject({
+   prompt: `
+Classify this company based on its website content.
+
+Do not rely on LinkedIn industry because it is sparse and often too generic.
+Use LinkedIn only as lightweight context for identity verification.
+
+Domain: ${row.domain}
+LinkedIn name: ${company?.name ?? "unknown"}
+LinkedIn description: ${company?.description ?? "unknown"}
+
+Website content:
+${markdown}
+   `,
+   schema: z.object({
+      industry: z.string().nullable(),
+      subindustry: z.string().nullable(),
+      businessModel: z.string().nullable(),
+      confidence: z.enum(["low", "medium", "high"])
+   })
+});
+
+return object;
+```
+
 ### Handle Missing Companies
 
 ```typescript

package/docs/services/company/scrapeCareersPage.md

@@ -0,0 +1,150 @@
+# Scrape ATS Careers Page
+
+Extract a standardized list of jobs from a supported **official ATS-hosted** careers page without using a browser when possible.
+
+This is best when you already have an ATS careers page URL, or when you first resolved one with `services.company.findCareersPage` and now want the actual jobs.
+
+## Input Parameters
+
+Provide **one** of:
+
+| Parameter        | Type     | Required | Description                                                                                     |
+| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `careersPageUrl` | `string` | No       | Official ATS board URL or ATS job/detail URL, e.g. `https://job-boards.greenhouse.io/anthropic` |
+| `url`            | `string` | No       | Alias for `careersPageUrl`                                                                      |
+
+**Optional:**
+
+| Parameter | Type     | Required | Description                          |
+| --------- | -------- | -------- | ------------------------------------ |
+| `timeout` | `string` | No       | Batch timeout override, e.g. `"30m"` |
+
+## Output
+
+```typescript
+{
+   status: "success" | "unsupported_url" | "unsupported_provider";
+   inputUrl: string;
+   normalizedBoardUrl: string | null;
+   atsProvider: string | null;
+   companyName: string | null;
+   source: "api" | "html" | null;
+   totalJobs: number;
+   jobs: Array<{
+      id: string;
+      title: string;
+      url: string;
+      applyUrl: string | null;
+      location: string | null;
+      locations: string[];
+      department: string | null;
+      team: string | null;
+      employmentType: string | null;
+      workplaceType: string | null;
+      postedAt: string | null;
+      postedText: string | null;
+      requisitionId: string | null;
+   }>;
+   checkedUrls: string[];
+   supportedProviders: string[];
+   message: string | null;
+}
+```
+
+## Examples
+
+### Scrape Jobs From a Known ATS Board
+
+```typescript
+const result = await services.company.scrapeCareersPage({
+   careersPageUrl: "https://job-boards.greenhouse.io/anthropic"
+});
+
+return result.jobs;
+```
+
+### Resolve Then Scrape
+
+```typescript
+const careers = await services.company.findCareersPage({
+   website: row.website
+});
+
+if (!careers.careerPageUrl || careers.pageType !== "ats") {
+   return [];
+}
+
+const jobs = await services.company.scrapeCareersPage({
+   careersPageUrl: careers.careerPageUrl
+});
+
+return jobs.jobs;
+```
+
+### Return Lightweight Job Summaries
+
+```typescript
+const result = await services.company.scrapeCareersPage({
+   careersPageUrl: row.careers_page
+});
+
+return result.jobs.map((job) => ({
+   title: job.title,
+   location: job.location,
+   department: job.department,
+   url: job.url
+}));
+```
+
+### Handle Unsupported Providers Gracefully
+
+```typescript
+const result = await services.company.scrapeCareersPage({
+   careersPageUrl: row.careers_page
+});
+
+if (result.status !== "success") {
+   return {
+      status: result.status,
+      provider: result.atsProvider,
+      message: result.message
+   };
+}
+
+return result.totalJobs;
+```
+
+### Pass a Job Detail URL
+
+```typescript
+const result = await services.company.scrapeCareersPage({
+   careersPageUrl: "https://jobs.lever.co/mistral/2a357282-9d44-4b41-a249-c75ffe878ce2"
+});
+
+return {
+   board: result.normalizedBoardUrl,
+   jobs: result.totalJobs
+};
+```
+
+## Supported Providers
+
+Current browser-free implementations:
+
+- `ashby`
+- `breezy`
+- `greenhouse`
+- `lever`
+- `recruitee`
+- `rippling`
+- `smartrecruiters`
+- `workable`
+- `workday`
+
+## Key Rules
+
+1. **Use this for official ATS pages** - this endpoint is not meant for generic `company.com/careers` pages unless they are clearly hosted by a supported ATS.
+2. **Prefer resolving first when starting from a company website** - use `services.company.findCareersPage` to find the canonical ATS URL, then pass that into this scraper.
+3. **Job/detail URLs are okay** - supported ATS detail URLs are normalized back to the board before scraping.
+4. **Treat `unsupported_provider` as expected** - it means the input was a recognized ATS, but this scraper does not implement that provider yet.
+5. **Use `checkedUrls` for debugging** - when counts or mappings look off, inspect the URLs that were actually queried.

package/docs/services/index.md

@@ -1,7 +1,7 @@
 - **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.
-- **company**: company data (getting employees at the company, getting company data, getting open jobs).
+- **company**: company data (getting employees at the company, finding careers pages, 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
@@ -9,5 +9,5 @@
 - **email**: send transactional notification emails through Orange Slice's managed sender.
 - **scrape**: website scraper, sitemap scraper
 - **web**: SERP
-- **predictLeads**: company intelligence datasets (financing events, technologies, products, job openings, news, and related company data).
+- **predictLeads**: company intelligence datasets (financing events, technologies, products, job openings, news, and related company data). Use these as prospecting/enrichment signals, not source-of-truth validation for whether a known company is hiring right now.
 - **guides**: agent notes & operational docs (see [Error Handling Cheatsheet](../error-handling-cheatsheet.md))

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

@@ -1,130 +1,133 @@
 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;
+   /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
+   lookalikeDomains?: string[];
+   /** 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 names to filter by */
+   industries?: 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 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;
+   /** 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.
+ * Verified v3 filters: companySizes, countries, industries, ecommerce, and top-level peopleFilters.
+ * Use `searchAfter` for pagination. Do not send `from`, `includeDomains`, `excludeDomains`, or `minScore` because Ocean v3 rejects them with 422 errors.
  */
 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>;
-}>;
+   /** Filters for company search (lookalike domains, size, country, industry, ecommerce) */
+   companiesFilters?: OceanCompaniesFilters;
+   /** Optional people filters. Returns companies that have at least one matching person. */
+   peopleFilters?: OceanPeopleFilters;
+   /** Number of results to return (default 10, max 100) */
+   size?: number;
+   /** Cursor token from a previous response for efficient pagination */
+   searchAfter?: string;
+}) => Promise<{
+   /** Ocean.io status detail (typically "OK") */
+   detail?: string;
+   /** 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/person/linkedin/findUrl.md

@@ -1,4 +1,4 @@
-/\*_ Credits: 2 for the name + company search path, or 50 when reverse-email lookup is used. Charged only if a valid URL is returned. _/
+/\*_ Credits: 2 for the 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, the service tries name + company search first when possible, then falls back to reverse-email lookup. _/
+  /\*_ Email address. For work emails, the service may infer the name from the email, try search with that + the email domain, validate the result against B2B current-company domain data, then fall back to reverse-email lookup. _/
   email?: string;
   }) => Promise<string | undefined>;