orangeslice 2.1.4 → 2.2.0

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/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.
@@ -193,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
@@ -211,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/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/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