@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/appDeployments.md

@@ -0,0 +1,471 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.appDeployments`: App Deployments
+
+7 operations (3 read, 4 write).
+
+6 of these also have a hand-written method (`g8.appPlatform`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+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: [appDeployments.d.ts](appDeployments.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createAppDeployment`](#op-createappdeployment) ★ | `POST /api/v1/apps/{app_id}/deployments` | write | `apps:write` | Create App Deployment |
+| [`getActiveDeployment`](#op-getactivedeployment) ★ | `GET /api/v1/apps/{app_id}/deployments/active` | read | `apps:read` | Get Active Deployment |
+| [`getDeployment`](#op-getdeployment) ★ | `GET /api/v1/apps/{app_id}/deployments/{deployment_id}` | read | `apps:read` | Get Deployment |
+| [`listAppDeployments`](#op-listappdeployments) ★ | `GET /api/v1/apps/{app_id}/deployments` | read | `apps:read` | List App Deployments |
+| [`promoteDeployment`](#op-promotedeployment) ★ | `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/promote` | write | `apps:write` | Promote Deployment |
+| [`reportDeploymentProgress`](#op-reportdeploymentprogress) | `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/status` | write |  | Report Deployment Progress |
+| [`rollbackDeployment`](#op-rollbackdeployment) ★ | `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/rollback` | write | `apps:write` | Rollback Deployment |
+
+---
+
+<a id="op-createappdeployment"></a>
+
+### `g8.api.appDeployments.createAppDeployment(input)`
+
+**Create App Deployment**
+
+- HTTP: `POST /api/v1/apps/{app_id}/deployments`
+- operationId: `create_app_deployment_apps__app_id__deployments_post` (also callable as `g8.api.call("create_app_deployment_apps__app_id__deployments_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.deploy()`](../sdk-clients.md#g8-appplatform-deploy)
+
+Queue a deployment from a pinned source ref.
+
+Returns `queued`. Nothing builds yet -- the provisioner (M6-8) is what moves
+it to `building`. Recording the intent before any infrastructure exists is
+deliberate: it makes the control plane the source of truth for what SHOULD be
+running, which is what a reconciler needs to exist against.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `CreateDeploymentRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`CreateDeploymentRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_ref` | `string` | yes | Immutable source reference (commit SHA). Branches move; deployments must not. min length 1, max length 255 |
+| `body.schema_version_id` | `string \| null` | no | Schema version this build expects. Pinned so a rollback restores the matching schema, not merely the matching image. |
+
+**Returns** `ApiResponse_DeploymentResponse_`: the envelope `{ data: DeploymentResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.createAppDeployment({ path: { app_id: "id" }, body: { source_ref: "example" } });
+```
+
+---
+
+<a id="op-getactivedeployment"></a>
+
+### `g8.api.appDeployments.getActiveDeployment(input)`
+
+**Get Active Deployment**
+
+- HTTP: `GET /api/v1/apps/{app_id}/deployments/active`
+- operationId: `get_active_deployment_apps__app_id__deployments_active_get` (also callable as `g8.api.call("get_active_deployment_apps__app_id__deployments_active_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.activeDeployment()`](../sdk-clients.md#g8-appplatform-activedeployment)
+
+What is serving traffic right now, or null.
+
+null rather than 404 when nothing is deployed: "this app has never shipped"
+is an answer, and a 404 would read as "no such app".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_Union_DeploymentResponse__NoneType__`: the envelope `{ data: DeploymentResponse | null, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`data` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.getActiveDeployment({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-getdeployment"></a>
+
+### `g8.api.appDeployments.getDeployment(input)`
+
+**Get Deployment**
+
+- HTTP: `GET /api/v1/apps/{app_id}/deployments/{deployment_id}`
+- operationId: `get_deployment_apps__app_id__deployments__deployment_id__get` (also callable as `g8.api.call("get_deployment_apps__app_id__deployments__deployment_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.getDeployment()`](../sdk-clients.md#g8-appplatform-getdeployment)
+
+Fetch one deployment.
+
+Polling a build is the most common loop in a deploy flow, and without this it
+required listing every deployment and filtering client-side.
+
+REGISTERED AFTER `GET /{app_id}/deployments/active`, and the order is
+load-bearing rather than cosmetic. Both are three segments with a literal or a
+parameter in the same position, so declaring this first would capture `active`
+as a deployment id and that endpoint would 404 for everyone. `GET
+/workflows/dispositions` spent months doing exactly that in production.
+
+404 rather than 403 for a deployment belonging to someone else's app, because
+a 403 confirms the id exists. `_own_deployment` is the only way this module
+loads one, so a new route cannot skip the ownership check without also having
+nothing to work with.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.deployment_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_DeploymentResponse_`: the envelope `{ data: DeploymentResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.getDeployment({ path: { app_id: "id", deployment_id: "id" } });
+```
+
+---
+
+<a id="op-listappdeployments"></a>
+
+### `g8.api.appDeployments.listAppDeployments(input)`
+
+**List App Deployments**
+
+- HTTP: `GET /api/v1/apps/{app_id}/deployments`
+- operationId: `list_app_deployments_apps__app_id__deployments_get` (also callable as `g8.api.call("list_app_deployments_apps__app_id__deployments_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.listDeployments()`](../sdk-clients.md#g8-appplatform-listdeployments)
+
+Every deployment for this app, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_DeploymentResponse__`: the envelope `{ data: Array<DeploymentResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.listAppDeployments({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-promotedeployment"></a>
+
+### `g8.api.appDeployments.promoteDeployment(input)`
+
+**Promote Deployment**
+
+- HTTP: `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/promote`
+- operationId: `promote_deployment_apps__app_id__deployments__deployment_id__promote_post` (also callable as `g8.api.call("promote_deployment_apps__app_id__deployments__deployment_id__promote_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.promote()`](../sdk-clients.md#g8-appplatform-promote)
+
+Promote a built deployment to serve traffic.
+
+409 when the state machine forbids it -- a deployment cannot become
+`deployed` without having been built, and a `failed` one cannot be revived.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.deployment_id` | `string` | yes |  |
+| `body` | `PromoteDeploymentRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`PromoteDeploymentRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.image_digest` | `string` | yes | The built image digest being promoted. Recorded so a rollback targets an artifact rather than a rebuild. min length 7, max length 128 |
+
+**Returns** `ApiResponse_DeploymentResponse_`: the envelope `{ data: DeploymentResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.promoteDeployment({
+  path: { app_id: "id", deployment_id: "id" },
+  body: { image_digest: "example" },
+});
+```
+
+---
+
+<a id="op-reportdeploymentprogress"></a>
+
+### `g8.api.appDeployments.reportDeploymentProgress(input)`
+
+**Report Deployment Progress**
+
+- HTTP: `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/status`
+- operationId: `report_deployment_progress_apps__app_id__deployments__deployment_id__status_post` (also callable as `g8.api.call("report_deployment_progress_apps__app_id__deployments__deployment_id__status_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: none published
+
+The build controller reports progress. THE KEYSTONE (M9 item J2).
+
+Without this, every deploy route below is inert. `POST /deployments` writes
+`queued`, and the state machine allows `queued -> building -> promoting ->
+deployed`. Nothing anywhere wrote `building` or `promoting`, so promote asked
+for `queued -> deployed`, which is illegal, and **every real deployment that
+has ever existed 409s on promote** while `deployments/active` returns null for
+every builder.
+
+AUTHENTICATED AS THE CONTROLLER, NOT THE BUILDER, and that is the whole point.
+A builder's own key must not be able to walk their deployment to `promoting`
+with no build having run, then promote it: the machine would read green and
+the image would be whatever was there before, or nothing. So this route takes
+no `user` at all. See `dependencies/build_controller_auth.py`.
+
+`deployed` IS NOT SETTABLE HERE. The controller knows when a build finished; it
+does not decide the app should take traffic. That is promote, a separate act
+by the builder. Collapsing them would let whichever pod ran the build put an
+app in front of users.
+
+409 on an illegal transition rather than a silent no-op, so a controller that
+reports out of order learns it rather than leaving a deployment wedged in a
+state nobody wrote.
+
+404 for an unknown deployment, and 404 for a wrong or absent controller token,
+deliberately indistinguishable. The controller is not a tenant and has no org,
+so there is no ownership check to make here: the deployment id is resolved
+against the control plane rather than trusted, and it is the only thing this
+credential can act on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.deployment_id` | `string` | yes |  |
+| `body` | `DeploymentProgressRequest` | yes | Request body; fields below. |
+| `headers.x-build-controller-token` | `string \| null` | no |  |
+
+Body fields (`DeploymentProgressRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `"building" \| "promoting" \| "failed"` | yes | Where the build has reached. `deployed` is not settable here -- taking traffic is a separate, builder-initiated promote. |
+| `body.image_digest` | `string \| null` | no | The pushed image digest, once there is one. Reported with `promoting`. max length 200 |
+| `body.last_error_sanitized` | `string \| null` | no | A short, ALREADY-SANITIZED failure reason, surfaced to the builder. Build logs carry secrets and other tenants' identifiers, so the controller sanitizes before sending and this field is truncated here. max length 4000 |
+
+**Returns** `ApiResponse_DeploymentResponse_`: the envelope `{ data: DeploymentResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.reportDeploymentProgress({
+  path: { app_id: "id", deployment_id: "id" },
+  body: { status: "building" },
+});
+```
+
+---
+
+<a id="op-rollbackdeployment"></a>
+
+### `g8.api.appDeployments.rollbackDeployment(input)`
+
+**Rollback Deployment**
+
+- HTTP: `POST /api/v1/apps/{app_id}/deployments/{deployment_id}/rollback`
+- operationId: `rollback_deployment_apps__app_id__deployments__deployment_id__rollback_post` (also callable as `g8.api.call("rollback_deployment_apps__app_id__deployments__deployment_id__rollback_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.rollback()`](../sdk-clients.md#g8-appplatform-rollback)
+
+Roll back a deployment that is currently serving.
+
+Only a `deployed` deployment may be rolled back. Rolling back one that never
+served is meaningless, and permitting it would let a builder mark a failed
+build `rolled_back` and hide the failure.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.deployment_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_DeploymentResponse_`: the envelope `{ data: DeploymentResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeploymentResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `deployment_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `build_finished_at` | `string (date-time) \| null` | no | When the build ended, at `promoting` or at `failed`. Not at `deployed`: that is reached after traffic is taken, so measuring to it would count promotion and rollout as build time. |
+| `build_seconds` | `number \| null` | no | Measured build duration. `null` means NOT MEASURED, never zero: a build whose transitions were not reported has no duration, and a metering pipeline reading 0 would bill nothing and look correct. |
+| `build_started_at` | `string (date-time) \| null` | no | When the build started. `null` means it was not measured. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deployed_at` | `string (date-time) \| null` | no |  |
+| `image_digest` | `string \| null` | no |  |
+| `last_error_sanitized` | `string \| null` | no | Sanitized at the write. Build logs carry secrets and other tenants' ids. |
+| `schema_version_id` | `string \| null` | no |  |
+| `source_ref` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDeployments.rollbackDeployment({ path: { app_id: "id", deployment_id: "id" } });
+```

package/docs/api/appDomains.d.ts

@@ -0,0 +1,171 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appDomains` (App Domains): 5 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"claim_app_domain_apps__app_id__domains_post">;
+ *
+ * Reference with examples: appDomains.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appDomains.<member>` -> the operationId it calls. */
+export interface AppDomainsMembers {
+  claimAppDomain: "claim_app_domain_apps__app_id__domains_post";
+  listAppDomains: "list_app_domains_apps__app_id__domains_get";
+  releaseAppDomain: "release_app_domain_apps__app_id__domains__hostname__delete";
+  tlsAuthorize: "tls_authorize_app_platform_tls_authorize_get";
+  verifyAppDomain: "verify_app_domain_apps__app_id__domains__hostname__verify_post";
+}
+
+/** Input and output of every `g8.api.appDomains` operation, keyed by operationId. */
+export interface AppDomainsOperations {
+  /**
+   * POST /apps/{app_id}/domains
+   * Claim App Domain
+   * tier: write · scope: apps:write
+   */
+  claim_app_domain_apps__app_id__domains_post: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+    body: ClaimDomainRequest;
+  };
+    output: ApiResponse_DomainVerificationInstructions_;
+  };
+  /**
+   * GET /apps/{app_id}/domains
+   * List App Domains
+   * tier: read · scope: apps:read
+   */
+  list_app_domains_apps__app_id__domains_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_DomainResponse__;
+  };
+  /**
+   * DELETE /apps/{app_id}/domains/{hostname}
+   * Release App Domain
+   * tier: destructive · scope: apps:delete
+   */
+  release_app_domain_apps__app_id__domains__hostname__delete: {
+    input: {
+    path: {
+      app_id: string;
+      hostname: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /app-platform/tls-authorize
+   * Tls Authorize
+   * tier: read · scope: n/a
+   */
+  tls_authorize_app_platform_tls_authorize_get: {
+    input: {
+    query: {
+      domain: string;
+    };
+  };
+    output: unknown;
+  };
+  /**
+   * POST /apps/{app_id}/domains/{hostname}/verify
+   * Verify App Domain
+   * tier: write · scope: apps:write
+   */
+  verify_app_domain_apps__app_id__domains__hostname__verify_post: {
+    input: {
+    path: {
+      app_id: string;
+      hostname: string;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DomainResponse_;
+  };
+}
+
+// 8 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_DomainResponse_ {
+  data: DomainResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DomainVerificationInstructions_ {
+  data: DomainVerificationInstructions;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_DomainResponse__ {
+  data: Array<DomainResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ClaimDomainRequest {
+  /** The hostname to serve this app on. Normalized server-side: case, a trailing dot and unicode all resolve to one canonical form. */
+  hostname: string;
+}
+
+export interface DomainResponse {
+  app_id: string;
+  created_at?: string | null;
+  domain_id: string;
+  /** The canonical, normalized form -- not necessarily what was submitted. */
+  hostname: string;
+  status: string;
+  verified_at?: string | null;
+}
+
+/**
+ * Everything the builder needs to prove control, and nothing else.
+ *
+ * The token is returned ONLY here, at claim time. It is also stored, but there
+ * is deliberately no route that reads it back: a token readable on demand is a
+ * token an attacker with a stolen read-only key can harvest for every pending
+ * domain on the platform.
+ */
+export interface DomainVerificationInstructions {
+  domain: DomainResponse;
+  /** Create the record at this name, e.g. _graph8-challenge.app.example.com */
+  record_name: string;
+  record_type?: string;
+  record_value: string;
+}
+
+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;
+}