@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/visitors.d.ts

@@ -0,0 +1,690 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.visitors` (Visitors): 26 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"build_tracked_link_visitors_links_build_post">;
+ *
+ * Reference with examples: visitors.md
+ */
+/* eslint-disable */
+
+/** `g8.api.visitors.<member>` -> the operationId it calls. */
+export interface VisitorsMembers {
+  buildTrackedLink: "build_tracked_link_visitors_links_build_post";
+  checkTrackingInstallation: "check_tracking_installation_visitors_installation_check_get";
+  createTailorQueryParamSet: "create_tailor_query_param_set_visitors_tailor_query_param_sets_post";
+  deleteTailorQueryParamSet: "delete_tailor_query_param_set_visitors_tailor_query_param_sets__set_id__delete";
+  getAggregatedLiveVisitors: "get_aggregated_live_visitors_visitors_live_aggregated_get";
+  getCampaignListSync: "get_campaign_list_sync_visitors_campaigns_list_syncs__job_id__get";
+  getContactVisitorEvents: "get_contact_visitor_events_visitors_contacts__contact_id__events_get";
+  getFormCaptureSettings: "get_form_capture_settings_visitors_form_capture_settings_get";
+  getLiveVisitors: "get_live_visitors_visitors_live_get";
+  getTrackingClientInfo: "get_tracking_client_info_visitors_client_info_get";
+  getVisitorContactMetrics: "get_visitor_contact_metrics_visitors_contacts_metrics_get";
+  getVisitorStatistics: "get_visitor_statistics_visitors__resource__statistics_post";
+  getVisitorWorkspace: "get_visitor_workspace_visitors_streams_get";
+  listAdVisitorEvents: "list_ad_visitor_events_visitors_ads_events_get";
+  listB2bcContactVisitorEvents: "list_b2bc_contact_visitor_events_visitors_contacts_b2bc_events_get";
+  listCampaignVisitorEvents: "list_campaign_visitor_events_visitors_campaigns_events_get";
+  listCompanyVisitorEvents: "list_company_visitor_events_visitors_companies_events_get";
+  listContactVisitorEvents: "list_contact_visitor_events_visitors_contacts_events_get";
+  listLinkVisitorEvents: "list_link_visitor_events_visitors_links_events_get";
+  listTailorQueryParamSets: "list_tailor_query_param_sets_visitors_tailor_query_param_sets_get";
+  listVisitorDistinctBrowsers: "list_visitor_distinct_browsers_visitors__resource__distinct_browsers_get";
+  listVisitorDistinctUtms: "list_visitor_distinct_utms_visitors__resource__distinct_utms_get";
+  listVisitorPageHosts: "list_visitor_page_hosts_visitors_page_hosts_get";
+  listVisitorStreams: "list_visitor_streams_visitors_streams_list_get";
+  startCampaignListSync: "start_campaign_list_sync_visitors_campaigns_list_syncs_post";
+  updateFormCaptureSettings: "update_form_capture_settings_visitors_form_capture_settings_patch";
+}
+
+/** Input and output of every `g8.api.visitors` operation, keyed by operationId. */
+export interface VisitorsOperations {
+  /**
+   * POST /visitors/links/build
+   * Build Tracked Link
+   * tier: write · scope: visitors:write
+   */
+  build_tracked_link_visitors_links_build_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: TrackedLinkRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /visitors/installation-check
+   * Check Tracking Installation
+   * tier: read · scope: visitors:read
+   */
+  check_tracking_installation_visitors_installation_check_get: {
+    input: {
+    query?: {
+      /** A stream's browser write key (`id:secret`); matched by key id. */
+      write_key?: string | null;
+      /** Website hostname to scope the check to, e.g. example.com. */
+      host?: string | null;
+      /** Look-back window in minutes (default 30 days). */
+      since_minutes?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * POST /visitors/tailor/query-param-sets
+   * Create Tailor Query Param Set
+   * tier: write · scope: visitors:write
+   */
+  create_tailor_query_param_set_visitors_tailor_query_param_sets_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: TailorQueryParamSetRequest;
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * DELETE /visitors/tailor/query-param-sets/{set_id}
+   * Delete Tailor Query Param Set
+   * tier: destructive · scope: visitors:write
+   */
+  delete_tailor_query_param_set_visitors_tailor_query_param_sets__set_id__delete: {
+    input: {
+    path: {
+      /** The set's id (a UUID). */
+      set_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * GET /visitors/live/aggregated
+   * Get Aggregated Live Visitors
+   * tier: read · scope: visitors:read
+   */
+  get_aggregated_live_visitors_visitors_live_aggregated_get: {
+    input: {
+    query?: {
+      /** Live window. */
+      time_window?: "5min" | "30min" | "1hr";
+      /** Comma-separated public keys, or "all". Omit for every stream. */
+      stream_id?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /visitors/campaigns/list-syncs/{job_id}
+   * Get Campaign List Sync
+   * tier: read · scope: visitors:read
+   */
+  get_campaign_list_sync_visitors_campaigns_list_syncs__job_id__get: {
+    input: {
+    path: {
+      /** `job_id` from the sync that started it. */
+      job_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorListSyncJob_;
+  };
+  /**
+   * GET /visitors/contacts/{contact_id}/events
+   * Get Contact Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  get_contact_visitor_events_visitors_contacts__contact_id__events_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorContactEvents_;
+  };
+  /**
+   * GET /visitors/form-capture-settings
+   * Get Form Capture Settings
+   * tier: read · scope: visitors:read
+   */
+  get_form_capture_settings_visitors_form_capture_settings_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * GET /visitors/live
+   * Get Live Visitors
+   * tier: read · scope: visitors:read
+   */
+  get_live_visitors_visitors_live_get: {
+    input: {
+    query?: {
+      /** Live window. */
+      time_window?: "5min" | "30min" | "1hr";
+      /** Comma-separated public keys, or "all". Omit for every stream. */
+      stream_id?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /visitors/client-info
+   * Get Tracking Client Info
+   * tier: read · scope: visitors:read
+   */
+  get_tracking_client_info_visitors_client_info_get: {
+    input: {
+    query?: {
+      /** A stream id. Omit for the org's default stream. */
+      source_id?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * GET /visitors/contacts-metrics
+   * Get Visitor Contact Metrics
+   * tier: read · scope: visitors:read
+   */
+  get_visitor_contact_metrics_visitors_contacts_metrics_get: {
+    input: {
+    query?: {
+      /** Preset period. */
+      timeframe?: string;
+      /** day | week | month | quarter. */
+      interval?: string | null;
+      /** Custom start, YYYY-MM-DD. */
+      start_date?: string | null;
+      /** Custom end, YYYY-MM-DD. */
+      end_date?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * POST /visitors/{resource}/statistics
+   * Get Visitor Statistics
+   * tier: write · scope: visitors:write
+   */
+  get_visitor_statistics_visitors__resource__statistics_post: {
+    input: {
+    path: {
+      /** What to count. */
+      resource: "contacts" | "companies";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: Array<Record<string, unknown>>;
+  };
+    output: ApiResponse_VisitorStatisticsResponse_;
+  };
+  /**
+   * GET /visitors/streams
+   * Get Visitor Workspace
+   * tier: read · scope: visitors:read
+   */
+  get_visitor_workspace_visitors_streams_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorStreamsResponse_;
+  };
+  /**
+   * GET /visitors/ads/events
+   * List Ad Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_ad_visitor_events_visitors_ads_events_get: {
+    input: {
+    query?: {
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/contacts/b2bc/events
+   * List B2Bc Contact Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_b2bc_contact_visitor_events_visitors_contacts_b2bc_events_get: {
+    input: {
+    query?: {
+      show_mode?: "grouped" | "raw";
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/campaigns/events
+   * List Campaign Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_campaign_visitor_events_visitors_campaigns_events_get: {
+    input: {
+    query?: {
+      /** Sequence id to scope to, or "all"/omitted for none. When set it ALWAYS constrains results to that campaign's sequencer steps: a step filter can only narrow within the campaign, never broaden to others, and a step belonging to a different campaign is rejected. */
+      campaign?: string | null;
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/companies/events
+   * List Company Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_company_visitor_events_visitors_companies_events_get: {
+    input: {
+    query?: {
+      show_mode?: "grouped" | "raw";
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/contacts/events
+   * List Contact Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_contact_visitor_events_visitors_contacts_events_get: {
+    input: {
+    query?: {
+      show_mode?: "grouped" | "raw";
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/links/events
+   * List Link Visitor Events
+   * tier: read · scope: visitors:read
+   */
+  list_link_visitor_events_visitors_links_events_get: {
+    input: {
+    query?: {
+      /** Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. */
+      filter?: string | null;
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorEventPage_;
+  };
+  /**
+   * GET /visitors/tailor/query-param-sets
+   * List Tailor Query Param Sets
+   * tier: read · scope: visitors:read
+   */
+  list_tailor_query_param_sets_visitors_tailor_query_param_sets_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+  /**
+   * GET /visitors/{resource}/distinct-browsers
+   * List Visitor Distinct Browsers
+   * tier: read · scope: visitors:read
+   */
+  list_visitor_distinct_browsers_visitors__resource__distinct_browsers_get: {
+    input: {
+    path: {
+      resource: "contacts" | "companies";
+    };
+    query?: {
+      /** Scope to a single stream. */
+      write_key?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_str__;
+  };
+  /**
+   * GET /visitors/{resource}/distinct-utms
+   * List Visitor Distinct Utms
+   * tier: read · scope: visitors:read
+   */
+  list_visitor_distinct_utms_visitors__resource__distinct_utms_get: {
+    input: {
+    path: {
+      resource: "contacts" | "companies";
+    };
+    query: {
+      /** Which UTM parameter to list values for. */
+      param: "utm_source" | "utm_medium" | "utm_campaign";
+      /** Scope to a single stream. */
+      write_key?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_str__;
+  };
+  /**
+   * GET /visitors/page-hosts
+   * List Visitor Page Hosts
+   * tier: read · scope: visitors:read
+   */
+  list_visitor_page_hosts_visitors_page_hosts_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /visitors/streams/list
+   * List Visitor Streams
+   * tier: read · scope: visitors:read
+   */
+  list_visitor_streams_visitors_streams_list_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_VisitorStreamsResponse_;
+  };
+  /**
+   * POST /visitors/campaigns/list-syncs
+   * Start Campaign List Sync
+   * tier: write · scope: visitors:write
+   */
+  start_campaign_list_sync_visitors_campaigns_list_syncs_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VisitorListSyncRequest;
+  };
+    output: ApiResponse_VisitorListSyncJob_;
+  };
+  /**
+   * PATCH /visitors/form-capture-settings
+   * Update Form Capture Settings
+   * tier: write · scope: visitors:write
+   */
+  update_form_capture_settings_visitors_form_capture_settings_patch: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FormCaptureSettingsRequest;
+  };
+    output: ApiResponse_SiteConnectionsPayload_;
+  };
+}
+
+// 21 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_SiteConnectionsPayload_ {
+  data: SiteConnectionsPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorContactEvents_ {
+  data: VisitorContactEvents;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorEventPage_ {
+  data: VisitorEventPage;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorListSyncJob_ {
+  data: VisitorListSyncJob;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorStatisticsResponse_ {
+  data: VisitorStatisticsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_VisitorStreamsResponse_ {
+  data: VisitorStreamsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_str__ {
+  data: Array<string>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Which pages form submissions are captured from.
+ *
+ * A FULL REPLACEMENT: every list is written as sent, so an omitted list is
+ * reset to empty and an omitted `track_appointments` goes back to true. Read
+ * `GET /visitors/form-capture-settings` first and send the whole object back.
+ */
+export interface FormCaptureSettingsRequest {
+  /** Capture only on these hosts. Empty means every host. */
+  allowed_hosts?: Array<string>;
+  /** Never capture on these hosts. */
+  blocked_hosts?: Array<string>;
+  /** Never capture on these URL paths. */
+  blocked_paths?: Array<string>;
+  /** Also capture booking-form submissions. */
+  track_appointments?: boolean;
+}
+
+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;
+}
+
+/** One handler response. Open-shaped - these payloads come from the tracking pipeline. */
+export type SiteConnectionsPayload = Record<string, unknown>;
+
+/** A named, saved set of page-personalisation query parameters. */
+export interface TailorQueryParamSetRequest {
+  name: string;
+  /** The saved parameter selection. */
+  settings?: Record<string, unknown>;
+}
+
+/** Mint a tracked short link. */
+export interface TrackedLinkRequest {
+  /** Attribute every click on this link to one contact. */
+  contact_id?: number | null;
+  /** Absolute http(s) URL the link points at. */
+  destination_url: string;
+  /** Display name. REQUIRED, and not cosmetic: clicks are GROUPED by it, so two links sharing a name report as one. */
+  link_name: string;
+  /** Static custom params baked into the token. */
+  params?: Record<string, string>;
+  /** Where the token goes when NOT shortened: `fragment` (`#t=...`) or `query` (`?g8t=...`). Ignored when `shorten` is true. */
+  placement?: string;
+  /** Mint the LinkedIn-safe short form (`{base}/t/{token}`) for surfaces that strip fragments and query params. */
+  shorten?: boolean;
+  /** PUBLIC KEY id of the stream clicks are attributed to - the id shape `GET /visitors/streams/list` emits, NOT the stream object's own id. Falls back to the org's dedicated `tracked-links` stream when unset or unresolvable, and is only meaningful with `shorten=true`. */
+  stream_id?: string | null;
+}
+
+/** One page view by one identified contact. */
+export interface VisitorContactEvent {
+  page_host?: string | null;
+  page_path?: string | null;
+  page_title?: string | null;
+  visit_time?: string | null;
+}
+
+/** Everything one identified contact did on the website, newest first. */
+export interface VisitorContactEvents {
+  events?: Array<VisitorContactEvent>;
+}
+
+/**
+ * A page of visitor events.
+ *
+ * Rows are open dicts on purpose: each feed (contact, company, campaign, ad,
+ * link) carries a different field set, and the tracker adds fields over
+ * time. A pinned per-feed schema would silently drop whatever it had not
+ * caught up on - and on an analytics surface a missing field reads as a
+ * missing visit.
+ */
+export interface VisitorEventPage {
+  events?: Array<Record<string, unknown>>;
+  limit?: number | null;
+  page?: number | null;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/** A campaign list sync job, or its status. Open-shaped - the receipt grows with the job store. */
+export interface VisitorListSyncJob {
+  job_id?: string | null;
+  status?: string | null;
+  [key: string]: unknown;
+}
+
+/**
+ * Which campaign steps' website visitors to sync into their campaign lists.
+ *
+ * The app's body is a list of filter conditions, but its handler accepts
+ * EXACTLY ONE shape - a single `sequencer_step_id` / `in` condition with a
+ * non-empty value - and 422s every other. This publishes that shape and
+ * nothing else; the proxy builds the one condition from it.
+ */
+export interface VisitorListSyncRequest {
+  /** Campaign (sequence) step ids whose visitors are synced into the campaign's list. */
+  sequencer_step_ids: Array<string>;
+}
+
+/**
+ * Counts over the visitor stream.
+ *
+ * `companies` counts UNIQUE BY IP and `contacts` does not, so the two series
+ * are not comparable row for row - charting them on one axis as if they were
+ * overstates or understates one of them depending on traffic shape.
+ */
+export interface VisitorStatisticsResponse {
+  series?: Array<Record<string, unknown>>;
+  total?: number | null;
+  [key: string]: unknown;
+}
+
+/** One tracking stream and the public keys the snippet sends with. */
+export interface VisitorStream {
+  id?: string | null;
+  name?: string | null;
+  /** Public write keys. Named in the app's camelCase rather than re-cased here - the snippet reads this value verbatim, and renaming it would be a silent breakage in a copy-paste flow. */
+  publicKeys?: Array<string>;
+  [key: string]: unknown;
+}
+
+/** The tracking workspace's streams. */
+export interface VisitorStreamsResponse {
+  streams?: Array<VisitorStream>;
+  total?: number;
+  [key: string]: unknown;
+}