@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/visitors.md

@@ -0,0 +1,1075 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.visitors`: Visitors
+
+26 operations (20 read, 5 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.visitors.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [visitors.d.ts](visitors.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`buildTrackedLink`](#op-buildtrackedlink) | `POST /api/v1/visitors/links/build` | write | `visitors:write` | Build Tracked Link |
+| [`checkTrackingInstallation`](#op-checktrackinginstallation) | `GET /api/v1/visitors/installation-check` | read | `visitors:read` | Check Tracking Installation |
+| [`createTailorQueryParamSet`](#op-createtailorqueryparamset) | `POST /api/v1/visitors/tailor/query-param-sets` | write | `visitors:write` | Create Tailor Query Param Set |
+| [`deleteTailorQueryParamSet`](#op-deletetailorqueryparamset) | `DELETE /api/v1/visitors/tailor/query-param-sets/{set_id}` | destructive | `visitors:write` | Delete Tailor Query Param Set |
+| [`getAggregatedLiveVisitors`](#op-getaggregatedlivevisitors) | `GET /api/v1/visitors/live/aggregated` | read | `visitors:read` | Get Aggregated Live Visitors |
+| [`getCampaignListSync`](#op-getcampaignlistsync) | `GET /api/v1/visitors/campaigns/list-syncs/{job_id}` | read | `visitors:read` | Get Campaign List Sync |
+| [`getContactVisitorEvents`](#op-getcontactvisitorevents) | `GET /api/v1/visitors/contacts/{contact_id}/events` | read | `visitors:read` | Get Contact Visitor Events |
+| [`getFormCaptureSettings`](#op-getformcapturesettings) | `GET /api/v1/visitors/form-capture-settings` | read | `visitors:read` | Get Form Capture Settings |
+| [`getLiveVisitors`](#op-getlivevisitors) | `GET /api/v1/visitors/live` | read | `visitors:read` | Get Live Visitors |
+| [`getTrackingClientInfo`](#op-gettrackingclientinfo) | `GET /api/v1/visitors/client-info` | read | `visitors:read` | Get Tracking Client Info |
+| [`getVisitorContactMetrics`](#op-getvisitorcontactmetrics) | `GET /api/v1/visitors/contacts-metrics` | read | `visitors:read` | Get Visitor Contact Metrics |
+| [`getVisitorStatistics`](#op-getvisitorstatistics) | `POST /api/v1/visitors/{resource}/statistics` | write | `visitors:write` | Get Visitor Statistics |
+| [`getVisitorWorkspace`](#op-getvisitorworkspace) | `GET /api/v1/visitors/streams` | read | `visitors:read` | Get Visitor Workspace |
+| [`listAdVisitorEvents`](#op-listadvisitorevents) | `GET /api/v1/visitors/ads/events` | read | `visitors:read` | List Ad Visitor Events |
+| [`listB2bcContactVisitorEvents`](#op-listb2bccontactvisitorevents) | `GET /api/v1/visitors/contacts/b2bc/events` | read | `visitors:read` | List B2Bc Contact Visitor Events |
+| [`listCampaignVisitorEvents`](#op-listcampaignvisitorevents) | `GET /api/v1/visitors/campaigns/events` | read | `visitors:read` | List Campaign Visitor Events |
+| [`listCompanyVisitorEvents`](#op-listcompanyvisitorevents) | `GET /api/v1/visitors/companies/events` | read | `visitors:read` | List Company Visitor Events |
+| [`listContactVisitorEvents`](#op-listcontactvisitorevents) | `GET /api/v1/visitors/contacts/events` | read | `visitors:read` | List Contact Visitor Events |
+| [`listLinkVisitorEvents`](#op-listlinkvisitorevents) | `GET /api/v1/visitors/links/events` | read | `visitors:read` | List Link Visitor Events |
+| [`listTailorQueryParamSets`](#op-listtailorqueryparamsets) | `GET /api/v1/visitors/tailor/query-param-sets` | read | `visitors:read` | List Tailor Query Param Sets |
+| [`listVisitorDistinctBrowsers`](#op-listvisitordistinctbrowsers) | `GET /api/v1/visitors/{resource}/distinct-browsers` | read | `visitors:read` | List Visitor Distinct Browsers |
+| [`listVisitorDistinctUtms`](#op-listvisitordistinctutms) | `GET /api/v1/visitors/{resource}/distinct-utms` | read | `visitors:read` | List Visitor Distinct Utms |
+| [`listVisitorPageHosts`](#op-listvisitorpagehosts) | `GET /api/v1/visitors/page-hosts` | read | `visitors:read` | List Visitor Page Hosts |
+| [`listVisitorStreams`](#op-listvisitorstreams) | `GET /api/v1/visitors/streams/list` | read | `visitors:read` | List Visitor Streams |
+| [`startCampaignListSync`](#op-startcampaignlistsync) | `POST /api/v1/visitors/campaigns/list-syncs` | write | `visitors:write` | Start Campaign List Sync |
+| [`updateFormCaptureSettings`](#op-updateformcapturesettings) | `PATCH /api/v1/visitors/form-capture-settings` | write | `visitors:write` | Update Form Capture Settings |
+
+---
+
+<a id="op-buildtrackedlink"></a>
+
+### `g8.api.visitors.buildTrackedLink(input)`
+
+**Build Tracked Link**
+
+- HTTP: `POST /api/v1/visitors/links/build`
+- operationId: `build_tracked_link_visitors_links_build_post` (also callable as `g8.api.call("build_tracked_link_visitors_links_build_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `visitors:write`
+
+Mint a tracked short link for a destination URL.
+
+Gated on `signals:run`, NOT `signals:read` - this mints a durable public
+URL that attributes real traffic, which is why the app puts it behind the
+run grant rather than the read one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TrackedLinkRequest` | yes | Request body; fields below. |
+
+Body fields (`TrackedLinkRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.destination_url` | `string` | yes | Absolute http(s) URL the link points at. |
+| `body.link_name` | `string` | yes | Display name. REQUIRED, and not cosmetic: clicks are GROUPED by it, so two links sharing a name report as one. min length 1, max length 120 |
+| `body.contact_id` | `integer \| null` | no | Attribute every click on this link to one contact. |
+| `body.params` | `Record<string, string>` | no | Static custom params baked into the token. |
+| `body.placement` | `string` | no | Where the token goes when NOT shortened: `fragment` (`#t=...`) or `query` (`?g8t=...`). Ignored when `shorten` is true. default `"fragment"`, pattern `^(fragment\|query)$` |
+| `body.shorten` | `boolean` | no | Mint the LinkedIn-safe short form (`{base}/t/{token}`) for surfaces that strip fragments and query params. default `false` |
+| `body.stream_id` | `string \| null` | no | 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`. max length 64 |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.buildTrackedLink({
+  body: { destination_url: "https://example.com", link_name: "Example" },
+});
+```
+
+---
+
+<a id="op-checktrackinginstallation"></a>
+
+### `g8.api.visitors.checkTrackingInstallation(input?)`
+
+**Check Tracking Installation**
+
+- HTTP: `GET /api/v1/visitors/installation-check`
+- operationId: `check_tracking_installation_visitors_installation_check_get` (also callable as `g8.api.call("check_tracking_installation_visitors_installation_check_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Is the tracking snippet installed? Answered by whether events are ARRIVING.
+
+At least one of `write_key` or `host` is required (422 otherwise). Both are
+filters inside the key's own org - they cannot reach another tenant's
+events.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.write_key` | `string \| null` | no | A stream's browser write key (`id:secret`); matched by key id. |
+| `query.host` | `string \| null` | no | Website hostname to scope the check to, e.g. example.com. |
+| `query.since_minutes` | `integer` | no | Look-back window in minutes (default 30 days). default `43200` |
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.checkTrackingInstallation();
+```
+
+---
+
+<a id="op-createtailorqueryparamset"></a>
+
+### `g8.api.visitors.createTailorQueryParamSet(input)`
+
+**Create Tailor Query Param Set**
+
+- HTTP: `POST /api/v1/visitors/tailor/query-param-sets`
+- operationId: `create_tailor_query_param_set_visitors_tailor_query_param_sets_post` (also callable as `g8.api.call("create_tailor_query_param_set_visitors_tailor_query_param_sets_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `visitors:write`
+
+Save a query-param set. At most ten per org; the eleventh is a 422.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TailorQueryParamSetRequest` | yes | Request body; fields below. |
+
+Body fields (`TailorQueryParamSetRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 3, max length 255 |
+| `body.settings` | `Record<string, unknown>` | no | The saved parameter selection. |
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.createTailorQueryParamSet({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-deletetailorqueryparamset"></a>
+
+### `g8.api.visitors.deleteTailorQueryParamSet(input)`
+
+**Delete Tailor Query Param Set**
+
+- HTTP: `DELETE /api/v1/visitors/tailor/query-param-sets/{set_id}`
+- operationId: `delete_tailor_query_param_set_visitors_tailor_query_param_sets__set_id__delete` (also callable as `g8.api.call("delete_tailor_query_param_set_visitors_tailor_query_param_sets__set_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `visitors:write`
+
+Delete one saved set. Another org's id is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.set_id` | `string` | yes | The set's id (a UUID). |
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.visitors.deleteTailorQueryParamSet({ path: { set_id: "id" } });
+```
+
+---
+
+<a id="op-getaggregatedlivevisitors"></a>
+
+### `g8.api.visitors.getAggregatedLiveVisitors(input?)`
+
+**Get Aggregated Live Visitors**
+
+- HTTP: `GET /api/v1/visitors/live/aggregated`
+- operationId: `get_aggregated_live_visitors_visitors_live_aggregated_get` (also callable as `g8.api.call("get_aggregated_live_visitors_visitors_live_aggregated_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Live sessions rolled up per visitor. Same PII rule as `/live`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.time_window` | `"5min" \| "30min" \| "1hr"` | no | Live window. default `"30min"` |
+| `query.stream_id` | `string \| null` | no | Comma-separated public keys, or "all". Omit for every stream. |
+| `query.limit` | `integer` | no | default `1000` |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getAggregatedLiveVisitors();
+```
+
+---
+
+<a id="op-getcampaignlistsync"></a>
+
+### `g8.api.visitors.getCampaignListSync(input)`
+
+**Get Campaign List Sync**
+
+- HTTP: `GET /api/v1/visitors/campaigns/list-syncs/{job_id}`
+- operationId: `get_campaign_list_sync_visitors_campaigns_list_syncs__job_id__get` (also callable as `g8.api.call("get_campaign_list_sync_visitors_campaigns_list_syncs__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+How a campaign list sync is going: its state and, once done, how many lists it updated.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string (uuid)` | yes | `job_id` from the sync that started it. |
+
+**Returns** `ApiResponse_VisitorListSyncJob_`: the envelope `{ data: VisitorListSyncJob, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorListSyncJob` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `job_id` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getCampaignListSync({ path: { job_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getcontactvisitorevents"></a>
+
+### `g8.api.visitors.getContactVisitorEvents(input)`
+
+**Get Contact Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/contacts/{contact_id}/events`
+- operationId: `get_contact_visitor_events_visitors_contacts__contact_id__events_get` (also callable as `g8.api.call("get_contact_visitor_events_visitors_contacts__contact_id__events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Every page ONE identified contact viewed on the website, newest first.
+
+`GET /visitors/contacts/events` is the org-wide feed; this is one person's
+history and carries the per-record access check. A contact outside the
+key's scope is a 404, so this cannot be used to probe which ids exist.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+
+**Returns** `ApiResponse_VisitorContactEvents_`: the envelope `{ data: VisitorContactEvents, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorContactEvents` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<VisitorContactEvent>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getContactVisitorEvents({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getformcapturesettings"></a>
+
+### `g8.api.visitors.getFormCaptureSettings(input?)`
+
+**Get Form Capture Settings**
+
+- HTTP: `GET /api/v1/visitors/form-capture-settings`
+- operationId: `get_form_capture_settings_visitors_form_capture_settings_get` (also callable as `g8.api.call("get_form_capture_settings_visitors_form_capture_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Which hosts and paths form submissions are captured from.
+
+Defaults (capture everywhere, bookings included) when nothing has been set.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getFormCaptureSettings();
+```
+
+---
+
+<a id="op-getlivevisitors"></a>
+
+### `g8.api.visitors.getLiveVisitors(input?)`
+
+**Get Live Visitors**
+
+- HTTP: `GET /api/v1/visitors/live`
+- operationId: `get_live_visitors_visitors_live_get` (also callable as `g8.api.call("get_live_visitors_visitors_live_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Raw live sessions in the window.
+
+Identifying fields are REDACTED unless the key's user holds a Signals
+write capability - the same rule the browser applies, resolved from the
+same principal.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.time_window` | `"5min" \| "30min" \| "1hr"` | no | Live window. default `"30min"` |
+| `query.stream_id` | `string \| null` | no | Comma-separated public keys, or "all". Omit for every stream. |
+| `query.limit` | `integer` | no | default `10000` |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getLiveVisitors();
+```
+
+---
+
+<a id="op-gettrackingclientinfo"></a>
+
+### `g8.api.visitors.getTrackingClientInfo(input?)`
+
+**Get Tracking Client Info**
+
+- HTTP: `GET /api/v1/visitors/client-info`
+- operationId: `get_tracking_client_info_visitors_client_info_get` (also callable as `g8.api.call("get_tracking_client_info_visitors_client_info_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+The browser write key and domains a snippet for this stream should use.
+
+The key is the PUBLIC browser key embedded in every page the snippet is on,
+not a secret. An unknown `source_id` falls back to the org default, as the
+app does.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.source_id` | `string \| null` | no | A stream id. Omit for the org's default stream. |
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getTrackingClientInfo();
+```
+
+---
+
+<a id="op-getvisitorcontactmetrics"></a>
+
+### `g8.api.visitors.getVisitorContactMetrics(input?)`
+
+**Get Visitor Contact Metrics**
+
+- HTTP: `GET /api/v1/visitors/contacts-metrics`
+- operationId: `get_visitor_contact_metrics_visitors_contacts_metrics_get` (also callable as `g8.api.call("get_visitor_contact_metrics_visitors_contacts_metrics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Identified-contact metrics over time.
+
+The path is `contacts-metrics`, hyphenated, matching every other path on
+this surface - the app's `contacts_metrics` is the odd one out.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.timeframe` | `string` | no | Preset period. default `"last_7_days"` |
+| `query.interval` | `string \| null` | no | day \| week \| month \| quarter. |
+| `query.start_date` | `string \| null` | no | Custom start, YYYY-MM-DD. |
+| `query.end_date` | `string \| null` | no | Custom end, YYYY-MM-DD. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getVisitorContactMetrics();
+```
+
+---
+
+<a id="op-getvisitorstatistics"></a>
+
+### `g8.api.visitors.getVisitorStatistics(input)`
+
+**Get Visitor Statistics**
+
+- HTTP: `POST /api/v1/visitors/{resource}/statistics`
+- operationId: `get_visitor_statistics_visitors__resource__statistics_post` (also callable as `g8.api.call("get_visitor_statistics_visitors__resource__statistics_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `visitors:write`
+
+Counts over the visitor stream, filtered.
+
+`companies` counts UNIQUE BY IP, `contacts` does not - the two series are
+not comparable row for row and should not be charted as if they were.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.resource` | `"contacts" \| "companies"` | yes | What to count. |
+| `body` | `Array<Record<string, unknown>>` | no | Request body; fields below. |
+
+**Returns** `ApiResponse_VisitorStatisticsResponse_`: the envelope `{ data: VisitorStatisticsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorStatisticsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `series` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getVisitorStatistics({ path: { resource: "contacts" }, body: [{}] });
+```
+
+---
+
+<a id="op-getvisitorworkspace"></a>
+
+### `g8.api.visitors.getVisitorWorkspace(input?)`
+
+**Get Visitor Workspace**
+
+- HTTP: `GET /api/v1/visitors/streams`
+- operationId: `get_visitor_workspace_visitors_streams_get` (also callable as `g8.api.call("get_visitor_workspace_visitors_streams_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+The tracking workspace: its streams and their public write keys.
+
+The write keys are what the browser snippet sends with, so this is the
+endpoint a rebuilt install flow reads to render the snippet.
+
+**Input**: none.
+
+**Returns** `ApiResponse_VisitorStreamsResponse_`: the envelope `{ data: VisitorStreamsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorStreamsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `streams` | `Array<VisitorStream>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.getVisitorWorkspace();
+```
+
+---
+
+<a id="op-listadvisitorevents"></a>
+
+### `g8.api.visitors.listAdVisitorEvents(input?)`
+
+**List Ad Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/ads/events`
+- operationId: `list_ad_visitor_events_visitors_ads_events_get` (also callable as `g8.api.call("list_ad_visitor_events_visitors_ads_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Visits attributed to an ad.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listAdVisitorEvents();
+```
+
+---
+
+<a id="op-listb2bccontactvisitorevents"></a>
+
+### `g8.api.visitors.listB2bcContactVisitorEvents(input?)`
+
+**List B2Bc Contact Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/contacts/b2bc/events`
+- operationId: `list_b2bc_contact_visitor_events_visitors_contacts_b2bc_events_get` (also callable as `g8.api.call("list_b2bc_contact_visitor_events_visitors_contacts_b2bc_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+The B2BC variant of the contact feed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.show_mode` | `"grouped" \| "raw"` | no | default `"grouped"` |
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listB2bcContactVisitorEvents();
+```
+
+---
+
+<a id="op-listcampaignvisitorevents"></a>
+
+### `g8.api.visitors.listCampaignVisitorEvents(input?)`
+
+**List Campaign Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/campaigns/events`
+- operationId: `list_campaign_visitor_events_visitors_campaigns_events_get` (also callable as `g8.api.call("list_campaign_visitor_events_visitors_campaigns_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Visits attributed to a sequence.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.campaign` | `string \| null` | no | 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. |
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listCampaignVisitorEvents();
+```
+
+---
+
+<a id="op-listcompanyvisitorevents"></a>
+
+### `g8.api.visitors.listCompanyVisitorEvents(input?)`
+
+**List Company Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/companies/events`
+- operationId: `list_company_visitor_events_visitors_companies_events_get` (also callable as `g8.api.call("list_company_visitor_events_visitors_companies_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Visits resolved to a company rather than a person.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.show_mode` | `"grouped" \| "raw"` | no | default `"grouped"` |
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listCompanyVisitorEvents();
+```
+
+---
+
+<a id="op-listcontactvisitorevents"></a>
+
+### `g8.api.visitors.listContactVisitorEvents(input?)`
+
+**List Contact Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/contacts/events`
+- operationId: `list_contact_visitor_events_visitors_contacts_events_get` (also callable as `g8.api.call("list_contact_visitor_events_visitors_contacts_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Visits attributed to a known contact.
+
+Carries BOTH gates the app declares: Signals read AND Contacts read. This
+feed joins website behaviour to identified people, so holding one without
+the other is not enough - and dropping either would be a quieter leak than
+it looks.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.show_mode` | `"grouped" \| "raw"` | no | default `"grouped"` |
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listContactVisitorEvents();
+```
+
+---
+
+<a id="op-listlinkvisitorevents"></a>
+
+### `g8.api.visitors.listLinkVisitorEvents(input?)`
+
+**List Link Visitor Events**
+
+- HTTP: `GET /api/v1/visitors/links/events`
+- operationId: `list_link_visitor_events_visitors_links_events_get` (also callable as `g8.api.call("list_link_visitor_events_visitors_links_events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Clicks on a tracked link.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.filter` | `string \| null` | no | 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. |
+| `query.page` | `integer` | no | Page number (1-indexed). default `1` |
+| `query.limit` | `integer` | no | Items per page. default `50` |
+
+**Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorEventPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `events` | `Array<Record<string, unknown>>` | no |  |
+| `limit` | `integer \| null` | no |  |
+| `page` | `integer \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listLinkVisitorEvents();
+```
+
+---
+
+<a id="op-listtailorqueryparamsets"></a>
+
+### `g8.api.visitors.listTailorQueryParamSets(input?)`
+
+**List Tailor Query Param Sets**
+
+- HTTP: `GET /api/v1/visitors/tailor/query-param-sets`
+- operationId: `list_tailor_query_param_sets_visitors_tailor_query_param_sets_get` (also callable as `g8.api.call("list_tailor_query_param_sets_visitors_tailor_query_param_sets_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Saved page-personalisation query-param sets, oldest first, as `sets`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listTailorQueryParamSets();
+```
+
+---
+
+<a id="op-listvisitordistinctbrowsers"></a>
+
+### `g8.api.visitors.listVisitorDistinctBrowsers(input)`
+
+**List Visitor Distinct Browsers**
+
+- HTTP: `GET /api/v1/visitors/{resource}/distinct-browsers`
+- operationId: `list_visitor_distinct_browsers_visitors__resource__distinct_browsers_get` (also callable as `g8.api.call("list_visitor_distinct_browsers_visitors__resource__distinct_browsers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Browser values present in the data - a filter picker, not analytics.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.resource` | `"contacts" \| "companies"` | yes |  |
+| `query.write_key` | `string \| null` | no | Scope to a single stream. |
+
+**Returns** `ApiResponse_list_str__`: the envelope `{ data: Array<string>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listVisitorDistinctBrowsers({ path: { resource: "contacts" } });
+```
+
+---
+
+<a id="op-listvisitordistinctutms"></a>
+
+### `g8.api.visitors.listVisitorDistinctUtms(input)`
+
+**List Visitor Distinct Utms**
+
+- HTTP: `GET /api/v1/visitors/{resource}/distinct-utms`
+- operationId: `list_visitor_distinct_utms_visitors__resource__distinct_utms_get` (also callable as `g8.api.call("list_visitor_distinct_utms_visitors__resource__distinct_utms_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+UTM values present in the data - the other half of the filter picker.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.resource` | `"contacts" \| "companies"` | yes |  |
+| `query.param` | `"utm_source" \| "utm_medium" \| "utm_campaign"` | yes | Which UTM parameter to list values for. |
+| `query.write_key` | `string \| null` | no | Scope to a single stream. |
+
+**Returns** `ApiResponse_list_str__`: the envelope `{ data: Array<string>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listVisitorDistinctUtms({ path: { resource: "contacts" }, query: { param: "utm_source" } });
+```
+
+---
+
+<a id="op-listvisitorpagehosts"></a>
+
+### `g8.api.visitors.listVisitorPageHosts(input?)`
+
+**List Visitor Page Hosts**
+
+- HTTP: `GET /api/v1/visitors/page-hosts`
+- operationId: `list_visitor_page_hosts_visitors_page_hosts_get` (also callable as `g8.api.call("list_visitor_page_hosts_visitors_page_hosts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Hostnames the snippet has actually reported from.
+
+Useful for catching a snippet installed on a staging domain, or missing
+from one you expected.
+
+**Input**: none.
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listVisitorPageHosts();
+```
+
+---
+
+<a id="op-listvisitorstreams"></a>
+
+### `g8.api.visitors.listVisitorStreams(input?)`
+
+**List Visitor Streams**
+
+- HTTP: `GET /api/v1/visitors/streams/list`
+- operationId: `list_visitor_streams_visitors_streams_list_get` (also callable as `g8.api.call("list_visitor_streams_visitors_streams_list_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `visitors:read`
+
+Just the streams, without the surrounding workspace payload.
+
+**Input**: none.
+
+**Returns** `ApiResponse_VisitorStreamsResponse_`: the envelope `{ data: VisitorStreamsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorStreamsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `streams` | `Array<VisitorStream>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.listVisitorStreams();
+```
+
+---
+
+<a id="op-startcampaignlistsync"></a>
+
+### `g8.api.visitors.startCampaignListSync(input)`
+
+**Start Campaign List Sync**
+
+- HTTP: `POST /api/v1/visitors/campaigns/list-syncs`
+- operationId: `start_campaign_list_sync_visitors_campaigns_list_syncs_post` (also callable as `g8.api.call("start_campaign_list_sync_visitors_campaigns_list_syncs_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `visitors:write`
+
+Sync the website visitors of some campaign steps into their campaign lists.
+
+ASYNCHRONOUS: 202 and a `job_id`; poll
+`GET /visitors/campaigns/list-syncs/{job_id}`. While a sync is already
+running for the org, the running job comes back with
+`status: already_running` and nothing new starts.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VisitorListSyncRequest` | yes | Request body; fields below. |
+
+Body fields (`VisitorListSyncRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.sequencer_step_ids` | `Array<string>` | yes | Campaign (sequence) step ids whose visitors are synced into the campaign's list. min items 1, max items 500 |
+
+**Returns** `ApiResponse_VisitorListSyncJob_`: the envelope `{ data: VisitorListSyncJob, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`VisitorListSyncJob` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `job_id` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.startCampaignListSync({ body: { sequencer_step_ids: ["id"] } });
+```
+
+---
+
+<a id="op-updateformcapturesettings"></a>
+
+### `g8.api.visitors.updateFormCaptureSettings(input)`
+
+**Update Form Capture Settings**
+
+- HTTP: `PATCH /api/v1/visitors/form-capture-settings`
+- operationId: `update_form_capture_settings_visitors_form_capture_settings_patch` (also callable as `g8.api.call("update_form_capture_settings_visitors_form_capture_settings_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `visitors:write`
+
+Replace the form-capture filters. Takes effect for the next submission on the site.
+
+PATCH is the app's verb, but the body is a FULL REPLACEMENT - see the
+request model.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FormCaptureSettingsRequest` | yes | Request body; fields below. |
+
+Body fields (`FormCaptureSettingsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.allowed_hosts` | `Array<string>` | no | Capture only on these hosts. Empty means every host. |
+| `body.blocked_hosts` | `Array<string>` | no | Never capture on these hosts. |
+| `body.blocked_paths` | `Array<string>` | no | Never capture on these URL paths. |
+| `body.track_appointments` | `boolean` | no | Also capture booking-form submissions. default `true` |
+
+**Returns** `ApiResponse_SiteConnectionsPayload_`: the envelope `{ data: SiteConnectionsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.visitors.updateFormCaptureSettings({ body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-visitorcontactevent"></a>
+
+### `VisitorContactEvent`
+
+One page view by one identified contact.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_host` | `string \| null` | no |  |
+| `page_path` | `string \| null` | no |  |
+| `page_title` | `string \| null` | no |  |
+| `visit_time` | `string (date-time) \| null` | no |  |
+
+<a id="type-visitorstream"></a>
+
+### `VisitorStream`
+
+One tracking stream and the public keys the snippet sends with.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `publicKeys` | `Array<string>` | no | 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. |