@graph8/sdk 0.308.1 → 0.358.0

package/docs/api/reports.md

@@ -0,0 +1,539 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.reports`: Reports
+
+7 operations (2 read, 4 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.reports.*` 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: [reports.d.ts](reports.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`archiveObjectReportApi`](#op-archiveobjectreportapi) | `DELETE /api/v1/reports/{report_id}` | destructive | `objects:delete` | Archive Object Report Api |
+| [`createObjectReportApi`](#op-createobjectreportapi) | `POST /api/v1/reports` | write | `objects:write` | Create Object Report Api |
+| [`executeObjectReportApi`](#op-executeobjectreportapi) | `POST /api/v1/reports/{report_id}/execute` | write | `objects:read` | Execute Object Report Api |
+| [`getObjectReportApi`](#op-getobjectreportapi) | `GET /api/v1/reports/{report_id}` | read | `objects:read` | Get Object Report Api |
+| [`listObjectReportsApi`](#op-listobjectreportsapi) | `GET /api/v1/reports` | read | `objects:read` | List Object Reports Api |
+| [`previewObjectReportApi`](#op-previewobjectreportapi) | `POST /api/v1/reports/preview` | write | `objects:read` | Preview Object Report Api |
+| [`updateObjectReportApi`](#op-updateobjectreportapi) | `PATCH /api/v1/reports/{report_id}` | write | `objects:write` | Update Object Report Api |
+
+---
+
+<a id="op-archiveobjectreportapi"></a>
+
+### `g8.api.reports.archiveObjectReportApi(input)`
+
+**Archive Object Report Api**
+
+- HTTP: `DELETE /api/v1/reports/{report_id}`
+- operationId: `archive_object_report_api_reports__report_id__delete` (also callable as `g8.api.call("archive_object_report_api_reports__report_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:delete`
+
+Delete (archive) a report this credential owns. Does not touch the source's records.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_NoneType_`: the envelope `{ data: null, ... }`. `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.reports.archiveObjectReportApi({ path: { report_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-createobjectreportapi"></a>
+
+### `g8.api.reports.createObjectReportApi(input)`
+
+**Create Object Report Api**
+
+- HTTP: `POST /api/v1/reports`
+- operationId: `create_object_report_api_reports_post` (also callable as `g8.api.call("create_object_report_api_reports_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Save a report owned by this credential. Private by default; a shared one (``visibility: "org"``) needs
+``objects:manage`` and current Admin access. Fields the credential cannot see are unknown to it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ReportCreate` | yes | Request body; fields below. |
+
+Body fields (`ReportCreate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `body.config` | `ReportConfig` | yes |  |
+| `body.object_slug` | `string` | yes | min length 1, max length 100 |
+| `body.title` | `string` | yes | min length 1, max length 200 |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.visibility` | `"private" \| "org"` | no | default `"private"` |
+
+**Returns** `ApiResponse_ReportDefinitionResponse_`: the envelope `{ data: ReportDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_delete` | `boolean` | yes |  |
+| `can_edit` | `boolean` | yes |  |
+| `chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `config` | `Record<string, unknown>` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_owner` | `boolean` | yes |  |
+| `owner` | `ReportOwner` | yes |  |
+| `revision` | `integer` | yes |  |
+| `source` | `ReportSource` | yes |  |
+| `title` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `visibility` | `"private" \| "org"` | yes |  |
+| `description` | `string \| null` | no |  |
+| `restricted` | `Array<RestrictedComponent>` | no |  |
+| `restricted_count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.reports.createObjectReportApi({
+  body: {
+    chart_type: "table",
+    config: {},
+    object_slug: "example",
+    title: "Example",
+  },
+});
+```
+
+---
+
+<a id="op-executeobjectreportapi"></a>
+
+### `g8.api.reports.executeObjectReportApi(input)`
+
+**Execute Object Report Api**
+
+- HTTP: `POST /api/v1/reports/{report_id}/execute`
+- operationId: `execute_object_report_api_reports__report_id__execute_post` (also callable as `g8.api.call("execute_object_report_api_reports__report_id__execute_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:read`
+
+Run a saved report as this credential, now or as of a past date; with ``drilldown`` open the records behind a
+number. A source that was archived is a 409; a config the schema no longer fits is a 422; over 10 s is a 504.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string (uuid)` | yes |  |
+| `body` | `ReportRun` | yes | Request body; fields below. |
+
+Body fields (`ReportRun`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.as_of` | `string (date) \| null` | no |  |
+| `body.drilldown` | `DrilldownRequest \| null` | no |  |
+
+**Returns** `ReportRunApiResponse`: the envelope `{ data: ReportResult | DrilldownResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.reports.executeObjectReportApi({
+  path: { report_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-getobjectreportapi"></a>
+
+### `g8.api.reports.getObjectReportApi(input)`
+
+**Get Object Report Api**
+
+- HTTP: `GET /api/v1/reports/{report_id}`
+- operationId: `get_object_report_api_reports__report_id__get` (also callable as `g8.api.call("get_object_report_api_reports__report_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+One report. A part of it this credential cannot see comes back as ``{"id": ..., "restricted": true}``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_ReportDefinitionResponse_`: the envelope `{ data: ReportDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_delete` | `boolean` | yes |  |
+| `can_edit` | `boolean` | yes |  |
+| `chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `config` | `Record<string, unknown>` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_owner` | `boolean` | yes |  |
+| `owner` | `ReportOwner` | yes |  |
+| `revision` | `integer` | yes |  |
+| `source` | `ReportSource` | yes |  |
+| `title` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `visibility` | `"private" \| "org"` | yes |  |
+| `description` | `string \| null` | no |  |
+| `restricted` | `Array<RestrictedComponent>` | no |  |
+| `restricted_count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.reports.getObjectReportApi({ path: { report_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listobjectreportsapi"></a>
+
+### `g8.api.reports.listObjectReportsApi(input?)`
+
+**List Object Reports Api**
+
+- HTTP: `GET /api/v1/reports`
+- operationId: `list_object_reports_api_reports_get` (also callable as `g8.api.call("list_object_reports_api_reports_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+
+List the reports this credential may open: its own, and shared ones whose source it can read. ``owner=me``
+narrows to this credential's. ``can_share`` says whether it may save a shared report.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.object_slug` | `string \| null` | no |  |
+| `query.owner` | `string \| null` | no |  |
+| `query.visibility` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_ReportListResponse_`: the envelope `{ data: ReportListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_share` | `boolean` | yes |  |
+| `reports` | `Array<ReportDefinitionResponse>` | yes |  |
+| `total` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.reports.listObjectReportsApi();
+```
+
+---
+
+<a id="op-previewobjectreportapi"></a>
+
+### `g8.api.reports.previewObjectReportApi(input)`
+
+**Preview Object Report Api**
+
+- HTTP: `POST /api/v1/reports/preview`
+- operationId: `preview_object_report_api_reports_preview_post` (also callable as `g8.api.call("preview_object_report_api_reports_preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:read`
+
+Run an unsaved report with this credential's own access and a 10 second budget (nothing partial is returned).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ReportPreview` | yes | Request body; fields below. |
+
+Body fields (`ReportPreview`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `body.config` | `ReportConfig` | yes |  |
+| `body.object_slug` | `string` | yes | min length 1, max length 100 |
+| `body.as_of` | `string (date) \| null` | no |  |
+
+**Returns** `ApiResponse_ReportResult_`: the envelope `{ data: ReportResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `source` | `ReportSource` | yes |  |
+| `timezone` | `string` | yes |  |
+| `as_of` | `AsOf \| null` | no |  |
+| `chart_limit` | `integer` | no | default `20` |
+| `chart_other` | `ChartOther \| null` | no |  |
+| `chart_truncated` | `boolean` | no | default `false` |
+| `columns` | `Array<ResultColumn>` | no |  |
+| `disclosures` | `Array<string>` | no |  |
+| `gaps` | `Array<GapNote>` | no |  |
+| `history_supported` | `boolean` | no | default `true` |
+| `kind` | `"result"` | no | default `"result"` |
+| `restricted` | `Array<RestrictedComponent>` | no |  |
+| `row_limit` | `integer` | no | default `500` |
+| `rows` | `Array<ResultRow>` | no |  |
+| `status` | `"ok" \| "restricted"` | no | default `"ok"` |
+| `total_base_records` | `integer` | no | default `0` |
+| `total_groups` | `integer` | no | default `0` |
+| `totals` | `ResultTotals \| null` | no |  |
+| `truncated` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.reports.previewObjectReportApi({ body: { chart_type: "table", config: {}, object_slug: "example" } });
+```
+
+---
+
+<a id="op-updateobjectreportapi"></a>
+
+### `g8.api.reports.updateObjectReportApi(input)`
+
+**Update Object Report Api**
+
+- HTTP: `PATCH /api/v1/reports/{report_id}`
+- operationId: `update_object_report_api_reports__report_id__patch` (also callable as `g8.api.call("update_object_report_api_reports__report_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+
+Edit a report this credential owns. ``expected_revision`` guards a concurrent edit (409).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string (uuid)` | yes |  |
+| `body` | `ReportUpdate` | yes | Request body; fields below. |
+
+Body fields (`ReportUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage" \| null` | no |  |
+| `body.config` | `ReportConfig \| null` | no |  |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.title` | `string \| null` | no | min length 1, max length 200 |
+| `body.visibility` | `"private" \| "org" \| null` | no |  |
+
+**Returns** `ApiResponse_ReportDefinitionResponse_`: the envelope `{ data: ReportDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ReportDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_delete` | `boolean` | yes |  |
+| `can_edit` | `boolean` | yes |  |
+| `chart_type` | `"table" \| "bar" \| "line" \| "funnel" \| "stage_over_time" \| "time_in_stage"` | yes |  |
+| `config` | `Record<string, unknown>` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `is_owner` | `boolean` | yes |  |
+| `owner` | `ReportOwner` | yes |  |
+| `revision` | `integer` | yes |  |
+| `source` | `ReportSource` | yes |  |
+| `title` | `string` | yes |  |
+| `updated_at` | `string (date-time)` | yes |  |
+| `visibility` | `"private" \| "org"` | yes |  |
+| `description` | `string \| null` | no |  |
+| `restricted` | `Array<RestrictedComponent>` | no |  |
+| `restricted_count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.reports.updateObjectReportApi({
+  path: { report_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-asof"></a>
+
+### `AsOf`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `date` | `string (date)` | yes |  |
+| `instant` | `string (date-time)` | yes |  |
+| `timezone` | `string` | yes |  |
+
+<a id="type-chartother"></a>
+
+### `ChartOther`
+
+What the chart folds into "Other": every group beyond ``chart_limit``. Only additive measures (count, sum, related_count) are filled in; an average, minimum or maximum cannot be folded and is None.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `group_count` | `integer` | yes |  |
+| `measures` | `Record<string, number \| integer \| null>` | yes |  |
+| `record_count` | `integer` | yes |  |
+
+<a id="type-drilldownrequest"></a>
+
+### `DrilldownRequest`
+
+Open the records behind one number: ``target`` is a result row's ``drilldown``, echoed back unchanged.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `target` | `GroupTarget \| StageTarget \| SnapshotTarget \| AllTarget` | yes |  |
+| `after_record_id` | `string (uuid) \| null` | no |  |
+| `limit` | `integer` | no | default `50`, min 1, max 200 |
+
+<a id="type-gapnote"></a>
+
+### `GapNote`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `component` | `string` | yes |  |
+| `records` | `integer` | yes |  |
+| `kind` | `"no_history"` | no | default `"no_history"` |
+
+<a id="type-reportconfig"></a>
+
+### `ReportConfig`
+
+What a report computes. ``timezone`` (an IANA name) fixes how dates are bucketed and what "end of day" means; when absent the organization's time zone applies (never the server's).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `filters` | `Array<ReportFilter>` | no | max items 10 |
+| `group_by` | `Array<ReportGroupBy>` | no | max items 3 |
+| `measures` | `Array<ReportMeasure>` | no | max items 10 |
+| `range` | `ReportRange \| null` | no |  |
+| `stage` | `ReportStage \| null` | no |  |
+| `timezone` | `string \| null` | no | max length 64 |
+
+<a id="type-reportowner"></a>
+
+### `ReportOwner`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| null` | no |  |
+| `is_you` | `boolean` | no | default `false` |
+| `name` | `string \| null` | no |  |
+
+<a id="type-reportsource"></a>
+
+### `ReportSource`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `kind` | `"object" \| "process_list"` | yes |  |
+| `plural_noun` | `string` | yes |  |
+| `singular_noun` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `is_archived` | `boolean` | no | default `false` |
+
+<a id="type-restrictedcomponent"></a>
+
+### `RestrictedComponent`
+
+A part of a report the viewer may not see. Hidden means ABSENT: it carries no title, no object name, no type and no reason, only its position id (``m0`` the first measure, ``g0`` the first group-by, ``f0`` the first filter, ``stage`` the stage field), so a client can lock that slot in place.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `restricted` | `true` | no | default `true` |
+
+<a id="type-resultcolumn"></a>
+
+### `ResultColumn`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `kind` | `"group_by" \| "measure" \| "stage" \| "gap"` | yes |  |
+| `grain` | `"day" \| "week" \| "month" \| "quarter" \| "year" \| null` | no |  |
+| `label` | `string \| null` | no |  |
+| `restricted` | `boolean` | no | default `false` |
+| `value_type` | `string \| null` | no |  |
+
+<a id="type-resultrow"></a>
+
+### `ResultRow`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `drilldown` | `GroupTarget \| StageTarget \| SnapshotTarget \| AllTarget` | yes |  |
+| `key` | `string` | yes |  |
+| `group` | `Array<GroupValue>` | no |  |
+| `measures` | `Record<string, number \| integer \| null>` | no |  |
+| `partial` | `boolean` | no | default `false` |
+| `record_count` | `integer` | no | default `0` |
+| `unstaged` | `Record<string, integer>` | no |  |
+
+<a id="type-resulttotals"></a>
+
+### `ResultTotals`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `record_count` | `integer` | yes |  |
+| `measures` | `Record<string, number \| integer \| null>` | no |  |

package/docs/api/revenueLifecycle.d.ts

@@ -153,7 +153,9 @@ export interface LifecycleRecordItem {
 }
 
 export interface LifecycleStageMoveRequest {
-  /** Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. */
+  /** Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. */
+  confirm_without_subscription?: boolean;
+  /** Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. */
   dry_run?: boolean;
   /** Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. */
   target_slug: string;

package/docs/api/revenueLifecycle.md

@@ -191,6 +191,10 @@ with a 400 unless the company is or was a customer. `target_slug` ignores
 case and surrounding whitespace. `dry_run: true` runs every check and
 returns the would-be transition without writing anything.
 
+A move to `customers` of a company with no subscription at all is a 409
+(`detail.code` 'customers_without_subscription', `detail.message` names the
+company) unless `confirm_without_subscription: true` is sent (R3-30).
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -203,7 +207,8 @@ Body fields (`LifecycleStageMoveRequest`):
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `body.target_slug` | `string` | yes | Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. |
-| `body.dry_run` | `boolean` | no | Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. default `false` |
+| `body.confirm_without_subscription` | `boolean` | no | Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. default `false` |
+| `body.dry_run` | `boolean` | no | Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. default `false` |
 
 **Returns** `ApiResponse_LifecycleStageMoveResponse_`: the envelope `{ data: LifecycleStageMoveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -247,6 +252,10 @@ yet, which is common for Suspects-stage contacts), and records the same
 audit trail the in-app Move-Stage dialog's contact mode does. Returns no
 contact PII (see the module docstring) — only the status transition.
 
+A move to `customers` of a contact with no company, or whose company has no
+subscription, is a 409 (`detail.code` 'customers_without_subscription')
+unless `confirm_without_subscription: true` is sent (R3-31).
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -259,7 +268,8 @@ Body fields (`LifecycleStageMoveRequest`):
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `body.target_slug` | `string` | yes | Destination lifecycle slug, e.g. 'suspects', 'leads', 'trials', 'customers', 'churned'. Case and surrounding whitespace are ignored, and a stage's display name is accepted too. |
-| `body.dry_run` | `boolean` | no | Company moves only: run every check the move runs (company exists, stage known, Customers/Churned guards) and return the would-be transition without writing anything. Ignored for contact moves. default `false` |
+| `body.confirm_without_subscription` | `boolean` | no | Confirm a move to Customers of a company with no subscription (or a contact with no company or whose company has none). Without it such a move is refused with 409 and detail.code 'customers_without_subscription'. default `false` |
+| `body.dry_run` | `boolean` | no | Run every check the move runs (record exists, stage known, Customers/Churned guards, the no-subscription confirmation) and return the would-be transition without writing anything. default `false` |
 
 **Returns** `ApiResponse_LifecycleStageMoveResponse_`: the envelope `{ data: LifecycleStageMoveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 

package/docs/api/scheduleBuy.d.ts

@@ -245,10 +245,10 @@ export interface ScheduleBuyDomainSuggestRequest {
 /**
  * Create and LOCK a staggered buying plan. PLACES REAL CREDIT HOLDS.
  *
- * Mirrors the app's ``CreatePlanRequest`` field for field, including its
- * mutual-exclusion rule between ``persona_ids`` and the manual
- * ``registrants``/``mailbox_aliases`` pair - the app raises that in a
- * validator, and it must fire as a 422 here rather than inside the proxy.
+ * Mirrors the app's ``CreatePlanRequest`` field for field, including the
+ * rule that new plans require ``persona_ids``. Manual ``registrants`` /
+ * ``mailbox_aliases`` are still parsed so a legacy payload 422s here
+ * rather than inside the proxy.
  */
 export interface ScheduleBuyPlanRequest {
   /** Sends per mailbox per day */
@@ -261,15 +261,15 @@ export interface ScheduleBuyPlanRequest {
   domains_per_batch?: number;
   /** Idle mailboxes you already hold, from /suggest */
   idle_mailboxes_snapshot: number;
-  /** One alias per mailbox_per_domain. Required unless persona_ids is set. */
+  /** Not accepted for new plans. Use persona_ids. */
   mailbox_aliases?: Array<Record<string, unknown>>;
   /** Mailboxes bought on each domain */
   mailboxes_per_domain?: number;
-  /** Sender personas to buy for. Excludes the two above. */
+  /** Sender identity IDs. At least one is required to start a schedule. */
   persona_ids?: Array<number> | null;
-  /** Registrant identities. Required unless persona_ids is set. */
+  /** Not accepted for new plans. Use persona_ids. */
   registrants?: Array<Record<string, unknown>>;
-  /** Adopt these owned EMPTY domains instead of buying */
+  /** Adopt these owned domains instead of buying. Each must have fewer live mailboxes than mailboxes_per_domain; the plan tops it up and holds credits for exactly the missing ones */
   reuse_domains?: Array<string> | null;
   /** Sending days assumed per month */
   sending_days_per_month?: number;
@@ -292,6 +292,10 @@ export interface ScheduleBuySuggestRequest {
   domains_per_batch?: number;
   /** Mailboxes bought on each domain */
   mailboxes_per_domain?: number;
+  /** Price a REUSE plan over this many owned domains instead */
+  reuse_domain_count?: number | null;
+  /** With reuse_domain_count: the total mailboxes those domains are missing (each domain: mailboxes_per_domain minus its live mailboxes). Omitted, every domain is priced as empty */
+  reuse_missing_mailboxes?: number | null;
   /** Sending days assumed per month */
   sending_days_per_month?: number;
   /** Contacts you intend to reach per month */