orangeslice 2.1.5 → 2.4.0-beta.0

package/dist/skills.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Knowledge Skills API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { skills } from "orangeslice";
+ *
+ *   // Create a skill
+ *   const skill = await skills.create({
+ *     title: "CRM Mapping",
+ *     description: "Maps company fields to HubSpot properties",
+ *     content: "When pushing to HubSpot, map ...",
+ *   });
+ *
+ *   // List all skills
+ *   const { skills: list } = await skills.list();
+ *
+ *   // Update a skill
+ *   await skills.update(skill.id, { autoInject: true });
+ */
+export interface Skill {
+    id: string;
+    title: string;
+    description: string;
+    content: string;
+    autoInject: boolean;
+    createdAt: string;
+    updatedAt: string;
+    scope: "account" | "spreadsheet";
+    spreadsheetId?: string | null;
+}
+export interface SkillListParams {
+    spreadsheetId?: string;
+}
+export interface SkillCreateParams {
+    title: string;
+    description: string;
+    content: string;
+    autoInject?: boolean;
+    spreadsheetId?: string;
+}
+export interface SkillUpdateParams {
+    title?: string;
+    description?: string;
+    content?: string;
+    autoInject?: boolean;
+}
+export declare const skills: {
+    list: (opts?: SkillListParams) => Promise<{
+        skills: Skill[];
+    }>;
+    get: (id: string) => Promise<Skill>;
+    create: (opts: SkillCreateParams) => Promise<Skill>;
+    update: (id: string, fields: SkillUpdateParams) => Promise<Skill>;
+    delete: (id: string) => Promise<{
+        success: boolean;
+    }>;
+};

package/dist/skills.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Knowledge Skills API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { skills } from "orangeslice";
+ *
+ *   // Create a skill
+ *   const skill = await skills.create({
+ *     title: "CRM Mapping",
+ *     description: "Maps company fields to HubSpot properties",
+ *     content: "When pushing to HubSpot, map ...",
+ *   });
+ *
+ *   // List all skills
+ *   const { skills: list } = await skills.list();
+ *
+ *   // Update a skill
+ *   await skills.update(skill.id, { autoInject: true });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skills = void 0;
+const api_1 = require("./api");
+// ---------------------------------------------------------------------------
+// CRUD (via batch-service)
+// ---------------------------------------------------------------------------
+exports.skills = {
+    list: (opts) => (0, api_1.post)("/ctx/skills/list", (opts ?? {})),
+    get: (id) => (0, api_1.post)("/ctx/skills/get", { id }),
+    create: (opts) => (0, api_1.post)("/ctx/skills/create", opts),
+    update: (id, fields) => (0, api_1.post)("/ctx/skills/update", { id, ...fields }),
+    delete: (id) => (0, api_1.post)("/ctx/skills/delete", { id })
+};

package/docs/data-enrichement/index.md

@@ -5,12 +5,18 @@ description: Patterns for enriching company data, tech stack detection, hiring d
 
 # Data Enrichment
 
-Standard pattern: **Search → Scrape → Extract**
+Standard pattern: **Search/Domain → Scrape → Extract**
 
-1. `web.search` with `site:` to find subpages likely to contain the data
+1. Start with a company `domain` when you already have it, otherwise use `web.search` with `site:` to find relevant pages
 2. `scrape.website` to get page content as markdown
 3. `ai.generateObject` to extract structured fields
 
+For company enrichment/classification, prefer the website over LinkedIn `industry`.
+
+- LinkedIn `industry` is acceptable as lightweight lookup context
+- LinkedIn `industry` is too sparse/generic to be your main enrichment signal
+- Preferred workflow: `domain` -> `scrape.website` -> `ai.generateObject`
+
 ---
 
 ## Example: Does this law firm handle medical malpractice?
@@ -42,6 +48,8 @@ async function checkMedMalPractice(domain: string) {
 
 ---
 
+---
+
 ## When to Use
 
 | Use Search → Scrape → Extract    | Use `browser.execute` instead |

package/docs/integrations/gmail/createDraft.md

@@ -0,0 +1,54 @@
+# createDraft
+
+Create a Gmail draft without sending it yet.
+
+```typescript
+// Create a new draft
+const draft = await integrations.gmail.createDraft({
+   recipient_email: "jane@example.com",
+   subject: "Draft follow-up",
+   body: "Sharing a quick follow-up before I send this."
+});
+
+// Draft a reply in an existing thread
+await integrations.gmail.createDraft({
+   thread_id: "19bf77729bcb3a44",
+   body: "Thanks for the update. I will review this today."
+});
+```
+
+## 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       | Draft subject                                |
+| `body`             | `string`   | No       | Draft body content                           |
+| `message_body`     | `string`   | No       | Alternate body field accepted by some tools  |
+| `is_html`          | `boolean`  | No       | Set to `true` when `body` contains HTML      |
+| `attachment`       | `object`   | No       | Optional attachment payload                  |
+| `thread_id`        | `string`   | No       | Existing thread to draft a reply into        |
+| `from_email`       | `string`   | No       | Optional verified send-as alias              |
+| `user_id`          | `string`   | No       | Gmail user id (`\"me\"` by default)          |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    id?: string;
+    draft_id?: string;
+    message?: GmailMessage;
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- Creating a draft is a mutating action and should be used intentionally
+- If you pass `thread_id`, leave `subject` empty to stay in the existing thread

package/docs/integrations/gmail/fetchEmails.md

@@ -0,0 +1,50 @@
+# fetchEmails
+
+Fetch inbox messages or Gmail search results from the connected account.
+
+```typescript
+// Read the current inbox
+const inbox = await integrations.gmail.fetchEmails({
+   query: "in:inbox",
+   max_results: 10
+});
+
+// Search for unread emails from a sender
+const unread = await integrations.gmail.fetchEmails({
+   query: "in:inbox is:unread from:alice@example.com",
+   max_results: 25
+});
+```
+
+## Input
+
+| Parameter             | Type       | Required | Description                                           |
+| --------------------- | ---------- | -------- | ----------------------------------------------------- |
+| `query`               | `string`   | No       | Gmail search query such as `in:inbox is:unread`       |
+| `verbose`             | `boolean`  | No       | Fetch richer message details                          |
+| `ids_only`            | `boolean`  | No       | Only return message/thread identifiers                |
+| `label_ids`           | `string[]` | No       | Filter by Gmail label IDs                             |
+| `page_token`          | `string`   | No       | Pagination token from a previous call                 |
+| `max_results`         | `number`   | No       | Maximum messages to fetch in this page                |
+| `include_payload`     | `boolean`  | No       | Include payload/body data when available              |
+| `include_spam_trash`  | `boolean`  | No       | Include spam and trash                                |
+| `user_id`             | `string`   | No       | Gmail user id (`\"me\"` by default)                   |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    messages?: GmailMessage[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- Results are not guaranteed to be sorted by recency, so sort client-side if order matters
+- For large mailboxes, fetch IDs first and then hydrate specific messages with `fetchMessageByMessageId(...)`

package/docs/integrations/gmail/fetchMessageByMessageId.md

@@ -0,0 +1,36 @@
+# fetchMessageByMessageId
+
+Fetch a single Gmail message by its Gmail API message ID.
+
+```typescript
+const message = await integrations.gmail.fetchMessageByMessageId({
+   message_id: "19b11732c1b578fd",
+   format: "full"
+});
+
+console.log(message.data?.subject);
+console.log(message.data?.threadId);
+```
+
+## Input
+
+| Parameter     | Type                                      | Required | Description                            |
+| ------------- | ----------------------------------------- | -------- | -------------------------------------- |
+| `message_id`  | `string`                                  | Yes      | Gmail API message ID                   |
+| `format`      | `\"minimal\" | \"full\" | \"raw\" | \"metadata\"` | No       | Response format                        |
+| `user_id`     | `string`                                  | No       | Gmail user id (`\"me\"` by default)    |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: GmailMessage;
+  error?: string;
+}
+```
+
+## Notes
+
+- Use real Gmail `message_id` values returned by Gmail list/search actions
+- `format: "full"` is best when you need headers, payload parts, or body data

package/docs/integrations/gmail/fetchMessageByThreadId.md

@@ -0,0 +1,37 @@
+# fetchMessageByThreadId
+
+Fetch all messages belonging to a Gmail thread.
+
+```typescript
+const thread = await integrations.gmail.fetchMessageByThreadId({
+   thread_id: "19bf77729bcb3a44"
+});
+
+for (const message of thread.data?.messages || []) {
+   console.log(message.subject);
+}
+```
+
+## Input
+
+| Parameter    | Type     | Required | Description                         |
+| ------------ | -------- | -------- | ----------------------------------- |
+| `thread_id`  | `string` | Yes      | Gmail API thread ID                 |
+| `user_id`    | `string` | No       | Gmail user id (`\"me\"` by default) |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    messages?: GmailMessage[];
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- Message order is not guaranteed, so sort by `internalDate` if you need oldest/newest order
+- Read threads first before calling `replyToThread(...)` so you have the correct `thread_id`

package/docs/integrations/gmail/getProfile.md

@@ -0,0 +1,37 @@
+# getProfile
+
+Read Gmail profile metadata for the connected account.
+
+```typescript
+const profile = await integrations.gmail.getProfile();
+
+console.log(profile.data?.emailAddress);
+console.log(profile.data?.messagesTotal);
+console.log(profile.data?.threadsTotal);
+```
+
+## Input
+
+| Parameter | Type     | Required | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| `user_id` | `string` | No       | Gmail user id (`\"me\"` by default) |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    emailAddress?: string;
+    messagesTotal?: number;
+    threadsTotal?: number;
+    historyId?: string;
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- This is a lightweight way to confirm which mailbox is connected
+- Mailbox totals are useful for diagnostics, health checks, and quick account introspection

package/docs/integrations/gmail/index.md

@@ -1,12 +1,29 @@
 ---
-description: Gmail email sending via Google integration
+description: Gmail inbox, drafts, threads, labels, profile, and email sending via Google integration
 ---
 
 # Gmail Integration
 
 Typed functions for Gmail actions powered by Orange Slice Google integrations.
 
-## Email
+## Write Actions
 
 - `integrations.gmail.sendEmail(input)` - Send an email through the connected Gmail account
+- `integrations.gmail.createDraft(input)` - Create a Gmail draft without sending it
+- `integrations.gmail.replyToThread(input)` - Reply inside an existing Gmail thread
 - Heavy rate limit: `sendEmail` is capped at **40 calls/day** per connected Gmail account
+- Mutating Gmail actions should be used intentionally because they require approval
+
+## Read Actions
+
+- `integrations.gmail.fetchEmails(input)` - Read inbox messages or Gmail search results
+- `integrations.gmail.fetchMessageByMessageId(input)` - Fetch one message by Gmail message ID
+- `integrations.gmail.fetchMessageByThreadId(input)` - Fetch all messages in a Gmail thread
+- `integrations.gmail.listLabels(input)` - List Gmail system and custom labels
+- `integrations.gmail.getProfile(input)` - Read Gmail profile metadata such as mailbox counts
+
+## Notes
+
+- Prefer `fetchEmails({ query: "in:inbox", max_results: 10 })` to read the current inbox
+- For large inbox scans, start with smaller `max_results` values or `ids_only: true`
+- Use real `messageId` and `threadId` values returned by Gmail read methods before drilling into a message or thread

package/docs/integrations/gmail/listLabels.md

@@ -0,0 +1,34 @@
+# listLabels
+
+List Gmail system labels and custom labels.
+
+```typescript
+const labels = await integrations.gmail.listLabels();
+
+for (const label of labels.data?.labels || []) {
+   console.log(label.id, label.name);
+}
+```
+
+## Input
+
+| Parameter | Type     | Required | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| `user_id` | `string` | No       | Gmail user id (`\"me\"` by default) |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    labels?: GmailLabel[];
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- Use this before any label-based workflow so you work with Gmail label IDs rather than display names
+- System labels and custom labels can both appear in the response

package/docs/integrations/gmail/replyToThread.md

@@ -0,0 +1,51 @@
+# replyToThread
+
+Reply inside an existing Gmail thread.
+
+```typescript
+await integrations.gmail.replyToThread({
+   thread_id: "19bf77729bcb3a44",
+   body: "Thanks for the note. I will get back to you tomorrow."
+});
+
+await integrations.gmail.replyToThread({
+   thread_id: "19bf77729bcb3a44",
+   body: "<p>Reviewed and approved.</p>",
+   is_html: true
+});
+```
+
+## Input
+
+| Parameter          | Type       | Required | Description                                  |
+| ------------------ | ---------- | -------- | -------------------------------------------- |
+| `thread_id`        | `string`   | Yes      | Gmail thread to reply within                 |
+| `body`             | `string`   | No       | Reply body                                   |
+| `message_body`     | `string`   | No       | Alternate body field accepted by some tools  |
+| `subject`          | `string`   | No       | Optional subject override                    |
+| `cc`               | `string[]` | No       | CC recipients                                |
+| `bcc`              | `string[]` | No       | BCC recipients                               |
+| `attachment`       | `object`   | No       | Optional attachment payload                  |
+| `is_html`          | `boolean`  | No       | Set to `true` when `body` contains HTML      |
+| `from_email`       | `string`   | No       | Optional verified send-as alias              |
+| `user_id`          | `string`   | No       | Gmail user id (`\"me\"` by default)          |
+
+## Output
+
+```typescript
+{
+  successful: boolean;
+  data?: {
+    id?: string;
+    messageId?: string;
+    threadId?: string;
+    labelIds?: string[];
+  };
+  error?: string;
+}
+```
+
+## Notes
+
+- This is a mutating action and should be used intentionally
+- Use a real `thread_id` from `fetchEmails(...)` or `fetchMessageByThreadId(...)`

package/docs/integrations/index.md

@@ -242,7 +242,7 @@ See [attio/](./attio/) for all available functions.
 
 ### Gmail
 
-Send emails from connected Google Gmail accounts.
+Read and write emails from connected Google Gmail accounts.
 
 ```typescript
 // Send a plain text email
@@ -260,6 +260,19 @@ await integrations.gmail.sendEmail({
    body: "<h2>Weekly Summary</h2><p>All systems operational.</p>",
    is_html: true
 });
+
+// Read the current inbox
+const inbox = await integrations.gmail.fetchEmails({
+   query: "in:inbox",
+   max_results: 10
+});
+
+// Create a draft without sending it
+await integrations.gmail.createDraft({
+   recipient_email: "john@example.com",
+   subject: "Draft follow-up",
+   body: "This is saved as a draft."
+});
 ```
 
 See [gmail/](./gmail/) for available functions.

package/docs/lookalike-search/index.md

@@ -51,20 +51,32 @@ const results = await services.ocean.search.companies({
 
 **Key filters:**
 
-| Filter             | Example                          | Notes                                            |
-| ------------------ | -------------------------------- | ------------------------------------------------ |
-| `lookalikeDomains` | `["stripe.com", "plaid.com"]`    | Core input — seed domains to find lookalikes for |
-| `companySizes`     | `["51-200", "201-500"]`          | Filter by employee count range                   |
-| `countries`        | `["us", "gb", "de"]`             | Two-letter ISO country codes                     |
-| `industries`       | `["SaaS", "Fintech"]`            | Industry category names                          |
-| `technologies`     | `["React", "Salesforce"]`        | Filter by tech stack                             |
-| `revenueRanges`    | `["1M-10M", "10M-50M"]`          | Revenue band filter                              |
-| `keywords`         | `["payments", "infrastructure"]` | Keyword filter                                   |
-| `ecommerce`        | `true`                           | E-commerce companies only                        |
-| `minScore`         | `0.5`                            | Minimum similarity score (0–1)                   |
+| Filter             | Example                        | Notes                                                        |
+| ------------------ | ------------------------------ | ------------------------------------------------------------ |
+| `lookalikeDomains` | `["stripe.com", "plaid.com"]`  | Core input — seed domains to find lookalikes for             |
+| `companySizes`     | `["51-200", "201-500"]`        | Filter by employee count range                               |
+| `countries`        | `["us", "gb", "de"]`           | Two-letter ISO country codes                                 |
+| `industries`       | `["SaaS", "Fintech"]`          | Industry category names                                      |
+| `ecommerce`        | `true`                         | E-commerce companies only                                    |
+| `peopleFilters`    | `{ seniorities: ["C-Level"] }` | Top-level filter. Only return companies with matching people |
 
 **Pagination:** Use `searchAfter` from the previous response for efficient cursor-based pagination. Max `size` per request is 100.
 
+**Do not send these fields to `services.ocean.search.companies`:**
+
+- `excludeDomains`
+- `includeDomains`
+- `from`
+- `minScore`
+- `technologyCategories`
+- `revenueRanges`
+
+Ocean v3 rejects each of those with `422`.
+
+**Fields that are not safe as simple string arrays:** `technologies` and `keywords`.
+
+When sent as string arrays, Ocean v3 returns `422` with `Input should be a valid dictionary or object to extract fields from`. Until we document the exact upstream shape, do not have the agent generate them.
+
 ### 2. `services.ocean.search.people` — Find People at Companies
 
 Combine company filters with people filters to find the right contacts.
@@ -150,5 +162,5 @@ for (let page = 0; page < 5; page++) {
 
 - **More seed domains = better results.** 3-5 seeds produce much better lookalikes than a single domain.
 - **Combine with enrichment.** Ocean.io returns firmographic data, but you can enrich further with LinkedIn, BuiltWith, or PredictLeads.
-- **Use `minScore`** to control result quality — higher = more similar but fewer results.
+- **Exclude seed domains client-side.** Ocean v3 rejects `excludeDomains`, so filter out seed domains after the response if needed.
 - **Credits:** 5 credits per result. A search returning 50 companies = 250 credits. Reserve is based on the requested `size`.

package/docs/prospecting/index.md

@@ -87,7 +87,7 @@ When using qualification columns, think Circle & Star:
 | **Web Search (Default)** | **ALL prospecting/discovery** — keywords, niche, fuzzy, specific, LinkedIn profiles & companies via `site:linkedin.com` | 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. |
 | **Ocean.io (Lookalike Default)** | User has seed domains and wants similar companies/people. "Find companies like X." | Needs seed domains as input. Not for keyword/niche discovery from scratch. See [guide](../lookalike-search/). |
-| **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. |
+| **PredictLeads**         | Company intelligence, buying signals, and structured company events at scale | Coverage varies by company/market. Treat it as a prospecting/enrichment signal, not source-of-truth validation for whether a known company currently has an opening. |
 | **Niche Directory Scrape** | Well-defined categories with existing lists (see below)   | Requires finding the right directory first.              |
 | **LinkedIn B2B DB**      | **Almost never for prospecting.** Only for: (1) lookups by known identifier (URL/domain/ID), (2) employees at a single known company, (3) trivially simple single-indexed-column filters like `industry_code` or `country_code`. | **Any query with keywords, descriptions, names, ILIKE, skills, or multi-criteria = web search.** The bar is extremely high — if in doubt, use web search. |
 | **Google Maps**          | Local/SMB, physical locations, restaurants, retail          | Limited to businesses with physical presence.            |
@@ -99,7 +99,7 @@ Use PredictLeads first when the user needs **high-quality structured company dat
 
 PredictLeads is usually the best choice for:
 - Tracking **company signals over time** (news, financing, hiring, tech detections, product changes, website evolution)
-- Pulling **normalized lists** (job openings, technologies, investors/connections, similar companies) without custom scraping
+- Pulling **normalized lists** (job openings, technologies, investors/connections, similar companies) for prospecting/enrichment without custom scraping
 - Building qualification columns where consistency matters more than recall
 - Workflows that need stable structured fields instead of parsing search snippets
 

package/docs/services/builtWith/index.md

@@ -9,8 +9,8 @@ description: Technographic data enrichment — discover what technologies, frame
 
 | Method          | Description                            | Credits |
 | --------------- | -------------------------------------- | ------- |
-| `lookupDomain`  | Get full technology stack for a domain | 75      |
-| `relationships` | Find related/connected domains         | 75      |
+| `lookupDomain`  | Get full technology stack for a domain | 20      |
+| `relationships` | Find related/connected domains         | 10      |
 | `searchByTech`  | Find companies using a specific tech   | 100     |
 
 ## Use Cases