@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/websiteEditor.md

@@ -0,0 +1,517 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.websiteEditor`: Website Editor
+
+12 operations (4 read, 5 write, 1 destructive, 2 external).
+
+No hand-written client covers this area. Call it through `g8.api.websiteEditor.*` 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: [websiteEditor.d.ts](websiteEditor.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`applyWebsitePageOperations`](#op-applywebsitepageoperations) | `POST /api/v1/website-editor/pages/{page_id}/ops` | write | `campaigns:write` | Apply Website Page Operations |
+| [`cloneWebsitePage`](#op-clonewebsitepage) | `POST /api/v1/website-editor/pages/{page_id}/clone` | write | `campaigns:write` | Clone Website Page |
+| [`connectWebsiteHosting`](#op-connectwebsitehosting) | `POST /api/v1/website-editor/connect` | write | `campaigns:write` | Connect Website Hosting |
+| [`disconnectWebsiteHosting`](#op-disconnectwebsitehosting) | `DELETE /api/v1/website-editor/disconnect` | destructive | `campaigns:delete` | Disconnect Website Hosting |
+| [`getWebsiteHostingConnection`](#op-getwebsitehostingconnection) | `GET /api/v1/website-editor/connection` | read | `campaigns:read` | Get Website Hosting Connection |
+| [`getWebsitePageConversation`](#op-getwebsitepageconversation) | `GET /api/v1/website-editor/pages/{page_id}/conversation` | read | `campaigns:read` | Get Website Page Conversation |
+| [`listWebsiteHostingProjects`](#op-listwebsitehostingprojects) | `GET /api/v1/website-editor/projects` | read | `campaigns:read` | List Website Hosting Projects |
+| [`listWebsitePageVersions`](#op-listwebsitepageversions) | `GET /api/v1/website-editor/pages/{page_id}/versions` | read | `campaigns:read` | List Website Page Versions |
+| [`publishWebsitePages`](#op-publishwebsitepages) | `POST /api/v1/website-editor/publish` | external | `campaigns:run` | Publish Website Pages |
+| [`restoreWebsitePageVersion`](#op-restorewebsitepageversion) | `POST /api/v1/website-editor/pages/{page_id}/restore-version` | write | `campaigns:write` | Restore Website Page Version |
+| [`syncWebsitePages`](#op-syncwebsitepages) | `POST /api/v1/website-editor/sync` | external | `campaigns:run` | Sync Website Pages |
+| [`updateWebsitePageText`](#op-updatewebsitepagetext) | `POST /api/v1/website-editor/pages/{page_id}/update-text` | write | `campaigns:write` | Update Website Page Text |
+
+---
+
+<a id="op-applywebsitepageoperations"></a>
+
+### `g8.api.websiteEditor.applyWebsitePageOperations(input)`
+
+**Apply Website Page Operations**
+
+- HTTP: `POST /api/v1/website-editor/pages/{page_id}/ops`
+- operationId: `apply_website_page_operations_website_editor_pages__page_id__ops_post` (also callable as `g8.api.call("apply_website_page_operations_website_editor_pages__page_id__ops_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Apply an ordered list of deterministic edit operations. FREE - no model runs.
+
+Send `base_version` (the page's version when you read it) to get a 409
+instead of overwriting a newer edit. `save_mode: "save"` also records a
+restorable version; `autosave` only updates the page.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+| `body` | `WebsiteEditorPageOpsRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorPageOpsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ops` | `Array<Record<string, unknown>>` | yes | Ordered edit operations. |
+| `body.base_version` | `integer \| null` | no | Your copy's version, for conflict detection. |
+| `body.instruction` | `string \| null` | no | A human-readable note stored on the version. |
+| `body.save_mode` | `"autosave" \| "save"` | no | default `"autosave"` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.applyWebsitePageOperations({ path: { page_id: "id" }, body: { ops: [{}] } });
+```
+
+---
+
+<a id="op-clonewebsitepage"></a>
+
+### `g8.api.websiteEditor.cloneWebsitePage(input)`
+
+**Clone Website Page**
+
+- HTTP: `POST /api/v1/website-editor/pages/{page_id}/clone`
+- operationId: `clone_website_page_website_editor_pages__page_id__clone_post` (also callable as `g8.api.call("clone_website_page_website_editor_pages__page_id__clone_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Fetch a page's live HTML so it can be edited. FREE.
+
+For pages imported by URL rather than synced from a hosting project. A
+page that already has HTML answers `already_cloned` and is not re-fetched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.cloneWebsitePage({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-connectwebsitehosting"></a>
+
+### `g8.api.websiteEditor.connectWebsiteHosting(input)`
+
+**Connect Website Hosting**
+
+- HTTP: `POST /api/v1/website-editor/connect`
+- operationId: `connect_website_hosting_website_editor_connect_post` (also callable as `g8.api.call("connect_website_hosting_website_editor_connect_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Connect the org's website hosting account. FREE.
+
+The credentials are validated against the provider before they are stored,
+so a wrong token is a 400 rather than a broken connection. Replaces any
+existing connection. The token is WRITE-ONLY - no response carries it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WebsiteEditorConnectRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorConnectRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.account_id` | `string` | yes | The hosting provider's account id. |
+| `body.api_token` | `string` | yes | An API token for that account. Never returned. |
+| `body.project_name` | `string \| null` | no | The site project to edit and publish. |
+
+**Returns** `ApiResponse_WebsiteEditorConnection_`: the envelope `{ data: WebsiteEditorConnection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebsiteEditorConnection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `connected` | `boolean` | yes |  |
+| `account_id` | `string \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_synced_at` | `string (date-time) \| null` | no |  |
+| `project_name` | `string \| null` | no |  |
+| `status` | `string \| null` | no | connected, syncing or error. |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.connectWebsiteHosting({ body: { account_id: "id", api_token: "example" } });
+```
+
+---
+
+<a id="op-disconnectwebsitehosting"></a>
+
+### `g8.api.websiteEditor.disconnectWebsiteHosting(input?)`
+
+**Disconnect Website Hosting**
+
+- HTTP: `DELETE /api/v1/website-editor/disconnect`
+- operationId: `disconnect_website_hosting_website_editor_disconnect_delete` (also callable as `g8.api.call("disconnect_website_hosting_website_editor_disconnect_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Remove the hosting connection and its stored credentials. FREE.
+
+Pages already synced stay in the content workspace; publishing afterwards
+goes to the graph8-hosted site instead of the org's own account.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.websiteEditor.disconnectWebsiteHosting();
+```
+
+---
+
+<a id="op-getwebsitehostingconnection"></a>
+
+### `g8.api.websiteEditor.getWebsiteHostingConnection(input?)`
+
+**Get Website Hosting Connection**
+
+- HTTP: `GET /api/v1/website-editor/connection`
+- operationId: `get_website_hosting_connection_website_editor_connection_get` (also callable as `g8.api.call("get_website_hosting_connection_website_editor_connection_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Whether a hosting account is connected, and its sync status. FREE.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WebsiteEditorConnection_`: the envelope `{ data: WebsiteEditorConnection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WebsiteEditorConnection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `connected` | `boolean` | yes |  |
+| `account_id` | `string \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `last_synced_at` | `string (date-time) \| null` | no |  |
+| `project_name` | `string \| null` | no |  |
+| `status` | `string \| null` | no | connected, syncing or error. |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.getWebsiteHostingConnection();
+```
+
+---
+
+<a id="op-getwebsitepageconversation"></a>
+
+### `g8.api.websiteEditor.getWebsitePageConversation(input)`
+
+**Get Website Page Conversation**
+
+- HTTP: `GET /api/v1/website-editor/pages/{page_id}/conversation`
+- operationId: `get_website_page_conversation_website_editor_pages__page_id__conversation_get` (also callable as `g8.api.call("get_website_page_conversation_website_editor_pages__page_id__conversation_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The AI edit conversation recorded against this page. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.getWebsitePageConversation({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-listwebsitehostingprojects"></a>
+
+### `g8.api.websiteEditor.listWebsiteHostingProjects(input?)`
+
+**List Website Hosting Projects**
+
+- HTTP: `GET /api/v1/website-editor/projects`
+- operationId: `list_website_hosting_projects_website_editor_projects_get` (also callable as `g8.api.call("list_website_hosting_projects_website_editor_projects_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The site projects in the connected hosting account. FREE.
+
+The valid `project_name` values for `POST /website-editor/sync`. 404 when
+no account is connected.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentListPayload_`: the envelope `{ data: StudioContentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioContentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.listWebsiteHostingProjects();
+```
+
+---
+
+<a id="op-listwebsitepageversions"></a>
+
+### `g8.api.websiteEditor.listWebsitePageVersions(input)`
+
+**List Website Page Versions**
+
+- HTTP: `GET /api/v1/website-editor/pages/{page_id}/versions`
+- operationId: `list_website_page_versions_website_editor_pages__page_id__versions_get` (also callable as `g8.api.call("list_website_page_versions_website_editor_pages__page_id__versions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The page's saved versions, newest first. FREE.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+
+**Returns** `ApiResponse_StudioContentListPayload_`: the envelope `{ data: StudioContentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioContentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.listWebsitePageVersions({ path: { page_id: "id" } });
+```
+
+---
+
+<a id="op-publishwebsitepages"></a>
+
+### `g8.api.websiteEditor.publishWebsitePages(input)`
+
+**Publish Website Pages**
+
+- HTTP: `POST /api/v1/website-editor/publish`
+- operationId: `publish_website_pages_website_editor_publish_post` (also callable as `g8.api.call("publish_website_pages_website_editor_publish_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Deploy edited pages to the LIVE website. Real visitors see it immediately.
+
+Goes to the org's own hosting account when one is connected with a
+project, otherwise to the graph8-hosted site. Omit `page_ids` to publish
+every page that has HTML. Spends no credit; it is outward-facing and tiered
+that way.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WebsiteEditorPublishRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorPublishRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.page_ids` | `Array<string (uuid)> \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.websiteEditor.publishWebsitePages({ body: {} });
+```
+
+---
+
+<a id="op-restorewebsitepageversion"></a>
+
+### `g8.api.websiteEditor.restoreWebsitePageVersion(input)`
+
+**Restore Website Page Version**
+
+- HTTP: `POST /api/v1/website-editor/pages/{page_id}/restore-version`
+- operationId: `restore_website_page_version_website_editor_pages__page_id__restore_version_post` (also callable as `g8.api.call("restore_website_page_version_website_editor_pages__page_id__restore_version_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Roll the page back to a saved version. FREE. Not live until `/publish`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+| `body` | `WebsiteEditorRestoreVersionRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorRestoreVersionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.version_num` | `integer` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.restoreWebsitePageVersion({ path: { page_id: "id" }, body: { version_num: 1 } });
+```
+
+---
+
+<a id="op-syncwebsitepages"></a>
+
+### `g8.api.websiteEditor.syncWebsitePages(input)`
+
+**Sync Website Pages**
+
+- HTTP: `POST /api/v1/website-editor/sync`
+- operationId: `sync_website_pages_website_editor_sync_post` (also callable as `g8.api.call("sync_website_pages_website_editor_sync_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `campaigns:run`
+
+Pull pages from a hosted site project into Studio. FREE.
+
+Each page's HTML is tagged with stable element ids and stored; a page that
+already exists (matched by URL, then by path) is OVERWRITTEN with the live
+HTML, so unpublished edits to it are replaced. Omit `paths` for every page.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WebsiteEditorSyncRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorSyncRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.project_name` | `string` | yes | From `GET /website-editor/projects`. |
+| `body.paths` | `Array<string> \| null` | no | Only these paths. Omit for every page. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.websiteEditor.syncWebsitePages({ body: { project_name: "Example" } });
+```
+
+---
+
+<a id="op-updatewebsitepagetext"></a>
+
+### `g8.api.websiteEditor.updateWebsitePageText(input)`
+
+**Update Website Page Text**
+
+- HTTP: `POST /api/v1/website-editor/pages/{page_id}/update-text`
+- operationId: `update_website_page_text_website_editor_pages__page_id__update_text_post` (also callable as `g8.api.call("update_website_page_text_website_editor_pages__page_id__update_text_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Set one element's text. FREE - no model runs.
+
+`element_id` is the element's `data-g8-id`. Saved as a new version, so
+`/restore-version` can undo it. Nothing goes live until `/publish`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.page_id` | `string` | yes | Website page id, from `GET /content-workspace/pages`. |
+| `body` | `WebsiteEditorUpdateTextRequest` | yes | Request body; fields below. |
+
+Body fields (`WebsiteEditorUpdateTextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.element_id` | `string` | yes | The element's `data-g8-id`. |
+| `body.new_text` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.websiteEditor.updateWebsitePageText({
+  path: { page_id: "id" },
+  body: { element_id: "id", new_text: "example" },
+});
+```