@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/sdrAnalytics.md

@@ -0,0 +1,246 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.sdrAnalytics`: SDR Analytics
+
+5 operations (5 read).
+
+No hand-written client covers this area. Call it through `g8.api.sdrAnalytics.*` 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: [sdrAnalytics.d.ts](sdrAnalytics.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getAiAgentsSummary`](#op-getaiagentssummary) | `GET /api/v1/analytics/sdr/ai-agents/summary` | read | `analytics:read` | Get Ai Agents Summary |
+| [`getSdrDetail`](#op-getsdrdetail) | `GET /api/v1/analytics/sdr/{sdr_email}` | read | `analytics:read` | Get Sdr Detail |
+| [`getSdrLeaderboard`](#op-getsdrleaderboard) | `GET /api/v1/analytics/sdr/leaderboard` | read | `analytics:read` | Get Sdr Leaderboard |
+| [`getSdrSummary`](#op-getsdrsummary) | `GET /api/v1/analytics/sdr/summary` | read | `analytics:read` | Get Sdr Summary |
+| [`getSdrTrends`](#op-getsdrtrends) | `GET /api/v1/analytics/sdr/trends` | read | `analytics:read` | Get Sdr Trends |
+
+---
+
+<a id="op-getaiagentssummary"></a>
+
+### `g8.api.sdrAnalytics.getAiAgentsSummary(input?)`
+
+**Get Ai Agents Summary**
+
+- HTTP: `GET /api/v1/analytics/sdr/ai-agents/summary`
+- operationId: `get_ai_agents_summary_analytics_sdr_ai_agents_summary_get` (also callable as `g8.api.call("get_ai_agents_summary_analytics_sdr_ai_agents_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get AI Agents summary with aggregate totals for all AI-powered activities.
+
+Returns org-wide AI metrics:
+- **total_ai_emails**: Total AI-generated emails sent
+- **total_ai_replies**: Total replies to AI emails
+- **total_ai_dials**: Total AI dialer calls initiated
+- **total_ai_connected**: Total AI calls that connected
+- **ai_connect_rate**: AI call connection rate percentage
+- **total_ai_meetings**: Total meetings booked by AI
+
+**Cache TTL**: 60 seconds
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `SDRAnalyticsResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (SDRAnalyticsMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.sdrAnalytics.getAiAgentsSummary();
+```
+
+---
+
+<a id="op-getsdrdetail"></a>
+
+### `g8.api.sdrAnalytics.getSdrDetail(input)`
+
+**Get Sdr Detail**
+
+- HTTP: `GET /api/v1/analytics/sdr/{sdr_email}`
+- operationId: `get_sdr_detail_analytics_sdr__sdr_email__get` (also callable as `g8.api.call("get_sdr_detail_analytics_sdr__sdr_email__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get detailed breakdown for a specific SDR.
+
+Returns:
+- **sdr_email**: SDR email address
+- **totals**: Aggregate metrics for the period
+- **daily**: Day-by-day breakdown of activity
+
+Useful for SDR detail modal/drill-down view.
+
+**Cache TTL**: 60 seconds
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.sdr_email` | `string` | yes | SDR email address |
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `SDRAnalyticsResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (SDRAnalyticsMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.sdrAnalytics.getSdrDetail({ path: { sdr_email: "jane@acme.com" } });
+```
+
+---
+
+<a id="op-getsdrleaderboard"></a>
+
+### `g8.api.sdrAnalytics.getSdrLeaderboard(input?)`
+
+**Get Sdr Leaderboard**
+
+- HTTP: `GET /api/v1/analytics/sdr/leaderboard`
+- operationId: `get_sdr_leaderboard_analytics_sdr_leaderboard_get` (also callable as `g8.api.call("get_sdr_leaderboard_analytics_sdr_leaderboard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get SDR leaderboard ranking all reps by activity.
+
+Returns a ranked list of SDRs with:
+- **emails_sent**: Total emails sent
+- **replies**: Total replies received
+- **reply_rate**: Reply rate percentage
+- **dials**: Total call dials
+- **connected**: Connected calls
+- **connect_rate**: Connect rate percentage
+- **meetings_booked**: Meetings scheduled
+- **activity_score**: Composite score (emails + dials*2 + meetings*10)
+
+**Cache TTL**: 60 seconds
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.limit` | `integer` | no | Maximum SDRs to return default `100` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `SDRAnalyticsResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (SDRAnalyticsMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.sdrAnalytics.getSdrLeaderboard();
+```
+
+---
+
+<a id="op-getsdrsummary"></a>
+
+### `g8.api.sdrAnalytics.getSdrSummary(input?)`
+
+**Get Sdr Summary**
+
+- HTTP: `GET /api/v1/analytics/sdr/summary`
+- operationId: `get_sdr_summary_analytics_sdr_summary_get` (also callable as `g8.api.call("get_sdr_summary_analytics_sdr_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get team-wide SDR summary with aggregate totals (human SDR activity only).
+
+Returns:
+- **active_sdrs**: Number of SDRs with activity
+- **total_emails_sent**: Total emails sent across team
+- **total_replies**: Total replies received
+- **total_meetings**: Total meetings booked
+- **avg_reply_rate**: Team average reply rate
+
+Note: Voice AI call metrics are available via /voice-ai/summary endpoint.
+
+**Cache TTL**: 60 seconds
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `SDRAnalyticsResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (SDRAnalyticsMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.sdrAnalytics.getSdrSummary();
+```
+
+---
+
+<a id="op-getsdrtrends"></a>
+
+### `g8.api.sdrAnalytics.getSdrTrends(input?)`
+
+**Get Sdr Trends**
+
+- HTTP: `GET /api/v1/analytics/sdr/trends`
+- operationId: `get_sdr_trends_analytics_sdr_trends_get` (also callable as `g8.api.call("get_sdr_trends_analytics_sdr_trends_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Get SDR activity trends over time for charts.
+
+Returns time series data with:
+- **period**: Date or week start
+- **emails_sent**: Emails sent in period
+- **replies**: Replies in period
+- **dials**: Dials in period
+- **connected**: Connected calls in period
+- **meetings_booked**: Meetings in period
+- **reply_rate**: Period reply rate
+- **connect_rate**: Period connect rate
+
+**Cache TTL**: 60 seconds
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Number of days to analyze default `30` |
+| `query.granularity` | `"day" \| "week"` | no | Aggregation period: 'day' or 'week' default `"day"` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `SDRAnalyticsResponse`: the envelope `{ data: Record<string, unknown> | Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `meta` (SDRAnalyticsMeta), `success` (boolean).
+
+**Example**
+
+```ts
+const result = await g8.api.sdrAnalytics.getSdrTrends();
+```