orangeslice 2.1.5 → 2.4.0-beta.0

package/docs/services/ocean/search/companies.ts

@@ -1,130 +1,133 @@
 interface OceanCompaniesFilters {
-  /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
-  lookalikeDomains?: string[];
-  /** Minimum similarity score (0-1) for lookalike matching */
-  minScore?: number;
-  /** Company size ranges to filter by */
-  companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
-  /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
-  countries?: string[];
-  /** Industry categories to filter by */
-  industries?: string[];
-  /** Technology names to filter by (e.g., ["React", "Salesforce"]) */
-  technologies?: string[];
-  /** Technology category names to filter by */
-  technologyCategories?: string[];
-  /** Keywords to search for */
-  keywords?: string[];
-  /** Revenue ranges to filter by (e.g., ["0-1M", "1M-10M"]) */
-  revenueRanges?: string[];
-  /** Filter for e-commerce companies */
-  ecommerce?: boolean;
+   /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
+   lookalikeDomains?: string[];
+   /** Company size ranges to filter by */
+   companySizes?: Array<
+      "0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+"
+   >;
+   /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
+   countries?: string[];
+   /** Industry names to filter by */
+   industries?: string[];
+   /** Filter for e-commerce companies */
+   ecommerce?: boolean;
+}
+
+interface OceanPeopleFilters {
+   /** Seniority levels to filter by (e.g., ["C-Level", "VP", "Director", "Manager"]) */
+   seniorities?: string[];
+   /** Departments to filter by (e.g., ["Engineering", "Sales", "Marketing"]) */
+   departments?: string[];
+   /** Job title keywords to search for */
+   jobTitleKeywords?: string[];
+   /** Two-letter country codes to filter by */
+   countries?: string[];
+   /** Array of Ocean.io people IDs to find lookalikes for */
+   lookalikePeopleIds?: string[];
 }
 
 interface OceanCompanyResult {
-  /** Company domain */
-  domain: string;
-  /** Company name */
-  name?: string;
-  /** Legal company name */
-  legalName?: string;
-  /** Company description */
-  description?: string;
-  /** Two-letter country codes where the company operates */
-  countries?: string[];
-  /** Primary country code */
-  primaryCountry?: string;
-  /** Company size range (e.g., "51-200") */
-  companySize?: string;
-  /** Industry categories */
-  industryCategories?: string[];
-  /** Industries */
-  industries?: string[];
-  /** LinkedIn industry classification */
-  linkedinIndustry?: string;
-  /** Whether the company is an e-commerce business */
-  ecommerce?: boolean;
-  /** Company keywords */
-  keywords?: string[];
-  /** Ocean.io employee count estimate */
-  employeeCountOcean?: number;
-  /** LinkedIn employee count */
-  employeeCountLinkedin?: number;
-  /** Revenue range (e.g., "1M-10M") */
-  revenue?: string;
-  /** Year founded */
-  yearFounded?: number;
-  /** Company email addresses */
-  emails?: string[];
-  /** Phone numbers with country and primary flag */
-  phones?: Array<{ country?: string; number: string; primary?: boolean }>;
-  /** Company logo URL */
-  logo?: string;
-  /** Technologies used */
-  technologies?: string[];
-  /** Technology categories */
-  technologyCategories?: string[];
-  /** Company website root URL */
-  rootUrl?: string;
-  /** Social media profiles */
-  medias?: Record<string, { url?: string; handle?: string; name?: string }>;
-  /** Office locations */
-  locations?: Array<{
-    primary?: boolean;
-    latitude?: number;
-    longitude?: number;
-    country?: string;
-    locality?: string;
-    region?: string;
-    postalCode?: string;
-    streetAddress?: string;
-    state?: string;
-  }>;
-  /** Department sizes */
-  departmentSizes?: Array<{ department: string; size: number }>;
-  /** Headcount growth metrics */
-  headcountGrowth?: {
-    threeMonths?: number;
-    threeMonthsPercentage?: number;
-    sixMonths?: number;
-    sixMonthsPercentage?: number;
-    twelveMonths?: number;
-    twelveMonthsPercentage?: number;
-  };
-  /** Last update timestamp */
-  updatedAt?: string;
+   /** Company domain */
+   domain: string;
+   /** Company name */
+   name?: string;
+   /** Legal company name */
+   legalName?: string;
+   /** Company description */
+   description?: string;
+   /** Two-letter country codes where the company operates */
+   countries?: string[];
+   /** Primary country code */
+   primaryCountry?: string;
+   /** Company size range (e.g., "51-200") */
+   companySize?: string;
+   /** Industry categories */
+   industryCategories?: string[];
+   /** Industries */
+   industries?: string[];
+   /** LinkedIn industry classification */
+   linkedinIndustry?: string;
+   /** Whether the company is an e-commerce business */
+   ecommerce?: boolean;
+   /** Company keywords */
+   keywords?: string[];
+   /** Ocean.io employee count estimate */
+   employeeCountOcean?: number;
+   /** LinkedIn employee count */
+   employeeCountLinkedin?: number;
+   /** Revenue range (e.g., "1M-10M") */
+   revenue?: string;
+   /** Year founded */
+   yearFounded?: number;
+   /** Company email addresses */
+   emails?: string[];
+   /** Phone numbers with country and primary flag */
+   phones?: Array<{ country?: string; number: string; primary?: boolean }>;
+   /** Company logo URL */
+   logo?: string;
+   /** Technologies used */
+   technologies?: string[];
+   /** Technology categories */
+   technologyCategories?: string[];
+   /** Company website root URL */
+   rootUrl?: string;
+   /** Social media profiles */
+   medias?: Record<string, { url?: string; handle?: string; name?: string }>;
+   /** Office locations */
+   locations?: Array<{
+      primary?: boolean;
+      latitude?: number;
+      longitude?: number;
+      country?: string;
+      locality?: string;
+      region?: string;
+      postalCode?: string;
+      streetAddress?: string;
+      state?: string;
+   }>;
+   /** Department sizes */
+   departmentSizes?: Array<{ department: string; size: number }>;
+   /** Headcount growth metrics */
+   headcountGrowth?: {
+      threeMonths?: number;
+      threeMonthsPercentage?: number;
+      sixMonths?: number;
+      sixMonthsPercentage?: number;
+      twelveMonths?: number;
+      twelveMonthsPercentage?: number;
+   };
+   /** Last update timestamp */
+   updatedAt?: string;
 }
 
 /**
  * Search for lookalike companies using Ocean.io.
  * Provide seed domains via companiesFilters.lookalikeDomains to find similar companies.
- * Filter by size, country, industry, technology, revenue, and more.
- * Returns up to `size` companies per call (default 10). Use `searchAfter` for pagination.
+ * Verified v3 filters: companySizes, countries, industries, ecommerce, and top-level peopleFilters.
+ * Use `searchAfter` for pagination. Do not send `from`, `includeDomains`, `excludeDomains`, or `minScore` because Ocean v3 rejects them with 422 errors.
  */
 type companies = (params: {
-    /** Filters for company search (lookalike domains, size, country, industry, etc.) */
-    companiesFilters?: OceanCompaniesFilters;
-    /** Number of results to return (default 10, max 100) */
-    size?: number;
-    /** Pagination offset (use searchAfter for cursor-based pagination instead) */
-    from?: number;
-    /** Cursor token from a previous response for efficient pagination */
-    searchAfter?: string;
-    /** Domains to always include in results */
-    includeDomains?: string[];
-    /** Domains to exclude from results */
-    excludeDomains?: string[];
-  }) => Promise<{
-  /** Total matching companies */
-  total: number;
-  /** Cursor for next page (pass as searchAfter) */
-  searchAfter?: string;
-  /** Matched companies with relevance scores */
-  companies: Array<{
-    company: OceanCompanyResult;
-    /** Relevance grade (A = best match) */
-    relevance?: string;
-  }>;
-  /** Domains that were redirected to canonical domains */
-  redirectMap?: Record<string, string>;
-}>;
+   /** Filters for company search (lookalike domains, size, country, industry, ecommerce) */
+   companiesFilters?: OceanCompaniesFilters;
+   /** Optional people filters. Returns companies that have at least one matching person. */
+   peopleFilters?: OceanPeopleFilters;
+   /** Number of results to return (default 10, max 100) */
+   size?: number;
+   /** Cursor token from a previous response for efficient pagination */
+   searchAfter?: string;
+}) => Promise<{
+   /** Ocean.io status detail (typically "OK") */
+   detail?: string;
+   /** Total matching companies */
+   total: number;
+   /** Cursor for next page (pass as searchAfter) */
+   searchAfter?: string;
+   /** Matched companies with relevance scores */
+   companies: Array<{
+      company: OceanCompanyResult;
+      /** Relevance grade (A = best match) */
+      relevance?: string;
+   }>;
+   /** Domains that were redirected to canonical domains */
+   redirectMap?: Record<string, string>;
+}>;

package/docs/services/person/linkedin/findUrl.md

@@ -1,4 +1,4 @@
-/\*_ Credits: 2 for the name + company search path, or 50 when reverse-email lookup is used. Charged only if a valid URL is returned. _/
+/\*_ Credits: 2 for the search path, or 50 when reverse-email lookup is used. Charged only if a valid URL is returned. _/
 
 /\*\*
 
@@ -15,6 +15,6 @@
   keyword?: string;
   /\*_ Location string (e.g., city, state, country) to narrow search results _/
   location?: string;
-  /\*_ Email address. If provided, the service tries name + company search first when possible, then falls back to reverse-email lookup. _/
+  /\*_ Email address. For work emails, the service may infer the name from the email, try search with that + the email domain, validate the result against B2B current-company domain data, then fall back to reverse-email lookup. _/
   email?: string;
   }) => Promise<string | undefined>;

package/docs/services/predictLeads/companyJobOpenings.ts

@@ -1,102 +1,176 @@
 /**
  * Retrieve company's Job Openings
  * Returns a list of company's Job Openings.
+ *
+ * Use this as a prospecting/enrichment signal, not as source-of-truth validation
+ * that a known company is currently hiring. For current validation, prefer the
+ *
+ * company's official careers page / ATS via services.company.findCareersPage and
+ * services.company.scrapeCareersPage.
  * HTTP GET /companies/{company_id_or_domain}/job_openings
  */
 type companyJobOpenings = (params: {
-  /** Company's ID or domain. */
-  company_id_or_domain: string;
-  /** Set to true if you'd like to receive JobOpenings that are not closed, have last_seen_at more recent than 5 days and were found in the last year. */
-  active_only?: boolean;
-  /** Similar to `active_only`, but without considering `last_seen_at` timestamp. */
-  not_closed?: boolean;
-  /** Only return `JobOpenings` first seen after given date (ISO 8601). */
-  first_seen_at_from?: string;
-  /** Only return `JobOpenings` first seen before given date (ISO 8601). */
-  first_seen_at_until?: string;
-  /** Only return `JobOpenings` last seen after given date (ISO 8601). */
-  last_seen_at_from?: string;
-  /** Only return `JobOpenings` last seen before given date (ISO 8601). */
-  last_seen_at_until?: string;
-  /** Only return JobOpenings that have description. */
-  with_description_only?: boolean;
-  /** Only return JobOpenings that have location. */
-  with_location_only?: boolean;
-  /** Comma-separated (,) `JobOpening` categories. */
-  categories?: Array<"administration" | "consulting" | "data_analysis" | "design" | "directors" | "education" | "engineering" | "finance" | "healthcare_services" | "human_resources" | "information_technology" | "internship" | "legal" | "management" | "marketing" | "military_and_protective_services" | "operations" | "purchasing" | "product_management" | "quality_assurance" | "real_estate" | "research" | "sales" | "software_development" | "support" | "manual_work" | "food">;
-  /** Page number of shown items. **NOTE**: If the parameter is not provided, the meta property `count` will be omitted from response for performance reasons. */
-  page?: number;
-  /** Limit the number of shown items per page. */
-  limit?: number;
+   /** Company's ID or domain. */
+   company_id_or_domain: string;
+   /** Set to true if you'd like to receive JobOpenings that are not closed, have last_seen_at more recent than 5 days and were found in the last year. */
+   active_only?: boolean;
+   /** Similar to `active_only`, but without considering `last_seen_at` timestamp. */
+   not_closed?: boolean;
+   /** Only return `JobOpenings` first seen after given date (ISO 8601). */
+   first_seen_at_from?: string;
+   /** Only return `JobOpenings` first seen before given date (ISO 8601). */
+   first_seen_at_until?: string;
+   /** Only return `JobOpenings` last seen after given date (ISO 8601). */
+   last_seen_at_from?: string;
+   /** Only return `JobOpenings` last seen before given date (ISO 8601). */
+   last_seen_at_until?: string;
+   /** Only return JobOpenings that have description. */
+   with_description_only?: boolean;
+   /** Only return JobOpenings that have location. */
+   with_location_only?: boolean;
+   /** Comma-separated (,) `JobOpening` categories. */
+   categories?: Array<
+      | "administration"
+      | "consulting"
+      | "data_analysis"
+      | "design"
+      | "directors"
+      | "education"
+      | "engineering"
+      | "finance"
+      | "healthcare_services"
+      | "human_resources"
+      | "information_technology"
+      | "internship"
+      | "legal"
+      | "management"
+      | "marketing"
+      | "military_and_protective_services"
+      | "operations"
+      | "purchasing"
+      | "product_management"
+      | "quality_assurance"
+      | "real_estate"
+      | "research"
+      | "sales"
+      | "software_development"
+      | "support"
+      | "manual_work"
+      | "food"
+   >;
+   /** Page number of shown items. **NOTE**: If the parameter is not provided, the meta property `count` will be omitted from response for performance reasons. */
+   page?: number;
+   /** Limit the number of shown items per page. */
+   limit?: number;
 }) => Promise<{
-  data: Array<{
-  id: string;
-  type: "job_opening";
-  attributes: {
-  title: string;
-  description: string | null;
-  url: string;
-  first_seen_at: string;
-  last_seen_at: string;
-  last_processed_at: string;
-  contract_types: Array<Record<string, unknown>>;
-  categories: Array<"administration" | "consulting" | "data_analysis" | "design" | "directors" | "education" | "engineering" | "finance" | "healthcare_services" | "human_resources" | "information_technology" | "internship" | "legal" | "management" | "marketing" | "military_and_protective_services" | "operations" | "purchasing" | "product_management" | "quality_assurance" | "real_estate" | "research" | "sales" | "software_development" | "support" | "manual_work" | "food">;
-  onet_data: {
-  code: string | null;
-  family: string | null;
-  occupation_name: string | null;
-};
-  posted_at: string | null;
-  recruiter_data: {
-  name: string | null;
-  title: string | null;
-  contact: string | null;
-};
-  salary: string | null;
-  salary_data: {
-  salary_low: number | null;
-  salary_high: number | null;
-  salary_currency: string | null;
-  salary_low_usd: number | null;
-  salary_high_usd: number | null;
-  salary_time_unit: "hour" | "day" | "week" | "month" | "year" | null;
-};
-  seniority: "not_set" | "founder" | "c_level" | "partner" | "president" | "vice_president" | "head" | "director" | "manager" | "mid_senior" | "junior" | "non_manager";
-  status: "closed" | null;
-  language: string | null;
-  location: string | null;
-  location_data: Array<{
-  city: unknown;
-  state: unknown;
-  zip_code: unknown;
-  country: unknown;
-  region: unknown;
-  continent: unknown;
-  fuzzy_match: unknown;
+   data: Array<{
+      id: string;
+      type: "job_opening";
+      attributes: {
+         title: string;
+         description: string | null;
+         url: string;
+         first_seen_at: string;
+         last_seen_at: string;
+         last_processed_at: string;
+         contract_types: Array<Record<string, unknown>>;
+         categories: Array<
+            | "administration"
+            | "consulting"
+            | "data_analysis"
+            | "design"
+            | "directors"
+            | "education"
+            | "engineering"
+            | "finance"
+            | "healthcare_services"
+            | "human_resources"
+            | "information_technology"
+            | "internship"
+            | "legal"
+            | "management"
+            | "marketing"
+            | "military_and_protective_services"
+            | "operations"
+            | "purchasing"
+            | "product_management"
+            | "quality_assurance"
+            | "real_estate"
+            | "research"
+            | "sales"
+            | "software_development"
+            | "support"
+            | "manual_work"
+            | "food"
+         >;
+         onet_data: {
+            code: string | null;
+            family: string | null;
+            occupation_name: string | null;
+         };
+         posted_at: string | null;
+         recruiter_data: {
+            name: string | null;
+            title: string | null;
+            contact: string | null;
+         };
+         salary: string | null;
+         salary_data: {
+            salary_low: number | null;
+            salary_high: number | null;
+            salary_currency: string | null;
+            salary_low_usd: number | null;
+            salary_high_usd: number | null;
+            salary_time_unit: "hour" | "day" | "week" | "month" | "year" | null;
+         };
+         seniority:
+            | "not_set"
+            | "founder"
+            | "c_level"
+            | "partner"
+            | "president"
+            | "vice_president"
+            | "head"
+            | "director"
+            | "manager"
+            | "mid_senior"
+            | "junior"
+            | "non_manager";
+         status: "closed" | null;
+         language: string | null;
+         location: string | null;
+         location_data: Array<{
+            city: unknown;
+            state: unknown;
+            zip_code: unknown;
+            country: unknown;
+            region: unknown;
+            continent: unknown;
+            fuzzy_match: unknown;
+         }>;
+         tags: Array<Record<string, unknown>>;
+      };
+      relationships: {
+         company: {
+            data: {
+               id: string;
+               type: "company";
+            };
+         };
+      };
+   }>;
+   included: Array<{
+      id: string;
+      type: "company";
+      attributes: {
+         domain: string;
+         company_name: string | null;
+         ticker: string | null;
+      };
+   }>;
+   meta?: {
+      schema_version: string;
+      record_state: "active";
+      count?: number;
+   };
 }>;
-  tags: Array<Record<string, unknown>>;
-};
-  relationships: {
-  company: {
-  data: {
-  id: string;
-  type: "company";
-};
-};
-};
-}>;
-  included: Array<{
-  id: string;
-  type: "company";
-  attributes: {
-  domain: string;
-  company_name: string | null;
-  ticker: string | null;
-};
-}>;
-  meta?: {
-  schema_version: string;
-  record_state: "active";
-  count?: number;
-};
-}>;

package/docs/services/skills/index.md

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