@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/revenue.md

@@ -0,0 +1,608 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.revenue`: Revenue
+
+14 operations (7 read, 3 write, 3 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.revenue.*` 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: [revenue.d.ts](revenue.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`cancelStageDocBackfillJob`](#op-cancelstagedocbackfilljob) | `POST /api/v1/revenue/backfills/{job_id}/cancel` | destructive | `deals:delete` | Cancel Stage Doc Backfill Job |
+| [`estimateAllStageDocBackfills`](#op-estimateallstagedocbackfills) | `POST /api/v1/revenue/backfills/estimate` | read | `deals:read` | Estimate All Stage Doc Backfills |
+| [`estimateStageDocBackfill`](#op-estimatestagedocbackfill) | `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill/estimate` | read | `deals:read` | Estimate Stage Doc Backfill |
+| [`getEventCatalog`](#op-geteventcatalog) | `GET /api/v1/revenue/lifecycle/event-catalog` | read | `deals:read` | Get Event Catalog |
+| [`getStageDocBackfillJob`](#op-getstagedocbackfilljob) | `GET /api/v1/revenue/backfills/{job_id}` | read | `deals:read` | Get Stage Doc Backfill Job |
+| [`getStageDocCatalog`](#op-getstagedoccatalog) | `GET /api/v1/revenue/stage-docs/catalog` | read | `deals:read` | Get Stage Doc Catalog |
+| [`getStageDocDefaults`](#op-getstagedocdefaults) | `GET /api/v1/revenue/stage-docs/defaults` | read | `deals:read` | Get Stage Doc Defaults |
+| [`getStageDocSlot`](#op-getstagedocslot) | `GET /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}` | read | `deals:read` | Get Stage Doc Slot |
+| [`patchStageDocSlot`](#op-patchstagedocslot) | `PATCH /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}` | write | `deals:write` | Patch Stage Doc Slot |
+| [`resetStageDocSlot`](#op-resetstagedocslot) | `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/reset` | destructive | `deals:delete` | Reset Stage Doc Slot |
+| [`seedLifecycleDefaults`](#op-seedlifecycledefaults) | `POST /api/v1/revenue/lifecycle/seed-defaults` | destructive | `deals:delete` | Seed Lifecycle Defaults |
+| [`startStageDocBackfill`](#op-startstagedocbackfill) | `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill` | billable | `knowledge:run` | Start Stage Doc Backfill |
+| [`syncLifecycleLists`](#op-synclifecyclelists) | `POST /api/v1/revenue/lifecycle/sync-lists` | write | `deals:write` | Sync Lifecycle Lists |
+| [`updateLifecycles`](#op-updatelifecycles) | `PUT /api/v1/revenue/lifecycle` | write | `deals:write` | Update Lifecycles |
+
+---
+
+<a id="op-cancelstagedocbackfilljob"></a>
+
+### `g8.api.revenue.cancelStageDocBackfillJob(input)`
+
+**Cancel Stage Doc Backfill Job**
+
+- HTTP: `POST /api/v1/revenue/backfills/{job_id}/cancel`
+- operationId: `cancel_stage_doc_backfill_job_revenue_backfills__job_id__cancel_post` (also callable as `g8.api.call("cancel_stage_doc_backfill_job_revenue_backfills__job_id__cancel_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Stop a running backfill, and stop it spending.
+
+IDEMPOTENT: a job that already finished or failed comes back with the
+status it has, not an error. Credits already spent are not refunded -
+cancelling stops the next document, it does not undo the last one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Backfill job id (UUID). |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `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.revenue.cancelStageDocBackfillJob({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-estimateallstagedocbackfills"></a>
+
+### `g8.api.revenue.estimateAllStageDocBackfills(input?)`
+
+**Estimate All Stage Doc Backfills**
+
+- HTTP: `POST /api/v1/revenue/backfills/estimate`
+- operationId: `estimate_all_stage_doc_backfills_revenue_backfills_estimate_post` (also callable as `g8.api.call("estimate_all_stage_doc_backfills_revenue_backfills_estimate_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What backfilling EVERY stage and both entities would cost. Spends nothing.
+
+The totals plus a per-stage, per-entity breakdown. Published although the
+matching "start them all" route is NOT (see the module docstring): seeing
+the whole bill in one call is exactly what a caller needs before deciding
+which stages to backfill, and this one cannot spend anything.
+
+Declared BEFORE `/backfills/{job_id}` so the literal wins. The two do not
+actually collide - one is a POST and the other a GET - but the ordering is
+the habit, and the test checks the job route still resolves.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.estimateAllStageDocBackfills();
+```
+
+---
+
+<a id="op-estimatestagedocbackfill"></a>
+
+### `g8.api.revenue.estimateStageDocBackfill(input)`
+
+**Estimate Stage Doc Backfill**
+
+- HTTP: `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill/estimate`
+- operationId: `estimate_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_estimate_post` (also callable as `g8.api.call("estimate_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_estimate_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What a backfill of this stage WOULD cost. Spends nothing.
+
+Records affected, documents to generate, and credits. It counts and
+returns; it queues no job and writes nothing. Call it first and use
+`estimated_credits` as the `max_credits` you send to the backfill below.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lifecycle_entry_id` | `string` | yes | Lifecycle stage id (UUID). |
+| `path.entity` | `"company" \| "contact"` | yes | Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.estimateStageDocBackfill({ path: { lifecycle_entry_id: "id", entity: "company" } });
+```
+
+---
+
+<a id="op-geteventcatalog"></a>
+
+### `g8.api.revenue.getEventCatalog(input?)`
+
+**Get Event Catalog**
+
+- HTTP: `GET /api/v1/revenue/lifecycle/event-catalog`
+- operationId: `get_event_catalog_revenue_lifecycle_event_catalog_get` (also callable as `g8.api.call("get_event_catalog_revenue_lifecycle_event_catalog_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Product events seen for this org in the last 30 days, busiest first.
+
+The source of the `event_name` values a stage's `event_tracking` config
+accepts - configure one that has never fired and the stage tracks nothing.
+
+A brand-new org has no events table yet; that is an empty list, not an
+error.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportListPayload_`: the envelope `{ data: ReportListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.getEventCatalog();
+```
+
+---
+
+<a id="op-getstagedocbackfilljob"></a>
+
+### `g8.api.revenue.getStageDocBackfillJob(input)`
+
+**Get Stage Doc Backfill Job**
+
+- HTTP: `GET /api/v1/revenue/backfills/{job_id}`
+- operationId: `get_stage_doc_backfill_job_revenue_backfills__job_id__get` (also callable as `g8.api.call("get_stage_doc_backfill_job_revenue_backfills__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+How a backfill is going: status, progress, credits USED so far, errors.
+
+`credits_used` is the number that matters while a job runs - it is the
+spend that has actually happened, against the `max_credits` ceiling the
+job was started with.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `string` | yes | Backfill job id (UUID). |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.getStageDocBackfillJob({ path: { job_id: "id" } });
+```
+
+---
+
+<a id="op-getstagedoccatalog"></a>
+
+### `g8.api.revenue.getStageDocCatalog(input?)`
+
+**Get Stage Doc Catalog**
+
+- HTTP: `GET /api/v1/revenue/stage-docs/catalog`
+- operationId: `get_stage_doc_catalog_revenue_stage_docs_catalog_get` (also callable as `g8.api.call("get_stage_doc_catalog_revenue_stage_docs_catalog_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Every document type a stage can generate, with its tier and grounding.
+
+The source of the `type` values `PATCH /revenue/stage-docs/{id}/{entity}`
+accepts, and of the `tier` that decides what each one costs. Read it before
+configuring a slot: a type is only offerable for certain stages and
+entities, and both are listed here.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportListPayload_`: the envelope `{ data: ReportListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.getStageDocCatalog();
+```
+
+---
+
+<a id="op-getstagedocdefaults"></a>
+
+### `g8.api.revenue.getStageDocDefaults(input?)`
+
+**Get Stage Doc Defaults**
+
+- HTTP: `GET /api/v1/revenue/stage-docs/defaults`
+- operationId: `get_stage_doc_defaults_revenue_stage_docs_defaults_get` (also callable as `g8.api.call("get_stage_doc_defaults_revenue_stage_docs_defaults_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The whole document-defaults matrix - every stage, both entities.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.getStageDocDefaults();
+```
+
+---
+
+<a id="op-getstagedocslot"></a>
+
+### `g8.api.revenue.getStageDocSlot(input)`
+
+**Get Stage Doc Slot**
+
+- HTTP: `GET /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}`
+- operationId: `get_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__get` (also callable as `g8.api.call("get_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+One stage's document configuration for one entity kind.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lifecycle_entry_id` | `string` | yes | Lifecycle stage id (UUID). |
+| `path.entity` | `"company" \| "contact"` | yes | Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.getStageDocSlot({ path: { lifecycle_entry_id: "id", entity: "company" } });
+```
+
+---
+
+<a id="op-patchstagedocslot"></a>
+
+### `g8.api.revenue.patchStageDocSlot(input)`
+
+**Patch Stage Doc Slot**
+
+- HTTP: `PATCH /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}`
+- operationId: `patch_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__patch` (also callable as `g8.api.call("patch_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Change one stage's document configuration for one entity kind.
+
+A MERGE: only the fields you send are applied. A field cannot be CLEARED
+by sending null - the app drops nulls from the patch rather than writing
+them - so send the value you want instead.
+
+`auto_generate` is the switch that costs money: with it on, every record
+that ARRIVES in this stage generates its `docs` immediately. `credit_cap`
+bounds that ongoing spend; the types come from
+`GET /revenue/stage-docs/catalog`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lifecycle_entry_id` | `string` | yes | Lifecycle stage id (UUID). |
+| `path.entity` | `"company" \| "contact"` | yes | Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. |
+| `body` | `StageDocSlotPatchRequest` | yes | Request body; fields below. |
+
+Body fields (`StageDocSlotPatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.auto_generate` | `boolean \| null` | no |  |
+| `body.credit_cap` | `integer \| null` | no | min 0 |
+| `body.docs` | `Array<StageDocSpecRequest> \| null` | no |  |
+| `body.on_demand` | `Array<string> \| null` | no |  |
+| `body.reuse_if_fresh_days` | `integer \| null` | no | min 0, max 365 |
+| `body.top_n_contacts` | `integer \| null` | no | min 1, max 100 |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.patchStageDocSlot({ path: { lifecycle_entry_id: "id", entity: "company" }, body: {} });
+```
+
+---
+
+<a id="op-resetstagedocslot"></a>
+
+### `g8.api.revenue.resetStageDocSlot(input)`
+
+**Reset Stage Doc Slot**
+
+- HTTP: `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/reset`
+- operationId: `reset_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__reset_post` (also callable as `g8.api.call("reset_stage_doc_slot_revenue_stage_docs__lifecycle_entry_id___entity__reset_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Put one slot back to its seeded default. Discards the configuration.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lifecycle_entry_id` | `string` | yes | Lifecycle stage id (UUID). |
+| `path.entity` | `"company" \| "contact"` | yes | Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `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.revenue.resetStageDocSlot({ path: { lifecycle_entry_id: "id", entity: "company" } });
+```
+
+---
+
+<a id="op-seedlifecycledefaults"></a>
+
+### `g8.api.revenue.seedLifecycleDefaults(input?)`
+
+**Seed Lifecycle Defaults**
+
+- HTTP: `POST /api/v1/revenue/lifecycle/seed-defaults`
+- operationId: `seed_lifecycle_defaults_revenue_lifecycle_seed_defaults_post` (also callable as `g8.api.call("seed_lifecycle_defaults_revenue_lifecycle_seed_defaults_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `deals:delete`
+
+Force-replace the stage config with the four seeded defaults.
+
+DESTRUCTIVE, and the app's own word for it is "force-replace": every
+custom stage and every document default attached to it is gone. Recoverable
+only by PUTting the old config back, so read it first if you might want it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `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.revenue.seedLifecycleDefaults();
+```
+
+---
+
+<a id="op-startstagedocbackfill"></a>
+
+### `g8.api.revenue.startStageDocBackfill(input)`
+
+**Start Stage Doc Backfill**
+
+- HTTP: `POST /api/v1/revenue/stage-docs/{lifecycle_entry_id}/{entity}/backfill`
+- operationId: `start_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_post` (also callable as `g8.api.call("start_stage_doc_backfill_revenue_stage_docs__lifecycle_entry_id___entity__backfill_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `knowledge:run`
+
+Generate this stage's documents for records already in it. SPENDS CREDITS.
+
+Queues a job and returns its id - poll `GET /revenue/backfills/{job_id}`.
+The work is asynchronous, so a 202 here is not a completed backfill and not
+a completed CHARGE either; the spend accrues as documents are produced.
+
+`max_credits` is a hard ceiling the worker enforces, not advice: the job
+stops the moment spend reaches it. `confirm` must be true - the app refuses
+the call otherwise, deliberately, because this is the one route here that
+costs money.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.lifecycle_entry_id` | `string` | yes | Lifecycle stage id (UUID). |
+| `path.entity` | `"company" \| "contact"` | yes | Which record kind the stage's documents are for. `company` and `contact` are configured independently - the same stage can generate documents for one and not the other. |
+| `body` | `StageBackfillRequest` | yes | Request body; fields below. |
+
+Body fields (`StageBackfillRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.confirm` | `boolean` | yes | Must be true. The app refuses the call with 400 otherwise - a deliberate second hand on a job that spends credits. |
+| `body.max_credits` | `integer` | yes | Hard credit ceiling for this job. The worker stops when spend reaches it. REQUIRED - there is no default, because a default would be a number nobody chose. min 0 |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `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.revenue.startStageDocBackfill({
+  path: { lifecycle_entry_id: "id", entity: "company" },
+  body: { confirm: true, max_credits: 0 },
+});
+```
+
+---
+
+<a id="op-synclifecyclelists"></a>
+
+### `g8.api.revenue.syncLifecycleLists(input?)`
+
+**Sync Lifecycle Lists**
+
+- HTTP: `POST /api/v1/revenue/lifecycle/sync-lists`
+- operationId: `sync_lifecycle_lists_revenue_lifecycle_sync_lists_post` (also callable as `g8.api.call("sync_lifecycle_lists_revenue_lifecycle_sync_lists_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Rebuild the saved list behind each lifecycle stage.
+
+202 and returns immediately - the rebuild runs in the background and there
+is no job id to poll, by the app's design. Call it after changing what a
+stage matches; membership is recomputed from the new rules.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.syncLifecycleLists();
+```
+
+---
+
+<a id="op-updatelifecycles"></a>
+
+### `g8.api.revenue.updateLifecycles(input)`
+
+**Update Lifecycles**
+
+- HTTP: `PUT /api/v1/revenue/lifecycle`
+- operationId: `update_lifecycles_revenue_lifecycle_put` (also callable as `g8.api.call("update_lifecycles_revenue_lifecycle_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+REPLACE the whole set of Revenue lifecycle stages.
+
+Not a merge. The posted `entries` array becomes the config, so a stage left
+out of it is DELETED along with the document defaults attached to it. Read
+`GET /lifecycle-stages` first and send the full list back with your change
+applied.
+
+An entry with an empty `id` is treated as NEW and gets a fresh UUID. An
+entry that keeps its id keeps its stage document defaults - those are
+merged forward by id, not rebuilt.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UpdateLifecyclesRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateLifecyclesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entries` | `Array<LifecycleEntryRequest>` | yes |  |
+
+**Returns** `ApiResponse_ReportPayload_`: the envelope `{ data: ReportPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.revenue.updateLifecycles({
+  body: { entries: [{ id: "id", name: "Example", slug: "example" }] },
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-lifecycleentryrequest"></a>
+
+### `LifecycleEntryRequest`
+
+One Revenue lifecycle stage. `id` is REQUIRED and may be the empty string: the app assigns a fresh UUID to any entry that arrives without one, which is how a new stage is created. Mirrored as required-but-emptyable rather than optional so the field cannot be omitted by accident on an entry that was meant to be an UPDATE - a missing id there does not fail, it silently creates a duplicate stage and orphans the original's documents.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `name` | `string` | yes | min length 1, max length 64 |
+| `slug` | `string` | yes | min length 1, max length 64 |
+| `auto_hide_if_empty` | `boolean` | no | default `true` |
+| `churn_reason_categories` | `Array<string> \| null` | no |  |
+| `custom_status_match` | `Array<string>` | no |  |
+| `description` | `string \| null` | no |  |
+| `event_tracking` | `LifecycleEventTrackingRequest \| null` | no |  |
+| `hidden` | `boolean` | no | default `false` |
+| `icon` | `string` | no | default `"Target"` |
+| `is_system_seed` | `boolean` | no | default `false` |
+| `sort_order` | `integer` | no | default `0` |
+| `status_match` | `Array<string>` | no |  |
+| `subscription_filter` | `Array<string> \| null` | no |  |
+
+<a id="type-stagedocspecrequest"></a>
+
+### `StageDocSpecRequest`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | `string` | yes | min length 1, max length 100 |
+| `mandatory` | `boolean` | no | default `false` |
+| `schedule` | `Record<string, unknown> \| null` | no |  |
+| `tier` | `string` | no | default `"sonnet"`, min length 1, max length 32 |
+| `trigger` | `"instant" \| "scheduled"` | no | default `"instant"` |