@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/intent.d.ts

@@ -0,0 +1,482 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.intent` (Intent): 16 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"intent_stats_intent_stats_get">;
+ *
+ * Reference with examples: intent.md
+ */
+/* eslint-disable */
+
+/** `g8.api.intent.<member>` -> the operationId it calls. */
+export interface IntentMembers {
+  intentStats: "intent_stats_intent_stats_get";
+  keywordCompanies: "keyword_companies_intent_keywords__keyword_id__companies_post";
+  keywordContacts: "keyword_contacts_intent_keywords__keyword_id__contacts_post";
+  keywordUpdateFilters: "keyword_update_filters_intent_keywords__keyword_id__filters_post";
+  keywordUrls: "keyword_urls_intent_keywords__keyword_id__urls_post";
+  keywordsAdd: "keywords_add_intent_keywords_add_post";
+  keywordsCreateFromDomain: "keywords_create_from_domain_intent_keywords_create_from_domain_post";
+  keywordsCreateFromSearch: "keywords_create_from_search_intent_keywords_create_from_search_post";
+  keywordsDelete: "keywords_delete_intent_keywords__keyword_id__delete";
+  keywordsList: "keywords_list_intent_keywords_list_post";
+  pagesByDomain: "pages_by_domain_intent_pages_by_domain_post";
+  pagesContacts: "pages_contacts_intent_pages_contacts_post";
+  pagesSearch: "pages_search_intent_pages_search_post";
+  pagesVisitorCounts: "pages_visitor_counts_intent_pages_visitor_counts_post";
+  pagesVisitors: "pages_visitors_intent_pages_visitors_post";
+  urlCompanies: "url_companies_intent_url_companies_post";
+}
+
+/** Input and output of every `g8.api.intent` operation, keyed by operationId. */
+export interface IntentOperations {
+  /**
+   * GET /intent/stats
+   * Intent Stats
+   * tier: read · scope: intent:read
+   */
+  intent_stats_intent_stats_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/{keyword_id}/companies
+   * Keyword Companies
+   * tier: billable · scope: intent:run
+   */
+  keyword_companies_intent_keywords__keyword_id__companies_post: {
+    input: {
+    path: {
+      keyword_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordDetailRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/{keyword_id}/contacts
+   * Keyword Contacts
+   * tier: billable · scope: intent:run
+   */
+  keyword_contacts_intent_keywords__keyword_id__contacts_post: {
+    input: {
+    path: {
+      keyword_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordDetailRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/{keyword_id}/filters
+   * Keyword Update Filters
+   * tier: billable · scope: intent:run
+   */
+  keyword_update_filters_intent_keywords__keyword_id__filters_post: {
+    input: {
+    path: {
+      keyword_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordFiltersUpdateRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/{keyword_id}/urls
+   * Keyword Urls
+   * tier: billable · scope: intent:run
+   */
+  keyword_urls_intent_keywords__keyword_id__urls_post: {
+    input: {
+    path: {
+      keyword_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordDetailRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/add
+   * Keywords Add
+   * tier: billable · scope: intent:run
+   */
+  keywords_add_intent_keywords_add_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordsAddRequest;
+  };
+    output: ApiResponse_KeywordsAddResponse_;
+  };
+  /**
+   * POST /intent/keywords/create-from-domain
+   * Keywords Create From Domain
+   * tier: billable · scope: intent:run
+   */
+  keywords_create_from_domain_intent_keywords_create_from_domain_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordCreateFromDomainRequest;
+  };
+    output: ApiResponse_KeywordCreateFromDomainResponse_;
+  };
+  /**
+   * POST /intent/keywords/create-from-search
+   * Keywords Create From Search
+   * tier: billable · scope: intent:run
+   */
+  keywords_create_from_search_intent_keywords_create_from_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordsCreateFromSearchRequest;
+  };
+    output: ApiResponse_KeywordsCreateFromSearchResponse_;
+  };
+  /**
+   * DELETE /intent/keywords/{keyword_id}
+   * Keywords Delete
+   * tier: destructive · scope: intent:delete
+   */
+  keywords_delete_intent_keywords__keyword_id__delete: {
+    input: {
+    path: {
+      /** Keyword row UUID. */
+      keyword_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/keywords/list
+   * Keywords List
+   * tier: billable · scope: intent:run
+   */
+  keywords_list_intent_keywords_list_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: KeywordsListRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/pages-by-domain
+   * Pages By Domain
+   * tier: billable · scope: intent:run
+   */
+  pages_by_domain_intent_pages_by_domain_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PagesByDomainRequest;
+  };
+    output: ApiResponse_PagesByDomainResponse_;
+  };
+  /**
+   * POST /intent/pages/contacts
+   * Pages Contacts
+   * tier: billable · scope: intent:run
+   */
+  pages_contacts_intent_pages_contacts_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PagesContactsRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/pages/search
+   * Pages Search
+   * tier: billable · scope: intent:run
+   */
+  pages_search_intent_pages_search_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PagesSearchRequest;
+  };
+    output: ApiResponse_PagesSearchResponse_;
+  };
+  /**
+   * POST /intent/pages/visitor-counts
+   * Pages Visitor Counts
+   * tier: billable · scope: intent:run
+   */
+  pages_visitor_counts_intent_pages_visitor_counts_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PagesVisitorCountsRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/pages/visitors
+   * Pages Visitors
+   * tier: billable · scope: intent:run
+   */
+  pages_visitors_intent_pages_visitors_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PagesVisitorsRequest;
+  };
+    output: unknown;
+  };
+  /**
+   * POST /intent/url-companies
+   * Url Companies
+   * tier: read · scope: intent:read
+   */
+  url_companies_intent_url_companies_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UrlCompaniesRequest;
+  };
+    output: unknown;
+  };
+}
+
+// 27 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_KeywordCreateFromDomainResponse_ {
+  data: KeywordCreateFromDomainResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_KeywordsAddResponse_ {
+  data: KeywordsAddResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_KeywordsCreateFromSearchResponse_ {
+  data: KeywordsCreateFromSearchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PagesByDomainResponse_ {
+  data: PagesByDomainResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_PagesSearchResponse_ {
+  data: PagesSearchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface IntentPageItem {
+  audience?: string | null;
+  commercial_score?: number | null;
+  domain_root?: string | null;
+  mention_score?: number | null;
+  page_type?: string | null;
+  summary?: string | null;
+  title?: string | null;
+  url?: string | null;
+}
+
+export interface KeywordAddedItem {
+  created_at?: string | null;
+  id: string;
+  /** Stored (lowercased) keyword text. */
+  keyword: string;
+  signal_type: string;
+}
+
+export interface KeywordCreateFromDomainRequest {
+  /** Max contacts to pre-resolve. */
+  contact_limit?: number;
+  /** Competitor domain to track, e.g. 'cognism.com'. */
+  domain: string;
+  /** Max pages to seed from the domain. */
+  page_limit?: number;
+}
+
+export interface KeywordCreateFromDomainResponse {
+  companies_seeded?: number;
+  contacts_seeded?: number;
+  keyword: string;
+  keyword_id?: string | null;
+  message?: string;
+  off_domain_rejected?: number;
+  pages_seeded?: number;
+}
+
+export interface KeywordCreateFromSearchItem {
+  companies_seeded?: number;
+  contacts_seeded?: number;
+  error?: string | null;
+  keyword: string;
+  keyword_id?: string | null;
+  pages_seeded?: number;
+  /** 'created' | 'skipped' | 'error' */
+  status: string;
+}
+
+export interface KeywordDetailRequest {
+  /** Optional `[{field, operator, value}]` filter conditions. */
+  conditions?: Array<Record<string, unknown>>;
+  limit?: number;
+  page?: number;
+}
+
+export interface KeywordFiltersUpdateRequest {
+  /** Full-replacement `search_filters` JSON. Typed fields in `intent.domain.models.keyword.KeywordSearchFilters`: audience, exclude_page_types, min_commercial_intent_level, max_urls_per_domain, llm_triage, exclude_domains. Extra keys allowed. */
+  search_filters: Record<string, unknown>;
+}
+
+export interface KeywordsAddRequest {
+  /** 1-50 keyword phrases to add as plain compete-tracking rows. Stored lowercased. Empty / whitespace-only entries and in-request duplicates (case-insensitive, trimmed) are skipped, not saved twice. */
+  keywords: Array<string>;
+  /** Signal source discriminator, same vocabulary as the web UI: 'intent' (default, buyer-intent tracking), 'jobs', or 'job_changes'. */
+  signal_type?: "intent" | "jobs" | "job_changes";
+}
+
+export interface KeywordsAddResponse {
+  created?: Array<KeywordAddedItem>;
+  created_count?: number;
+  skipped?: Array<KeywordsAddSkippedItem>;
+  skipped_count?: number;
+}
+
+export interface KeywordsAddSkippedItem {
+  keyword: string;
+  /** 'empty' | 'duplicate_in_request' | 'already_exists' */
+  reason: string;
+}
+
+export interface KeywordsCreateFromSearchRequest {
+  /** Max contacts to pre-resolve per keyword. */
+  contact_limit?: number;
+  /** 1-10 free-text keyword queries. Each is searched against the intent page index, contacts/companies are resolved, and a compete-tracking keyword row is saved. Duplicates within the request (case-insensitive, trimmed) are skipped, not re-saved. */
+  keywords: Array<string>;
+  /** Max pages to seed per keyword. Deliberately smaller than create-from-domain's 200 default since this runs once per keyword. */
+  page_limit?: number;
+  /** Optional intent-search filters applied to EVERY keyword in the batch (audience, page_type, commercial_score_min, etc.). Stored verbatim on each saved keyword row so the daily resolver replays them. */
+  search_filters?: Record<string, unknown> | null;
+  /** 0 = text search (default, cheapest), 1 = semantic, between = hybrid. */
+  semantic_ratio?: number;
+}
+
+export interface KeywordsCreateFromSearchResponse {
+  created_count?: number;
+  error_count?: number;
+  results?: Array<KeywordCreateFromSearchItem>;
+  skipped_count?: number;
+}
+
+export interface KeywordsListRequest {
+  /** Case-insensitive keyword substring filter. */
+  keyword_contains?: string | null;
+  limit?: number;
+  page?: number;
+}
+
+export interface PagesByDomainRequest {
+  /** Competitor root domain. Subdomains auto-matched. */
+  domain: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface PagesByDomainResponse {
+  domain: string;
+  pages?: Array<IntentPageItem>;
+  took_ms?: number;
+  total_hits?: number;
+}
+
+export interface PagesContactsRequest {
+  limit?: number;
+  mode?: string;
+  offset?: number;
+  urls: Array<string>;
+}
+
+export interface PagesSearchRequest {
+  filters?: Record<string, unknown> | null;
+  include_visitors?: boolean;
+  limit?: number;
+  offset?: number;
+  query: string;
+  /** 0 = text, 1 = semantic, between = hybrid */
+  semantic_ratio?: number;
+  sort?: Array<string> | null;
+}
+
+export interface PagesSearchResponse {
+  mode?: string;
+  pages?: Array<IntentPageItem>;
+  query: string;
+  took_ms?: number;
+  total_hits?: number;
+}
+
+export interface PagesVisitorCountsRequest {
+  urls: Array<string>;
+}
+
+export interface PagesVisitorsRequest {
+  limit?: number;
+  /** 'quick' (~500ms) or 'full' (~2-3s, all paths). */
+  mode?: string;
+  offset?: number;
+  /** Canonical PAGE_URL, e.g. 'cognism.com/pricing' (no scheme, no www). */
+  url: string;
+}
+
+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;
+}
+
+export interface UrlCompaniesRequest {
+  days?: number;
+  limit?: number;
+  /** Canonical page_url (no scheme, no www) */
+  url: string;
+}