orangeslice 2.1.4 → 2.2.0

package/docs/services/company/findCareersPage.md

@@ -0,0 +1,137 @@
+# Find Company Careers Page
+
+Resolve a company's official careers page and, when possible, return the underlying ATS jobs page instead.
+
+This is best when you have a company website or a specific company page and want the canonical place to browse jobs.
+
+## Input Parameters
+
+Provide **one** of:
+
+| Parameter | Type     | Required | Description                                                        |
+| --------- | -------- | -------- | ------------------------------------------------------------------ |
+| `website` | `string` | No       | Company website or page URL, e.g. `stripe.com` or `https://ro.co/` |
+| `url`     | `string` | No       | Alias for `website`                                                |
+
+**Optional:**
+
+| Parameter | Type     | Required | Description                          |
+| --------- | -------- | -------- | ------------------------------------ |
+| `timeout` | `string` | No       | Batch timeout override, e.g. `"30m"` |
+
+## Output
+
+```typescript
+{
+   inputUrl: string;
+   normalizedWebsiteUrl: string;
+   careerPageUrl: string | null;
+   pageType: "ats" | "official" | "not_found";
+   atsProvider: string | null;
+   detectionMethod:
+      | "input-ats"
+      | "homepage-ats-link"
+      | "homepage-careers-link"
+      | "deterministic-candidate"
+      | "candidate-ats-link"
+      | "embedded-ats"
+      | "candidate-redirect"
+      | "ats-unverified"
+      | "not-found";
+   checkedUrls: string[];
+}
+```
+
+## Examples
+
+### Basic Careers Lookup
+
+```typescript
+const result = await services.company.findCareersPage({
+   website: row.website
+});
+
+return result.careerPageUrl;
+```
+
+### Prefer ATS When Available
+
+```typescript
+const result = await services.company.findCareersPage({
+   website: "https://plaid.com"
+});
+
+return {
+   url: result.careerPageUrl,
+   type: result.pageType,
+   ats: result.atsProvider
+};
+```
+
+### Handle Not Found
+
+```typescript
+const result = await services.company.findCareersPage({
+   website: row.website
+});
+
+if (result.pageType === "not_found") {
+   return null;
+}
+
+return result.careerPageUrl;
+```
+
+### Debug Why a Result Was Chosen
+
+```typescript
+const result = await services.company.findCareersPage({
+   website: row.website
+});
+
+return {
+   careerPageUrl: result.careerPageUrl,
+   pageType: result.pageType,
+   atsProvider: result.atsProvider,
+   detectionMethod: result.detectionMethod,
+   checkedUrls: result.checkedUrls
+};
+```
+
+## What It Detects
+
+- Official careers pages like `https://company.com/careers`
+- Careers subdomains like `https://careers.company.com/`
+- ATS boards when discoverable from the company site
+- Embedded/wrapped ATS pages when the company site hosts the jobs UI directly
+
+Common ATS providers currently recognized include:
+
+- `ashby`
+- `greenhouse`
+- `lever`
+- `workday`
+- `icims`
+- `gem`
+- `kula`
+- `breezy`
+- `bamboohr`
+- `rippling`
+- `personio`
+- `phenom`
+- `smartrecruiters`
+- `successfactors`
+- `jobvite`
+- `recruitee`
+- `teamtailor`
+- `indeed`
+- `bestjobs`
+- `ejobs`
+
+## Key Rules
+
+1. **Pass the company website when possible** - homepage/company URLs usually produce the best canonical result.
+2. **ATS is preferred over generic careers pages** - if the company site clearly points to an ATS board, that board is returned.
+3. **Deep location/provider pages can still work** - the resolver attempts to collapse some subdomains and detail pages back to the parent organization's careers site.
+4. **`pageType: "official"` is still a success** - many enterprises host jobs on branded careers portals instead of a third-party ATS URL.
+5. **Use `checkedUrls` for debugging** - when a result looks wrong or missing, inspect the visited candidates.

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

@@ -49,7 +49,6 @@ interface B2BCompany {
    company_size: string | null; // Size range label
    ticker: string | null; // Stock ticker
    logo: string | null; // Logo URL
-   specialties: string[] | null; // Company specialties
    twitter_handle: string | null; // Twitter handle
    linkedin_url: string | null; // Full LinkedIn URL
    created_at: string | null; // Record created timestamp
@@ -57,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`
 
@@ -283,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

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>;

package/docs/services/web/search.md

@@ -67,6 +67,22 @@ Web search returns URLs based on keywords, **not confirmed matches**. Scrape the
 
 ---
 
+## Company Subpage Discovery Rule
+
+To find pages on a company's own website, **never search Google by company name**. Always start from the verified domain and dork with `site:` plus `inurl:` hints.
+
+```ts
+await services.web.search({ query: "site:stripe.com inurl:team OR inurl:about OR inurl:careers" });
+```
+
+Never do this for subpage discovery:
+
+```ts
+await services.web.search({ query: '"Stripe" careers' });
+```
+
+---
+
 ## Parallel Query Permutations
 
 Always run multiple query variations for better coverage.
@@ -87,17 +103,17 @@ const allResults = await services.web.batchSearch({
 const uniqueLinks = [...new Set(allResults.flatMap((r) => r.results.map((x) => x.link)))];
 ```
 
-| Use Case       | Permutation Ideas                                        |
-| -------------- | -------------------------------------------------------- |
-| Person search  | Full name, initials, nicknames, with/without middle name |
-| Company search | Full name, abbreviations, domain, Inc/LLC variations     |
-| Title search   | CEO/Founder/Chief, VP/Director, formal/informal titles   |
+| Use Case       | Permutation Ideas                                                           |
+| -------------- | --------------------------------------------------------------------------- |
+| Person search  | Full name, initials, nicknames, with/without middle name                    |
+| Company search | Prefer verified domain first; use name variants only for off-site discovery |
+| Title search   | CEO/Founder/Chief, VP/Director, formal/informal titles                      |
 
 ---
 
 ## Google Dorking
 
-Use `site:` and `inurl:` to target specific platforms.
+Use `site:` and `inurl:` to target specific platforms and verified company domains.
 
 | Platform           | Dork                        | Example                                      |
 | ------------------ | --------------------------- | -------------------------------------------- |
@@ -107,20 +123,19 @@ Use `site:` and `inurl:` to target specific platforms.
 | Reddit             | `site:reddit.com`           | `site:reddit.com/r/sales "cold email"`       |
 
 ```ts
-// Find company employees with multiple dork variations
-const company = "Stripe";
+// Find company subpages from a verified domain
+const domain = "stripe.com";
 const queries = [
-   `"${company}" site:linkedin.com/in`,
-   `"${company}" CEO OR Founder site:linkedin.com/in`,
-   `"${company}" VP OR Director site:linkedin.com/in`,
-   `"${company}" Engineer site:linkedin.com/in`,
-   `stripe.com site:linkedin.com/in`
+   `site:${domain} inurl:team OR inurl:about OR inurl:leadership`,
+   `site:${domain} inurl:careers OR inurl:jobs`,
+   `site:${domain} inurl:blog OR inurl:news OR inurl:press`,
+   `site:${domain} inurl:contact OR inurl:locations`
 ];
 
 const results = await services.web.batchSearch({
    queries: queries.map((query) => ({ query }))
 });
-const profiles = [...new Set(results.flatMap((r) => r.results.map((x) => x.link)))];
+const subpages = [...new Set(results.flatMap((r) => r.results.map((x) => x.link)))];
 ```
 
 ---

package/docs/triggers-runtime.md

@@ -5,11 +5,21 @@ description: Trigger mental model + runtime API + webhook shape access. Read bef
 
 # Triggers Runtime (Agent)
 
-## What Triggers Are For
+## Core Rule: Triggers Push Data, Columns Do Work
 
-- Triggers are spreadsheet-level automations that run TypeScript code.
-- A trigger starts from one of: manual run, cron schedule, webhook.
-- Use triggers for orchestration; use sheet columns for row-level compute.
+**Triggers are thin data ingesters, NOT processing engines.** Push bare minimum data into rows; all enrichment, AI, scoring, and transformation belongs in code columns.
+
+The spreadsheet is a live workspace, not a log. Columns make work visible, debuggable, retryable per-row, and composable across data sources. Processing inside triggers hides failures in run logs.
+
+**Trigger code should only:**
+
+- Parse/extract fields from `ctx.trigger.payload`
+- Light dedup (`SELECT` to check if row exists)
+- `addRows()` with raw data + `{ run: true }` to kick off columns
+- Paginate via self-invocation for large ingestion
+- Route to the right sheet based on payload type
+
+**Never put in trigger code:** `services.*` enrichment, AI calls, scoring, or per-row transformation loops — the sheet IS the loop.
 
 ## Webhook Data Model (from DB schema)
 
@@ -175,11 +185,22 @@ interface Ctx {
 ## Minimal Example
 
 ```ts
+// Inspect recent webhook payloads to understand shape
 const t = await ctx.triggers.byName("Inbound Lead Webhook");
 const recent = await t.webhooks.list({ limit: 10 });
 const samplePayload = recent[0]?.payload;
 
+// Trigger code: push minimal data, let columns do the work
 await t.update({
-   code: `const body = ctx.trigger.payload; return { ok: true, body };`
+   code: `
+const leads = Array.isArray(ctx.trigger.payload) ? ctx.trigger.payload : [ctx.trigger.payload];
+const sheet = await ctx.sheet("Inbound Leads");
+await sheet.addRows(
+  leads.map(l => ({ "Name": l.name, "Email": l.email, "Source": "webhook" })),
+  { run: true }
+);
+return { pushed: leads.length };
+`
 });
+// Then create enrichment columns on "Inbound Leads" to do the actual work
 ```

package/package.json

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