@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/search.d.ts

@@ -0,0 +1,598 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.search` (Search): 19 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"delete_saved_search_search_saved_searches__query_id__delete">;
+ *
+ * Reference with examples: search.md
+ */
+/* eslint-disable */
+
+/** `g8.api.search.<member>` -> the operationId it calls. */
+export interface SearchMembers {
+  deleteSavedSearch: "delete_saved_search_search_saved_searches__query_id__delete";
+  getAutocompleteSuggestions: "get_autocomplete_suggestions_search_autocomplete_get";
+  getFilterOptions: "get_filter_options_search_filter_options_get";
+  getFilteredFilterOptions: "get_filtered_filter_options_search_filter_options_post";
+  getSearchSignalOptions: "get_search_signal_options_search_signals_options_get";
+  listIntentTopics: "list_intent_topics_search_filter_options_intent_topics_get";
+  listSavedSearches: "list_saved_searches_search_saved_searches_get";
+  listWorkspaceSearchSections: "list_workspace_search_sections_search_workspace_sections_get";
+  previewSearchSignal: "preview_search_signal_search_signals_preview_post";
+  saveCompanySearch: "save_company_search_search_companies_save_post";
+  saveContactSearch: "save_contact_search_search_contacts_save_post";
+  saveSearch: "save_search_search_saved_searches_post";
+  searchCompanies: "search_companies_search_companies_post";
+  searchContacts: "search_contacts_search_contacts_post";
+  searchCrmEntities: "search_crm_entities_search_entities_get";
+  searchWorkspaceDocuments: "search_workspace_documents_search_workspace_post";
+  searchWorkspaceGlobal: "search_workspace_global_search_global_get";
+  suggestSearchSignalTech: "suggest_search_signal_tech_search_signals_tech_get";
+  suggestWorkspaceSearch: "suggest_workspace_search_search_workspace_suggest_post";
+}
+
+/** Input and output of every `g8.api.search` operation, keyed by operationId. */
+export interface SearchOperations {
+  /**
+   * DELETE /search/saved-searches/{query_id}
+   * Delete Saved Search
+   * tier: destructive · scope: search:delete
+   */
+  delete_saved_search_search_saved_searches__query_id__delete: {
+    input: {
+    path: {
+      /** Saved-search id. */
+      query_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SearchDiscoveryPayload_;
+  };
+  /**
+   * GET /search/autocomplete
+   * Get Autocomplete Suggestions
+   * tier: read · scope: search:read
+   */
+  get_autocomplete_suggestions_search_autocomplete_get: {
+    input: {
+    query: {
+      /** Which vocabulary `field` is in. */
+      resource: "contacts" | "companies";
+      /** Developer field name to search within. */
+      field: string;
+      /** What the person has typed so far. */
+      value: string;
+      /** How many suggestions to return. */
+      size?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SearchDiscoveryPayload_;
+  };
+  /**
+   * GET /search/filter-options
+   * Get Filter Options
+   * tier: read · scope: search:read
+   */
+  get_filter_options_search_filter_options_get: {
+    input: {
+    query: {
+      /** Which vocabulary the field names are in. */
+      resource: "contacts" | "companies";
+      /** Developer field names, REPEATABLE (`?fields=company_industry&fields=seniority_level`). The same names `POST /search/{resource}` takes. */
+      fields: Array<string>;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__list_FilterOptionItem___;
+  };
+  /**
+   * POST /search/filter-options
+   * Get Filtered Filter Options
+   * tier: read · scope: search:read
+   */
+  get_filtered_filter_options_search_filter_options_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FilterOptionsRequest;
+  };
+    output: ApiResponse_dict_str__list_FilterOptionItem___;
+  };
+  /**
+   * GET /search/signals/options
+   * Get Search Signal Options
+   * tier: read · scope: search:read
+   */
+  get_search_signal_options_search_signals_options_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+  /**
+   * GET /search/filter-options/intent-topics
+   * List Intent Topics
+   * tier: read · scope: search:read
+   */
+  list_intent_topics_search_filter_options_intent_topics_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_;
+  };
+  /**
+   * GET /search/saved-searches
+   * List Saved Searches
+   * tier: read · scope: search:read
+   */
+  list_saved_searches_search_saved_searches_get: {
+    input: {
+    query?: {
+      /** Only saved searches over this resource, e.g. `contacts`. */
+      scope?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_;
+  };
+  /**
+   * GET /search/workspace/sections
+   * List Workspace Search Sections
+   * tier: read · scope: search:read
+   */
+  list_workspace_search_sections_search_workspace_sections_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchListPayload_;
+  };
+  /**
+   * POST /search/signals/preview
+   * Preview Search Signal
+   * tier: read · scope: search:read
+   */
+  preview_search_signal_search_signals_preview_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SearchSignalFilter;
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+  /**
+   * POST /search/companies/save
+   * Save Company Search
+   * tier: billable · scope: search:run
+   */
+  save_company_search_search_companies_save_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SearchSaveRequest;
+  };
+    output: ApiResponse_SearchSaveResponse_;
+  };
+  /**
+   * POST /search/contacts/save
+   * Save Contact Search
+   * tier: billable · scope: search:run
+   */
+  save_contact_search_search_contacts_save_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SearchSaveRequest;
+  };
+    output: ApiResponse_SearchSaveResponse_;
+  };
+  /**
+   * POST /search/saved-searches
+   * Save Search
+   * tier: write · scope: search:write
+   */
+  save_search_search_saved_searches_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SaveSearchRequest;
+  };
+    output: ApiResponse_SearchDiscoveryPayload_;
+  };
+  /**
+   * POST /search/companies
+   * Search Companies
+   * tier: billable · scope: search:run
+   */
+  search_companies_search_companies_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SearchRequest;
+  };
+    output: ApiResponse_list_SearchCompanyItem__;
+  };
+  /**
+   * POST /search/contacts
+   * Search Contacts
+   * tier: billable · scope: search:run
+   */
+  search_contacts_search_contacts_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SearchRequest;
+  };
+    output: ApiResponse_list_SearchContactItem__;
+  };
+  /**
+   * GET /search/entities
+   * Search Crm Entities
+   * tier: read · scope: search:read
+   */
+  search_crm_entities_search_entities_get: {
+    input: {
+    query: {
+      q: string;
+      /** Comma-separated: companies,contacts,deals. */
+      types?: string | null;
+      /** Only records in this lifecycle stage. */
+      lifecycle?: string | null;
+      /** Results per record type. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+  /**
+   * POST /search/workspace
+   * Search Workspace Documents
+   * tier: read · scope: search:read
+   */
+  search_workspace_documents_search_workspace_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: WorkspaceSearchRequest;
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+  /**
+   * GET /search/global
+   * Search Workspace Global
+   * tier: read · scope: search:read
+   */
+  search_workspace_global_search_global_get: {
+    input: {
+    query: {
+      q: string;
+      /** Results per category. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+  /**
+   * GET /search/signals/tech
+   * Suggest Search Signal Tech
+   * tier: read · scope: search:read
+   */
+  suggest_search_signal_tech_search_signals_tech_get: {
+    input: {
+    query: {
+      q: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchListPayload_;
+  };
+  /**
+   * POST /search/workspace/suggest
+   * Suggest Workspace Search
+   * tier: read · scope: search:read
+   */
+  suggest_workspace_search_search_workspace_suggest_post: {
+    input: {
+    query: {
+      /** What has been typed so far. */
+      query: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_WorkspaceSearchPayload_;
+  };
+}
+
+// 24 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_SearchDiscoveryPayload_ {
+  data: SearchDiscoveryPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_SearchSaveResponse_ {
+  data: SearchSaveResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_WorkspaceSearchListPayload_ {
+  data: WorkspaceSearchListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_WorkspaceSearchPayload_ {
+  data: WorkspaceSearchPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_str__list_FilterOptionItem___ {
+  data: Record<string, Array<FilterOptionItem>>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ {
+  data: Array<unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_SearchCompanyItem__ {
+  data: Array<SearchCompanyItem>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_SearchContactItem__ {
+  data: Array<SearchContactItem>;
+  pagination?: PaginationMeta | null;
+}
+
+/** One distinct value a field can hold. */
+export interface FilterOptionItem {
+  /** Other spellings a person might type (`USA`, `UK`). */
+  aliases?: Array<string> | null;
+  /** Records carrying this value, when the backend computed it. */
+  count?: number | null;
+  /** Normalised value - this is what you send back as a filter value. */
+  id: string;
+  /** The value as it is spelled in the data, for display. */
+  label: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Ask what values a set of fields holds, narrowed by a search.
+ *
+ * Mirrors the app's `FilteredFilterOptionsRequest` in substance - `fields`
+ * plus an ICP query - but in the PUBLISHED vocabulary.
+ *
+ * It SUBCLASSES the published `SearchRequest` rather than restating its
+ * fields, so `filters`, `page` and `limit` cannot drift away from the search
+ * they are meant to describe: a body that works against
+ * `POST /search/contacts` works here with two fields added.
+ *
+ * `filters` must be non-empty. That is not this contract being fussy - it is
+ * the same refusal `POST /search/contacts` makes, because an unfiltered
+ * request scans the entire open-data index.
+ */
+export interface FilterOptionsRequest {
+  /** Developer field names, as used by `POST /search/{resource}`. */
+  fields: Array<string>;
+  /** Filter conditions (AND logic) */
+  filters?: Array<SearchFilter>;
+  /** Results per page (max 100) */
+  limit?: number;
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Which index the field names belong to. Decides the vocabulary. */
+  resource: "contacts" | "companies";
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * Store a search so a person can run it again later.
+ *
+ * `icp_query` is OPAQUE and round-tripped verbatim: the app stores it as a
+ * plain JSON blob and does not interpret it at save time, so this contract
+ * does not either. That is also why it is the one place here that does not
+ * go through the field map - translating a blob nobody reads would change
+ * what the caller gets back.
+ *
+ * `id` present means UPDATE the saved search rather than create a new one.
+ */
+export interface SaveSearchRequest {
+  /** The search itself. Opaque and round-tripped as-is. */
+  icp_query: Record<string, unknown>;
+  /** Send the id of an existing saved search to REPLACE it. */
+  id?: number | null;
+  /** What the saved search is over - `contacts` or `companies` today. Deliberately a free string rather than a closed enum, matching the app, which is designed to add more. */
+  scope: string;
+  title: string;
+}
+
+/** Company result from open data search. */
+export interface SearchCompanyItem {
+  address?: string | null;
+  city?: string | null;
+  country?: string | null;
+  crunchbase_url?: string | null;
+  description?: string | null;
+  domain?: string | null;
+  employee_count?: string | null;
+  facebook_url?: string | null;
+  founded_year?: number | null;
+  industry?: string | null;
+  industry_group?: string | null;
+  linkedin_followers?: string | null;
+  linkedin_url?: string | null;
+  logo_url?: string | null;
+  name?: string | null;
+  phone?: string | null;
+  revenue?: string | null;
+  state?: string | null;
+  twitter_url?: string | null;
+  website?: string | null;
+  zip?: number | null;
+}
+
+/** Contact result from open data search. */
+export interface SearchContactItem {
+  city?: string | null;
+  company_country?: string | null;
+  company_domain?: string | null;
+  company_employee_count?: string | null;
+  company_industry?: string | null;
+  company_name?: string | null;
+  confidence_score?: number | null;
+  country?: string | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_headline?: string | null;
+  linkedin_url?: string | null;
+  middle_name?: string | null;
+  mobile_phone?: string | null;
+  personal_emails?: string | null;
+  role?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  work_email?: string | null;
+}
+
+/** An open envelope for an autocomplete or filter-option result. */
+export type SearchDiscoveryPayload = Record<string, unknown>;
+
+/** A single filter condition. */
+export interface SearchFilter {
+  /** Field name to filter on (e.g., 'job_title', 'country', 'industry') */
+  field: string;
+  /** Filter operator */
+  operator: SearchOperator;
+  /** Filter values */
+  value?: Array<unknown>;
+}
+
+/** Supported filter operators for search queries. */
+export type SearchOperator = "any_of" | "contains" | "all_of" | "none_of" | "is_empty" | "is_not_empty" | "between" | "exists";
+
+/** Request body for search endpoints. */
+export interface SearchRequest {
+  /** Filter conditions (AND logic) */
+  filters?: Array<SearchFilter>;
+  /** Results per page (max 100) */
+  limit?: number;
+  /** Page number (1-indexed) */
+  page?: number;
+}
+
+/** Request to search and save results to a list. */
+export interface SearchSaveRequest {
+  /** Filter conditions (AND logic) */
+  filters?: Array<SearchFilter>;
+  /** Results per page (max 100) */
+  limit?: number;
+  /** Title for the new list */
+  list_title: string;
+  /** Maximum results to save (max 10,000) */
+  max_results?: number;
+  /** Page number (1-indexed) */
+  page?: number;
+}
+
+/** Response from save-to-list endpoints. */
+export interface SearchSaveResponse {
+  estimated_total: number;
+  list_id: number;
+  list_title: string;
+  status?: string;
+}
+
+/** One signal. Which list must be non-empty depends on `type`. */
+export interface SearchSignalFilter {
+  /** company_type: category ids. */
+  categories?: Array<string>;
+  /** hiring / new_in_role: look-back window. */
+  days?: number;
+  /** lookalike: seed company domains. */
+  domains?: Array<string>;
+  exclude_staffing?: boolean;
+  facet?: "what" | "sells" | "serves";
+  match?: "any" | "all";
+  min_roles?: number;
+  /** Match companies WITHOUT the signal (hiring, tech, company_type). */
+  negate?: boolean;
+  /** hiring: role titles. */
+  roles?: Array<string>;
+  status?: "new" | "open";
+  /** tech: technologies. */
+  techs?: Array<string>;
+  /** describes: what the companies do. */
+  text?: string;
+  top_k?: number;
+  type: "hiring" | "tech" | "company_type" | "describes" | "lookalike" | "new_in_role";
+}
+
+/** A list result under `items`. */
+export interface WorkspaceSearchListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** Search results, grouped the way the app groups them. */
+export type WorkspaceSearchPayload = Record<string, unknown>;
+
+export interface WorkspaceSearchRequest {
+  filters?: Record<string, unknown> | null;
+  /** How many results. */
+  k?: number;
+  query: string;
+  /** `auto` picks keyword or semantic from the wording of the query. */
+  search_type?: "semantic" | "exact" | "hybrid" | "auto";
+}