@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/revenueAnalytics.d.ts

@@ -0,0 +1,147 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.revenueAnalytics` (Revenue Analytics): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_acquisition_breakdown_analytics_attribution_acquisition_breakdown_get">;
+ *
+ * Reference with examples: revenueAnalytics.md
+ */
+/* eslint-disable */
+
+/** `g8.api.revenueAnalytics.<member>` -> the operationId it calls. */
+export interface RevenueAnalyticsMembers {
+  getAcquisitionBreakdown: "get_acquisition_breakdown_analytics_attribution_acquisition_breakdown_get";
+  getSenderPerformance: "get_sender_performance_analytics_attribution_sender_performance_get";
+  getTeamConversionFunnel: "get_team_conversion_funnel_analytics_team_conversion_funnel_get";
+  getTeamPipelineVelocity: "get_team_pipeline_velocity_analytics_team_pipeline_velocity_get";
+  getTeamRevenueDashboard: "get_team_revenue_dashboard_analytics_team_dashboard_get";
+  getTeamRevenueForecast: "get_team_revenue_forecast_analytics_team_forecast_get";
+}
+
+/** Input and output of every `g8.api.revenueAnalytics` operation, keyed by operationId. */
+export interface RevenueAnalyticsOperations {
+  /**
+   * GET /analytics/attribution/acquisition-breakdown
+   * Get Acquisition Breakdown
+   * tier: read · scope: analytics:read
+   */
+  get_acquisition_breakdown_analytics_attribution_acquisition_breakdown_get: {
+    input: {
+    query?: {
+      /** Lookback window. */
+      since_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+  /**
+   * GET /analytics/attribution/sender-performance
+   * Get Sender Performance
+   * tier: read · scope: analytics:read
+   */
+  get_sender_performance_analytics_attribution_sender_performance_get: {
+    input: {
+    query?: {
+      /** Lookback window. */
+      since_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+  /**
+   * GET /analytics/team/conversion-funnel
+   * Get Team Conversion Funnel
+   * tier: read · scope: analytics:read
+   */
+  get_team_conversion_funnel_analytics_team_conversion_funnel_get: {
+    input: {
+    query?: {
+      /** Days to analyse. */
+      period_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+  /**
+   * GET /analytics/team/pipeline-velocity
+   * Get Team Pipeline Velocity
+   * tier: read · scope: analytics:read
+   */
+  get_team_pipeline_velocity_analytics_team_pipeline_velocity_get: {
+    input: {
+    query?: {
+      /** Days to analyse. */
+      period_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+  /**
+   * GET /analytics/team/dashboard
+   * Get Team Revenue Dashboard
+   * tier: read · scope: analytics:read
+   */
+  get_team_revenue_dashboard_analytics_team_dashboard_get: {
+    input: {
+    query?: {
+      /** Days to look back. */
+      period_days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+  /**
+   * GET /analytics/team/forecast
+   * Get Team Revenue Forecast
+   * tier: read · scope: analytics:read
+   */
+  get_team_revenue_forecast_analytics_team_forecast_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RevenueAnalyticsPayload_;
+  };
+}
+
+// 3 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_RevenueAnalyticsPayload_ {
+  data: RevenueAnalyticsPayload;
+  pagination?: PaginationMeta | null;
+}
+
+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;
+}
+
+/** A dashboard or rollup, as the app computes it. */
+export type RevenueAnalyticsPayload = Record<string, unknown>;

package/docs/api/revenueAnalytics.md

@@ -0,0 +1,212 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.revenueAnalytics`: Revenue Analytics
+
+6 operations (6 read).
+
+No hand-written client covers this area. Call it through `g8.api.revenueAnalytics.*` 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: [revenueAnalytics.d.ts](revenueAnalytics.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getAcquisitionBreakdown`](#op-getacquisitionbreakdown) | `GET /api/v1/analytics/attribution/acquisition-breakdown` | read | `analytics:read` | Get Acquisition Breakdown |
+| [`getSenderPerformance`](#op-getsenderperformance) | `GET /api/v1/analytics/attribution/sender-performance` | read | `analytics:read` | Get Sender Performance |
+| [`getTeamConversionFunnel`](#op-getteamconversionfunnel) | `GET /api/v1/analytics/team/conversion-funnel` | read | `analytics:read` | Get Team Conversion Funnel |
+| [`getTeamPipelineVelocity`](#op-getteampipelinevelocity) | `GET /api/v1/analytics/team/pipeline-velocity` | read | `analytics:read` | Get Team Pipeline Velocity |
+| [`getTeamRevenueDashboard`](#op-getteamrevenuedashboard) | `GET /api/v1/analytics/team/dashboard` | read | `analytics:read` | Get Team Revenue Dashboard |
+| [`getTeamRevenueForecast`](#op-getteamrevenueforecast) | `GET /api/v1/analytics/team/forecast` | read | `analytics:read` | Get Team Revenue Forecast |
+
+---
+
+<a id="op-getacquisitionbreakdown"></a>
+
+### `g8.api.revenueAnalytics.getAcquisitionBreakdown(input?)`
+
+**Get Acquisition Breakdown**
+
+- HTTP: `GET /api/v1/analytics/attribution/acquisition-breakdown`
+- operationId: `get_acquisition_breakdown_analytics_attribution_acquisition_breakdown_get` (also callable as `g8.api.call("get_acquisition_breakdown_analytics_attribution_acquisition_breakdown_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Signups by UTM source and campaign.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.since_days` | `integer` | no | Lookback window. default `30` |
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getAcquisitionBreakdown();
+```
+
+---
+
+<a id="op-getsenderperformance"></a>
+
+### `g8.api.revenueAnalytics.getSenderPerformance(input?)`
+
+**Get Sender Performance**
+
+- HTTP: `GET /api/v1/analytics/attribution/sender-performance`
+- operationId: `get_sender_performance_analytics_attribution_sender_performance_get` (also callable as `g8.api.call("get_sender_performance_analytics_attribution_sender_performance_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Sends, clicks and signups per mailbox, sending domain and channel.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.since_days` | `integer` | no | Lookback window. default `30` |
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getSenderPerformance();
+```
+
+---
+
+<a id="op-getteamconversionfunnel"></a>
+
+### `g8.api.revenueAnalytics.getTeamConversionFunnel(input?)`
+
+**Get Team Conversion Funnel**
+
+- HTTP: `GET /api/v1/analytics/team/conversion-funnel`
+- operationId: `get_team_conversion_funnel_analytics_team_conversion_funnel_get` (also callable as `g8.api.call("get_team_conversion_funnel_analytics_team_conversion_funnel_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Account/lead to closed-deal conversion, stage by stage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.period_days` | `integer` | no | Days to analyse. default `90` |
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getTeamConversionFunnel();
+```
+
+---
+
+<a id="op-getteampipelinevelocity"></a>
+
+### `g8.api.revenueAnalytics.getTeamPipelineVelocity(input?)`
+
+**Get Team Pipeline Velocity**
+
+- HTTP: `GET /api/v1/analytics/team/pipeline-velocity`
+- operationId: `get_team_pipeline_velocity_analytics_team_pipeline_velocity_get` (also callable as `g8.api.call("get_team_pipeline_velocity_analytics_team_pipeline_velocity_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+How deals move through pipeline stages: time in stage and conversion.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.period_days` | `integer` | no | Days to analyse. default `90` |
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getTeamPipelineVelocity();
+```
+
+---
+
+<a id="op-getteamrevenuedashboard"></a>
+
+### `g8.api.revenueAnalytics.getTeamRevenueDashboard(input?)`
+
+**Get Team Revenue Dashboard**
+
+- HTTP: `GET /api/v1/analytics/team/dashboard`
+- operationId: `get_team_revenue_dashboard_analytics_team_dashboard_get` (also callable as `g8.api.call("get_team_revenue_dashboard_analytics_team_dashboard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Team-wide pipeline, win and activity metrics over a window.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.period_days` | `integer` | no | Days to look back. default `30` |
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getTeamRevenueDashboard();
+```
+
+---
+
+<a id="op-getteamrevenueforecast"></a>
+
+### `g8.api.revenueAnalytics.getTeamRevenueForecast(input?)`
+
+**Get Team Revenue Forecast**
+
+- HTTP: `GET /api/v1/analytics/team/forecast`
+- operationId: `get_team_revenue_forecast_analytics_team_forecast_get` (also callable as `g8.api.call("get_team_revenue_forecast_analytics_team_forecast_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `analytics:read`
+
+Revenue forecast from the open pipeline and stage probabilities.
+
+**Input**: none.
+
+**Returns** `ApiResponse_RevenueAnalyticsPayload_`: the envelope `{ data: RevenueAnalyticsPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueAnalytics.getTeamRevenueForecast();
+```

package/docs/api/revenueLifecycle.d.ts

@@ -0,0 +1,207 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.revenueLifecycle` (Revenue Lifecycle): 5 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_lifecycle_stage_counts_lifecycle_stages_counts_get">;
+ *
+ * Reference with examples: revenueLifecycle.md
+ */
+/* eslint-disable */
+
+/** `g8.api.revenueLifecycle.<member>` -> the operationId it calls. */
+export interface RevenueLifecycleMembers {
+  getLifecycleStageCounts: "get_lifecycle_stage_counts_lifecycle_stages_counts_get";
+  listLifecycleStageRecords: "list_lifecycle_stage_records_lifecycle_stages__stage__records_get";
+  listLifecycleStages: "list_lifecycle_stages_lifecycle_stages_get";
+  moveCompanyLifecycleStage: "move_company_lifecycle_stage_companies__company_id__lifecycle_stage_post";
+  moveContactLifecycleStage: "move_contact_lifecycle_stage_contacts__contact_id__lifecycle_stage_post";
+}
+
+/** Input and output of every `g8.api.revenueLifecycle` operation, keyed by operationId. */
+export interface RevenueLifecycleOperations {
+  /**
+   * GET /lifecycle-stages/counts
+   * Get Lifecycle Stage Counts
+   * tier: read · scope: deals:read
+   */
+  get_lifecycle_stage_counts_lifecycle_stages_counts_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_str__int__;
+  };
+  /**
+   * GET /lifecycle-stages/{stage}/records
+   * List Lifecycle Stage Records
+   * tier: read · scope: deals:read
+   */
+  list_lifecycle_stage_records_lifecycle_stages__stage__records_get: {
+    input: {
+    path: {
+      /** Lifecycle slug (e.g. 'leads') OR lifecycle entry UUID — either works. */
+      stage: string;
+    };
+    query?: {
+      /** Page number (1-indexed). */
+      page?: number;
+      /** Items per page (max 200). */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_LifecycleRecordItem__;
+  };
+  /**
+   * GET /lifecycle-stages
+   * List Lifecycle Stages
+   * tier: read · scope: deals:read
+   */
+  list_lifecycle_stages_lifecycle_stages_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_LifecycleStageResponse__;
+  };
+  /**
+   * POST /companies/{company_id}/lifecycle-stage
+   * Move Company Lifecycle Stage
+   * tier: write · scope: deals:write
+   */
+  move_company_lifecycle_stage_companies__company_id__lifecycle_stage_post: {
+    input: {
+    path: {
+      /** Company ID (mashup_companies.id, same as GET /companies/{company_id}). */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LifecycleStageMoveRequest;
+  };
+    output: ApiResponse_LifecycleStageMoveResponse_;
+  };
+  /**
+   * POST /contacts/{contact_id}/lifecycle-stage
+   * Move Contact Lifecycle Stage
+   * tier: write · scope: deals:write
+   */
+  move_contact_lifecycle_stage_contacts__contact_id__lifecycle_stage_post: {
+    input: {
+    path: {
+      /** Contact ID — accepts mashup_contacts.CONTACT_ID or .id, same as GET /contacts/{contact_id}. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: LifecycleStageMoveRequest;
+  };
+    output: ApiResponse_LifecycleStageMoveResponse_;
+  };
+}
+
+// 9 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_LifecycleStageMoveResponse_ {
+  data: LifecycleStageMoveResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_str__int__ {
+  data: Record<string, number>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_LifecycleRecordItem__ {
+  data: Array<LifecycleRecordItem>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_LifecycleStageResponse__ {
+  data: Array<LifecycleStageResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * One company-level record in a lifecycle stage.
+ *
+ * Mashup-first: ``company_id`` is ``mashup_companies.id`` — pass it straight
+ * to ``GET /companies/{company_id}`` or ``POST /companies/{company_id}/
+ * lifecycle-stage``. ``status``/``owner_id`` are coalesced across the
+ * ``cb_accounts``/``cb_company_extensions`` overlays exactly like the
+ * in-app Companies lifecycle grid.
+ */
+export interface LifecycleRecordItem {
+  company_id: number;
+  custom_status?: string | null;
+  domain?: string | null;
+  industry?: string | null;
+  mrr_cents?: number | null;
+  name?: string | null;
+  owner_id?: string | null;
+  status?: string | null;
+  subscription_status?: string | null;
+}
+
+export interface LifecycleStageMoveRequest {
+  /** Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. */
+  target_slug: string;
+}
+
+/**
+ * Mirrors the exact dict shape ``set_company_lifecycle_stage`` /
+ * ``set_contact_lifecycle_stage`` return. Contact moves only ever populate
+ * ``custom_status`` (contacts have no company-level ``status`` column), so
+ * ``previous_status``/``new_status`` are null on that path.
+ */
+export interface LifecycleStageMoveResponse {
+  new_custom_status?: string | null;
+  new_status?: string | null;
+  previous_custom_status?: string | null;
+  previous_status?: string | null;
+  target_slug: string;
+}
+
+/**
+ * One configured lifecycle entry (Suspects/Leads/Trial/Customers/Churned,
+ * or a custom org-defined stage).
+ */
+export interface LifecycleStageResponse {
+  /** cb_accounts.custom_status values that also match this stage. */
+  custom_status_match?: Array<string>;
+  description?: string | null;
+  hidden: boolean;
+  icon: string;
+  /** Lifecycle entry UUID — the key `GET /lifecycle-stages/counts` uses. */
+  id: string;
+  name: string;
+  /** Stable machine slug, e.g. 'leads', 'trials'. Accepted by the /records path. */
+  slug: string;
+  sort_order: number;
+  /** cb_accounts.status values that match this stage. */
+  status_match?: Array<string>;
+  /** When set, cb_accounts.subscription_status must also be one of these. */
+  subscription_filter?: Array<string> | null;
+}
+
+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;
+}