docs-combiner 0.2.2 → 1.0.0

package/dist/agentApi/spec.js

@@ -0,0 +1,1045 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAgentApiSpec = getAgentApiSpec;
+/** OpenAPI-like description for GET /api/spec */
+function getAgentApiSpec(host, port, version) {
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'Docs Combiner Agent API',
+            version,
+            description: 'Local-only API for automation agents controlling Docs Combiner.',
+        },
+        servers: [
+            {
+                url: `http://${host}:${port}`,
+                description: 'Loopback-only Electron main process API',
+            },
+        ],
+        paths: {
+            '/api/windows': {
+                get: {
+                    operationId: 'listWindows',
+                    summary: 'List open Docs Combiner work sessions',
+                    responses: {
+                        '200': {
+                            description: 'Current work sessions available to an automation agent',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'windows'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            windows: {
+                                                type: 'array',
+                                                items: { $ref: '#/components/schemas/AgentWorkSessionInfo' },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                post: {
+                    operationId: 'createWindow',
+                    summary: 'Open a new Docs Combiner work session (Electron window)',
+                    requestBody: {
+                        required: false,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        workspaceId: {
+                                            type: 'string',
+                                            description: 'Optional stable session id. Generated if omitted.',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '201': {
+                            description: 'New session created and Agent API is ready in the renderer',
+                        },
+                        '202': {
+                            description: 'New window opened, but renderer Agent API is not ready yet',
+                        },
+                    },
+                },
+            },
+            '/api/catalog': {
+                get: {
+                    operationId: 'getDriveCatalog',
+                    summary: 'List offers, campaign groups and workspace folders from Google Drive',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                            description: 'Prefer data from this session if available.',
+                        },
+                    ],
+                    responses: {
+                        '200': { description: 'Drive catalog snapshot' },
+                        '503': { description: 'No session with Agent API ready' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}': {
+                get: {
+                    operationId: 'getSessionInfo',
+                    summary: 'Return all agent-visible information from one work session',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Current live session state',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'session'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            session: { $ref: '#/components/schemas/AgentSessionInfo' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+                delete: {
+                    operationId: 'closeSession',
+                    summary: 'Close one work session window',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Session window closed',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'closed'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            closed: { type: 'string' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '404': { description: 'Session not found' },
+                    },
+                },
+                patch: {
+                    operationId: 'patchSessionInfo',
+                    summary: 'Partially update one work session without touching omitted fields',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/PatchSessionInfoRequest' },
+                                examples: {
+                                    productOnly: {
+                                        value: { generation: { product: 'Detoxil Water' } },
+                                    },
+                                    firstGeoOnly: {
+                                        value: { generation: { firstGeo: 'Romania' } },
+                                    },
+                                    geoPriceLinkPartial: {
+                                        value: {
+                                            generation: {
+                                                geoBlock: [
+                                                    { id: 'market-1', link: 'https://example.com/ro/' },
+                                                ],
+                                            },
+                                        },
+                                    },
+                                    creativeSelectionsOnly: {
+                                        value: {
+                                            creativeSelections: {
+                                                selectedTextApproachNumbers: [1, 2, 3],
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Session was partially updated',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'session'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            session: { $ref: '#/components/schemas/AgentSessionInfo' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': { description: 'Invalid partial update payload' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/catalog/groups': {
+                post: {
+                    operationId: 'createCampaignGroup',
+                    summary: 'Create a campaign group folder on Google Drive (same as UI «Создать» for group)',
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['name'],
+                                    properties: {
+                                        name: { type: 'string', description: 'Group folder name under campaigns root' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Group folder created' },
+                        '400': { description: 'Invalid payload or group already exists' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/catalog/workspaces': {
+                post: {
+                    operationId: 'createWorkspaceFolder',
+                    summary: 'Create a workspace folder inside a campaign group on Google Drive',
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['groupName', 'name'],
+                                    properties: {
+                                        groupName: { type: 'string' },
+                                        name: { type: 'string', description: 'Workspace folder name' },
+                                        select: {
+                                            type: 'boolean',
+                                            default: true,
+                                            description: 'Select the new workspace in this session after creation',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Workspace folder created' },
+                        '400': { description: 'Invalid payload or folder already exists' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/generate': {
+                post: {
+                    operationId: 'startGeneration',
+                    summary: 'Start content, image or catalog generation (same as UI buttons)',
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                    ],
+                    requestBody: {
+                        required: false,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        targets: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'string',
+                                                enum: ['content', 'images', 'catalog', 'all'],
+                                            },
+                                            description: 'Sequential targets. Default: ["content"]. "images" creates the initial image slot matrix only; after slots exist it is blocked unless force:true is passed, otherwise use regenerate-images with explicit indices.',
+                                        },
+                                        async: {
+                                            type: 'boolean',
+                                            description: 'If true, return 202 immediately and poll jobs for completion.',
+                                        },
+                                        force: {
+                                            type: 'boolean',
+                                            description: 'If true, allow a full "images" run even when image slots already exist. This overwrites the entire existing batch (including OK/uploaded slots). Without it, full image generation is blocked once slots exist.',
+                                        },
+                                    },
+                                },
+                                examples: {
+                                    contentAndImages: {
+                                        value: { targets: ['content', 'images'] },
+                                    },
+                                    fullPipeline: {
+                                        value: { targets: ['content', 'images', 'catalog'] },
+                                    },
+                                    forceFullImageRebuild: {
+                                        value: { targets: ['images'], force: true },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Generation started or completed for requested targets' },
+                        '202': { description: 'Async generation accepted; poll jobs endpoints' },
+                        '400': { description: 'Validation failed or unknown target' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready or job already running' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/setup-campaign': {
+                post: {
+                    operationId: 'setupCampaignWorkspace',
+                    summary: 'Select campaign group, workspace folder, offer binding and optional generation fields',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/SetupCampaignWorkspaceRequest' },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Campaign workspace configured' },
+                        '400': { description: 'Invalid payload or workspace not found' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/geo-block': {
+                post: {
+                    operationId: 'fillGeoBlock',
+                    summary: 'Update the geo + price + link block in one work session',
+                    description: 'A single object partially updates one row and preserves omitted fields. A markets array sets the exact row list, removing rows not present in the array; omitted fields inside each row are preserved by id/index when possible.',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/FillGeoBlockRequest' },
+                                examples: {
+                                    singleMarket: {
+                                        value: {
+                                            geo: 'Romania',
+                                            priceWithCurrency: '149 RON',
+                                            link: 'https://example.com/product/',
+                                        },
+                                    },
+                                    multipleMarkets: {
+                                        value: {
+                                            markets: [
+                                                {
+                                                    geo: 'Romania',
+                                                    priceWithCurrency: '149 RON',
+                                                    link: 'https://example.com/ro/',
+                                                },
+                                                {
+                                                    geo: 'Hungary',
+                                                    priceWithCurrency: '11400 HUF',
+                                                    link: 'https://example.com/hu/',
+                                                },
+                                            ],
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Geo block was replaced',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'markets'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            markets: {
+                                                type: 'array',
+                                                items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': { description: 'Invalid geo block payload' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/creative-selections': {
+                get: {
+                    operationId: 'getCreativeSelections',
+                    summary: 'Return selected text and image creative approaches for one work session',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Current creative approach selections',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'selections'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            selections: { $ref: '#/components/schemas/CreativeSelections' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+                post: {
+                    operationId: 'setCreativeSelections',
+                    summary: 'Set selected text and image creative approaches for one work session',
+                    parameters: [
+                        {
+                            name: 'sessionId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/SetCreativeSelectionsRequest' },
+                                examples: {
+                                    uiNumbers: {
+                                        value: {
+                                            selectedTextApproachNumbers: [1, 2, 3],
+                                            imageApproachCounts: [1, 1, 0, 0, 2, 0, 0, 0, 0, 0],
+                                        },
+                                    },
+                                    imageNumbers: {
+                                        value: {
+                                            selectedTextApproachIndices: [0, 1, 2],
+                                            selectedImageApproachNumbers: [1, 5],
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Creative approach selections were updated',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['ok', 'selections'],
+                                        properties: {
+                                            ok: { type: 'boolean', const: true },
+                                            selections: { $ref: '#/components/schemas/CreativeSelections' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': { description: 'Invalid creative selections payload' },
+                        '404': { description: 'Session not found' },
+                        '409': { description: 'Session renderer is not ready for agent calls' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/capabilities': {
+                get: {
+                    operationId: 'getCapabilities',
+                    summary: 'Return what the agent is allowed to read or change in this session',
+                    responses: { '200': { description: 'Session capabilities' } },
+                },
+            },
+            '/api/windows/{sessionId}/validation': {
+                get: {
+                    operationId: 'getValidation',
+                    summary: 'Return readiness checks and blocking issues for this session',
+                    responses: { '200': { description: 'Validation checklist' } },
+                },
+            },
+            '/api/windows/{sessionId}/jobs': {
+                get: {
+                    operationId: 'listJobs',
+                    summary: 'Return observable UI job statuses for this session',
+                    responses: { '200': { description: 'Known job statuses' } },
+                },
+            },
+            '/api/windows/{sessionId}/jobs/{jobId}': {
+                get: {
+                    operationId: 'getJobStatus',
+                    summary: 'Return one observable UI job status',
+                    parameters: [
+                        { name: 'sessionId', in: 'path', required: true, schema: { type: 'string' } },
+                        { name: 'jobId', in: 'path', required: true, schema: { type: 'string' } },
+                        { name: 'wait', in: 'query', required: false, schema: { type: 'string', enum: ['1', 'true'] } },
+                        { name: 'timeout', in: 'query', required: false, schema: { type: 'integer', minimum: 1, maximum: 600 } },
+                    ],
+                    responses: { '200': { description: 'Job status' }, '404': { description: 'Unknown job id' } },
+                },
+            },
+            '/api/windows/{sessionId}/approach-matrix': {
+                get: {
+                    operationId: 'getApproachMatrix',
+                    summary: 'Return creative approach matrix for one work session',
+                    responses: { '200': { description: 'Approach matrix snapshot' } },
+                },
+                post: {
+                    operationId: 'setApproachMatrix',
+                    summary: 'Set creative approach matrix for one work session',
+                    responses: { '200': { description: 'Approach matrix updated' }, '400': { description: 'Invalid matrix payload' } },
+                },
+            },
+            '/api/windows/{sessionId}/agent-control': {
+                get: {
+                    operationId: 'getAgentControlStatus',
+                    summary: 'Return whether this session is agent-controlled or manual',
+                    responses: { '200': { description: 'Agent control mode' } },
+                },
+                post: {
+                    operationId: 'setAgentControlMode',
+                    summary: 'Switch agent control mode for this session window',
+                    responses: { '200': { description: 'Mode updated' }, '400': { description: 'Invalid mode' } },
+                },
+            },
+            '/api/windows/{sessionId}/actions/load-content': {
+                post: {
+                    operationId: 'loadContent',
+                    summary: 'Load project-settings and generated artifacts from Drive',
+                    responses: { '200': { description: 'Load completed' }, '202': { description: 'Async load accepted' } },
+                },
+            },
+            '/api/windows/{sessionId}/actions/upload-images': {
+                post: {
+                    operationId: 'uploadImages',
+                    summary: 'Upload pending creative images to Drive',
+                    responses: { '200': { description: 'Upload completed' }, '202': { description: 'Async upload accepted' } },
+                },
+            },
+            '/api/windows/{sessionId}/actions/check-images': {
+                post: {
+                    operationId: 'checkImages',
+                    summary: 'Re-run validator on existing creative images (no new generation; manual/agent only)',
+                    responses: { '200': { description: 'Check completed' }, '202': { description: 'Async check accepted' } },
+                },
+            },
+            '/api/windows/{sessionId}/actions/regenerate-pair': {
+                post: {
+                    operationId: 'regeneratePair',
+                    summary: 'Regenerate one title+text pair (same geo and approach as in UI)',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['index'],
+                                    properties: {
+                                        index: { type: 'integer', minimum: 1, description: '1-based pair number' },
+                                    },
+                                },
+                                examples: {
+                                    pair1: { value: { index: 1 } },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Pair regenerated successfully' },
+                        '400': { description: 'Invalid index or pair still incomplete after retries' },
+                    },
+                },
+            },
+            '/api/windows/{sessionId}/actions/regenerate-images': {
+                post: {
+                    operationId: 'regenerateImages',
+                    summary: 'Regenerate selected creative image slots without resetting the full matrix',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['indices'],
+                                    properties: {
+                                        indices: {
+                                            type: 'array',
+                                            items: { type: 'integer', minimum: 1 },
+                                            minItems: 1,
+                                            description: 'Required 1-based creative slot numbers; Agent API does not auto-select by mode.',
+                                        },
+                                        regenerateMode: {
+                                            type: 'string',
+                                            enum: ['improve', 'fresh'],
+                                            default: 'fresh',
+                                            description: 'improve = UI regenerate; fresh = regenerate from scratch',
+                                        },
+                                        async: { type: 'boolean', default: true },
+                                        runValidator: { type: 'boolean', default: true },
+                                        uploadAfterOk: { type: 'boolean', description: 'Upload to Drive after validator OK' },
+                                    },
+                                },
+                                examples: {
+                                    explicitIndices: {
+                                        value: {
+                                            indices: [3, 10, 15, 16],
+                                            regenerateMode: 'fresh',
+                                            async: true,
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Regeneration completed for accepted slots' },
+                        '202': { description: 'Async regeneration accepted; poll jobs/regenerateImages' },
+                        '400': { description: 'No eligible slots or invalid payload' },
+                    },
+                },
+            },
+            '/api/health': {
+                get: {
+                    operationId: 'getHealth',
+                    summary: 'Return Agent API liveness and session counts',
+                    responses: { '200': { description: 'Health snapshot' } },
+                },
+            },
+            '/api/windows/{sessionId}/generated': {
+                get: {
+                    operationId: 'getGenerated',
+                    summary: 'Return generated titles, texts, images and catalog rows',
+                    responses: { '200': { description: 'Generated session artifacts' } },
+                },
+                patch: {
+                    operationId: 'patchGenerated',
+                    summary: 'Partially edit generated titles, texts or image metadata without starting generation',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: { $ref: '#/components/schemas/PatchGeneratedRequest' },
+                                examples: {
+                                    titleText: {
+                                        value: {
+                                            titles: [{ index: 1, title: 'New title' }],
+                                            texts: [{ index: 1, text: 'New text' }],
+                                        },
+                                    },
+                                    imageMetadata: {
+                                        value: {
+                                            images: [{ index: 1, failed: false, errorMessage: '' }],
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: { '200': { description: 'Generated artifacts were updated' }, '400': { description: 'Invalid patch' } },
+                },
+            },
+            '/api/windows/{sessionId}/logs': {
+                get: {
+                    operationId: 'getLogs',
+                    summary: 'Return recent content, image and catalog replacement logs',
+                    responses: { '200': { description: 'Session logs' } },
+                },
+            },
+            '/api/spec': {
+                get: {
+                    operationId: 'getAgentApiSpec',
+                    summary: 'Return the machine-readable Agent API description',
+                    responses: {
+                        '200': {
+                            description: 'OpenAPI-like API description for automation agents',
+                        },
+                    },
+                },
+            },
+        },
+        components: {
+            schemas: {
+                AgentWorkSessionInfo: {
+                    type: 'object',
+                    required: ['id', 'title', 'description', 'active', 'url', 'endpoints'],
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Stable workspace/session id to use in future agent operations.',
+                        },
+                        title: { type: 'string' },
+                        description: {
+                            type: 'string',
+                            description: 'Short human-readable summary of what is open in this session.',
+                        },
+                        folderId: {
+                            type: 'string',
+                            description: 'Current Google Drive folder id, when selected.',
+                        },
+                        folderPath: {
+                            type: 'string',
+                            description: 'Two-level display path for the current Drive folder, for example OFFERS/OfferName.',
+                        },
+                        active: { type: 'boolean' },
+                        url: {
+                            type: 'string',
+                            description: 'Full local URL for reading this session state.',
+                        },
+                        endpoints: {
+                            type: 'object',
+                            required: ['info', 'update', 'geoBlock', 'creativeSelections', 'capabilities', 'validation', 'generated', 'logs', 'jobs'],
+                            properties: {
+                                info: { type: 'string' },
+                                update: { type: 'string' },
+                                geoBlock: { type: 'string' },
+                                creativeSelections: { type: 'string' },
+                                capabilities: { type: 'string' },
+                                validation: { type: 'string' },
+                                generated: { type: 'string' },
+                                logs: { type: 'string' },
+                                jobs: { type: 'string' },
+                            },
+                        },
+                    },
+                },
+                GeoBlockMarket: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        geo: { type: 'string' },
+                        priceWithCurrency: { type: 'string' },
+                        link: { type: 'string' },
+                    },
+                },
+                FillGeoBlockRequest: {
+                    oneOf: [
+                        { $ref: '#/components/schemas/GeoBlockMarket' },
+                        {
+                            type: 'object',
+                            required: ['markets'],
+                            properties: {
+                                markets: {
+                                    type: 'array',
+                                    minItems: 1,
+                                    items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                                },
+                            },
+                        },
+                    ],
+                },
+                PatchSessionInfoRequest: {
+                    type: 'object',
+                    description: 'Partial session update. Omitted fields are left unchanged.',
+                    properties: {
+                        generateProduct: { type: 'string' },
+                        generateAdditionalInfo: { type: 'string' },
+                        generateGeo: { type: 'string' },
+                        generatePriceWithCurrency: { type: 'string' },
+                        link: { type: 'string' },
+                        generationMarkets: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                        },
+                        markets: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                        },
+                        geoBlock: {
+                            type: 'array',
+                            items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                        },
+                        generation: {
+                            type: 'object',
+                            properties: {
+                                product: { type: 'string' },
+                                additionalInfo: { type: 'string' },
+                                firstGeo: { type: 'string' },
+                                firstPriceWithCurrency: { type: 'string' },
+                                firstLink: { type: 'string' },
+                                geoBlock: {
+                                    type: 'array',
+                                    items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                                },
+                            },
+                        },
+                        catalogUrlSettings: { type: 'object' },
+                        creativeSelections: { $ref: '#/components/schemas/SetCreativeSelectionsRequest' },
+                        promptSettings: { type: 'object' },
+                        drive: {
+                            type: 'object',
+                            description: 'Select campaign group, workspace folder and offer binding before generation.',
+                            properties: {
+                                groupName: { type: 'string' },
+                                workspaceFolderId: { type: 'string' },
+                                workspaceName: { type: 'string' },
+                                offer: { type: 'string' },
+                            },
+                        },
+                    },
+                },
+                SetupCampaignWorkspaceRequest: {
+                    type: 'object',
+                    required: ['groupName'],
+                    properties: {
+                        groupName: { type: 'string' },
+                        workspaceFolderId: { type: 'string' },
+                        workspaceName: { type: 'string' },
+                        offer: { type: 'string' },
+                        generation: { type: 'object' },
+                        creativeSelections: { $ref: '#/components/schemas/SetCreativeSelectionsRequest' },
+                    },
+                },
+                DriveCatalog: {
+                    type: 'object',
+                    description: 'Offers root, campaigns tree and current session Drive bindings.',
+                },
+                CreativeSelections: {
+                    type: 'object',
+                    required: ['textApproaches', 'imageApproaches'],
+                    properties: {
+                        textApproaches: {
+                            type: 'object',
+                            required: ['selectedIndices', 'selectedNumbers'],
+                            properties: {
+                                selectedIndices: {
+                                    type: 'array',
+                                    description: '0-based selected text approach indices.',
+                                    items: { type: 'number' },
+                                },
+                                selectedNumbers: {
+                                    type: 'array',
+                                    description: '1-based selected text approach numbers as shown in the UI.',
+                                    items: { type: 'number' },
+                                },
+                            },
+                        },
+                        imageApproaches: {
+                            type: 'object',
+                            required: ['counts', 'selectedIndices', 'selectedNumbers', 'maxPerApproach'],
+                            properties: {
+                                counts: {
+                                    type: 'array',
+                                    description: 'Image count per creative approach, 10 items, values from 0 to maxPerApproach.',
+                                    items: { type: 'number' },
+                                },
+                                selectedIndices: {
+                                    type: 'array',
+                                    description: '0-based image approach indices where count is greater than 0.',
+                                    items: { type: 'number' },
+                                },
+                                selectedNumbers: {
+                                    type: 'array',
+                                    description: '1-based image approach numbers where count is greater than 0.',
+                                    items: { type: 'number' },
+                                },
+                                maxPerApproach: { type: 'number' },
+                            },
+                        },
+                    },
+                },
+                SetCreativeSelectionsRequest: {
+                    type: 'object',
+                    properties: {
+                        selectedTextApproachIndices: {
+                            type: 'array',
+                            description: '0-based text approach indices. At least two unique approaches are required if provided.',
+                            items: { type: 'number' },
+                        },
+                        selectedTextApproachNumbers: {
+                            type: 'array',
+                            description: '1-based text approach numbers as shown in the UI. At least two unique approaches are required if provided.',
+                            items: { type: 'number' },
+                        },
+                        imageApproachCounts: {
+                            type: 'array',
+                            description: 'Image count per creative approach, 10 items, values from 0 to maxPerApproach.',
+                            items: { type: 'number' },
+                        },
+                        selectedImageApproachIndices: {
+                            type: 'array',
+                            description: '0-based image approach indices. Each selected approach gets count=1.',
+                            items: { type: 'number' },
+                        },
+                        selectedImageApproachNumbers: {
+                            type: 'array',
+                            description: '1-based image approach numbers as shown in the UI. Each selected approach gets count=1.',
+                            items: { type: 'number' },
+                        },
+                    },
+                },
+                PatchGeneratedRequest: {
+                    type: 'object',
+                    description: 'Partial edit for generated artifacts. Omitted fields are unchanged.',
+                    properties: {
+                        titles: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                required: ['index'],
+                                properties: {
+                                    index: { type: 'number', description: '1-based title row index.' },
+                                    title: { type: 'string' },
+                                    failed: { type: 'boolean' },
+                                    errorMessage: { type: 'string' },
+                                },
+                            },
+                        },
+                        texts: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                required: ['index'],
+                                properties: {
+                                    index: { type: 'number', description: '1-based text row index.' },
+                                    text: { type: 'string' },
+                                    failed: { type: 'boolean' },
+                                    errorMessage: { type: 'string' },
+                                },
+                            },
+                        },
+                        images: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                required: ['index'],
+                                properties: {
+                                    index: { type: 'number', description: '1-based image slot index.' },
+                                    imageUrl: { type: 'string' },
+                                    approach: { type: 'string' },
+                                    geo: { type: 'string' },
+                                    priceWithCurrency: { type: 'string' },
+                                    aspectRatio: { type: 'string' },
+                                    uploaded: { type: 'boolean' },
+                                    failed: { type: 'boolean' },
+                                    errorMessage: { type: 'string' },
+                                    checkStatus: { type: 'string', description: 'pending | checking | ok | needs_rebuild.' },
+                                    checkResult: { type: 'string' },
+                                    checkErrors: { type: 'array', items: { type: 'string' } },
+                                    checkFailed: {
+                                        type: 'boolean',
+                                        description: 'true = validator transport error (e.g. "Failed to fetch"), not a real rejection. The image is fine; just re-run the validator (check-images) instead of regenerating.',
+                                    },
+                                    recommendedAction: {
+                                        type: 'string',
+                                        enum: ['recheck', 'rebuild'],
+                                        description: 'Present only for problem slots. "recheck" → POST .../actions/check-images with this index (validator transport error). "rebuild" → POST .../actions/regenerate-images with this index (generation failed or validator rejected the image).',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                AgentSessionInfo: {
+                    type: 'object',
+                    description: 'Live renderer state for one Docs Combiner work session.',
+                    required: ['id', 'title', 'updatedAt', 'generation', 'snapshot'],
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        updatedAt: { type: 'string', format: 'date-time' },
+                        drive: { type: 'object' },
+                        generation: {
+                            type: 'object',
+                            properties: {
+                                product: { type: 'string' },
+                                additionalInfo: { type: 'string' },
+                                geoBlock: {
+                                    type: 'array',
+                                    items: { $ref: '#/components/schemas/GeoBlockMarket' },
+                                },
+                                firstGeo: { type: 'string' },
+                                firstPriceWithCurrency: { type: 'string' },
+                                firstLink: { type: 'string' },
+                                brand: { type: 'string' },
+                            },
+                        },
+                        catalogUrlSettings: { type: 'object' },
+                        promptSettings: { type: 'object' },
+                        snapshot: {
+                            type: 'object',
+                            description: 'Serializable workspace snapshot used by the app autosave.',
+                        },
+                    },
+                },
+            },
+        },
+    };
+}