@okostream/mcp 0.11.1 → 0.11.2

package/dist/tools/events.js

@@ -0,0 +1,437 @@
+// Создание и настройка события: карточка, блоки, карточки-предложения.
+//
+// Список строится по индексу доступа eventAccess/{uid}/grants, а не по
+// массивам события: массивы сняты 31.08.
+//
+// Настройка меняет только Firestore. Живое состояние (что показано зрителю
+// прямо сейчас) живёт в RTDB и правится инструментами live.
+import { z } from "zod";
+import { serialize, textResult } from "../utils.js";
+import { authed, eventLinks, randomId } from "./context.js";
+import { cardsConfigOutputSchema, createWebinarOutputSchema, cursorField, eventIdField, eventOutputSchema, eventsOutputSchema, formSchema, limitField, readOnlyTool, setupValidationOutputSchema, toolDescription, updateOutputSchema, writeTool } from "./schemas.js";
+import { buildCardsItems, CARD_IMAGE_RATIOS, cardHasImage, cardItemInputSchema, eventFormIds, MAX_CARD_ITEMS, readCardsConfig } from "./imagePipeline.js";
+import { collection, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, startAfter, Timestamp, updateDoc, where } from "firebase/firestore";
+import { addEventWithRtdbMirror, assertCanCreateInWorkspace } from "./eventCreate.js";
+import { cursorMeta, normalizeVideo, parseIsoBound, parseTimestampCursor, pickPage, timestampCursorFrom } from "./formatting.js";
+import { firestore } from "../firebase.js";
+import { isFirestorePermissionDenied, readEvent } from "./eventAccess.js";
+import { validateEventSetup } from "./setupValidation.js";
+export function registerEventTools(server) {
+    server.registerTool("oko_list_my_events", {
+        title: "List my events",
+        description: toolDescription({
+            summary: "List OKO events visible to the authenticated organizer.",
+            args: [
+                "limit: maximum events to return, default 30, max 100.",
+                "cursor: pagination cursor returned as nextCursor by the previous page; reuse it with the same filters.",
+                "workspaceId: optional workspace filter.",
+                'detail: "compact" (default) returns the light card projection; "full" returns complete event documents.',
+                "from/to: optional ISO timestamps bounding meta.eventDate; sorting switches to eventDate descending and undated events are excluded.",
+            ],
+            returns: "events plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
+            examples: [
+                "Use limit=10 first; if hasMore is true, call again with cursor=nextCursor.",
+                'For "today\'s webinar" pass from/to covering the day; use detail="full" only when block contents are needed.',
+            ],
+        }),
+        inputSchema: {
+            limit: limitField(),
+            cursor: cursorField,
+            workspaceId: z.string().optional().describe("Optional workspace id to filter returned events."),
+            detail: z.enum(["compact", "full"]).default("compact").describe('Response shape: "compact" card projection (default) or "full" event documents.'),
+            from: z.string().optional().describe("Include only events with meta.eventDate at or after this ISO timestamp."),
+            to: z.string().optional().describe("Include only events with meta.eventDate at or before this ISO timestamp."),
+        },
+        outputSchema: eventsOutputSchema,
+        annotations: readOnlyTool,
+    }, async (args) => {
+        const { uid } = await authed(["events:read"]);
+        const fromTs = parseIsoBound(args.from, "from");
+        const toTs = parseIsoBound(args.to, "to");
+        const dateFiltered = fromTs !== null || toTs !== null;
+        const orderField = dateFiltered ? "eventDate" : "createdAt";
+        const constraints = [
+            // При датном фильтре workspaceId отсеивается по загруженной странице:
+            // составного индекса grants(workspaceId+eventDate) нет намеренно.
+            ...(!dateFiltered && args.workspaceId ? [where("workspaceId", "==", args.workspaceId)] : []),
+            ...(fromTs ? [where("eventDate", ">=", fromTs)] : []),
+            ...(toTs ? [where("eventDate", "<=", toTs)] : []),
+            orderBy(orderField, "desc"),
+            limit(args.limit + 1),
+        ];
+        if (args.cursor)
+            constraints.splice(constraints.length - 1, 0, startAfter(parseTimestampCursor(args.cursor)));
+        const snap = await getDocs(query(collection(firestore, "eventAccess", uid, "grants"), ...constraints)).catch((error) => {
+            // Отказ в чтении собственных grants — это не повод молча уйти на
+            // legacy-путь: с 31.08 он мёртв вдвойне (правило `allow list` оставлено
+            // только владельцу платформы, а девять массивов сняты с документов).
+            // Фолбэк дал бы вторую, непонятную ошибку вместо настоящей причины.
+            if (!isFirestorePermissionDenied(error))
+                throw error;
+            throw new Error("Не удалось прочитать eventAccess/grants организатора. Права событий "
+                + "живут только в индексе; проверь, что ключ активен и его область "
+                + "доступа включает events:read.");
+        });
+        if (snap !== null) {
+            const { page, hasMore } = pickPage(snap.docs, args.limit);
+            const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data()[orderField]) : null;
+            const pageItems = dateFiltered && args.workspaceId
+                ? page.filter((item) => item.data().workspaceId === args.workspaceId)
+                : page;
+            let events;
+            if (args.detail === "full") {
+                const eventDocuments = await Promise.all(pageItems.map((item) => (getDoc(doc(firestore, "events", item.id)))));
+                events = eventDocuments.flatMap((item) => (item.exists()
+                    ? [{ id: item.id, ...serialize(item.data()) }]
+                    : []));
+            }
+            else {
+                // Компактный режим отдаёт grant-проекцию как есть — без чтения
+                // полных документов событий.
+                events = pageItems.map((item) => {
+                    const data = serialize(item.data());
+                    delete data.schemaVersion;
+                    delete data.uid;
+                    delete data.eventId;
+                    return { id: item.id, ...data };
+                });
+            }
+            return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) }, { truncationHint: 'Use a smaller limit, cursor pagination, or detail="compact".' });
+        }
+        // Legacy-путь (запрос событий по accessibleBy) снят 31.08 вместе с самими
+        // массивами: правило `allow list` оставлено только владельцу платформы, а
+        // поля стёрты со всех документов. Ветка была недостижима — выше остаётся
+        // единственный источник списка, индекс grants.
+        throw new Error("Список событий не получен: индекс eventAccess вернул пустой результат.");
+    });
+    server.registerTool("oko_get_event", {
+        title: "Get event",
+        description: toolDescription({
+            summary: "Read one OKO event visible to the organizer.",
+            args: ["eventId: OKO event document id."],
+            returns: "full event document fields plus id and public event URL.",
+            examples: ["Use after oko_create_webinar to verify setup and return the event URL to the user."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: eventOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:read"]);
+        const data = await readEvent(eventId, uid, "read");
+        return textResult({ id: eventId, ...serialize(data), ...eventLinks(eventId) });
+    });
+    server.registerTool("oko_validate_event_setup", {
+        title: "Validate event setup",
+        description: toolDescription({
+            summary: "Run a read-only setup readiness lint for one OKO event.",
+            args: ["eventId: OKO event document id."],
+            returns: "ok flag, score, errors, warnings, suggestions, next actions, and useful links.",
+            examples: [
+                "Use after creating/configuring a webinar and before telling the organizer it is ready.",
+                "Use before live-session prep to catch missing video, pending image variants, and invalid form bindings.",
+            ],
+            notes: ["This tool does not modify the event and does not start/end analytics sessions."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: setupValidationOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:read"]);
+        const data = await readEvent(eventId, uid, "read");
+        return textResult(validateEventSetup(eventId, data));
+    });
+    server.registerTool("oko_create_webinar", {
+        title: "Create webinar",
+        description: toolDescription({
+            summary: "Create an OKO webinar and its required RTDB owner/workspace mirror.",
+            args: [
+                "title: webinar title.",
+                "workspaceId: optional workspace id; omitted means personal workspace.",
+                "videoUrl: optional iframe/source/player URL; normalized by OKO.",
+                "eventDate: optional ISO datetime.",
+                "chatEnabled: whether the chat block is enabled at creation.",
+            ],
+            returns: "new event id, public event URL, and workspaceId.",
+            examples: ["Use for a complete create flow, then call oko_configure_blocks and oko_get_event."],
+            notes: ["This creates an event page; OKO has no draft/live/ended event status."],
+        }),
+        inputSchema: {
+            title: z.string().min(1).max(160).describe("Webinar title shown on the public event page."),
+            workspaceId: z.string().optional().describe("Workspace id; omit for the organizer's personal workspace."),
+            videoUrl: z.string().nullable().optional().describe("Optional source/player/iframe URL to normalize."),
+            eventDate: z.string().datetime().nullable().optional().describe("Optional webinar datetime in ISO format."),
+            speakerName: z.string().max(160).nullable().optional().describe("Optional speaker display name."),
+            description: z.string().max(3000).nullable().optional().describe("Optional event description."),
+            chatEnabled: z.boolean().default(false).describe("Whether the chat block starts enabled."),
+        },
+        outputSchema: createWebinarOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["events:write"]);
+        const workspaceId = args.workspaceId ?? uid;
+        await assertCanCreateInWorkspace(uid, workspaceId);
+        const video = normalizeVideo(args.videoUrl);
+        // Девять массивов доступа не пишутся (31.08): grants строит CF7 из
+        // владельца и shares рабочего пространства.
+        const docRef = await addEventWithRtdbMirror({
+            ownerId: uid,
+            workspaceId,
+            createdAt: serverTimestamp(),
+            title: args.title.trim(),
+            pinned: false,
+            video,
+            meta: {
+                eventDate: args.eventDate ? Timestamp.fromDate(new Date(args.eventDate)) : null,
+                speakerName: args.speakerName?.trim() || null,
+                description: args.description?.trim() || null,
+            },
+            blocks: {
+                chat: { enabled: args.chatEnabled, visibility: "always" },
+                promoBanner: { enabled: false, text: "", link: "", visibility: "always" },
+            },
+        });
+        return textResult({ id: docRef.id, ...eventLinks(docRef.id), workspaceId });
+    });
+    server.registerTool("oko_update_event", {
+        title: "Update event metadata",
+        description: toolDescription({
+            summary: "Update safe top-level event/setup metadata fields.",
+            args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned, sessionMode, durationMinutes."],
+            returns: "event id and the list of Firestore fields updated.",
+            examples: ["Use for title/date/speaker/video edits; use oko_configure_blocks for blocks and forms."],
+            notes: [
+                "sessionMode 'schedule' makes OKO start and end the analytics session automatically at eventDate for durationMinutes; 'manual' keeps the Start/End buttons and a Telegram reminder 10 minutes before eventDate. This is still an analytics session, not an event status.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            title: z.string().min(1).max(160).optional().describe("New webinar title."),
+            videoUrl: z.string().nullable().optional().describe("New source/player/iframe URL, or null to clear."),
+            eventDate: z.string().datetime().nullable().optional().describe("New ISO datetime, or null to clear."),
+            speakerName: z.string().max(160).nullable().optional().describe("New speaker display name, or null to clear."),
+            description: z.string().max(3000).nullable().optional().describe("New description, or null to clear."),
+            pinned: z.boolean().optional().describe("Whether this event is pinned in the dashboard."),
+            sessionMode: z.enum(["manual", "schedule"]).optional().describe("Analytics session mode: manual Start/End buttons, or automatic start/end on schedule at eventDate."),
+            durationMinutes: z.number().int().min(15).max(1440).optional().describe("Event duration in minutes (15-1440) used by schedule mode to end the session."),
+        },
+        outputSchema: updateOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const requiredScopes = new Set();
+        if (args.title !== undefined || args.pinned !== undefined)
+            requiredScopes.add("events:write");
+        if (args.videoUrl !== undefined
+            || args.eventDate !== undefined
+            || args.speakerName !== undefined
+            || args.description !== undefined
+            || args.sessionMode !== undefined
+            || args.durationMinutes !== undefined) {
+            requiredScopes.add("setup:write");
+        }
+        if (requiredScopes.size === 0)
+            throw new Error("Provide at least one field to update.");
+        const { uid } = await authed([...requiredScopes]);
+        await readEvent(args.eventId, uid, "edit");
+        const patch = {};
+        if (args.title !== undefined)
+            patch.title = args.title.trim();
+        if (args.videoUrl !== undefined) {
+            const video = normalizeVideo(args.videoUrl);
+            patch["video.originalUrl"] = video.originalUrl;
+            patch["video.embedUrl"] = video.embedUrl;
+        }
+        if (args.eventDate !== undefined)
+            patch["meta.eventDate"] = args.eventDate ? Timestamp.fromDate(new Date(args.eventDate)) : null;
+        if (args.speakerName !== undefined)
+            patch["meta.speakerName"] = args.speakerName?.trim() || null;
+        if (args.description !== undefined)
+            patch["meta.description"] = args.description?.trim() || null;
+        if (args.pinned !== undefined)
+            patch.pinned = args.pinned;
+        if (args.sessionMode !== undefined)
+            patch.analyticsSessionMode = args.sessionMode;
+        if (args.durationMinutes !== undefined)
+            patch["meta.durationMinutes"] = args.durationMinutes;
+        await updateDoc(doc(firestore, "events", args.eventId), patch);
+        return textResult({ id: args.eventId, updated: Object.keys(patch) });
+    });
+    server.registerTool("oko_configure_blocks", {
+        title: "Configure event blocks",
+        description: toolDescription({
+            summary: "Configure supported event setup blocks, forms, and Telegram channel ids.",
+            args: [
+                "eventId: event to edit.",
+                "chat/promoBanner/primaryCta/videoPlaceholder: optional block patches.",
+                "forms: replaces configured lead forms when provided.",
+                "telegramChannelIds: replaces configured Telegram channels when provided.",
+            ],
+            returns: "event id and the list of Firestore fields updated.",
+            examples: ["Use after oko_create_webinar to set chat visibility, CTA/form binding, and other audience blocks."],
+            notes: [
+                "A block toggle and its image are independent: enabling a block here works with an image already uploaded via oko_upload_image, and uploading an image never enables the block by itself.",
+                "promoBanner has no text field by design: the banner is image+link. blocks.promoBanner.text seen in event documents is legacy and is never rendered on the event page.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            chat: z.object({ enabled: z.boolean().optional(), visibility: z.enum(["always", "hidden"]).optional() }).optional(),
+            promoBanner: z.object({ enabled: z.boolean().optional(), link: z.string().max(1000).optional(), visibility: z.enum(["always", "hidden"]).optional(), formId: z.string().nullable().optional() }).optional(),
+            primaryCta: z.object({ enabled: z.boolean().optional(), visibility: z.enum(["always", "hidden"]).optional(), title: z.string().nullable().optional(), text: z.string().nullable().optional(), buttonLabel: z.string().nullable().optional(), buttonUrl: z.string().nullable().optional(), formId: z.string().nullable().optional() }).optional(),
+            videoPlaceholder: z.object({ enabled: z.boolean().optional(), mode: z.enum(["glass", "image"]).optional(), title: z.string().nullable().optional(), subtitle: z.string().nullable().optional(), showTimer: z.boolean().optional() }).optional(),
+            forms: z.array(formSchema).max(20).optional(),
+            telegramChannelIds: z.array(z.number().int()).max(20).optional(),
+        },
+        outputSchema: updateOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["setup:write"]);
+        await readEvent(args.eventId, uid, "edit");
+        const patch = {};
+        if (args.chat?.enabled !== undefined)
+            patch["blocks.chat.enabled"] = args.chat.enabled;
+        if (args.chat?.visibility !== undefined)
+            patch["blocks.chat.visibility"] = args.chat.visibility;
+        if (args.promoBanner?.enabled !== undefined)
+            patch["blocks.promoBanner.enabled"] = args.promoBanner.enabled;
+        if (args.promoBanner?.link !== undefined)
+            patch["blocks.promoBanner.link"] = args.promoBanner.link;
+        if (args.promoBanner?.visibility !== undefined)
+            patch["blocks.promoBanner.visibility"] = args.promoBanner.visibility;
+        if (args.promoBanner?.formId !== undefined)
+            patch["blocks.promoBanner.formId"] = args.promoBanner.formId;
+        if (args.primaryCta?.enabled !== undefined)
+            patch["blocks.primaryCta.enabled"] = args.primaryCta.enabled;
+        if (args.primaryCta?.visibility !== undefined)
+            patch["blocks.primaryCta.visibility"] = args.primaryCta.visibility;
+        if (args.primaryCta?.title !== undefined)
+            patch["blocks.primaryCta.title"] = args.primaryCta.title?.trim() || null;
+        if (args.primaryCta?.text !== undefined)
+            patch["blocks.primaryCta.text"] = args.primaryCta.text?.trim() || null;
+        if (args.primaryCta?.buttonLabel !== undefined)
+            patch["blocks.primaryCta.buttonLabel"] = args.primaryCta.buttonLabel?.trim() || null;
+        if (args.primaryCta?.buttonUrl !== undefined)
+            patch["blocks.primaryCta.buttonUrl"] = args.primaryCta.buttonUrl?.trim() || null;
+        if (args.primaryCta?.formId !== undefined)
+            patch["blocks.primaryCta.formId"] = args.primaryCta.formId;
+        if (args.videoPlaceholder?.enabled !== undefined)
+            patch["blocks.video.placeholder.enabled"] = args.videoPlaceholder.enabled;
+        if (args.videoPlaceholder?.mode !== undefined)
+            patch["blocks.video.placeholder.mode"] = args.videoPlaceholder.mode;
+        if (args.videoPlaceholder?.title !== undefined)
+            patch["blocks.video.placeholder.title"] = args.videoPlaceholder.title?.trim() || null;
+        if (args.videoPlaceholder?.subtitle !== undefined)
+            patch["blocks.video.placeholder.subtitle"] = args.videoPlaceholder.subtitle?.trim() || null;
+        if (args.videoPlaceholder?.showTimer !== undefined)
+            patch["blocks.video.placeholder.showTimer"] = args.videoPlaceholder.showTimer;
+        if (args.forms !== undefined)
+            patch.forms = args.forms.map((form) => ({
+                id: form.id ?? randomId(),
+                type: "lead",
+                title: form.title?.trim() || null,
+                description: form.description?.trim() || null,
+                submitLabel: form.submitLabel?.trim() || null,
+                successText: form.successText?.trim() || null,
+                consentText: form.consentText?.trim() || null,
+                consentRequired: form.consentRequired !== false,
+                fields: form.fields.map((field) => ({
+                    id: field.id ?? randomId(),
+                    label: field.label.trim(),
+                    type: field.type,
+                    required: field.required === true,
+                    placeholder: field.placeholder?.trim() || null,
+                })),
+            }));
+        if (args.telegramChannelIds !== undefined) {
+            patch["telegram.enabled"] = args.telegramChannelIds.length > 0;
+            patch["telegram.channelIds"] = args.telegramChannelIds;
+        }
+        await updateDoc(doc(firestore, "events", args.eventId), patch);
+        return textResult({ id: args.eventId, updated: Object.keys(patch) });
+    });
+    server.registerTool("oko_configure_cards", {
+        title: "Configure event cards",
+        description: toolDescription({
+            summary: "Configure the Cards setup block and replace its card list. Images are managed separately through oko_upload_image and are preserved by matching card id.",
+            args: [
+                "eventId: event to edit.",
+                "enabled: optional Cards block enabled flag.",
+                "visibility: optional default visibility, always or hidden.",
+                "cardImageRatio: optional image ratio, one of auto, 1:1, 4:3, 3:2, 16:9, 2:3, 3:4.",
+                "items: optional full replacement array, max 6 cards. Each item may include id, title, text, buttonLabel, buttonUrl, formId.",
+            ],
+            returns: "event id, updated Firestore fields, normalized cards config, generated card ids, preserved image ids, removed card ids, and warnings.",
+            examples: [
+                "Use after oko_create_webinar to create cards before uploading per-card images.",
+                "Call oko_get_event first and pass the full desired items array when editing existing cards.",
+                "Use formId instead of buttonUrl when a card button should open a lead form.",
+            ],
+            notes: [
+                "This tool replaces blocks.cards.items when items is provided; omitted text fields become null.",
+                "Existing card images are preserved only when the same card id remains in the replacement list.",
+                "buttonUrl allows http(s), mailto, or tel URLs; javascript/data URLs are rejected.",
+                "If a removed card had an image, Storage cleanup is not automatic; this matches the web Setup behavior.",
+            ],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            enabled: z.boolean().optional().describe("Whether the Cards block is enabled in setup."),
+            visibility: z.enum(["always", "hidden"]).optional().describe("Default visibility when no live override exists."),
+            cardImageRatio: z.enum(CARD_IMAGE_RATIOS).optional().describe("Image aspect ratio for all cards."),
+            items: z.array(cardItemInputSchema).max(MAX_CARD_ITEMS).optional().describe("Full replacement list, max 6 cards. Omit to update only block settings."),
+        },
+        outputSchema: cardsConfigOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["setup:write"]);
+        const event = await readEvent(args.eventId, uid, "edit");
+        const currentCards = readCardsConfig(event);
+        const patch = {};
+        const finalCards = {
+            enabled: args.enabled ?? currentCards.enabled,
+            visibility: args.visibility ?? currentCards.visibility,
+            cardImageRatio: args.cardImageRatio ?? currentCards.cardImageRatio,
+            items: currentCards.items,
+        };
+        const generatedCardIds = [];
+        const preservedImageCardIds = [];
+        let removedCardIds = [];
+        let removedCardsWithImages = [];
+        if (args.enabled !== undefined)
+            patch["blocks.cards.enabled"] = args.enabled;
+        if (args.visibility !== undefined)
+            patch["blocks.cards.visibility"] = args.visibility;
+        if (args.cardImageRatio !== undefined)
+            patch["blocks.cards.cardImageRatio"] = args.cardImageRatio;
+        if (args.items !== undefined) {
+            const built = buildCardsItems({
+                inputs: args.items,
+                existing: currentCards.items,
+                formIds: eventFormIds(event),
+            });
+            finalCards.items = built.items;
+            generatedCardIds.push(...built.generatedCardIds);
+            preservedImageCardIds.push(...built.preservedImageCardIds);
+            const nextIds = new Set(built.items.map((item) => item.id));
+            const removed = currentCards.items.filter((item) => !nextIds.has(item.id));
+            removedCardIds = removed.map((item) => item.id);
+            removedCardsWithImages = removed.filter(cardHasImage).map((item) => item.id);
+            patch["blocks.cards.items"] = built.items;
+        }
+        if (Object.keys(patch).length > 0) {
+            await updateDoc(doc(firestore, "events", args.eventId), patch);
+        }
+        const warnings = removedCardsWithImages.length > 0
+            ? [`Removed cards had images and their Storage files were not deleted: ${removedCardsWithImages.join(", ")}.`]
+            : [];
+        return textResult({
+            eventId: args.eventId,
+            updated: Object.keys(patch),
+            cards: finalCards,
+            generatedCardIds,
+            removedCardIds,
+            removedCardsWithImages,
+            preservedImageCardIds,
+            warnings,
+        });
+    });
+}

package/dist/tools/formatting.js

@@ -0,0 +1,177 @@
+// Пагинация, курсоры и приведение данных к виду, который читает модель.
+//
+// Курсор — непрозрачная для клиента строка: пара `timestampCursorFrom` и
+// `parseTimestampCursor` обязана быть обратимой, иначе листание молча
+// зацикливается или теряет страницу.
+//
+// Отчёт по сессии собирается в Markdown здесь, а не в обработчике: модели
+// нужен текст, пригодный к пересказу, а не сырой документ.
+import { Timestamp } from "firebase/firestore";
+import { csvCell, safeString, serialize } from "../utils.js";
+import { detectAndNormalize, extractIframeSrc } from "../videoUrl.js";
+import { eventUrl, sessionReportUrl } from "./context.js";
+export function cursorMeta(count, max, hasMore, nextCursor) {
+    return {
+        count,
+        limit: max,
+        hasMore,
+        nextCursor,
+        has_more: hasMore,
+        next_cursor: nextCursor,
+    };
+}
+export function pickPage(items, max) {
+    return {
+        page: items.slice(0, max),
+        hasMore: items.length > max,
+    };
+}
+export function normalizeVideo(videoUrl) {
+    const raw = videoUrl?.trim();
+    if (!raw)
+        return { originalUrl: null, embedUrl: null };
+    const effective = extractIframeSrc(raw) ?? raw;
+    const detected = detectAndNormalize(effective);
+    if (detected.provider !== "unknown" && !detected.normalizedUrl) {
+        throw new Error(`Could not extract a valid ${detected.provider} video id from videoUrl.`);
+    }
+    return { originalUrl: raw, embedUrl: detected.normalizedUrl ?? effective };
+}
+export function csvRows(headers, rows) {
+    return [headers, ...rows].map((row) => row.map(csvCell).join(",")).join("\n");
+}
+export function toMillis(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (value && typeof value === "object" && typeof value.toMillis === "function") {
+        return value.toMillis();
+    }
+    return null;
+}
+export function parseTimestampCursor(cursor) {
+    const millis = Number(cursor);
+    if (Number.isFinite(millis) && millis > 0)
+        return Timestamp.fromMillis(millis);
+    const parsed = Date.parse(cursor);
+    if (Number.isFinite(parsed))
+        return Timestamp.fromMillis(parsed);
+    throw new Error("Invalid cursor. Use the nextCursor value returned by the previous page.");
+}
+export function timestampCursorFrom(value) {
+    const millis = toMillis(value);
+    return millis == null ? null : String(millis);
+}
+export function parseIsoBound(value, label) {
+    if (value === undefined)
+        return null;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid ${label}: expected an ISO timestamp such as 2026-08-28T00:00:00+03:00.`);
+    }
+    return Timestamp.fromMillis(parsed);
+}
+// Компактная карточка события из полного (сериализованного) документа —
+// той же формы, что grant-проекция в eventAccess.
+export function compactEventFromFullDoc(event) {
+    const meta = (event.meta && typeof event.meta === "object" ? event.meta : {});
+    const telegram = (event.telegram && typeof event.telegram === "object" ? event.telegram : {});
+    return {
+        id: event.id,
+        ownerId: event.ownerId ?? null,
+        workspaceId: event.workspaceId ?? null,
+        title: event.title ?? null,
+        createdAt: event.createdAt ?? null,
+        eventDate: meta.eventDate ?? null,
+        speakerName: meta.speakerName ?? null,
+        pinned: event.pinned === true,
+        telegramEnabled: telegram.enabled === true,
+        trashed: Boolean(event.trashedAt),
+        trashedAt: event.trashedAt ?? null,
+        activeAnalyticsSessionId: event.activeAnalyticsSessionId ?? null,
+    };
+}
+export function compactAnalyticsSession(raw, options) {
+    const session = serialize(raw);
+    const timeline = Array.isArray(session.timeline) ? session.timeline : null;
+    if (timeline) {
+        session.timelineBucketCount = timeline.length;
+        if (options.includeTimeline) {
+            const page = timeline.slice(-options.timelineLimit);
+            session.timeline = page;
+            session.timelineTruncated = timeline.length > page.length;
+            session.timelineReturned = page.length;
+        }
+        else {
+            delete session.timeline;
+            session.timelineOmitted = true;
+        }
+    }
+    if (!options.includeSnapshots) {
+        if (session.baselineSnapshot !== undefined) {
+            delete session.baselineSnapshot;
+            session.baselineSnapshotOmitted = true;
+        }
+        if (session.finalSnapshot !== undefined) {
+            delete session.finalSnapshot;
+            session.finalSnapshotOmitted = true;
+        }
+    }
+    delete session[["n", "moEvaluation"].join("")];
+    return session;
+}
+export function numberMetric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function formatSeconds(value) {
+    const seconds = numberMetric(value);
+    if (seconds == null)
+        return "n/a";
+    const total = Math.max(0, Math.round(seconds));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${String(m).padStart(2, "0")}m ${String(s).padStart(2, "0")}s`;
+    return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+export function formatDateTime(value) {
+    const millis = toMillis(value);
+    if (millis == null)
+        return "n/a";
+    return new Date(millis).toISOString();
+}
+export function markdownMetric(label, value, suffix = "") {
+    const metric = value === null || value === undefined || value === "" ? "n/a" : String(value);
+    return `- ${label}: ${metric}${suffix}`;
+}
+export function sessionReportMarkdown({ eventId, event, sessionId, session, }) {
+    const lines = [
+        `# OKO session report`,
+        "",
+        `Event: ${safeString(event.title, eventId)}`,
+        `Event URL: ${eventUrl(eventId)}`,
+        `Report URL: ${sessionReportUrl(eventId, sessionId)}`,
+        `Session: ${sessionId}`,
+        "",
+        "## Timing",
+        markdownMetric("Started", formatDateTime(session.startedAt)),
+        markdownMetric("Ended", formatDateTime(session.endedAt)),
+        markdownMetric("Duration", formatSeconds(session.durationSec)),
+        "",
+        "## Audience",
+        markdownMetric("Peak viewers", session.peakViewers),
+        markdownMetric("Unique visitors", session.uniqueVisitors),
+        markdownMetric("Views", session.viewCount),
+        markdownMetric("Average watch time", formatSeconds(session.avgTimeSec)),
+        markdownMetric("Median watch time", formatSeconds(session.medianTimeSec)),
+        "",
+        "## Engagement",
+        markdownMetric("Chat messages", session.chatMessages),
+        markdownMetric("Banner impressions", session.bannerImpressions),
+        markdownMetric("Banner clicks", session.bannerClicks),
+        markdownMetric("Banner CTR", session.bannerCtr, session.bannerCtr == null ? "" : "%"),
+        markdownMetric("CTA clicks", session.ctaClicks),
+        markdownMetric("Cards clicks", session.cardsClicks),
+    ];
+    return lines.join("\n");
+}