orangeslice 2.3.0-beta.0 → 2.3.1-beta.0

package/README.md

@@ -52,6 +52,21 @@ pnpm add orangeslice
 yarn add orangeslice
 ```
 
+## Integrations & Skills
+
+```ts
+import { integrations, skills } from "orangeslice";
+
+// Connect a third-party service (opens browser for OAuth)
+const hubspot = await integrations.connect("hubspot");
+
+// List connected integrations
+const { integrations: list } = await integrations.list();
+
+// Create a knowledge skill
+await skills.create({ name: "ICP", content: "B2B SaaS, 50-500 employees..." });
+```
+
 ## Public API (services-first)
 
 Use `services.*` as the primary API surface.
@@ -103,6 +118,8 @@ const startups = await services.crunchbase.search({
 - `services.googleMaps.scrape`
 - `services.geo.parseAddress`
 - `services.builtWith.lookupDomain/relationships/searchByTech`
+- `integrations.connect/list/get/create/update/delete`
+- `skills.list/get/create/update/delete`
 
 ## How routing works today
 

package/dist/cli.js

@@ -179,6 +179,7 @@ Use these docs as the source of truth. If there is any conflict between your pri
 ## Package Setup (Do Not Guess)
 - Import from the package name, not a local file path:
   - \`import { services } from "orangeslice"\`
+  - \`import { integrations, skills } from "orangeslice"\` for integration and skill management
   - \`import { configure, services } from "orangeslice"\` when setting API key programmatically
 - Do NOT use \`import { services } from "./orangeslice"\` unless the user explicitly has a local wrapper file at that path.
 - The orangeslice bootstrap commands (\`npx orangeslice\`, \`bunx orangeslice\`, \`pnpm dlx orangeslice\`, \`yarn dlx orangeslice\`) sync docs, install the package, and handle auth. They do NOT execute user app scripts.
@@ -192,7 +193,9 @@ Use these docs as the source of truth. If there is any conflict between your pri
 ## Mandatory Read Order (Before writing code)
 1. \`./services/index.md\` - service map and capabilities
 2. Relevant docs under \`./services/**\` for every service you plan to call
-3. \`./prospecting/index.md\` when doing discovery or lead generation tasks
+3. \`./services/integrations/index.md\` when connecting or managing third-party integrations
+4. \`./services/skills/index.md\` when managing knowledge skills
+5. \`./prospecting/index.md\` when doing discovery or lead generation tasks
 
 Do not call a service before reading its documentation.
 
@@ -203,6 +206,12 @@ Do not call a service before reading its documentation.
 - For broad scraping by URL, use \`services.scrape.website\`.
 - Use \`services.ai.generateObject\` for structured extraction/classification with a JSON schema.
 
+## Integration & Skill Management
+- To connect a third-party service, use \`integrations.connect(provider)\`. This opens the browser for OAuth (HubSpot, Salesforce, Attio, Gmail, Slack) or prompts for an API key (Instantly, HeyReach).
+- To list connected integrations, use \`integrations.list()\`.
+- To manage knowledge skills (ICP descriptions, templates, etc.), use \`skills.create/list/update/delete\`.
+- Read \`./services/integrations/index.md\` and \`./services/skills/index.md\` for full API details.
+
 ## Execution Rules
 - Parallelize independent async calls with \`Promise.all\`.
 - Avoid serial \`await\` inside loops when calls can run concurrently.
@@ -246,6 +255,8 @@ This project includes orangeslice for B2B sales operations, lead generation, enr
 - Structured AI generation
 - Website scraping and browser execution
 - PredictLeads and BuiltWith-backed discovery
+- Integration management — connect HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach via \`integrations.connect(provider)\`
+- Knowledge skills — create and manage reusable knowledge snippets via \`skills.create/list/update/delete\`
 `;
     fs.writeFileSync(CLAUDE_GUIDE_FILE, content, "utf8");
 }

package/docs/services/index.md

@@ -10,4 +10,6 @@
 - **scrape**: website scraper, sitemap scraper
 - **web**: SERP
 - **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(...)`  |

package/docs/services/skills/index.md

@@ -0,0 +1,87 @@
+---
+description: Create and manage knowledge skills — reusable knowledge snippets that guide AI agents
+---
+
+# skills — Knowledge Skills
+
+Create, read, update, and delete knowledge skills. Skills are reusable knowledge snippets (company context, ICP descriptions, email templates, product info) that agents reference during research and outreach.
+
+## Quick start
+
+```typescript
+import { skills } from "orangeslice";
+
+// Create a skill
+const skill = await skills.create({
+  name: "ICP description",
+  content: "We sell to B2B SaaS companies, 50-500 employees, Series A-C..."
+});
+
+// List all skills
+const { skills: all } = await skills.list();
+console.log(all.map(s => `${s.name}: ${s.content.slice(0, 50)}...`));
+
+// Update a skill
+await skills.update(skill.id, { content: "Updated ICP: ..." });
+
+// Delete a skill
+await skills.delete(skill.id);
+```
+
+## Methods
+
+### `skills.list(opts?)`
+
+List knowledge skills for the current account.
+
+**Parameters:**
+- `opts.spreadsheetId` — Filter to a specific spreadsheet's skills
+
+**Returns:** `{ skills: Skill[] }`
+
+### `skills.get(id)`
+
+Get a single skill by ID.
+
+**Returns:** `Skill`
+
+### `skills.create(opts)`
+
+Create a new knowledge skill.
+
+**Parameters:**
+- `opts.name` — Skill name (e.g. "ICP description", "Email template")
+- `opts.content` — The knowledge content
+- `opts.spreadsheetId` — Optional, scope to a specific spreadsheet
+
+**Returns:** `Skill`
+
+### `skills.update(id, fields)`
+
+Update an existing skill.
+
+**Parameters:**
+- `fields.name` — New name
+- `fields.content` — New content
+
+**Returns:** `Skill`
+
+### `skills.delete(id)`
+
+Delete a skill by ID.
+
+**Returns:** `{ success: boolean }`
+
+## Skill object
+
+```typescript
+{
+  id: string;
+  name: string;
+  content: string;
+  createdAt: string;
+  updatedAt: string;
+  scope: "account" | "spreadsheet";
+  spreadsheetId: string | null;
+}
+```

package/package.json

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