orangeslice 2.4.0-beta.1 → 2.4.1

package/README.md

@@ -58,13 +58,23 @@ yarn add orangeslice
 import { integrations, skills } from "orangeslice";
 
 // Connect a third-party service (opens browser for OAuth)
-const hubspot = await integrations.connect("hubspot");
+await integrations.connect("hubspot");
+
+// Execute integration methods directly
+const contact = await integrations.hubspot.createContact({
+  properties: { email: "john@acme.com", firstname: "John" }
+});
+await integrations.instantly.addLeadsToCampaign({
+  campaignId: "abc-123",
+  leads: [{ email: "lead@company.com" }]
+});
+await integrations.slack.chatPostMessage({ channel: "#leads", text: "New lead!" });
 
 // List connected integrations
 const { integrations: list } = await integrations.list();
 
 // Create a knowledge skill
-await skills.create({ name: "ICP", content: "B2B SaaS, 50-500 employees..." });
+await skills.create({ title: "ICP", description: "Ideal customer profile criteria", content: "B2B SaaS, 50-500 employees..." });
 ```
 
 ## Public API (services-first)

package/dist/cli.js

@@ -208,6 +208,8 @@ Do not call a service before reading its documentation.
 
 ## 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 execute integration methods, use \`integrations.<provider>.<method>(args)\` — e.g. \`integrations.hubspot.createContact({...})\`, \`integrations.instantly.addLeadsToCampaign({...})\`.
+- **Always read the per-method docs** at \`./integrations/<provider>/<method>.md\` before calling any integration method. Do not guess parameters.
 - 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.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { configure } from "./api";
 export type { OrangesliceConfig } from "./api";
 export { integrations } from "./integrations";
-export type { Integration, IntegrationProvider, IntegrationListParams, IntegrationCreateParams, IntegrationUpdateParams, IntegrationConnectOptions } from "./integrations";
+export type { Integration, IntegrationProvider, IntegrationListParams, IntegrationCreateParams, IntegrationUpdateParams, IntegrationConnectOptions, IntegrationExecuteOptions } from "./integrations";
 export { skills } from "./skills";
 export type { Skill, SkillListParams, SkillCreateParams, SkillUpdateParams } from "./skills";
 export { findCareersPage, scrapeCareersPage } from "./careers";
@@ -110,6 +110,15 @@ export declare const services: {
         delete: (id: string) => Promise<{
             success: boolean;
         }>;
+        execute: (provider: import("./integrations").IntegrationProvider, method: string, ...args: unknown[]) => Promise<unknown>;
+    } & {
+        readonly hubspot: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly salesforce: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly attio: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly gmail: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly slack: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly instantly: Record<string, (...args: unknown[]) => Promise<unknown>>;
+        readonly heyreach: Record<string, (...args: unknown[]) => Promise<unknown>>;
     };
     skills: {
         list: (opts?: import("./skills").SkillListParams) => Promise<{

package/dist/integrations.d.ts

@@ -7,6 +7,10 @@
  *   // Connect an OAuth provider (opens browser)
  *   const hubspot = await integrations.connect("hubspot");
  *
+ *   // Execute integration methods
+ *   await integrations.hubspot.createContact({ properties: { email: "j@acme.com" } });
+ *   await integrations.instantly.addLeadsToCampaign({ campaignId: "abc", leads: [...] });
+ *
  *   // List connected integrations
  *   const { integrations: list } = await integrations.list();
  *
@@ -46,7 +50,11 @@ export interface IntegrationUpdateParams {
 export interface IntegrationConnectOptions {
     noBrowser?: boolean;
 }
-export declare const integrations: {
+export interface IntegrationExecuteOptions {
+    spreadsheetId?: string;
+    integrationId?: string;
+}
+declare const integrationsBase: {
     connect: (provider: IntegrationProvider, opts?: IntegrationConnectOptions) => Promise<Integration>;
     list: (opts?: IntegrationListParams) => Promise<{
         integrations: Integration[];
@@ -57,4 +65,15 @@ export declare const integrations: {
     delete: (id: string) => Promise<{
         success: boolean;
     }>;
+    execute: (provider: IntegrationProvider, method: string, ...args: unknown[]) => Promise<unknown>;
+};
+export declare const integrations: typeof integrationsBase & {
+    readonly hubspot: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly salesforce: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly attio: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly gmail: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly slack: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly instantly: Record<string, (...args: unknown[]) => Promise<unknown>>;
+    readonly heyreach: Record<string, (...args: unknown[]) => Promise<unknown>>;
 };
+export {};

package/dist/integrations.js

@@ -8,6 +8,10 @@
  *   // Connect an OAuth provider (opens browser)
  *   const hubspot = await integrations.connect("hubspot");
  *
+ *   // Execute integration methods
+ *   await integrations.hubspot.createContact({ properties: { email: "j@acme.com" } });
+ *   await integrations.instantly.addLeadsToCampaign({ campaignId: "abc", leads: [...] });
+ *
  *   // List connected integrations
  *   const { integrations: list } = await integrations.list();
  *
@@ -94,14 +98,46 @@ async function connectIntegration(provider, opts) {
     }
     throw new Error(`[orangeslice] integrations.connect: Timed out waiting for authorization.`);
 }
+function executeMethod(provider, method, args, opts) {
+    return (0, api_1.post)("/execute/integration", {
+        provider,
+        method,
+        args,
+        ...(opts?.spreadsheetId ? { spreadsheetId: opts.spreadsheetId } : {}),
+        ...(opts?.integrationId ? { integrationId: opts.integrationId } : {})
+    });
+}
+const PROVIDER_NAMES = new Set(["hubspot", "salesforce", "attio", "gmail", "slack", "instantly", "heyreach"]);
+const CRUD_KEYS = new Set(["connect", "list", "get", "create", "update", "delete", "execute"]);
+function createProviderProxy(provider) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== "string")
+                return undefined;
+            return (...args) => executeMethod(provider, prop, args);
+        }
+    });
+}
 // ---------------------------------------------------------------------------
-// CRUD (via batch-service)
+// CRUD + Execute (via batch-service)
 // ---------------------------------------------------------------------------
-exports.integrations = {
+const integrationsBase = {
     connect: (provider, opts) => connectIntegration(provider, opts),
     list: (opts) => (0, api_1.post)("/ctx/integrations/list", (opts ?? {})),
     get: (id) => (0, api_1.post)("/ctx/integrations/get", { id }),
     create: (opts) => (0, api_1.post)("/ctx/integrations/create", opts),
     update: (id, fields) => (0, api_1.post)("/ctx/integrations/update", { id, ...fields }),
-    delete: (id) => (0, api_1.post)("/ctx/integrations/delete", { id })
+    delete: (id) => (0, api_1.post)("/ctx/integrations/delete", { id }),
+    execute: (provider, method, ...args) => executeMethod(provider, method, args)
 };
+exports.integrations = new Proxy(integrationsBase, {
+    get(target, prop) {
+        if (typeof prop !== "string")
+            return undefined;
+        if (CRUD_KEYS.has(prop))
+            return target[prop];
+        if (PROVIDER_NAMES.has(prop))
+            return createProviderProxy(prop);
+        return target[prop];
+    }
+});

package/docs/services/index.md

@@ -10,6 +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.
+- **integrations**: connect, manage, and **execute** third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach). Use `integrations.connect(provider)` to connect, then `integrations.<provider>.<method>(args)` to execute methods (e.g. `integrations.hubspot.createContact({...})`). Read per-method docs at `./integrations/<provider>/<method>.md` before calling.
 - **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

@@ -1,10 +1,10 @@
 ---
-description: Connect and manage third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach)
+description: Connect, manage, and execute third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach)
 ---
 
-# integrations — Integration Management
+# integrations — Integration Management & Execution
 
-Connect, list, and manage third-party service integrations. Supports both OAuth providers (HubSpot, Salesforce, Attio, Gmail, Slack) and API-key providers (Instantly, HeyReach).
+Connect third-party services, manage integration records, and **execute integration methods** directly. Supports both OAuth providers (HubSpot, Salesforce, Attio, Gmail, Slack) and API-key providers (Instantly, HeyReach).
 
 ## Quick start
 
@@ -12,21 +12,27 @@ Connect, list, and manage third-party service integrations. Supports both OAuth
 import { integrations } from "orangeslice";
 
 // Connect an OAuth provider (opens browser for authorization)
-const hubspot = await integrations.connect("hubspot");
-console.log(`Connected: ${hubspot.displayName}`);
+await integrations.connect("hubspot");
 
-// List all connected integrations
-const { integrations: list } = await integrations.list();
-console.log(list.map(i => `${i.provider}: ${i.displayName}`));
+// Execute integration methods directly
+const contact = await integrations.hubspot.createContact({
+   properties: { email: "john@acme.com", firstname: "John" }
+});
 
-// Connect an API-key provider programmatically (no browser)
-await integrations.create({
-  provider: "instantly",
-  apiKey: "inst_abc123...",
-  displayName: "My Instantly"
+const campaigns = await integrations.instantly.listCampaigns();
+
+await integrations.slack.chatPostMessage({
+   channel: "#leads",
+   text: "New lead: john@acme.com"
 });
+
+// List all connected integrations
+const { integrations: list } = await integrations.list();
+console.log(list.map((i) => `${i.provider}: ${i.displayName}`));
 ```
 
+**Important**: Read the per-method docs at `./integrations/<provider>/<method>.md` for available methods, parameters, and response shapes. Do not invent methods.
+
 ## Methods
 
 ### `integrations.connect(provider, opts?)`
@@ -36,6 +42,7 @@ Opens the user's browser to complete OAuth authorization (or API key entry for I
 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
 
@@ -51,6 +58,7 @@ const salesforce = await integrations.connect("salesforce");
 List connected integrations for the current account.
 
 **Parameters:**
+
 - `opts.spreadsheetId` — Filter to a specific spreadsheet's integrations
 - `opts.provider` — Filter by provider name
 
@@ -72,6 +80,7 @@ Get a single integration by ID.
 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
@@ -85,6 +94,7 @@ Programmatically create an API-key integration without opening a browser. Only w
 Update an existing integration.
 
 **Parameters:**
+
 - `fields.apiKey` — New API key
 - `fields.displayName` — New display name
 - `fields.isActive` — Enable/disable
@@ -98,31 +108,95 @@ Delete an integration by ID.
 
 **Returns:** `{ success: boolean }`
 
+## Executing integration methods
+
+Once an integration is connected, call its methods directly via `integrations.<provider>.<method>(args)`.
+
+```typescript
+// HubSpot
+const contact = await integrations.hubspot.createContact({
+   properties: { email: "jane@acme.com", firstname: "Jane" }
+});
+const companies = await integrations.hubspot.searchCompanies({
+   filterGroups: [{ filters: [{ propertyName: "domain", operator: "EQ", value: "acme.com" }] }]
+});
+
+// Instantly
+await integrations.instantly.addLeadsToCampaign({
+   campaignId: "abc-123",
+   leads: [{ email: "lead@company.com", firstName: "Lead" }]
+});
+const campaigns = await integrations.instantly.listCampaigns();
+
+// Slack
+await integrations.slack.chatPostMessage({ channel: "#sales", text: "New deal closed!" });
+const channels = await integrations.slack.conversationsList();
+
+// Gmail
+await integrations.gmail.sendEmail({
+   to: "prospect@company.com",
+   subject: "Following up",
+   body: "Hi, just wanted to check in..."
+});
+
+// Attio
+await integrations.attio.createRecord({
+   objectSlug: "companies",
+   data: { values: { name: [{ value: "Acme Corp" }] } }
+});
+
+// Salesforce
+await integrations.salesforce.createRecord({
+   objectType: "Contact",
+   fields: { Email: "new@example.com", LastName: "Smith" }
+});
+
+// HeyReach
+await integrations.heyreach.addLeadsToList({
+   listId: "list-123",
+   leads: [{ linkedinUrl: "https://linkedin.com/in/johndoe" }]
+});
+```
+
+### `integrations.execute(provider, method, ...args)`
+
+Explicit dispatch for dynamic provider/method names:
+
+```typescript
+const provider = "hubspot";
+const method = "searchContacts";
+const result = await integrations.execute(provider, method, { query: "acme" });
+```
+
+### Per-method documentation
+
+Every provider method is documented at `./integrations/<provider>/<method>.md`. **Always read the method docs before calling** to get the correct parameter shapes and response types.
+
 ## 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;
+   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(...)`  |
+| 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/package.json

@@ -1,40 +1,40 @@
 {
-  "name": "orangeslice",
-  "version": "2.4.0-beta.1",
-  "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "orangeslice": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "docs",
-    "README.md"
-  ],
-  "scripts": {
-    "sync-docs": "node scripts/sync-docs.mjs",
-    "build": "tsc",
-    "prepublishOnly": "npm run sync-docs && npm run build"
-  },
-  "keywords": [
-    "b2b",
-    "rate-limit",
-    "ai-agent",
-    "linkedin",
-    "sales-agent",
-    "claude-code",
-    "cursor",
-    "mcp"
-  ],
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kishansripada/npx-orangeslice.git"
-  },
-  "devDependencies": {
-    "@types/node": "^25.1.0",
-    "typescript": "^5.9.3"
-  }
+   "name": "orangeslice",
+   "version": "2.4.1",
+   "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
+   "main": "dist/index.js",
+   "types": "dist/index.d.ts",
+   "bin": {
+      "orangeslice": "dist/cli.js"
+   },
+   "files": [
+      "dist",
+      "docs",
+      "README.md"
+   ],
+   "scripts": {
+      "sync-docs": "node scripts/sync-docs.mjs",
+      "build": "tsc",
+      "prepublishOnly": "npm run sync-docs && npm run build"
+   },
+   "keywords": [
+      "b2b",
+      "rate-limit",
+      "ai-agent",
+      "linkedin",
+      "sales-agent",
+      "claude-code",
+      "cursor",
+      "mcp"
+   ],
+   "author": "",
+   "license": "MIT",
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/kishansripada/npx-orangeslice.git"
+   },
+   "devDependencies": {
+      "@types/node": "^25.1.0",
+      "typescript": "^5.9.3"
+   }
 }