orangeslice 2.1.5 → 2.4.0-beta.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

@@ -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,7 @@
 - **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.
+- **integrations**: connect and manage third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach). Use `integrations.connect(provider)` to open the browser OAuth flow from a script, or `integrations.create(...)` for API-key providers.
+- **skills**: create and manage knowledge skills — reusable knowledge snippets (ICP, templates, product info) that guide AI agents.
 - **guides**: agent notes & operational docs (see [Error Handling Cheatsheet](../error-handling-cheatsheet.md))

package/docs/services/integrations/index.md

@@ -0,0 +1,128 @@
+---
+description: Connect and manage third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach)
+---
+
+# integrations — Integration Management
+
+Connect, list, and manage third-party service integrations. Supports both OAuth providers (HubSpot, Salesforce, Attio, Gmail, Slack) and API-key providers (Instantly, HeyReach).
+
+## Quick start
+
+```typescript
+import { integrations } from "orangeslice";
+
+// Connect an OAuth provider (opens browser for authorization)
+const hubspot = await integrations.connect("hubspot");
+console.log(`Connected: ${hubspot.displayName}`);
+
+// List all connected integrations
+const { integrations: list } = await integrations.list();
+console.log(list.map(i => `${i.provider}: ${i.displayName}`));
+
+// Connect an API-key provider programmatically (no browser)
+await integrations.create({
+  provider: "instantly",
+  apiKey: "inst_abc123...",
+  displayName: "My Instantly"
+});
+```
+
+## Methods
+
+### `integrations.connect(provider, opts?)`
+
+Opens the user's browser to complete OAuth authorization (or API key entry for Instantly/HeyReach). Polls until the user finishes, then returns the connected integration.
+
+This is the recommended way to connect any integration from a script or agent.
+
+**Parameters:**
+- `provider` — One of: `"hubspot"`, `"salesforce"`, `"attio"`, `"gmail"`, `"slack"`, `"instantly"`, `"heyreach"`
+- `opts.noBrowser` — If `true`, prints the URL instead of auto-opening the browser
+
+**Returns:** `Integration` object
+
+```typescript
+const salesforce = await integrations.connect("salesforce");
+// Browser opens -> user authorizes -> returns when complete
+```
+
+### `integrations.list(opts?)`
+
+List connected integrations for the current account.
+
+**Parameters:**
+- `opts.spreadsheetId` — Filter to a specific spreadsheet's integrations
+- `opts.provider` — Filter by provider name
+
+**Returns:** `{ integrations: Integration[] }`
+
+```typescript
+const { integrations: all } = await integrations.list();
+const { integrations: crms } = await integrations.list({ provider: "hubspot" });
+```
+
+### `integrations.get(id)`
+
+Get a single integration by ID.
+
+**Returns:** `Integration`
+
+### `integrations.create(opts)`
+
+Programmatically create an API-key integration without opening a browser. Only works for API-key providers (`instantly`, `heyreach`). For OAuth providers, use `connect()` instead.
+
+**Parameters:**
+- `opts.provider` — `"instantly"` or `"heyreach"`
+- `opts.apiKey` — The provider API key
+- `opts.displayName` — Optional display name
+- `opts.config` — Optional key-value config
+- `opts.spreadsheetId` — Optional, scope to a specific spreadsheet
+
+**Returns:** `Integration`
+
+### `integrations.update(id, fields)`
+
+Update an existing integration.
+
+**Parameters:**
+- `fields.apiKey` — New API key
+- `fields.displayName` — New display name
+- `fields.isActive` — Enable/disable
+- `fields.config` — New config object
+
+**Returns:** `Integration`
+
+### `integrations.delete(id)`
+
+Delete an integration by ID.
+
+**Returns:** `{ success: boolean }`
+
+## Integration object
+
+```typescript
+{
+  id: string;
+  provider: string;        // "hubspot", "salesforce", etc.
+  displayName: string;     // "HubSpot portal acme.hubspot.com"
+  isActive: boolean;
+  hasApiKey: boolean;       // true if API key is set (key itself is never returned)
+  hasOauthToken: boolean;   // true if OAuth token is set
+  createdAt: string;
+  updatedAt: string;
+  scope: "account" | "spreadsheet";
+  spreadsheetId: string | null;
+}
+```
+
+## Supported providers
+
+| Provider    | Auth Type | Connect method         |
+| ----------- | --------- | ---------------------- |
+| HubSpot     | OAuth     | `connect("hubspot")`   |
+| Salesforce  | OAuth     | `connect("salesforce")`|
+| Attio       | OAuth     | `connect("attio")`     |
+| Gmail       | OAuth     | `connect("gmail")`     |
+| Slack       | OAuth     | `connect("slack")`     |
+| Instantly   | API Key   | `connect("instantly")` or `create(...)` |
+| HeyReach    | API Key   | `connect("heyreach")` or `create(...)`  |