diff --git a/astro.config.mjs b/astro.config.mjs index 77afbd5..c7caeeb 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -133,6 +133,7 @@ export default defineConfig({ { label: 'Cells', slug: 'reference/cells' }, { label: 'Layers', slug: 'reference/layers' }, { label: 'Variables', slug: 'reference/variables' }, + { label: 'Undo / Redo', slug: 'reference/undo-redo' }, { label: 'Assets & Content Resources', slug: 'reference/content-resources' }, { label: 'Proof of Genesis Backups', slug: 'reference/proof-of-genesis' }, { label: 'Trigger + Poll a Generation', slug: 'reference/generations' }, diff --git a/public/llms-full.txt b/public/llms-full.txt index 9db45e0..40c6737 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -715,6 +715,20 @@ POST /v1/vidsheet/{id}/import_global_variables?agent_id={id} (multipart XLS GET /v1/vidsheet/global_variables_template (XLSX template download) ``` +## Undo / Redo (change-set history) + +Every grouped write to a vidsheet (rows/columns/cells/layers edited in one request) is +recorded as a change set on an undo/redo stack. List recent change sets, see the next-to-undo +one, and undo/redo. Pass `change_set_id` to target a specific change set instead of the most +recent one. `409 conflict` = the sheet changed underneath you — re-fetch and retry. + +``` +GET /v1/vidsheet/{id}/operations?agent_id={id}&limit={1-100}&include_undone={bool} → { change_sets: [...] } newest first +GET /v1/vidsheet/{id}/operations/last?agent_id={id} → { change_set: {...}|null } +POST /v1/vidsheet/{id}/operations/undo?agent_id={id} body { change_set_id? } → { change_set_id, undone:[...], next_undoable } (422 nothing_to_undo) +POST /v1/vidsheet/{id}/operations/redo?agent_id={id} body { change_set_id? } → { change_set_id, redone:[...], next_undoable } (422 nothing_to_redo) +``` + ## Content Resources (upload and manage assets) ``` diff --git a/public/llms.txt b/public/llms.txt index 9d0ed6a..5c2a851 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -446,6 +446,12 @@ GET /v1/vidsheet/:id/global_variables?agent_id= POST /v1/vidsheet/:id/import_global_variables?agent_id= (XLSX) GET /v1/vidsheet/global_variables_template (download template) +# Undo / Redo (change-set history — undo/redo a grouped edit) +GET /v1/vidsheet/:id/operations?agent_id=&limit=&include_undone= — recent undoable change sets (newest first) +GET /v1/vidsheet/:id/operations/last?agent_id= — next-to-undo change set (or null) +POST /v1/vidsheet/:id/operations/undo?agent_id= — undo last (or {change_set_id}); 422 nothing_to_undo, 409 undo_conflict +POST /v1/vidsheet/:id/operations/redo?agent_id= — redo last undone (or {change_set_id}); 422 nothing_to_redo, 409 redo_conflict + # Content Resources & Assets GET /v1/content_resources?agent_id=&type=&page= POST /v1/content_resources?agent_id= (multipart) diff --git a/public/openapi.yaml b/public/openapi.yaml index ac4757f..5baa156 100644 --- a/public/openapi.yaml +++ b/public/openapi.yaml @@ -1581,6 +1581,205 @@ paths: type: string format: binary + # ── Undo / redo (change-set history) ─────────────────────── + /vidsheet/{sheet_id}/operations: + get: + operationId: listVidsheetOperations + x-phase: edit + summary: List undo/redo change sets + description: | + Returns the recent undoable change sets for a vidsheet (the undo/redo history), + newest-first. Each change set is a grouped, atomic write (rows/columns/cells/layers + edited together in one request). Set `include_undone=true` to also list change sets + that have already been undone. + tags: [Sheets] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + description: Max change sets to return (1-100, default 20). + - name: include_undone + in: query + required: false + schema: + type: boolean + default: false + description: Include already-undone change sets (default false). + responses: + '200': + description: Recent change sets + content: + application/json: + schema: + type: object + properties: + change_sets: + type: array + items: + $ref: '#/components/schemas/ChangeSet' + '401': + $ref: '#/components/responses/Unauthorized' + '422': + description: Project not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /vidsheet/{sheet_id}/operations/last: + get: + operationId: getLastVidsheetOperation + x-phase: edit + summary: Get the next-to-undo change set + description: | + Returns the single next-to-undo change set for a vidsheet — what the undo + button would take back. `{change_set: null}` when the undo stack is empty. + Cheaper than `GET /operations` when you only need the top of the undo stack. + tags: [Sheets] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + responses: + '200': + description: Next-to-undo change set (or null) + content: + application/json: + schema: + type: object + properties: + change_set: + allOf: + - $ref: '#/components/schemas/ChangeSet' + nullable: true + '401': + $ref: '#/components/responses/Unauthorized' + '422': + description: Project not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /vidsheet/{sheet_id}/operations/undo: + post: + operationId: undoVidsheetOperation + x-phase: edit + summary: Undo the last change set + description: | + Undoes the most recent undoable change set (or a specific one by `change_set_id`). + Returns the operations that were undone plus the new next-to-undo change set. + `nothing_to_undo` (422) when the stack is empty; `undo_conflict` (409) means the + vidsheet changed underneath you — refresh the engine and retry. + tags: [Sheets] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Undo this specific change set instead of the most recent undoable one. + responses: + '200': + description: Change set undone + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + undone: + type: array + items: + $ref: '#/components/schemas/ChangeSet' + next_undoable: + allOf: + - $ref: '#/components/schemas/ChangeSet' + nullable: true + '401': + $ref: '#/components/responses/Unauthorized' + '409': + description: Undo conflict — refresh the engine and retry + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: Nothing to undo, or project not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + /vidsheet/{sheet_id}/operations/redo: + post: + operationId: redoVidsheetOperation + x-phase: edit + summary: Redo the last undone change set + description: | + Redoes the most recently undone change set (or a specific one by `change_set_id`). + Re-applies something just undone. `nothing_to_redo` (422) when there is nothing to + redo; `redo_conflict` (409) — refresh the engine and retry. + tags: [Sheets] + parameters: + - $ref: '#/components/parameters/AgentId' + - $ref: '#/components/parameters/SheetId' + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + description: Redo this specific change set instead of the most recently undone one. + responses: + '200': + description: Change set redone + content: + application/json: + schema: + type: object + properties: + change_set_id: + type: string + redone: + type: array + items: + $ref: '#/components/schemas/ChangeSet' + next_undoable: + allOf: + - $ref: '#/components/schemas/ChangeSet' + nullable: true + '401': + $ref: '#/components/responses/Unauthorized' + '409': + description: Redo conflict — refresh the engine and retry + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: Nothing to redo, or project not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + # ── Automation ───────────────────────────────────────────── /agents/{agent_id}/automation_config: get: @@ -4968,6 +5167,28 @@ components: type: string description: Machine-readable error code. + ChangeSet: + type: object + description: | + A grouped, atomic vidsheet change set on the undo/redo stack. Each change set + bundles the operations (row/column/cell/layer writes) from a single request so + they can be walked back or re-applied together. + properties: + change_set_id: + type: string + description: Stable ID of this change set. Pass to undo/redo to target a specific one. + undone: + type: boolean + description: Whether this change set has been undone (true) or is still applied (false). + summary: + type: string + description: Short human-readable label for the change set (e.g. "Updated 3 cells"). + operations: + type: array + description: The individual operations grouped in this change set. + items: + type: object + # ── Agent Core schemas ────────────────────────────────── # Flat schema — every field name mirrors the public Agent Core setup fields. AgentCore: diff --git a/src/content/docs/reference/endpoints-index.mdx b/src/content/docs/reference/endpoints-index.mdx index 3f1da42..d3ba650 100644 --- a/src/content/docs/reference/endpoints-index.mdx +++ b/src/content/docs/reference/endpoints-index.mdx @@ -189,6 +189,15 @@ All endpoints authenticate with `X-API-Key: ` or `Authorization: Beare | POST | /v1/vidsheet/:id/import_global_variables | edit | | GET | /v1/vidsheet/global_variables_template | edit | +## Undo / Redo + +| Method | Path | Phase | +|--------|------|-------| +| GET | /v1/vidsheet/:id/operations | edit | +| GET | /v1/vidsheet/:id/operations/last | edit | +| POST | /v1/vidsheet/:id/operations/undo | edit | +| POST | /v1/vidsheet/:id/operations/redo | edit | + ## Content Resources & Assets | Method | Path | Phase | diff --git a/src/content/docs/reference/undo-redo.mdx b/src/content/docs/reference/undo-redo.mdx new file mode 100644 index 0000000..c4a16cd --- /dev/null +++ b/src/content/docs/reference/undo-redo.mdx @@ -0,0 +1,164 @@ +--- +title: Undo / Redo +description: Walk back and re-apply grouped changes to a vidsheet. +--- + +import { Aside } from '@astrojs/starlight/components'; + +Every grouped write to a vidsheet — a row, column, cell, or layer edit made in a single +request — is recorded as a **change set** on an undo/redo stack. You can list recent change +sets, see what the next undo would take back, and undo or redo a change set. Pass an explicit +`change_set_id` to undo or redo a specific change set instead of the most recent one. + + + + + +--- + +## List change sets + +Returns the recent undoable change sets for a sheet, newest-first. + +``` +GET /v1/vidsheet/{id}/operations?agent_id={agent_id} +``` + +### Path parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `id` | integer | The sheet ID. | + +### Query parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `limit` | integer | `20` | Max change sets to return (`1`–`100`). | +| `include_undone` | boolean | `false` | Include change sets that have already been undone. | + +### Response + +Returns `{ change_sets: [...] }`, newest first. Each change set has a `change_set_id`, a +`summary`, and the grouped `operations`. + +### Example + +```bash +curl "https://api.gen.pro/v1/vidsheet/101/operations?agent_id=42&limit=10" \ + -H "X-API-Key: your-api-key" +``` + +--- + +## Get the next-to-undo change set + +Returns the single change set that the undo button would take back. Cheaper than listing when +you only need the top of the undo stack. + +``` +GET /v1/vidsheet/{id}/operations/last?agent_id={agent_id} +``` + +### Response + +Returns `{ change_set: { ... } }`, or `{ change_set: null }` when the undo stack is empty. + +### Example + +```bash +curl "https://api.gen.pro/v1/vidsheet/101/operations/last?agent_id=42" \ + -H "X-API-Key: your-api-key" +``` + +--- + +## Undo a change set + +Undoes the most recent undoable change set, or a specific one when you pass `change_set_id`. + +``` +POST /v1/vidsheet/{id}/operations/undo?agent_id={agent_id} +``` + +### Request body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `change_set_id` | string | No | Undo this specific change set instead of the most recent undoable one. | + +### Response + +Returns `{ change_set_id, undone: [...], next_undoable: { ... } | null }`. `undone` lists the +operations that were reversed; `next_undoable` is the new top of the undo stack. + +### Example + +```bash +# undo the most recent change set +curl -X POST "https://api.gen.pro/v1/vidsheet/101/operations/undo?agent_id=42" \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{}' + +# undo a specific change set +curl -X POST "https://api.gen.pro/v1/vidsheet/101/operations/undo?agent_id=42" \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{"change_set_id":"01J..."}' +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `409` | `undo_conflict` | The sheet changed underneath you — re-fetch the sheet and retry. | +| `422` | `nothing_to_undo` | The undo stack is empty. | +| `422` | `change_set_not_found` | The given `change_set_id` does not exist. | +| `422` | `project_not_found` | The sheet does not exist or is not accessible. | + +--- + +## Redo a change set + +Redoes the most recently undone change set, or a specific one when you pass `change_set_id`. +Use this to re-apply something you just undid. + +``` +POST /v1/vidsheet/{id}/operations/redo?agent_id={agent_id} +``` + +### Request body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `change_set_id` | string | No | Redo this specific change set instead of the most recently undone one. | + +### Response + +Returns `{ change_set_id, redone: [...], next_undoable: { ... } | null }`. + +### Example + +```bash +curl -X POST "https://api.gen.pro/v1/vidsheet/101/operations/redo?agent_id=42" \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +### Errors + +| Status | Error code | Description | +|--------|------------|-------------| +| `409` | `redo_conflict` | The sheet changed underneath you — re-fetch the sheet and retry. | +| `422` | `nothing_to_redo` | There is nothing to redo. | +| `422` | `change_set_not_found` | The given `change_set_id` does not exist. | +| `422` | `project_not_found` | The sheet does not exist or is not accessible. |