@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/marketingIntelligence.md

@@ -0,0 +1,454 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.marketingIntelligence`: Marketing Intelligence
+
+10 operations (10 read).
+
+No hand-written client covers this area. Call it through `g8.api.marketingIntelligence.*` 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: [marketingIntelligence.d.ts](marketingIntelligence.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getCampaignsWithAttribution`](#op-getcampaignswithattribution) | `GET /api/v1/analytics/marketing/campaigns` | read | `analytics:read` | Get Campaigns With Attribution |
+| [`getContentWithAttribution`](#op-getcontentwithattribution) | `GET /api/v1/analytics/marketing/content` | read | `analytics:read` | Get Content With Attribution |
+| [`getLandingPagesWithAttribution`](#op-getlandingpageswithattribution) | `GET /api/v1/analytics/marketing/content/by-landing` | read | `analytics:read` | Get Landing Pages With Attribution |
+| [`getMarketingOverview`](#op-getmarketingoverview) | `GET /api/v1/analytics/marketing/overview` | read | `analytics:read` | Get Marketing Overview |
+| [`getOutboundBridgeByCampaign`](#op-getoutboundbridgebycampaign) | `GET /api/v1/analytics/marketing/outbound-bridge/by-campaign` | read | `analytics:read` | Get Outbound Bridge By Campaign |
+| [`getOutboundBridgeByChannel`](#op-getoutboundbridgebychannel) | `GET /api/v1/analytics/marketing/outbound-bridge/by-channel` | read | `analytics:read` | Get Outbound Bridge By Channel |
+| [`getOutboundBridgeByLandingPage`](#op-getoutboundbridgebylandingpage) | `GET /api/v1/analytics/marketing/outbound-bridge/by-landing-page` | read | `analytics:read` | Get Outbound Bridge By Landing Page |
+| [`getOutboundBridgeOverview`](#op-getoutboundbridgeoverview) | `GET /api/v1/analytics/marketing/outbound-bridge` | read | `analytics:read` | Get Outbound Bridge Overview |
+| [`getOutboundBridgeTrend`](#op-getoutboundbridgetrend) | `GET /api/v1/analytics/marketing/outbound-bridge/trend` | read | `analytics:read` | Get Outbound Bridge Trend |
+| [`getTopPerformingSources`](#op-gettopperformingsources) | `GET /api/v1/analytics/marketing/outbound-bridge/top-sources` | read | `analytics:read` | Get Top Performing Sources |
+
+---
+
+<a id="op-getcampaignswithattribution"></a>
+
+### `g8.api.marketingIntelligence.getCampaignsWithAttribution(input?)`
+
+**Get Campaigns With Attribution**
+
+- HTTP: `GET /api/v1/analytics/marketing/campaigns`
+- operationId: `get_campaigns_with_attribution_analytics_marketing_campaigns_get` (also callable as `g8.api.call("get_campaigns_with_attribution_analytics_marketing_campaigns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get campaign performance with full attribution chain.
+
+**PRD Reference:** FR-2 Campaign Attribution View
+
+Returns per campaign:
+- campaign_name, source, medium
+- visitors
+- engaged_pct (>1 page AND >30s)
+- identified_contacts
+- added_to_outbound
+- reply_rate
+- meetings_booked
+
+**Cache TTL**: 300 seconds (5 min)
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of campaigns to return default `50` |
+| `query.sort_by` | `"visitors" \| "meetings_booked" \| "reply_rate" \| "engaged_pct"` | no | Sort by this metric (descending) default `"visitors"` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getCampaignsWithAttribution();
+```
+
+---
+
+<a id="op-getcontentwithattribution"></a>
+
+### `g8.api.marketingIntelligence.getContentWithAttribution(input?)`
+
+**Get Content With Attribution**
+
+- HTTP: `GET /api/v1/analytics/marketing/content`
+- operationId: `get_content_with_attribution_analytics_marketing_content_get` (also callable as `g8.api.call("get_content_with_attribution_analytics_marketing_content_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get content performance with full attribution chain.
+
+**PRD Reference:** FR-4 Content Performance View
+
+Returns per page:
+- page_path, page_title
+- views
+- unique_visitors
+- identified_contacts
+- added_to_outbound
+- reply_rate
+- meetings_booked
+
+Only includes pages with at least 10 unique visitors.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of pages to return default `50` |
+| `query.sort_by` | `"views" \| "meetings_booked" \| "reply_rate" \| "unique_visitors"` | no | Sort by this metric (descending) default `"views"` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getContentWithAttribution();
+```
+
+---
+
+<a id="op-getlandingpageswithattribution"></a>
+
+### `g8.api.marketingIntelligence.getLandingPagesWithAttribution(input?)`
+
+**Get Landing Pages With Attribution**
+
+- HTTP: `GET /api/v1/analytics/marketing/content/by-landing`
+- operationId: `get_landing_pages_with_attribution_analytics_marketing_content_by_landing_get` (also callable as `g8.api.call("get_landing_pages_with_attribution_analytics_marketing_content_by_landing_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get landing page performance with attribution metrics.
+
+Same as outbound-bridge/by-landing-page but with content context.
+Shows which entry pages drive best business outcomes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of pages to return default `50` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getLandingPagesWithAttribution();
+```
+
+---
+
+<a id="op-getmarketingoverview"></a>
+
+### `g8.api.marketingIntelligence.getMarketingOverview(input?)`
+
+**Get Marketing Overview**
+
+- HTTP: `GET /api/v1/analytics/marketing/overview`
+- operationId: `get_marketing_overview_analytics_marketing_overview_get` (also callable as `g8.api.call("get_marketing_overview_analytics_marketing_overview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get the Marketing Intelligence Overview (4-card dashboard).
+
+**PRD Reference:** FR-1 Marketing System Health
+
+Returns:
+- **qualified_traffic**: Identified visitors, identification rate, trend
+- **engagement_quality**: Session depth, time on site, bounce rate, trends
+- **campaign_influence**: Top campaign, influenced count, outbound conversion
+- **pipeline_impact**: Meetings booked, replies, outbound metrics, trends
+
+**Typical use**: Main Marketing Intelligence dashboard landing page.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getMarketingOverview();
+```
+
+---
+
+<a id="op-getoutboundbridgebycampaign"></a>
+
+### `g8.api.marketingIntelligence.getOutboundBridgeByCampaign(input?)`
+
+**Get Outbound Bridge By Campaign**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge/by-campaign`
+- operationId: `get_outbound_bridge_by_campaign_analytics_marketing_outbound_bridge_by_campaign_get` (also callable as `g8.api.call("get_outbound_bridge_by_campaign_analytics_marketing_outbound_bridge_by_campaign_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get web-to-outbound metrics by UTM campaign.
+
+**PRD Reference:** FR-2 Campaign Attribution + FR-6 Outbound Bridge
+
+Shows the full attribution chain per campaign:
+Campaign -> Visitors -> Identified -> Engaged -> Outbound -> Replies -> Meetings
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of campaigns to return default `50` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getOutboundBridgeByCampaign();
+```
+
+---
+
+<a id="op-getoutboundbridgebychannel"></a>
+
+### `g8.api.marketingIntelligence.getOutboundBridgeByChannel(input?)`
+
+**Get Outbound Bridge By Channel**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge/by-channel`
+- operationId: `get_outbound_bridge_by_channel_analytics_marketing_outbound_bridge_by_channel_get` (also callable as `g8.api.call("get_outbound_bridge_by_channel_analytics_marketing_outbound_bridge_by_channel_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get web-to-outbound metrics by acquisition channel.
+
+Shows which channels drive best outbound outcomes.
+Channels: Direct, Paid Search, Paid Social, Organic Search, Organic Social, etc.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getOutboundBridgeByChannel();
+```
+
+---
+
+<a id="op-getoutboundbridgebylandingpage"></a>
+
+### `g8.api.marketingIntelligence.getOutboundBridgeByLandingPage(input?)`
+
+**Get Outbound Bridge By Landing Page**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge/by-landing-page`
+- operationId: `get_outbound_bridge_by_landing_page_analytics_marketing_outbound_bridge_by_landing_page_get` (also callable as `g8.api.call("get_outbound_bridge_by_landing_page_analytics_marketing_outbound_bridge_by_landing_page_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get web-to-outbound metrics by landing page.
+
+Shows which entry pages drive best outbound outcomes.
+Only includes pages with at least 10 visitors.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of pages to return default `50` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getOutboundBridgeByLandingPage();
+```
+
+---
+
+<a id="op-getoutboundbridgeoverview"></a>
+
+### `g8.api.marketingIntelligence.getOutboundBridgeOverview(input?)`
+
+**Get Outbound Bridge Overview**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge`
+- operationId: `get_outbound_bridge_overview_analytics_marketing_outbound_bridge_get` (also callable as `g8.api.call("get_outbound_bridge_overview_analytics_marketing_outbound_bridge_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get overview of web-to-outbound bridge performance.
+
+**PRD Reference:** FR-6 Outbound Bridge View
+
+Returns:
+- **web_visitors**: Total unique web visitors
+- **identified_visitors**: Visitors resolved to contacts
+- **added_to_outbound**: Contacts who received outbound emails
+- **total_replies**: Total email replies
+- **meetings_booked**: Total meetings from web visitors
+- **identification_rate**: % of visitors identified
+- **outbound_conversion_pct**: % of identified contacts added to outbound
+- **reply_rate**: % of outbound contacts who replied
+
+This is the key differentiator: connecting web behavior to outbound outcomes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getOutboundBridgeOverview();
+```
+
+---
+
+<a id="op-getoutboundbridgetrend"></a>
+
+### `g8.api.marketingIntelligence.getOutboundBridgeTrend(input?)`
+
+**Get Outbound Bridge Trend**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge/trend`
+- operationId: `get_outbound_bridge_trend_analytics_marketing_outbound_bridge_trend_get` (also callable as `g8.api.call("get_outbound_bridge_trend_analytics_marketing_outbound_bridge_trend_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get daily trend of web-to-outbound bridge metrics.
+
+Returns daily breakdown of:
+- web_visitors
+- identified_visitors
+- added_to_outbound
+- replies
+- meetings
+
+NOTE: the outbound series (`added_to_outbound`, `replies`, `meetings`) stay
+org-wide when `write_key` is set — those events carry no site attribution.
+See the SITE FILTER SCOPE block in `queries/outbound_bridge.py`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getOutboundBridgeTrend();
+```
+
+---
+
+<a id="op-gettopperformingsources"></a>
+
+### `g8.api.marketingIntelligence.getTopPerformingSources(input?)`
+
+**Get Top Performing Sources**
+
+- HTTP: `GET /api/v1/analytics/marketing/outbound-bridge/top-sources`
+- operationId: `get_top_performing_sources_analytics_marketing_outbound_bridge_top_sources_get` (also callable as `g8.api.call("get_top_performing_sources_analytics_marketing_outbound_bridge_top_sources_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get top performing web sources by outbound reply rate.
+
+**PRD Reference:** FR-6.3 Recommended Automations
+
+Identifies the best sources for outbound engagement.
+Only includes sources with at least 5 contacts added to outbound.
+
+Use this to identify which web behaviors predict outbound success.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Number of sources to return default `10` |
+| `query.write_key` | `string \| null` | no | Comma-separated public keys to filter by |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `MarketingResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (MarketingMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.marketingIntelligence.getTopPerformingSources();
+```