orangeslice 2.1.4 → 2.1.5

package/dist/expansion.js

@@ -71,17 +71,28 @@ async function companyLinkedinEnrich(params) {
     if (!shorthand && !url && !domain) {
         throw new Error("[orangeslice] company.linkedin.enrich: provide shorthand, url, or domain");
     }
-    const where = [];
-    if (shorthand)
-        where.push(`slug = ${sqlString(shorthand)}`);
-    if (url)
-        where.push(`linkedin_url = ${sqlString(url)}`);
-    if (domain)
-        where.push(`lower(website) LIKE ${sqlString(`%${domain}%`)}`);
     const fields = extended
-        ? "*"
-        : "name, slug, website, description, employee_count, follower_count, founded_year, locality, region, country_iso, country_name, type, size, ticker, specialties, linkedin_url, created_at, updated_at";
-    const sql = `SELECT ${fields} FROM lkd_company WHERE ${where.join(" OR ")} LIMIT 1`;
+        ? "lkd.*"
+        : "lkd.name, lkd.slug, lkd.website, lkd.description, lkd.employee_count, lkd.follower_count, lkd.founded_year, lkd.locality, lkd.region, lkd.country_iso, lkd.country_name, lkd.type, lkd.size, lkd.ticker, lkd.specialties, lkd.linkedin_url, lkd.created_at, lkd.updated_at";
+    let sql;
+    if (domain) {
+        const bare = domain.replace(/^www\./, "");
+        sql = `SELECT ${fields}
+FROM linkedin_company lc
+JOIN lkd_company lkd ON lkd.linkedin_company_id = lc.id
+WHERE lc.domain IN (${sqlString(bare)}, ${sqlString("www." + bare)})
+ORDER BY CASE WHEN lc.website ~ ${sqlString("^https?://(www\\.)?" + bare.replace(/\./g, "\\.") + "(/([a-z]{2}(-[a-z]{2})?)?)?(\\?.*)?/?$")} THEN 0 ELSE 1 END,
+  lc.employee_count DESC NULLS LAST
+LIMIT 1`;
+    }
+    else {
+        const where = [];
+        if (shorthand)
+            where.push(`lkd.slug = ${sqlString(shorthand)}`);
+        if (url)
+            where.push(`lkd.linkedin_url = ${sqlString(url)}`);
+        sql = `SELECT ${fields} FROM lkd_company lkd WHERE ${where.join(" OR ")} LIMIT 1`;
+    }
     const data = await (0, api_1.post)("/execute/sql", { sql });
     return data.rows?.[0] ?? null;
 }

package/docs/integrations/hubspot/createWebhookFlow.md

@@ -0,0 +1,137 @@
+# createWebhookFlow
+
+Create a HubSpot workflow that sends a webhook from the user's HubSpot portal.
+
+This helper is for OAuth-authorized workflow webhooks, not HubSpot's app-level Webhooks API.
+
+```typescript
+const flow = await integrations.hubspot.createWebhookFlow({
+   name: "Orange Slice - Enrich Missing Contact Emails",
+   description: "Enroll new lead contacts missing email and send to Orange Slice",
+   objectTypeId: "0-1", // Contacts
+   webhookUrl: "https://www.orangeslice.ai/api/triggers/<trigger-id>/webhook",
+   method: "POST",
+   enrollmentCriteria: {
+      type: "EVENT_BASED",
+      shouldReEnroll: false,
+      eventFilterBranches: [
+         {
+            eventTypeId: "4-1463224", // CRM Object Created
+            operator: "HAS_COMPLETED",
+            filterBranchType: "UNIFIED_EVENTS",
+            filterBranchOperator: "AND",
+            filterBranches: [],
+            filters: []
+         }
+      ],
+      listMembershipFilterBranches: [],
+      refinementCriteria: {
+         filterBranchType: "AND",
+         filterBranchOperator: "AND",
+         filterBranches: [],
+         filters: [
+            {
+               property: "lifecyclestage",
+               filterType: "PROPERTY",
+               operation: {
+                  operationType: "ENUMERATION",
+                  operator: "IS_ANY_OF",
+                  includeObjectsWithNoValueSet: false,
+                  values: ["lead"]
+               }
+            },
+            {
+               property: "email",
+               filterType: "PROPERTY",
+               operation: {
+                  operationType: "MULTISTRING",
+                  operator: "IS_EQUAL_TO",
+                  includeObjectsWithNoValueSet: true,
+                  values: []
+               }
+            }
+         ]
+      }
+   }
+});
+```
+
+## Input
+
+```typescript
+{
+  name?: string;
+  description?: string;
+  type?: "CONTACT_FLOW" | "PLATFORM_FLOW";
+  objectTypeId: string;
+  isEnabled?: boolean;
+  webhookActionId?: string;
+  nextAvailableActionId?: string;
+  webhookUrl: string;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "CONNECT" | "TRACE";
+  queryParams?: Array<{ name: string; value: any }>;
+  headers?: Array<{ name: string; value: any }>;
+  requestBody?: string | { type: "STATIC"; value: string };
+  authSettings?: {
+    type: "NONE" | "AUTH_KEY" | "SIGNATURE" | "OAUTH";
+    [key: string]: any;
+  };
+  enrollmentCriteria?: any;
+  enrollmentSchedule?: any;
+  timeWindows?: any[];
+  blockedDates?: any[];
+  suppressionListIds?: string[];
+  canEnrollFromSalesforce?: boolean;
+  customProperties?: Record<string, string>;
+}
+```
+
+## Output
+
+```typescript
+HubSpotFlow;
+```
+
+## Notes
+
+This uses the HubSpot workflows API, not the app-level Webhooks API. The connected HubSpot user must authorize your app with the `automation` OAuth scope.
+
+HubSpot's v4 workflow payload is stricter in practice than our local generated types suggest. The following details are important and were confirmed to work:
+
+- Include top-level `flowType: "WORKFLOW"` when creating workflows via `createFlow(...)`.
+- Use a webhook action with `type: "WEBHOOK"` rather than trying to guess an `actionTypeId`.
+- If you pass `isEnabled: true`, this helper creates the workflow disabled first, then performs a second update call with the full workflow payload HubSpot expects for activation.
+- HubSpot accepts a webhook action shape like:
+
+```typescript
+{
+  type: "WEBHOOK",
+  actionId: "1",
+  method: "POST",
+  webhookUrl: "https://example.com/webhook",
+  requestBody: { type: "STATIC", value: "" },
+  queryParams: [],
+  headers: [],
+  authSettings: { type: "NONE", value: null }
+}
+```
+
+- For the contact lifecycle stage filter, use `operationType: "ENUMERATION"`.
+- For "email is missing", HubSpot accepted:
+
+```typescript
+{
+  property: "email",
+  filterType: "PROPERTY",
+  operation: {
+    operationType: "MULTISTRING",
+    operator: "IS_EQUAL_TO",
+    includeObjectsWithNoValueSet: true,
+    values: []
+  }
+}
+```
+
+- The CRM Object Created event trigger is `eventTypeId: "4-1463224"`.
+
+If the helper fails, fall back to `integrations.hubspot.createFlow(...)` with the exact working payload shape above.

package/docs/integrations/hubspot/index.md

@@ -1,10 +1,10 @@
 ---
-description: HubSpot CRM - contacts, companies, deals, lists, workflows
+description: HubSpot CRM and workflows
 ---
 
 # HubSpot Integration
 
-Typed functions for HubSpot CRM operations.
+Typed functions for HubSpot CRM operations and workflows.
 
 ## Contacts
 
@@ -39,6 +39,8 @@ Typed functions for HubSpot CRM operations.
 - `integrations.hubspot.getFlow(flowId)` - Get workflow details by ID
 - `integrations.hubspot.createFlow(input)` - Create a new workflow
 - `integrations.hubspot.updateFlow(flowId, input)` - Update an existing workflow
+- `integrations.hubspot.createWebhookFlow(input)` - Create a workflow containing a webhook action using OAuth `automation` scope. For advanced payloads, `createFlow(...)` may be more reliable.
+- `integrations.hubspot.updateWebhookFlow(flowId, input)` - Update the webhook action in an existing workflow
 - `integrations.hubspot.deleteFlow(flowId)` - Delete a workflow
 
 ## Lists
@@ -49,6 +51,10 @@ Typed functions for HubSpot CRM operations.
 
 - `integrations.hubspot.listProperties(objectType, options?)` - List all property definitions for an object type
 
+Use `createWebhookFlow` / `updateWebhookFlow` when a user authorizes your app with HubSpot OAuth and grants the `automation` scope.
+
+In practice, HubSpot's workflows v4 API may require extra top-level fields such as `flowType`, `nextAvailableActionId`, and `crmObjectCreationStatus`, plus a strict `WEBHOOK` action payload. See `createWebhookFlow.md` for the currently working payload shape.
+
 ## Owners
 
 - `integrations.hubspot.listOwners(options?)` - List all owners (users) with pagination

package/docs/integrations/hubspot/updateFlow.md

@@ -3,12 +3,7 @@
 Update an existing workflow.
 
 ```typescript
-// First get the current flow to obtain revisionId
-const currentFlow = await integrations.hubspot.getFlow("12345678");
-
-// Update the flow
 const updatedFlow = await integrations.hubspot.updateFlow("12345678", {
-   revisionId: currentFlow.revisionId,
    name: "Updated Workflow Name",
    isEnabled: true
 });
@@ -16,15 +11,15 @@ const updatedFlow = await integrations.hubspot.updateFlow("12345678", {
 
 ## Input
 
-| Parameter                  | Type        | Description                                               |
-| -------------------------- | ----------- | --------------------------------------------------------- |
-| `flowId`                   | `string`    | The ID of the workflow to update                          |
-| `input.revisionId`         | `string`    | **Required** - Current revision ID for optimistic locking |
-| `input.name`               | `string`    | Updated name                                              |
-| `input.description`        | `string`    | Updated description                                       |
-| `input.isEnabled`          | `boolean`   | Enable/disable the workflow                               |
-| `input.actions`            | `unknown[]` | Updated workflow actions                                  |
-| `input.enrollmentCriteria` | `unknown`   | Updated enrollment criteria                               |
+| Parameter                  | Type        | Description                                                                        |
+| -------------------------- | ----------- | ---------------------------------------------------------------------------------- |
+| `flowId`                   | `string`    | The ID of the workflow to update                                                   |
+| `input.revisionId`         | `string`    | Optional current revision ID. If omitted, the helper fetches the latest flow first |
+| `input.name`               | `string`    | Updated name                                                                       |
+| `input.description`        | `string`    | Updated description                                                                |
+| `input.isEnabled`          | `boolean`   | Enable/disable the workflow                                                        |
+| `input.actions`            | `unknown[]` | Updated workflow actions                                                           |
+| `input.enrollmentCriteria` | `unknown`   | Updated enrollment criteria                                                        |
 
 ## Output
 
@@ -43,3 +38,7 @@ Returns the updated workflow object.
   updatedAt: string;
 }
 ```
+
+## Notes
+
+This helper now fetches the current workflow and preserves HubSpot-required top-level fields such as `type`, `objectTypeId`, `flowType`, `nextAvailableActionId`, and `crmObjectCreationStatus` before sending the update request.

package/docs/integrations/hubspot/updateWebhookFlow.md

@@ -0,0 +1,52 @@
+# updateWebhookFlow
+
+Update the webhook action in an existing HubSpot workflow.
+
+```typescript
+const updated = await integrations.hubspot.updateWebhookFlow("12345678", {
+   webhookUrl: "https://example.com/webhooks/hubspot/v2",
+   isEnabled: true
+});
+```
+
+## Input
+
+```typescript
+flowId: string
+
+input: {
+  name?: string;
+  description?: string;
+  isEnabled?: boolean;
+  webhookUrl?: string;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "CONNECT" | "TRACE";
+  queryParams?: Array<{ name: string; value: any }>;
+  headers?: Array<{ name: string; value: any }>;
+  requestBody?: string;
+  authSettings?: {
+    type: "AUTH_KEY" | "SIGNATURE" | "OAUTH";
+    [key: string]: any;
+  };
+  enrollmentCriteria?: any;
+  enrollmentSchedule?: any;
+  timeWindows?: any[];
+  blockedDates?: any[];
+  suppressionListIds?: string[];
+  canEnrollFromSalesforce?: boolean;
+  customProperties?: Record<string, string>;
+}
+```
+
+## Output
+
+```typescript
+HubSpotFlow;
+```
+
+## Notes
+
+This helper fetches the current workflow, preserves its existing revision and non-webhook settings, and updates the first webhook action it finds.
+
+When working with HubSpot workflow webhooks, prefer preserving any existing top-level workflow fields such as `flowType`, `nextAvailableActionId`, and `crmObjectCreationStatus`. HubSpot's v4 workflow API is sensitive to omitted fields during updates.
+
+This helper now preserves those top-level workflow fields automatically before sending the `updateFlow(...)` request.

package/docs/integrations/index.md

@@ -6,7 +6,7 @@ Access external APIs through `integrations.<provider>.<function>()`.
 
 ### HubSpot
 
-CRM operations for contacts, companies, and deals.
+CRM operations plus workflows.
 
 ```typescript
 // Create a contact
@@ -22,6 +22,55 @@ const deals = await integrations.hubspot.searchDeals({
       }
    ]
 });
+
+// Create a workflow that sends a webhook from the user's HubSpot portal
+await integrations.hubspot.createWebhookFlow({
+   name: "Orange Slice - Enrich Missing Contact Emails",
+   objectTypeId: "0-1",
+   webhookUrl: "https://www.orangeslice.ai/api/triggers/<trigger-id>/webhook",
+   enrollmentCriteria: {
+      type: "EVENT_BASED",
+      shouldReEnroll: false,
+      eventFilterBranches: [
+         {
+            eventTypeId: "4-1463224",
+            operator: "HAS_COMPLETED",
+            filterBranchType: "UNIFIED_EVENTS",
+            filterBranchOperator: "AND",
+            filterBranches: [],
+            filters: []
+         }
+      ],
+      listMembershipFilterBranches: [],
+      refinementCriteria: {
+         filterBranchType: "AND",
+         filterBranchOperator: "AND",
+         filterBranches: [],
+         filters: [
+            {
+               property: "lifecyclestage",
+               filterType: "PROPERTY",
+               operation: {
+                  operationType: "ENUMERATION",
+                  operator: "IS_ANY_OF",
+                  includeObjectsWithNoValueSet: false,
+                  values: ["lead"]
+               }
+            },
+            {
+               property: "email",
+               filterType: "PROPERTY",
+               operation: {
+                  operationType: "MULTISTRING",
+                  operator: "IS_EQUAL_TO",
+                  includeObjectsWithNoValueSet: true,
+                  values: []
+               }
+            }
+         ]
+      }
+   }
+});
 ```
 
 See [hubspot/](./hubspot/) for all available functions.

package/docs/integrations/salesforce/index.md

@@ -25,6 +25,10 @@ Typed functions for Salesforce CRM operations using SOQL queries and the REST AP
 - `integrations.salesforce.describeGlobal()` - List all available SObjects
 - `integrations.salesforce.describeSObject(sobject)` - Get schema for an SObject
 
+## Generic Request Operations
+
+- `integrations.salesforce.request(input)` - Make an authenticated request to any Salesforce endpoint
+
 ## Collection/Batch Operations
 
 - `integrations.salesforce.createRecords(input)` - Create up to 200 records

package/docs/integrations/salesforce/request.md

@@ -0,0 +1,58 @@
+const result = await integrations.salesforce.request({
+path: "/services/data/v62.0/actions/standard",
+});
+
+const compositeResult = await integrations.salesforce.request({
+method: "POST",
+path: "/services/data/v62.0/composite/",
+body: {
+allOrNone: true,
+compositeRequest: [
+{
+method: "GET",
+url: "/services/data/v62.0/sobjects/Lead/00Qxx000001abcDEAY",
+referenceId: "lead"
+}
+
+    ]
+
+}
+});
+
+const apexResult = await integrations.salesforce.request({
+method: "POST",
+path: "/services/apexrest/leadconvert/00Qxx000001abcDEAY",
+body: {
+doNotCreateOpportunity: true
+}
+});
+
+Use `request()` when Salesforce has an endpoint that Orange Slice does not expose as a first-class helper.
+
+## Input
+
+| Field     | Type                                                               | Required | Description                                              |
+| --------- | ------------------------------------------------------------------ | -------- | -------------------------------------------------------- |
+| `path`    | `string`                                                           | Yes      | Absolute URL or instance-relative path starting with `/` |
+| `method`  | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"`                  | No       | HTTP method. Defaults to `GET`                           |
+| `query`   | `Record<string, string \| number \| boolean \| null \| undefined>` | No       | Query params appended to the URL                         |
+| `headers` | `Record<string, string>`                                           | No       | Additional request headers                               |
+| `body`    | `unknown`                                                          | No       | Request body. Objects are JSON-stringified automatically |
+
+## Response
+
+Returns:
+
+```ts
+{
+   status: number;
+   headers: Record<string, string>;
+   data: unknown;
+}
+```
+
+## Notes
+
+- OAuth and the Salesforce instance URL are handled automatically.
+- `path` must be a full URL or start with `/`.
+- This is the escape hatch for non-CRUD Salesforce APIs such as Apex REST, composite APIs, quick actions, and other special endpoints.

package/docs/services/ai/generateObject.ts

@@ -1,4 +1,4 @@
-/** Credits: 1 (standard) */
+/** Credits: 1 (low) or 10 (medium) */
 
 /**
  * Generate an object using AI.
@@ -17,12 +17,16 @@
  * for each one individually. The runtime handles parallelization for you.
  *
  * The field will be present in the output but can have a null value when the AI has no data.
+ *
+ * Intelligence guidance:
+ * - Prefer `low` for classification, tagging, extraction, normalization, and other constrained schema-filling tasks.
+ * - Prefer `medium` for more nuanced generation quality, like writing outreach hooks, personalized messaging, or other higher-judgment copy that still returns structured fields.
  */
 type generateObject = (params: {
    /** The prompt to generate the object from */
    prompt: string;
    /** A JSON schema object describing the output shape */
    schema: any;
-   /** Optional model override. All models currently route to gpt-5-mini */
-   model?: "gpt-5-mini";
+   /** Optional intelligence level. Defaults to "low" (gpt-5-mini, 1 credit). Prefer `low` for classification/extraction and `medium` for higher-quality writing tasks like outreach (gemini-3-flash-preview, 10 credits). */
+   intelligence?: "low" | "medium";
 }) => Promise<{ object: Record<string, any> }>;

package/docs/services/ai/generateText.ts

@@ -1,14 +1,18 @@
-/** Credits: 1 (standard) */
+/** Credits: 1 (low) or 10 (medium) */
 
 /**
  * Generate text using AI, optionally with web search.
  * IMPORTANT: Always incorporate the user's guidelines (i.e. no fabrication, writing style, format) into your prompt. See index.md.
+ *
+ * Intelligence guidance:
+ * - Prefer `low` for classification-like prompts, terse transformations, extraction-adjacent formatting, and other constrained text tasks.
+ * - Prefer `medium` for higher-quality writing tasks like outreach, hooks, personalized messaging, and nuanced copy generation.
  */
 type generateText = (params: {
    /** The prompt to generate the text from */
    prompt: string;
    /** Whether to enable web search */
    enableWebSearch?: boolean;
-   /** Optional model override. All models currently route to gpt-5-mini */
-   model?: "gpt-5-mini";
+   /** Optional intelligence level. Defaults to "low" (gpt-5-mini, 1 credit). Prefer `low` for constrained text tasks and `medium` for higher-quality writing like outreach (gemini-3-flash-preview, 10 credits). */
+   intelligence?: "low" | "medium";
 }) => Promise<{ text: string }>;

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

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.1.5",
   "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",