orangeslice 2.1.4 → 2.2.0

package/README.md

@@ -90,8 +90,10 @@ const startups = await services.crunchbase.search({
 ## Service map
 
 - `services.company.linkedin.search/enrich`
+- `services.company.findCareersPage/scrapeCareersPage`
 - `services.crunchbase.search` (returns rows array directly)
 - `services.company.getEmployeesFromLinkedin` (database-only B2B path)
+- `services.ocean.search.companies/people`
 - `services.person.linkedin.search/enrich`
 - `services.web.search/batchSearch`
 - `services.ai.generateObject`
@@ -106,7 +108,7 @@ const startups = await services.crunchbase.search({
 
 All service calls go through `post()` in `src/api.ts`.
 
-- Submit path: `https://enrichly-production.up.railway.app/function`
+- Execute paths: `https://enrichly-production.up.railway.app/execute/*` and `https://enrichly-production.up.railway.app/ctx/*`
 - Pending responses (`pending: true` / `202`) poll batch-service result endpoints.
 - Polling timeout supports long-running workflows (up to 10 minutes).
 - This package now exposes only batch-backed services.

package/dist/careers.d.ts

@@ -0,0 +1,47 @@
+export interface FindCareersPageParams {
+    website?: string;
+    url?: string;
+}
+export interface FindCareersPageResult {
+    inputUrl: string;
+    normalizedWebsiteUrl: string;
+    careerPageUrl: string | null;
+    pageType: "ats" | "official" | "not_found";
+    atsProvider: string | null;
+    detectionMethod: "input-ats" | "homepage-ats-link" | "homepage-careers-link" | "deterministic-candidate" | "candidate-ats-link" | "embedded-ats" | "candidate-redirect" | "ats-unverified" | "not-found";
+    checkedUrls: string[];
+}
+export interface ScrapeCareersPageParams {
+    careersPageUrl?: string;
+    url?: string;
+}
+export interface ScrapeCareersPageJob {
+    id: string;
+    title: string;
+    url: string;
+    applyUrl: string | null;
+    location: string | null;
+    locations: string[];
+    department: string | null;
+    team: string | null;
+    employmentType: string | null;
+    workplaceType: string | null;
+    postedAt: string | null;
+    postedText: string | null;
+    requisitionId: string | null;
+}
+export interface ScrapeCareersPageResult {
+    status: "success" | "unsupported_url" | "unsupported_provider";
+    inputUrl: string;
+    normalizedBoardUrl: string | null;
+    atsProvider: string | null;
+    companyName: string | null;
+    source: "api" | "html" | null;
+    totalJobs: number;
+    jobs: ScrapeCareersPageJob[];
+    checkedUrls: string[];
+    supportedProviders: string[];
+    message: string | null;
+}
+export declare function findCareersPage(params: FindCareersPageParams): Promise<FindCareersPageResult>;
+export declare function scrapeCareersPage(params: ScrapeCareersPageParams): Promise<ScrapeCareersPageResult>;

package/dist/careers.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCareersPage = findCareersPage;
+exports.scrapeCareersPage = scrapeCareersPage;
+const api_1 = require("./api");
+async function findCareersPage(params) {
+    return (0, api_1.post)("/execute/find-careers-page", { ...params });
+}
+async function scrapeCareersPage(params) {
+    return (0, api_1.post)("/execute/scrape-careers-page", { ...params });
+}

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/dist/index.d.ts

@@ -1,11 +1,15 @@
 export { configure } from "./api";
 export type { OrangesliceConfig } from "./api";
+export { findCareersPage, scrapeCareersPage } from "./careers";
+export type { FindCareersPageParams, FindCareersPageResult, ScrapeCareersPageParams, ScrapeCareersPageResult, ScrapeCareersPageJob } from "./careers";
 export { ctx } from "./ctx";
 export type { Spreadsheet, SpreadsheetListItem, SqlResult, SqlQueryResult, SqlActionResult, RowsAddResult } from "./ctx";
 export { linkedinSearch } from "./b2b";
 export type { LinkedInSearchParams, LinkedInSearchResponse } from "./b2b";
 export { crunchbaseSearch } from "./crunchbase";
 export type { CrunchbaseSearchParams } from "./crunchbase";
+export { executeOcean, oceanSearchCompanies, oceanSearchPeople, OCEAN_OPERATION_IDS } from "./ocean";
+export type { OceanOperationId, OceanCompaniesFilters, OceanPeopleFilters, OceanCompaniesSearchParams, OceanCompaniesSearchResponse, OceanCompanyResult, OceanCompanyMatch, OceanPeopleSearchParams, OceanPeopleSearchResponse, OceanPersonResult } from "./ocean";
 export { webSearch, webBatchSearch } from "./serp";
 export type { WebSearchQuery, WebSearchResult, WebSearchResponse, BatchWebSearchParams } from "./serp";
 export { generateObject } from "./generateObject";
@@ -25,11 +29,13 @@ export type { PersonLinkedinFindUrlParams, CompanyLinkedinFindUrlParams, PersonC
 import { runApifyActor } from "./apify";
 import { linkedinSearch } from "./b2b";
 import { browserExecute } from "./browser";
+import { findCareersPage, scrapeCareersPage } from "./careers";
 import { crunchbaseSearch } from "./crunchbase";
 import { personLinkedinEnrich, personLinkedinFindUrl, personContactGet, companyLinkedinEnrich, companyLinkedinFindUrl, companyGetEmployeesFromLinkedin, geoParseAddress, builtWithLookupDomain, builtWithRelationships, builtWithSearchByTech } from "./expansion";
 import { scrapeWebsite } from "./firecrawl";
 import { generateObject } from "./generateObject";
 import { googleMapsScrape } from "./googleMaps";
+import { oceanSearchCompanies, oceanSearchPeople } from "./ocean";
 import { webBatchSearch, webSearch } from "./serp";
 export declare const services: {
     crunchbase: {
@@ -42,6 +48,8 @@ export declare const services: {
             search: typeof linkedinSearch;
         };
         getEmployeesFromLinkedin: typeof companyGetEmployeesFromLinkedin;
+        findCareersPage: typeof findCareersPage;
+        scrapeCareersPage: typeof scrapeCareersPage;
     };
     person: {
         linkedin: {
@@ -75,6 +83,12 @@ export declare const services: {
     googleMaps: {
         scrape: typeof googleMapsScrape;
     };
+    ocean: {
+        search: {
+            companies: typeof oceanSearchCompanies;
+            people: typeof oceanSearchPeople;
+        };
+    };
     builtWith: {
         lookupDomain: typeof builtWithLookupDomain;
         relationships: typeof builtWithRelationships;

package/dist/index.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.configure = void 0;
+exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.OCEAN_OPERATION_IDS = exports.oceanSearchPeople = exports.oceanSearchCompanies = exports.executeOcean = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.scrapeCareersPage = exports.findCareersPage = exports.configure = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return api_1.configure; } });
+var careers_1 = require("./careers");
+Object.defineProperty(exports, "findCareersPage", { enumerable: true, get: function () { return careers_1.findCareersPage; } });
+Object.defineProperty(exports, "scrapeCareersPage", { enumerable: true, get: function () { return careers_1.scrapeCareersPage; } });
 var ctx_1 = require("./ctx");
 Object.defineProperty(exports, "ctx", { enumerable: true, get: function () { return ctx_1.ctx; } });
 var b2b_1 = require("./b2b");
 Object.defineProperty(exports, "linkedinSearch", { enumerable: true, get: function () { return b2b_1.linkedinSearch; } });
 var crunchbase_1 = require("./crunchbase");
 Object.defineProperty(exports, "crunchbaseSearch", { enumerable: true, get: function () { return crunchbase_1.crunchbaseSearch; } });
+var ocean_1 = require("./ocean");
+Object.defineProperty(exports, "executeOcean", { enumerable: true, get: function () { return ocean_1.executeOcean; } });
+Object.defineProperty(exports, "oceanSearchCompanies", { enumerable: true, get: function () { return ocean_1.oceanSearchCompanies; } });
+Object.defineProperty(exports, "oceanSearchPeople", { enumerable: true, get: function () { return ocean_1.oceanSearchPeople; } });
+Object.defineProperty(exports, "OCEAN_OPERATION_IDS", { enumerable: true, get: function () { return ocean_1.OCEAN_OPERATION_IDS; } });
 var serp_1 = require("./serp");
 Object.defineProperty(exports, "webSearch", { enumerable: true, get: function () { return serp_1.webSearch; } });
 Object.defineProperty(exports, "webBatchSearch", { enumerable: true, get: function () { return serp_1.webBatchSearch; } });
@@ -40,11 +48,13 @@ Object.defineProperty(exports, "builtWithSearchByTech", { enumerable: true, get:
 const apify_2 = require("./apify");
 const b2b_2 = require("./b2b");
 const browser_2 = require("./browser");
+const careers_2 = require("./careers");
 const crunchbase_2 = require("./crunchbase");
 const expansion_2 = require("./expansion");
 const firecrawl_2 = require("./firecrawl");
 const generateObject_2 = require("./generateObject");
 const googleMaps_2 = require("./googleMaps");
+const ocean_2 = require("./ocean");
 const predictLeads_2 = require("./predictLeads");
 const serp_2 = require("./serp");
 exports.services = {
@@ -57,7 +67,9 @@ exports.services = {
             enrich: expansion_2.companyLinkedinEnrich,
             search: b2b_2.linkedinSearch
         },
-        getEmployeesFromLinkedin: expansion_2.companyGetEmployeesFromLinkedin
+        getEmployeesFromLinkedin: expansion_2.companyGetEmployeesFromLinkedin,
+        findCareersPage: careers_2.findCareersPage,
+        scrapeCareersPage: careers_2.scrapeCareersPage
     },
     person: {
         linkedin: {
@@ -91,6 +103,12 @@ exports.services = {
     googleMaps: {
         scrape: googleMaps_2.googleMapsScrape
     },
+    ocean: {
+        search: {
+            companies: ocean_2.oceanSearchCompanies,
+            people: ocean_2.oceanSearchPeople
+        }
+    },
     builtWith: {
         lookupDomain: expansion_2.builtWithLookupDomain,
         relationships: expansion_2.builtWithRelationships,

package/dist/ocean.d.ts

@@ -0,0 +1,166 @@
+export declare const OCEAN_OPERATION_IDS: {
+    readonly searchCompanies: "search-companies";
+    readonly searchPeople: "search-people";
+};
+export type OceanOperationId = (typeof OCEAN_OPERATION_IDS)[keyof typeof OCEAN_OPERATION_IDS];
+export interface OceanCompaniesFilters {
+    lookalikeDomains?: string[];
+    minScore?: number;
+    companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
+    countries?: string[];
+    industries?: string[];
+    technologies?: string[];
+    technologyCategories?: string[];
+    keywords?: string[];
+    revenueRanges?: string[];
+    ecommerce?: boolean;
+}
+export interface OceanPeopleFilters {
+    seniorities?: string[];
+    departments?: string[];
+    jobTitleKeywords?: string[];
+    countries?: string[];
+    lookalikePeopleIds?: string[];
+}
+export interface OceanCompaniesSearchParams {
+    companiesFilters?: OceanCompaniesFilters;
+    size?: number;
+    from?: number;
+    searchAfter?: string;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+}
+export interface OceanPhone {
+    country?: string;
+    number: string;
+    primary?: boolean;
+}
+export interface OceanMediaProfile {
+    url?: string;
+    handle?: string;
+    name?: string;
+}
+export interface OceanLocation {
+    primary?: boolean;
+    latitude?: number;
+    longitude?: number;
+    country?: string;
+    locality?: string;
+    region?: string;
+    postalCode?: string;
+    streetAddress?: string;
+    state?: string;
+}
+export interface OceanDepartmentSize {
+    department: string;
+    size: number;
+}
+export interface OceanHeadcountGrowth {
+    threeMonths?: number;
+    threeMonthsPercentage?: number;
+    sixMonths?: number;
+    sixMonthsPercentage?: number;
+    twelveMonths?: number;
+    twelveMonthsPercentage?: number;
+}
+export interface OceanCompanyResult {
+    domain: string;
+    name?: string;
+    legalName?: string;
+    description?: string;
+    countries?: string[];
+    primaryCountry?: string;
+    companySize?: string;
+    industryCategories?: string[];
+    industries?: string[];
+    linkedinIndustry?: string;
+    ecommerce?: boolean;
+    keywords?: string[];
+    employeeCountOcean?: number;
+    employeeCountLinkedin?: number;
+    revenue?: string;
+    yearFounded?: number;
+    emails?: string[];
+    phones?: OceanPhone[];
+    logo?: string;
+    technologies?: string[];
+    technologyCategories?: string[];
+    rootUrl?: string;
+    medias?: Record<string, OceanMediaProfile>;
+    locations?: OceanLocation[];
+    departmentSizes?: OceanDepartmentSize[];
+    headcountGrowth?: OceanHeadcountGrowth;
+    updatedAt?: string;
+}
+export interface OceanCompanyMatch {
+    company: OceanCompanyResult;
+    relevance?: string;
+}
+export interface OceanCompaniesSearchResponse {
+    total: number;
+    searchAfter?: string;
+    companies: OceanCompanyMatch[];
+    redirectMap?: Record<string, string>;
+}
+export interface OceanPersonExperience {
+    dateFrom?: string;
+    dateTo?: string;
+    description?: string;
+    domain?: string;
+    jobTitle?: string;
+}
+export interface OceanContactField {
+    address?: string;
+    status?: string;
+}
+export interface OceanPhoneField {
+    numbers?: string[];
+    status?: string;
+}
+export interface OceanPersonCompanySnapshot {
+    companySize?: string;
+    logo?: string;
+    name?: string;
+}
+export interface OceanPersonResult {
+    id: string;
+    domain?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    country?: string;
+    state?: string;
+    location?: string;
+    linkedinUrl?: string;
+    seniorities?: string[];
+    departments?: string[];
+    photo?: string;
+    jobTitle?: string;
+    jobTitleEnglish?: string;
+    currentJobDescription?: string;
+    experiences?: OceanPersonExperience[];
+    summary?: string;
+    skills?: string[];
+    phone?: OceanPhoneField;
+    email?: OceanContactField;
+    updatedAt?: string;
+    company?: OceanPersonCompanySnapshot;
+}
+export interface OceanPeopleSearchParams {
+    companiesFilters?: OceanCompaniesFilters;
+    peopleFilters?: OceanPeopleFilters;
+    size?: number;
+    from?: number;
+    searchAfter?: string;
+    enableEmailSearch?: boolean;
+    enablePhoneSearch?: boolean;
+}
+export interface OceanPeopleSearchResponse {
+    total: number;
+    searchAfter?: string;
+    people: OceanPersonResult[];
+    redirectMap?: Record<string, string>;
+}
+export declare function executeOcean<T = unknown>(operationId: OceanOperationId, params?: Record<string, unknown>): Promise<T>;
+export declare function oceanSearchCompanies(params: OceanCompaniesSearchParams): Promise<OceanCompaniesSearchResponse>;
+export declare function oceanSearchPeople(params: OceanPeopleSearchParams): Promise<OceanPeopleSearchResponse>;

package/dist/ocean.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OCEAN_OPERATION_IDS = void 0;
+exports.executeOcean = executeOcean;
+exports.oceanSearchCompanies = oceanSearchCompanies;
+exports.oceanSearchPeople = oceanSearchPeople;
+const api_1 = require("./api");
+exports.OCEAN_OPERATION_IDS = {
+    searchCompanies: "search-companies",
+    searchPeople: "search-people"
+};
+async function executeOcean(operationId, params) {
+    return (0, api_1.post)("/execute/oceanio", {
+        operationId,
+        params: params ?? {}
+    });
+}
+async function oceanSearchCompanies(params) {
+    return executeOcean(exports.OCEAN_OPERATION_IDS.searchCompanies, params);
+}
+async function oceanSearchPeople(params) {
+    return executeOcean(exports.OCEAN_OPERATION_IDS.searchPeople, params);
+}

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