@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/revenueRecords.md

@@ -0,0 +1,563 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.revenueRecords`: Revenue Records
+
+15 operations (9 read, 4 write, 1 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.revenueRecords.*` 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: [revenueRecords.d.ts](revenueRecords.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createRevenuePlan`](#op-createrevenueplan) | `POST /api/v1/revenue/plans` | write | `deals:write` | Create Revenue Plan |
+| [`deactivateRevenuePlan`](#op-deactivaterevenueplan) | `DELETE /api/v1/revenue/plans/{plan_id}` | destructive | `deals:delete` | Deactivate Revenue Plan |
+| [`getActivity`](#op-getactivity) | `GET /api/v1/activities/{activity_id}` | read | `deals:read` | Get Activity |
+| [`getActivityMetrics`](#op-getactivitymetrics) | `GET /api/v1/activities/metrics/summary` | read | `deals:read` | Get Activity Metrics |
+| [`getCompanyEvents`](#op-getcompanyevents) | `GET /api/v1/companies/{company_id}/events` | read | `deals:read` | Get Company Events |
+| [`getCompanyLifecycleSnapshot`](#op-getcompanylifecyclesnapshot) | `GET /api/v1/companies/{company_id}/lifecycle-snapshot` | read | `deals:read` | Get Company Lifecycle Snapshot |
+| [`getContactLifecycleSnapshot`](#op-getcontactlifecyclesnapshot) | `GET /api/v1/contacts/{contact_id}/lifecycle-snapshot` | read | `deals:read` | Get Contact Lifecycle Snapshot |
+| [`listCompanyActivities`](#op-listcompanyactivities) | `GET /api/v1/companies/{company_id}/activities` | read | `deals:read` | List Company Activities |
+| [`listDealActivities`](#op-listdealactivities) | `GET /api/v1/deals/{deal_id}/activities` | read | `deals:read` | List Deal Activities |
+| [`listLifecycleContacts`](#op-listlifecyclecontacts) | `GET /api/v1/lifecycle-contacts` | read | `deals:read` | List Lifecycle Contacts |
+| [`listRevenuePlans`](#op-listrevenueplans) | `GET /api/v1/revenue/plans` | read | `deals:read` | List Revenue Plans |
+| [`normalizeRevenuePlans`](#op-normalizerevenueplans) | `POST /api/v1/revenue/plans/normalize` | write | `deals:write` | Normalize Revenue Plans |
+| [`setDefaultPipeline`](#op-setdefaultpipeline) | `PUT /api/v1/deals/pipelines/{pipeline_id}/default` | write | `deals:write` | Set Default Pipeline |
+| [`unlockLifecycleContacts`](#op-unlocklifecyclecontacts) | `POST /api/v1/lifecycle-contacts/unlock` | billable | `deals:run` | Unlock Lifecycle Contacts |
+| [`updateRevenuePlan`](#op-updaterevenueplan) | `PUT /api/v1/revenue/plans/{plan_id}` | write | `deals:write` | Update Revenue Plan |
+
+---
+
+<a id="op-createrevenueplan"></a>
+
+### `g8.api.revenueRecords.createRevenuePlan(input)`
+
+**Create Revenue Plan**
+
+- HTTP: `POST /api/v1/revenue/plans`
+- operationId: `create_revenue_plan_revenue_plans_post` (also callable as `g8.api.call("create_revenue_plan_revenue_plans_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Add a plan. The slug is unique per org.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RevenuePlanCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`RevenuePlanCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 255 |
+| `body.list_price_cents` | `integer \| null` | no | min 0 |
+| `body.mrr_band` | `"<1k" \| "1k-5k" \| "5k-25k" \| ">25k" \| null` | no |  |
+| `body.slug` | `string \| null` | no | Derived from `name` when omitted. max length 255 |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.createRevenuePlan({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-deactivaterevenueplan"></a>
+
+### `g8.api.revenueRecords.deactivateRevenuePlan(input)`
+
+**Deactivate Revenue Plan**
+
+- HTTP: `DELETE /api/v1/revenue/plans/{plan_id}`
+- operationId: `deactivate_revenue_plan_revenue_plans__plan_id__delete` (also callable as `g8.api.call("deactivate_revenue_plan_revenue_plans__plan_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Deactivate a plan. Accounts already on it keep it; it just stops being offered.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.plan_id` | `string` | yes | Plan id. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `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.revenueRecords.deactivateRevenuePlan({ path: { plan_id: "id" } });
+```
+
+---
+
+<a id="op-getactivity"></a>
+
+### `g8.api.revenueRecords.getActivity(input)`
+
+**Get Activity**
+
+- HTTP: `GET /api/v1/activities/{activity_id}`
+- operationId: `get_activity_activities__activity_id__get` (also callable as `g8.api.call("get_activity_activities__activity_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+One activity.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.activity_id` | `string` | yes | Activity id. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.getActivity({ path: { activity_id: "id" } });
+```
+
+---
+
+<a id="op-getactivitymetrics"></a>
+
+### `g8.api.revenueRecords.getActivityMetrics(input?)`
+
+**Get Activity Metrics**
+
+- HTTP: `GET /api/v1/activities/metrics/summary`
+- operationId: `get_activity_metrics_activities_metrics_summary_get` (also callable as `g8.api.call("get_activity_metrics_activities_metrics_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Activity counts and trends over a window.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.period_days` | `integer` | no | Days to analyse. default `30` |
+| `query.owner_id` | `string \| null` | no | Only this owner's activities. |
+| `query.source` | `string \| null` | no | Only activities from this source. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.getActivityMetrics();
+```
+
+---
+
+<a id="op-getcompanyevents"></a>
+
+### `g8.api.revenueRecords.getCompanyEvents(input)`
+
+**Get Company Events**
+
+- HTTP: `GET /api/v1/companies/{company_id}/events`
+- operationId: `get_company_events_companies__company_id__events_get` (also callable as `g8.api.call("get_company_events_companies__company_id__events_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Counts of named product events for a company over a window.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Account or company id. |
+| `query.names` | `string` | yes | Comma-separated event names. |
+| `query.window_days` | `integer` | no | default `30` |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.getCompanyEvents({ path: { company_id: "id" }, query: { names: "Example" } });
+```
+
+---
+
+<a id="op-getcompanylifecyclesnapshot"></a>
+
+### `g8.api.revenueRecords.getCompanyLifecycleSnapshot(input)`
+
+**Get Company Lifecycle Snapshot**
+
+- HTTP: `GET /api/v1/companies/{company_id}/lifecycle-snapshot`
+- operationId: `get_company_lifecycle_snapshot_companies__company_id__lifecycle_snapshot_get` (also callable as `g8.api.call("get_company_lifecycle_snapshot_companies__company_id__lifecycle_snapshot_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The lifecycle-aware snapshot of one company: stage, and the event counts that matter for it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Account, company-extension or company id. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.getCompanyLifecycleSnapshot({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-getcontactlifecyclesnapshot"></a>
+
+### `g8.api.revenueRecords.getContactLifecycleSnapshot(input)`
+
+**Get Contact Lifecycle Snapshot**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/lifecycle-snapshot`
+- operationId: `get_contact_lifecycle_snapshot_contacts__contact_id__lifecycle_snapshot_get` (also callable as `g8.api.call("get_contact_lifecycle_snapshot_contacts__contact_id__lifecycle_snapshot_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The lifecycle-aware snapshot of one contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.getContactLifecycleSnapshot({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-listcompanyactivities"></a>
+
+### `g8.api.revenueRecords.listCompanyActivities(input)`
+
+**List Company Activities**
+
+- HTTP: `GET /api/v1/companies/{company_id}/activities`
+- operationId: `list_company_activities_companies__company_id__activities_get` (also callable as `g8.api.call("list_company_activities_companies__company_id__activities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+A company's activity timeline, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `string` | yes | Company id. |
+| `query.activity_type` | `string \| null` | no |  |
+| `query.source` | `string \| null` | no | Only activities from this source. |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_RevenueRecordListPayload_`: the envelope `{ data: RevenueRecordListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RevenueRecordListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.listCompanyActivities({ path: { company_id: "id" } });
+```
+
+---
+
+<a id="op-listdealactivities"></a>
+
+### `g8.api.revenueRecords.listDealActivities(input)`
+
+**List Deal Activities**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/activities`
+- operationId: `list_deal_activities_deals__deal_id__activities_get` (also callable as `g8.api.call("list_deal_activities_deals__deal_id__activities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+A deal's activity timeline, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal id. |
+| `query.activity_type` | `string \| null` | no |  |
+| `query.source` | `string \| null` | no | Only activities from this source. |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_RevenueRecordListPayload_`: the envelope `{ data: RevenueRecordListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RevenueRecordListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.listDealActivities({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listlifecyclecontacts"></a>
+
+### `g8.api.revenueRecords.listLifecycleContacts(input)`
+
+**List Lifecycle Contacts**
+
+- HTTP: `GET /api/v1/lifecycle-contacts`
+- operationId: `list_lifecycle_contacts_lifecycle_contacts_get` (also callable as `g8.api.call("list_lifecycle_contacts_lifecycle_contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The contacts in one lifecycle stage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.lifecycle_id` | `string` | yes | The lifecycle stage. |
+| `query.skip` | `integer` | no | default `0` |
+| `query.limit` | `integer \| null` | no |  |
+| `query.company_status` | `string \| null` | no |  |
+| `query.search` | `string \| null` | no |  |
+| `query.agFilterModel` | `string \| null` | no | JSON grid filter model. |
+| `query.agSortModel` | `string \| null` | no | JSON grid sort model. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.listLifecycleContacts({ query: { lifecycle_id: "id" } });
+```
+
+---
+
+<a id="op-listrevenueplans"></a>
+
+### `g8.api.revenueRecords.listRevenuePlans(input?)`
+
+**List Revenue Plans**
+
+- HTTP: `GET /api/v1/revenue/plans`
+- operationId: `list_revenue_plans_revenue_plans_get` (also callable as `g8.api.call("list_revenue_plans_revenue_plans_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The org's plan catalog, active plans first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_inactive` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.listRevenuePlans();
+```
+
+---
+
+<a id="op-normalizerevenueplans"></a>
+
+### `g8.api.revenueRecords.normalizeRevenuePlans(input?)`
+
+**Normalize Revenue Plans**
+
+- HTTP: `POST /api/v1/revenue/plans/normalize`
+- operationId: `normalize_revenue_plans_revenue_plans_normalize_post` (also callable as `g8.api.call("normalize_revenue_plans_revenue_plans_normalize_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Match every account's free-text plan to a catalog plan, and report what did not match.
+
+**Input**: none.
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.normalizeRevenuePlans();
+```
+
+---
+
+<a id="op-setdefaultpipeline"></a>
+
+### `g8.api.revenueRecords.setDefaultPipeline(input)`
+
+**Set Default Pipeline**
+
+- HTTP: `PUT /api/v1/deals/pipelines/{pipeline_id}/default`
+- operationId: `set_default_pipeline_deals_pipelines__pipeline_id__default_put` (also callable as `g8.api.call("set_default_pipeline_deals_pipelines__pipeline_id__default_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Make a pipeline the org default. Every other pipeline stops being the default.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.pipeline_id` | `string` | yes | Pipeline id. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.setDefaultPipeline({ path: { pipeline_id: "id" } });
+```
+
+---
+
+<a id="op-unlocklifecyclecontacts"></a>
+
+### `g8.api.revenueRecords.unlockLifecycleContacts(input)`
+
+**Unlock Lifecycle Contacts**
+
+- HTTP: `POST /api/v1/lifecycle-contacts/unlock`
+- operationId: `unlock_lifecycle_contacts_lifecycle_contacts_unlock_post` (also callable as `g8.api.call("unlock_lifecycle_contacts_lifecycle_contacts_unlock_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Unlock contact details in a lifecycle stage (charges credits per newly unlocked contact).
+
+Contacts already unlocked cost nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `LifecycleContactsUnlockRequest` | yes | Request body; fields below. |
+
+Body fields (`LifecycleContactsUnlockRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lifecycle_id` | `string` | yes | The lifecycle stage to unlock contacts in. |
+| `body.agFilterModel` | `Record<string, unknown> \| null` | no | Grid filter model. With no `contact_ids`, every matching contact in the stage is unlocked; with neither, the WHOLE stage is. |
+| `body.company_status` | `string \| null` | no | Comma-separated company_status narrowing. |
+| `body.contact_ids` | `Array<integer> \| null` | no | Unlock exactly these. Takes precedence over `agFilterModel`. |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.revenueRecords.unlockLifecycleContacts({ body: { lifecycle_id: "id" } });
+```
+
+---
+
+<a id="op-updaterevenueplan"></a>
+
+### `g8.api.revenueRecords.updateRevenuePlan(input)`
+
+**Update Revenue Plan**
+
+- HTTP: `PUT /api/v1/revenue/plans/{plan_id}`
+- operationId: `update_revenue_plan_revenue_plans__plan_id__put` (also callable as `g8.api.call("update_revenue_plan_revenue_plans__plan_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Edit any subset of a plan's fields.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.plan_id` | `string` | yes | Plan id. |
+| `body` | `RevenuePlanUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`RevenuePlanUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.active` | `boolean \| null` | no |  |
+| `body.list_price_cents` | `integer \| null` | no | min 0 |
+| `body.mrr_band` | `"<1k" \| "1k-5k" \| "5k-25k" \| ">25k" \| null` | no |  |
+| `body.name` | `string \| null` | no | min length 1, max length 255 |
+| `body.slug` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_RevenueRecordPayload_`: the envelope `{ data: RevenueRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenueRecords.updateRevenuePlan({ path: { plan_id: "id" }, body: {} });
+```