docs-combiner 0.4.0 → 1.0.0

package/dist/server/spec.js

@@ -0,0 +1,544 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getServerApiSpec = getServerApiSpec;
+function getServerApiSpec(baseUrl, version) {
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'Docs Combiner Server API',
+            version,
+            description: 'Single-user VPS API for Docs Combiner. Phase 1 skeleton: health, protected spec, write-only secrets and global settings.',
+        },
+        servers: [{ url: baseUrl }],
+        security: [{ bearerAuth: [] }],
+        paths: {
+            '/api/health': {
+                get: {
+                    security: [],
+                    summary: 'Public health check',
+                    responses: {
+                        '200': { description: 'Server is running' },
+                    },
+                },
+            },
+            '/api/spec': {
+                get: {
+                    summary: 'Return this API spec',
+                    responses: {
+                        '200': { description: 'OpenAPI-like JSON spec' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/secrets/status': {
+                get: {
+                    summary: 'Return booleans for configured secrets; never returns secret values',
+                    responses: {
+                        '200': { description: 'Secret status map' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/secrets': {
+                put: {
+                    summary: 'Write-only update for server secrets',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    additionalProperties: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Secrets updated; response contains only updated keys and status booleans' },
+                        '400': { description: 'JSON object required' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/settings': {
+                get: {
+                    summary: 'Return global non-secret server settings',
+                    responses: {
+                        '200': { description: 'Settings JSON' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+                put: {
+                    summary: 'Replace global non-secret server settings',
+                    responses: {
+                        '200': { description: 'Settings saved' },
+                        '400': { description: 'JSON object required' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/catalog': {
+                get: {
+                    summary: 'Read offers, campaign groups, workspaces and campaigns.csv from Google Drive',
+                    description: 'If folder ids are omitted, the server uses settings.driveRoots from /api/settings.',
+                    parameters: [
+                        {
+                            name: 'offersRootFolderId',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                            description: 'Google Drive folder id or folder URL for the offers root.',
+                        },
+                        {
+                            name: 'campaignsRootFolderId',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                            description: 'Google Drive folder id or folder URL for the campaigns root.',
+                        },
+                    ],
+                    responses: {
+                        '200': { description: 'Drive catalog snapshot' },
+                        '400': { description: 'Missing folder ids or Drive error' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/workspaces/{workspaceId}': {
+                get: {
+                    summary: 'Read a single workspace snapshot from Google Drive',
+                    description: 'Reads project-settings.json, campaign binding from campaigns.csv, offer-settings.json and product image availability. Read-only.',
+                    parameters: [
+                        {
+                            name: 'workspaceId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                            description: 'Google Drive workspace folder id.',
+                        },
+                    ],
+                    responses: {
+                        '200': { description: 'Workspace snapshot' },
+                        '400': { description: 'Invalid workspace id' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/google/refresh': {
+                post: {
+                    summary: 'Refresh server-side Google OAuth access token',
+                    description: 'Uses server-side clientId/clientSecret/refreshToken, writes the fresh accessToken to server secrets, and returns only secret status booleans.',
+                    responses: {
+                        '200': { description: 'Google OAuth refreshed' },
+                        '400': { description: 'Google OAuth secrets missing or refresh failed' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/list': {
+                post: {
+                    summary: 'Proxy Google Drive files.list through the VPS OAuth credentials',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['q', 'fields'],
+                                    properties: {
+                                        q: { type: 'string' },
+                                        fields: { type: 'string' },
+                                        supportsAllDrives: { type: 'boolean' },
+                                        pageSize: { type: 'number' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Drive list response' },
+                        '400': { description: 'Invalid payload or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/{fileId}/metadata': {
+                get: {
+                    summary: 'Proxy Google Drive files.get metadata',
+                    responses: {
+                        '200': { description: 'Drive metadata response' },
+                        '400': { description: 'Missing fields or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/{fileId}/download': {
+                get: {
+                    summary: 'Download Drive file bytes through VPS as base64 JSON',
+                    responses: {
+                        '200': { description: 'Base64 file content and content type' },
+                        '400': { description: 'Invalid file id or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/folders': {
+                post: {
+                    summary: 'Create a Google Drive folder through VPS',
+                    responses: {
+                        '200': { description: 'Drive folder create response' },
+                        '400': { description: 'Invalid payload or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/multipart': {
+                post: {
+                    summary: 'Create or update a Drive file using multipart upload through VPS',
+                    description: 'Accepts JSON multipart parts with text/base64 content to avoid exposing Google OAuth to the client.',
+                    responses: {
+                        '200': { description: 'Drive upload response' },
+                        '400': { description: 'Invalid payload or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/{fileId}/media': {
+                patch: {
+                    summary: 'Replace Drive file media content through VPS',
+                    responses: {
+                        '200': { description: 'Drive media update response' },
+                        '400': { description: 'Invalid payload or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/{fileId}': {
+                delete: {
+                    summary: 'Delete a Drive file through VPS',
+                    responses: {
+                        '200': { description: 'Drive delete response' },
+                        '400': { description: 'Invalid file id or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/drive/files/{fileId}/permissions': {
+                post: {
+                    summary: 'Create Drive file permission through VPS',
+                    responses: {
+                        '200': { description: 'Drive permission create response' },
+                        '400': { description: 'Invalid payload or server Google OAuth missing' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/openrouter/models': {
+                get: {
+                    summary: 'Fetch OpenRouter model metadata using the server-side API key',
+                    description: 'Returns raw OpenRouter models plus pre-filtered image, chat and validation model lists. Secret keys are never returned.',
+                    responses: {
+                        '200': { description: 'OpenRouter models fetched and filtered' },
+                        '400': { description: 'Server OpenRouter key is not configured' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                        '502': { description: 'OpenRouter fetch failed' },
+                    },
+                },
+            },
+            '/api/openrouter/balance': {
+                get: {
+                    summary: 'Fetch OpenRouter account/key balance using the server-side API key',
+                    responses: {
+                        '200': { description: 'OpenRouter balance fetched' },
+                        '400': { description: 'Server OpenRouter key is not configured' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/flexcard/balance': {
+                get: {
+                    summary: 'Fetch FlexCard USD finance balance using the server-side API key',
+                    responses: {
+                        '200': { description: 'FlexCard USD balance fetched' },
+                        '400': { description: 'Server FlexCard key is not configured' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/telegram/send': {
+                post: {
+                    summary: 'Send a Telegram notification using server-side bot settings',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['text'],
+                                    properties: {
+                                        text: { type: 'string' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Telegram message sent' },
+                        '400': { description: 'Server Telegram settings missing or text empty' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/jobs/content': {
+                post: {
+                    summary: 'Create a server-side content generation job',
+                    description: 'Creates a content job owned by the VPS. Each market is generated as a slot using OpenRouter, parsed into title/text pairs, and retained in job memory for polling or WebSocket events.',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['workspaceId', 'product', 'markets'],
+                                    properties: {
+                                        workspaceId: { type: 'string' },
+                                        task: { type: 'string', enum: ['generate-pairs', 'translate-ru'] },
+                                        product: { type: 'string' },
+                                        additionalInfo: { type: 'string' },
+                                        model: { type: 'string' },
+                                        count: { type: 'number' },
+                                        selectedPairApproaches: { type: 'array', items: { type: 'number' } },
+                                        pairs: {
+                                            type: 'array',
+                                            description: 'Required for task=translate-ru. Existing title/text pairs to translate to Russian.',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    title: { type: 'string' },
+                                                    text: { type: 'string' },
+                                                },
+                                            },
+                                        },
+                                        markets: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                                required: ['geo'],
+                                                properties: {
+                                                    index: { type: 'number' },
+                                                    marketId: { type: 'string' },
+                                                    marketKey: { type: 'string' },
+                                                    geo: { type: 'string' },
+                                                    priceWithCurrency: { type: 'string' },
+                                                },
+                                            },
+                                        },
+                                        metadata: { type: 'object' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '202': { description: 'Job accepted' },
+                        '400': { description: 'Invalid payload' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/jobs/images': {
+                post: {
+                    summary: 'Create a server-side in-memory image job',
+                    description: 'Creates an image job owned by the VPS and starts OpenRouter image generation for slots with prompts. Generated data URLs stay in server memory and are emitted over WebSocket; validation and Drive upload are later phases.',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['workspaceId'],
+                                    properties: {
+                                        workspaceId: { type: 'string' },
+                                        count: { type: 'number' },
+                                        model: { type: 'string' },
+                                        referenceImageUrls: { type: 'array', items: { type: 'string' } },
+                                        referenceImageJobSlots: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    jobId: { type: 'string' },
+                                                    slotIndex: { type: 'number' },
+                                                },
+                                            },
+                                        },
+                                        slots: {
+                                            type: 'array',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    index: { type: 'number' },
+                                                    prompt: { type: 'string' },
+                                                    approach: { type: 'string' },
+                                                    aspectRatio: { type: 'string', enum: ['1:1', '2:3', '4:5'] },
+                                                    imageSize: { type: 'string', enum: ['1K', '2K', '4K'] },
+                                                    model: { type: 'string' },
+                                                    sourceImageUrl: { type: 'string' },
+                                                    sourceImageJobSlot: {
+                                                        type: 'object',
+                                                        properties: {
+                                                            jobId: { type: 'string' },
+                                                            slotIndex: { type: 'number' },
+                                                        },
+                                                    },
+                                                    referenceImageUrls: { type: 'array', items: { type: 'string' } },
+                                                    referenceImageJobSlots: {
+                                                        type: 'array',
+                                                        items: {
+                                                            type: 'object',
+                                                            properties: {
+                                                                jobId: { type: 'string' },
+                                                                slotIndex: { type: 'number' },
+                                                            },
+                                                        },
+                                                    },
+                                                    validation: {
+                                                        type: 'object',
+                                                        description: 'Optional validation input. When present, server validates generated data URL in memory before upload.',
+                                                        properties: {
+                                                            product: { type: 'string' },
+                                                            geo: { type: 'string' },
+                                                            approachName: { type: 'string' },
+                                                            productReferenceUrl: { type: 'string' },
+                                                            priceBrief: { type: 'string' },
+                                                            model: { type: 'string' },
+                                                            disabled: { type: 'boolean' },
+                                                            expectNoBullets: { type: 'boolean' },
+                                                        },
+                                                    },
+                                                    upload: {
+                                                        type: 'object',
+                                                        description: 'Optional Drive upload config. Uploaded only after validation OK (or disabled validation OK).',
+                                                        properties: {
+                                                            enabled: { type: 'boolean' },
+                                                            folderId: { type: 'string' },
+                                                            filename: { type: 'string' },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        metadata: { type: 'object' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '202': { description: 'Job accepted' },
+                        '400': { description: 'Invalid payload' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/jobs/{jobId}': {
+                get: {
+                    summary: 'Return server image job status',
+                    parameters: [
+                        {
+                            name: 'jobId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    responses: {
+                        '200': { description: 'Job snapshot' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                        '404': { description: 'Job not found or expired' },
+                    },
+                },
+                delete: {
+                    summary: 'Cancel a server image job',
+                    parameters: [
+                        {
+                            name: 'jobId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                    ],
+                    responses: {
+                        '200': { description: 'Cancelled job snapshot' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                        '404': { description: 'Job not found or expired' },
+                    },
+                },
+            },
+            '/api/jobs/status': {
+                post: {
+                    summary: 'Return multiple server job statuses',
+                    description: 'Batch-friendly polling endpoint. Accepts up to 100 job ids and returns found job snapshots plus missing ids.',
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['jobIds'],
+                                    properties: {
+                                        jobIds: { type: 'array', items: { type: 'string' } },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': { description: 'Batch job snapshots' },
+                        '400': { description: 'Invalid payload' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                    },
+                },
+            },
+            '/api/jobs/{jobId}/events': {
+                get: {
+                    summary: 'WebSocket stream for image job events',
+                    description: 'Upgrade to WebSocket. Browser clients authenticate with ?token=...; non-browser clients may use Authorization: Bearer. Optional lastEventId replays retained events.',
+                    parameters: [
+                        {
+                            name: 'jobId',
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' },
+                        },
+                        {
+                            name: 'token',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'string' },
+                        },
+                        {
+                            name: 'lastEventId',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'number' },
+                        },
+                    ],
+                    responses: {
+                        '101': { description: 'WebSocket upgrade accepted' },
+                        '401': { description: 'Missing or invalid bearer token' },
+                        '404': { description: 'Job not found or expired' },
+                    },
+                },
+            },
+        },
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                },
+            },
+        },
+    };
+}

package/dist/server/storage.js

@@ -0,0 +1,133 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerStore = exports.SERVER_SETTINGS_FILENAME = exports.SERVER_CONFIG_FILENAME = void 0;
+exports.getSecretKeys = getSecretKeys;
+exports.resolveServerDataDir = resolveServerDataDir;
+exports.buildSecretsStatus = buildSecretsStatus;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+exports.SERVER_CONFIG_FILENAME = 'config.json';
+exports.SERVER_SETTINGS_FILENAME = 'settings.json';
+const SECRET_KEYS = [
+    'clientId',
+    'clientSecret',
+    'accessToken',
+    'refreshToken',
+    'openaiApiKey',
+    'flexcardApiKey',
+    'telegramBotToken',
+    'telegramChatId',
+    'apiBearerToken',
+];
+function getSecretKeys() {
+    return [...SECRET_KEYS];
+}
+function resolveServerDataDir(env = process.env) {
+    return path_1.default.resolve(env.DOCS_COMBINER_SERVER_DATA_DIR || path_1.default.join(process.cwd(), 'server-data'));
+}
+function ensureDataDir(dataDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield fs_1.promises.mkdir(dataDir, { recursive: true, mode: 0o700 });
+    });
+}
+function readJsonFile(filePath, fallback) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const raw = yield fs_1.promises.readFile(filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+        }
+        catch (err) {
+            if ((err === null || err === void 0 ? void 0 : err.code) === 'ENOENT')
+                return fallback;
+            throw err;
+        }
+    });
+}
+function writeJsonFile(filePath, data, mode) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+        yield fs_1.promises.writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n', { mode });
+        yield fs_1.promises.rename(tmpPath, filePath);
+        yield fs_1.promises.chmod(filePath, mode);
+    });
+}
+class ServerStore {
+    constructor(dataDir = resolveServerDataDir()) {
+        this.dataDir = dataDir;
+        this.configPath = path_1.default.join(dataDir, exports.SERVER_CONFIG_FILENAME);
+        this.settingsPath = path_1.default.join(dataDir, exports.SERVER_SETTINGS_FILENAME);
+    }
+    init() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield ensureDataDir(this.dataDir);
+        });
+    }
+    readConfig() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.init();
+            return readJsonFile(this.configPath, {});
+        });
+    }
+    writeConfig(config) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.init();
+            yield writeJsonFile(this.configPath, config, 0o600);
+        });
+    }
+    patchSecrets(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const current = yield this.readConfig();
+            const updated = [];
+            const ignored = [];
+            for (const [key, value] of Object.entries(input || {})) {
+                if (!SECRET_KEYS.includes(key)) {
+                    ignored.push(key);
+                    continue;
+                }
+                if (typeof value !== 'string') {
+                    ignored.push(key);
+                    continue;
+                }
+                current[key] = value;
+                updated.push(key);
+            }
+            if (updated.length > 0) {
+                yield this.writeConfig(current);
+            }
+            return { updated, ignored };
+        });
+    }
+    readSettings() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.init();
+            return readJsonFile(this.settingsPath, {});
+        });
+    }
+    writeSettings(settings) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.init();
+            yield writeJsonFile(this.settingsPath, settings, 0o644);
+        });
+    }
+}
+exports.ServerStore = ServerStore;
+function buildSecretsStatus(config) {
+    return SECRET_KEYS.reduce((acc, key) => {
+        var _a;
+        acc[key] = Boolean((_a = config[key]) === null || _a === void 0 ? void 0 : _a.trim());
+        return acc;
+    }, {});
+}