@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/appPages.md

@@ -0,0 +1,796 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.appPages`: App Pages
+
+16 operations (8 read, 6 write, 1 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.appPages.*` 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: [appPages.d.ts](appPages.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`chatEditAppPage`](#op-chateditapppage) | `POST /api/v1/app-pages/{page_id}/chat-edit` | write | `apps:write` | Chat Edit App Page |
+| [`createAppPage`](#op-createapppage) | `POST /api/v1/app-pages` | write | `apps:write` | Create App Page |
+| [`deleteAppPage`](#op-deleteapppage) | `DELETE /api/v1/app-pages/{page_id}` | destructive | `apps:delete` | Delete App Page |
+| [`generateAppPage`](#op-generateapppage) | `POST /api/v1/app-pages/{page_id}/generate` | billable | `apps:run` | Generate App Page |
+| [`getAppPage`](#op-getapppage) | `GET /api/v1/app-pages/{page_id}` | read | `apps:read` | Get App Page |
+| [`getAppPageArtifact`](#op-getapppageartifact) | `GET /api/v1/app-pages/{page_id}/artifact` | read | `apps:read` | Get App Page Artifact |
+| [`getAppPageStatus`](#op-getapppagestatus) | `GET /api/v1/app-pages/{page_id}/status` | read | `apps:read` | Get App Page Status |
+| [`invokeAppPageAction`](#op-invokeapppageaction) | `POST /api/v1/app-pages/{page_id}/actions/{alias}/{action_name}` | write | `apps:write` | Invoke App Page Action |
+| [`listAppPageActions`](#op-listapppageactions) | `GET /api/v1/app-pages/{page_id}/actions` | read | `apps:read` | List App Page Actions |
+| [`listAppPageSourceInstances`](#op-listapppagesourceinstances) | `GET /api/v1/app-page-sources/{source_kind}/instances` | read | `apps:read` | List App Page Source Instances |
+| [`listAppPageSourceKinds`](#op-listapppagesourcekinds) | `GET /api/v1/app-page-sources` | read | `apps:read` | List App Page Source Kinds |
+| [`listAppPageVersions`](#op-listapppageversions) | `GET /api/v1/app-pages/{page_id}/versions` | read | `apps:read` | List App Page Versions |
+| [`listAppPages`](#op-listapppages) | `GET /api/v1/app-pages` | read | `apps:read` | List App Pages |
+| [`mintAppPageFrameSession`](#op-mintapppageframesession) | `POST /api/v1/app-pages/{page_id}/frame-session` | write | `apps:write` | Mint App Page Frame Session |
+| [`replaceAppPageSources`](#op-replaceapppagesources) | `PUT /api/v1/app-pages/{page_id}/sources` | write | `apps:write` | Replace App Page Sources |
+| [`restoreAppPageVersion`](#op-restoreapppageversion) | `POST /api/v1/app-pages/{page_id}/versions/{version_num}/restore` | write | `apps:write` | Restore App Page Version |
+
+---
+
+<a id="op-chateditapppage"></a>
+
+### `g8.api.appPages.chatEditAppPage(input)`
+
+**Chat Edit App Page**
+
+- HTTP: `POST /api/v1/app-pages/{page_id}/chat-edit`
+- operationId: `chat_edit_app_page_app_pages__page_id__chat_edit_post` (also callable as `g8.api.call("chat_edit_app_page_app_pages__page_id__chat_edit_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Change the page by describing the change. Billed and rate-capped.
+
+An edit that would strip every live-data binding is refused: a page whose
+data wiring is gone renders stale markup that still looks live, which is
+worse than a failed edit. Each accepted edit snapshots a new version.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+| `body` | `AppPageChatEditRequest` | yes | Request body; fields below. |
+
+Body fields (`AppPageChatEditRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.instruction` | `string` | yes | min length 1, max length 2000 |
+
+**Returns** `ApiResponse_AppPageChatEditResponse_`: the envelope `{ data: AppPageChatEditResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageChatEditResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `edit_summary` | `string` | yes |  |
+| `page_id` | `string` | yes |  |
+| `version_num` | `integer` | yes |  |
+| `status` | `string` | no | default `"ready"` |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.chatEditAppPage({ path: { page_id: "id" }, body: { instruction: "example" } });
+```
+
+---
+
+<a id="op-createapppage"></a>
+
+### `g8.api.appPages.createAppPage(input)`
+
+**Create App Page**
+
+- HTTP: `POST /api/v1/app-pages`
+- operationId: `create_app_page_app_pages_post` (also callable as `g8.api.call("create_app_page_app_pages_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Create a page over one or more data sources.
+
+Every source is validated against the connector registry BEFORE anything is
+persisted, so a page can never reference a source that cannot be read.
+422 names the offending source rather than failing generically later.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateAppPageRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateAppPageRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes |  |
+| `body.sources` | `Array<AppPageSourceDto>` | yes | At least one. A page with no data source can never be generated. min items 1 |
+| `body.description` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_CreatedAppPageResponse_`: the envelope `{ data: CreatedAppPageResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreatedAppPageResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.createAppPage({
+  body: {
+    name: "Example",
+    sources: [{ source_id: "id", source_kind: "example" }],
+  },
+});
+```
+
+---
+
+<a id="op-deleteapppage"></a>
+
+### `g8.api.appPages.deleteAppPage(input)`
+
+**Delete App Page**
+
+- HTTP: `DELETE /api/v1/app-pages/{page_id}`
+- operationId: `delete_app_page_app_pages__page_id__delete` (also callable as `g8.api.call("delete_app_page_app_pages__page_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+
+Delete a page. Its sources and version history go with it.
+
+A real delete, unlike most of the app platform: a page is the builder's own
+generated artifact rather than a record of something that happened, so there
+is no audit reason to keep a tombstone.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.appPages.deleteAppPage({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-generateapppage"></a>
+
+### `g8.api.appPages.generateAppPage(input)`
+
+**Generate App Page**
+
+- HTTP: `POST /api/v1/app-pages/{page_id}/generate`
+- operationId: `generate_app_page_app_pages__page_id__generate_post` (also callable as `g8.api.call("generate_app_page_app_pages__page_id__generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `apps:run`
+
+Generate the page from its sources. Asynchronous; poll `/status`.
+
+Billed, and rate-capped per organization per day. The ordering behind this
+(re-authorize every source before spend, consume the cap, mark generating,
+enqueue, refund and mark failed on error) is shared with the internal surface
+rather than reimplemented here.
+
+404 covers both an unknown page and a source that has become unreachable
+since the page was created. Distinguishing them would let a caller probe
+which sources exist.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+| `body` | `GenerateAppPageRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateAppPageRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.instruction` | `string \| null` | no | What the page should show. Free text; the generator composes every bound source. max length 2000 |
+
+**Returns** `ApiResponse_GenerateAppPageResponse_`: the envelope `{ data: GenerateAppPageResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`GenerateAppPageResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+| `job_id` | `string \| null` | no |  |
+| `status` | `string` | no | default `"generating"` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.appPages.generateAppPage({ path: { page_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-getapppage"></a>
+
+### `g8.api.appPages.getAppPage(input)`
+
+**Get App Page**
+
+- HTTP: `GET /api/v1/app-pages/{page_id}`
+- operationId: `get_app_page_app_pages__page_id__get` (also callable as `g8.api.call("get_app_page_app_pages__page_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+One page and its bound sources.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageResponse_`: the envelope `{ data: AppPageResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes |  |
+| `page_id` | `string` | yes |  |
+| `status` | `string` | yes | draft \| generating \| ready \| failed |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `sources` | `Array<AppPageSourceDto>` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.getAppPage({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-getapppageartifact"></a>
+
+### `g8.api.appPages.getAppPageArtifact(input)`
+
+**Get App Page Artifact**
+
+- HTTP: `GET /api/v1/app-pages/{page_id}/artifact`
+- operationId: `get_app_page_artifact_app_pages__page_id__artifact_get` (also callable as `g8.api.call("get_app_page_artifact_app_pages__page_id__artifact_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+The generated HTML and the manifest wiring it to its sources.
+
+This is the source, for reading or storing. To DISPLAY a page, mint a frame
+session instead: the HTML is written for a sandboxed origin with an injected
+SDK and is not safe to embed directly in your own document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageArtifactResponse_`: the envelope `{ data: AppPageArtifactResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageArtifactResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes |  |
+| `page_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `data_manifest` | `Record<string, unknown>` | no |  |
+| `html_source` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.getAppPageArtifact({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-getapppagestatus"></a>
+
+### `g8.api.appPages.getAppPageStatus(input)`
+
+**Get App Page Status**
+
+- HTTP: `GET /api/v1/app-pages/{page_id}/status`
+- operationId: `get_app_page_status_app_pages__page_id__status_get` (also callable as `g8.api.call("get_app_page_status_app_pages__page_id__status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+Is the page built yet?
+
+`has_page` is separate from `status` because a page can be `ready` with no
+stored HTML, and treating that as ready sends a viewer to an empty frame.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageStatusResponse_`: the envelope `{ data: AppPageStatusResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageStatusResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `has_page` | `boolean` | no | True once generation has stored HTML. `status: ready` alone is not enough. default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.getAppPageStatus({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-invokeapppageaction"></a>
+
+### `g8.api.appPages.invokeAppPageAction(input)`
+
+**Invoke App Page Action**
+
+- HTTP: `POST /api/v1/app-pages/{page_id}/actions/{alias}/{action_name}`
+- operationId: `invoke_app_page_action_app_pages__page_id__actions__alias___action_name__post` (also callable as `g8.api.call("invoke_app_page_action_app_pages__page_id__actions__alias___action_name__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Invoke a declared action on one of this page's bound sources.
+
+The bound source is RE-AUTHORIZED on every invocation, not just when the
+page was created, so a source revoked since then stops accepting writes
+immediately rather than at the next regeneration.
+
+`404` covers an unknown page, an alias this page does not bind, and a source
+that is no longer reachable. They are indistinguishable on purpose: telling
+a caller which of the three it was lets a page enumerate what exists.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+| `path.alias` | `string` | yes |  |
+| `path.action_name` | `string` | yes |  |
+| `body` | `InvokeActionRequest` | yes | Request body; fields below. |
+
+Body fields (`InvokeActionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.args` | `Record<string, unknown>` | no | Action arguments. Validated against the object's own schema; an undeclared field is refused, not dropped. |
+
+**Returns** `ApiResponse_InvokeActionResponse_`: the envelope `{ data: InvokeActionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InvokeActionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `ok` | `boolean` | yes |  |
+| `invalidates` | `Array<string>` | no | Sources whose data is now stale, so a page can refresh only what changed. |
+| `message` | `string \| null` | no |  |
+| `record_id` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.invokeAppPageAction({
+  path: { page_id: "id", alias: "example", action_name: "Example" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-listapppageactions"></a>
+
+### `g8.api.appPages.listAppPageActions(input)`
+
+**List App Page Actions**
+
+- HTTP: `GET /api/v1/app-pages/{page_id}/actions`
+- operationId: `list_app_page_actions_app_pages__page_id__actions_get` (also callable as `g8.api.call("list_app_page_actions_app_pages__page_id__actions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+What this page can do, grouped by the alias each action acts on.
+
+A source that no longer authorizes contributes nothing rather than failing
+the whole listing: one revoked binding should not make a page's other
+actions undiscoverable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageActionsResponse_`: the envelope `{ data: AppPageActionsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageActionsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+| `actions_by_alias` | `Record<string, Array<ActionDescriptorDto>>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.listAppPageActions({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-listapppagesourceinstances"></a>
+
+### `g8.api.appPages.listAppPageSourceInstances(input)`
+
+**List App Page Source Instances**
+
+- HTTP: `GET /api/v1/app-page-sources/{source_kind}/instances`
+- operationId: `list_app_page_source_instances_app_page_sources__source_kind__instances_get` (also callable as `g8.api.call("list_app_page_source_instances_app_page_sources__source_kind__instances_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+The sources of one family this org can build a page over.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.source_kind` | `string` | yes | A family `kind` from `GET /app-page-sources`. |
+| `query.limit` | `integer` | no | default `100` |
+| `query.query` | `string \| null` | no | Filter by name. |
+
+**Returns** `ApiResponse_AppPageSourceCatalogPayload_`: the envelope `{ data: AppPageSourceCatalogPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageSourceCatalogPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.listAppPageSourceInstances({ path: { source_kind: "example" } });
+```
+
+---
+
+<a id="op-listapppagesourcekinds"></a>
+
+### `g8.api.appPages.listAppPageSourceKinds(input?)`
+
+**List App Page Source Kinds**
+
+- HTTP: `GET /api/v1/app-page-sources`
+- operationId: `list_app_page_source_kinds_app_page_sources_get` (also callable as `g8.api.call("list_app_page_source_kinds_app_page_sources_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+The source families an app page can be built over, and whether each is available.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AppPageSourceCatalogPayload_`: the envelope `{ data: AppPageSourceCatalogPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageSourceCatalogPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.listAppPageSourceKinds();
+```
+
+---
+
+<a id="op-listapppageversions"></a>
+
+### `g8.api.appPages.listAppPageVersions(input)`
+
+**List App Page Versions**
+
+- HTTP: `GET /api/v1/app-pages/{page_id}/versions`
+- operationId: `list_app_page_versions_app_pages__page_id__versions_get` (also callable as `g8.api.call("list_app_page_versions_app_pages__page_id__versions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+Every stored version of this page, with the instruction that produced it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageVersionListResponse_`: the envelope `{ data: AppPageVersionListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageVersionListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+| `versions` | `Array<AppPageVersionDto>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.listAppPageVersions({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-listapppages"></a>
+
+### `g8.api.appPages.listAppPages(input?)`
+
+**List App Pages**
+
+- HTTP: `GET /api/v1/app-pages`
+- operationId: `list_app_pages_app_pages_get` (also callable as `g8.api.call("list_app_pages_app_pages_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+
+Your organization's app pages, most recently updated first.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_AppPageResponse__`: the envelope `{ data: Array<AppPageResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes |  |
+| `page_id` | `string` | yes |  |
+| `status` | `string` | yes | draft \| generating \| ready \| failed |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `sources` | `Array<AppPageSourceDto>` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.listAppPages();
+```
+
+---
+
+<a id="op-mintapppageframesession"></a>
+
+### `g8.api.appPages.mintAppPageFrameSession(input)`
+
+**Mint App Page Frame Session**
+
+- HTTP: `POST /api/v1/app-pages/{page_id}/frame-session`
+- operationId: `mint_app_page_frame_session_app_pages__page_id__frame_session_post` (also callable as `g8.api.call("mint_app_page_frame_session_app_pages__page_id__frame_session_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Mint a one-shot token for loading this page's sandboxed frame.
+
+The generated HTML is not safe to embed in your own document: it is written
+for an isolated, cookieless origin under a `default-src 'none'` policy with
+an injected data SDK. Load the returned `frame_url` in an iframe instead.
+
+Single use and short lived, by design. A token that could be replayed would
+be a bearer credential for the page's data, so each load mints a new one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_AppPageFrameSessionResponse_`: the envelope `{ data: AppPageFrameSessionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageFrameSessionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `expires_in` | `integer` | yes |  |
+| `token` | `string` | yes |  |
+| `view_session_id` | `string` | yes |  |
+| `frame_url` | `string \| null` | no | Absolute URL to load, token included. Absent when no frame origin is configured. |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.mintAppPageFrameSession({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-replaceapppagesources"></a>
+
+### `g8.api.appPages.replaceAppPageSources(input)`
+
+**Replace App Page Sources**
+
+- HTTP: `PUT /api/v1/app-pages/{page_id}/sources`
+- operationId: `replace_app_page_sources_app_pages__page_id__sources_put` (also callable as `g8.api.call("replace_app_page_sources_app_pages__page_id__sources_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Replace a page's sources. Each new source is validated before anything is written.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | App page id. |
+| `body` | `AppPageSourcesReplaceRequest` | yes | Request body; fields below. |
+
+Body fields (`AppPageSourcesReplaceRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.sources` | `Array<AppPageSourceDto>` | yes | The page's full source list. min items 1 |
+
+**Returns** `ApiResponse_AppPageSourcesPayload_`: the envelope `{ data: AppPageSourcesPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.replaceAppPageSources({
+  path: { page_id: "id" },
+  body: { sources: [{ source_id: "id", source_kind: "example" }] },
+});
+```
+
+---
+
+<a id="op-restoreapppageversion"></a>
+
+### `g8.api.appPages.restoreAppPageVersion(input)`
+
+**Restore App Page Version**
+
+- HTTP: `POST /api/v1/app-pages/{page_id}/versions/{version_num}/restore`
+- operationId: `restore_app_page_version_app_pages__page_id__versions__version_num__restore_post` (also callable as `g8.api.call("restore_app_page_version_app_pages__page_id__versions__version_num__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Restore an earlier version.
+
+Restoring SNAPSHOTS rather than rewinds: the current page becomes a new
+version before the old one is applied, so a restore is itself undoable and
+nothing is destroyed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes |  |
+| `path.version_num` | `integer` | yes |  |
+
+**Returns** `ApiResponse_AppPageRestoreResponse_`: the envelope `{ data: AppPageRestoreResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppPageRestoreResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `page_id` | `string` | yes |  |
+| `restored_from_version` | `integer` | yes |  |
+| `snapshot_version` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appPages.restoreAppPageVersion({ path: { page_id: "id", version_num: 1 } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-actiondescriptordto"></a>
+
+### `ActionDescriptorDto`
+
+One action a page may invoke on one of its bound sources.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `description` | `string` | no | default `""` |
+| `irreversible` | `boolean` | no | Cannot be undone. Surfaced so a host can confirm before invoking. default `false` |
+| `params` | `Array<ActionParamDto>` | no |  |
+
+<a id="type-apppagesourcedto"></a>
+
+### `AppPageSourceDto`
+
+One data source bound into a page. `alias` is the handle the generated page's JavaScript addresses it by.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source_id` | `string` | yes | Opaque to everything but the connector that owns it |
+| `source_kind` | `string` | yes | Connector family, e.g. staging-table or custom-object |
+| `alias` | `string \| null` | no | Handle used inside the page. Auto-assigned from the kind when omitted. |
+| `position` | `integer` | no | default `0` |
+| `role` | `string` | no | default `"data"` |
+
+<a id="type-apppageversiondto"></a>
+
+### `AppPageVersionDto`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `version_num` | `integer` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `edit_instruction` | `string \| null` | no |  |
+| `edit_summary` | `string \| null` | no |  |