@okostream/mcp 0.12.14 → 0.12.16

package/dist/server.js

@@ -116291,7 +116291,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.12.14";
+var OKO_MCP_VERSION = "0.12.16";
 
 // build/auth.js
 var state = null;
@@ -117212,15 +117212,39 @@ async function uploadMasterImage(eventId, kind, cardId, source) {
   });
   return result.data;
 }
-async function updateCardImageInTransaction(eventId, cardId, patch) {
+function imageReplacedSinceRead(fresh, expected) {
+  return fresh.imageMasterUrl !== expected.imageMasterUrl || fresh.imageUrl !== expected.imageUrl;
+}
+async function clearEventImageInTransaction(eventId, kind, cardId, expected) {
   const eventRef = doc(firestore, "events", eventId);
   await runTransaction2(firestore, async (transaction) => {
     const snap = await transaction.get(eventRef);
     if (!snap.exists())
       throw new Error("Event not found.");
     const data = snap.data();
+    const fresh = readImageRef(data, kind, cardId);
+    if (imageReplacedSinceRead(fresh, expected)) {
+      throw new Error("The image changed between reading it and deleting it \u2014 someone replaced it in the meantime. Nothing was deleted and no file was removed. Read the event again and repeat the call if the new image should go too.");
+    }
+    if (kind === "card") {
+      transaction.update(eventRef, {
+        "blocks.cards.items": cardItemsWithImage(data, cardId, {
+          imageUrl: null,
+          imageMasterUrl: null,
+          imageVariants: null,
+          imageWidth: null,
+          imageHeight: null
+        })
+      });
+      return;
+    }
+    const prefix = kind === "promoBanner" ? "blocks.promoBanner" : "blocks.video.placeholder";
     transaction.update(eventRef, {
-      "blocks.cards.items": cardItemsWithImage(data, cardId, patch)
+      [`${prefix}.imageMasterUrl`]: deleteField(),
+      [`${prefix}.imageUrl`]: deleteField(),
+      [`${prefix}.imageVariants`]: deleteField(),
+      [`${prefix}.imageWidth`]: deleteField(),
+      [`${prefix}.imageHeight`]: deleteField()
     });
   });
 }
@@ -117972,17 +117996,22 @@ function toMillis(value) {
   return null;
 }
 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.");
-}
-function timestampCursorFrom(value) {
+  const separator = cursor.indexOf("|");
+  const head = separator === -1 ? cursor : cursor.slice(0, separator);
+  const docId = separator === -1 ? "" : cursor.slice(separator + 1);
+  const millis = Number(head);
+  const at = Number.isFinite(millis) && millis > 0 ? millis : Date.parse(head);
+  if (!Number.isFinite(at)) {
+    throw new Error("Invalid cursor. Use the nextCursor value returned by the previous page.");
+  }
+  const boundary = Timestamp.fromMillis(at);
+  return docId ? [boundary, docId] : [boundary];
+}
+function timestampCursorFrom(value, docId) {
   const millis = toMillis(value);
-  return millis == null ? null : String(millis);
+  if (millis == null)
+    return null;
+  return docId ? `${millis}|${docId}` : String(millis);
 }
 var ISO_WITH_OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/;
 function parseIsoBound(value, label) {
@@ -118744,7 +118773,7 @@ function registerEventTools(server2) {
       limit(args.limit + 1)
     ];
     if (args.cursor)
-      constraints.splice(constraints.length - 1, 0, startAfter(parseTimestampCursor(args.cursor)));
+      constraints.splice(constraints.length - 1, 0, startAfter(...parseTimestampCursor(args.cursor)));
     const snap = await getDocs(query2(collection(firestore, "eventAccess", uid, "grants"), ...constraints)).catch((error3) => {
       if (!isFirestorePermissionDenied(error3))
         throw error3;
@@ -118752,7 +118781,7 @@ function registerEventTools(server2) {
     });
     if (snap !== null) {
       const { page, hasMore } = pickPage(snap.docs, args.limit);
-      const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data()[orderField]) : null;
+      const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data()[orderField], page.at(-1)?.id) : null;
       const pageItems = dateFiltered && args.workspaceId ? page.filter((item) => item.data().workspaceId === args.workspaceId) : page;
       let events;
       if (args.detail === "full") {
@@ -118783,7 +118812,7 @@ function registerEventTools(server2) {
       returns: "event document fields plus id and public event URL. The event's access composition (the historical uid arrays) is never returned; ask oko_list_workspace_access for who has access.",
       examples: ["Use after oko_create_webinar to verify setup and return the event URL to the user."],
       notes: [
-        "blocks.chat.mode and blocks.chat.visibility are both legacy: the event page reads neither \u2014 the chat panel exists exactly when blocks.chat.enabled is true, and sending is opened or closed live with oko_set_chat_mode. Ignore both fields."
+        "blocks.chat: the panel exists exactly when blocks.chat.enabled is true. blocks.chat.intake says whether it ACCEPTS MESSAGES before anyone touches the live control \u2014 closed (default), open, schedule (at the event time), or session (while an analytics session runs); oko_set_chat_mode overrides it live. blocks.chat.mode and blocks.chat.visibility are legacy and read by nobody \u2014 ignore those two."
       ]
     }),
     inputSchema: { eventId: eventIdField },
@@ -118828,7 +118857,7 @@ function registerEventTools(server2) {
         "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."
+        "chatEnabled: whether the chat block is on the page at creation. It does NOT open message sending: a new event starts with intake closed, so the chat is visible and silent until the organizer opens it (oko_set_chat_mode) or sets blocks.chat.intake."
       ],
       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."],
@@ -118841,7 +118870,7 @@ function registerEventTools(server2) {
       eventDate: external_exports.string().datetime().nullable().optional().describe("Optional webinar datetime in ISO format."),
       speakerName: external_exports.string().max(160).nullable().optional().describe("Optional speaker display name."),
       description: external_exports.string().max(3e3).nullable().optional().describe('Optional event description shown under the speaker name. Omit or pass "" for none; the literal text "null" is rejected.'),
-      chatEnabled: external_exports.boolean().default(false).describe("Whether the chat block starts enabled.")
+      chatEnabled: external_exports.boolean().default(false).describe("Whether the chat block is on the page at creation; message sending stays closed until opened.")
     },
     outputSchema: createWebinarOutputSchema,
     annotations: writeTool
@@ -118955,6 +118984,7 @@ function registerEventTools(server2) {
       returns: "event id and the list of Firestore fields updated.",
       examples: ["Use after oko_create_webinar to enable chat, bind a CTA/form, and configure other audience blocks."],
       notes: [
+        '\u{1F534} "Turn off the chat" is ambiguous, and the two meanings are not close. chat.enabled=false REMOVES the chat block from the page together with every message people wrote \u2014 irreversible for the audience, and almost never what someone asks for mid-webinar. Stopping new messages is a different tool: oko_set_chat_mode with mode="off" leaves the block and the whole history in place. When the organizer says "turn off the chat", "close the chat", "stop the chat", "disable chat", assume they mean the mode, and ASK before removing the block. The same trap in reverse: "turn the chat back on" after a pause means mode="public", not this field.',
         "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.",
         'videoPlaceholder.enabled only allows the placeholder; viewers see it after oko_set_block_visibility with block "placeholder" and visible true (a live override, stored outside the event document). Chat, CTA, banner and cards appear as soon as they are enabled here.',
@@ -118965,7 +118995,11 @@ function registerEventTools(server2) {
     }),
     inputSchema: {
       eventId: eventIdField,
-      chat: external_exports.object({ enabled: external_exports.boolean().optional(), visibility: external_exports.enum(["always", "hidden"]).optional() }).optional(),
+      chat: external_exports.object({
+        enabled: external_exports.boolean().optional().describe("Whether the chat block is ON THE PAGE. false removes it together with the message history \u2014 see the note above before using it."),
+        intake: external_exports.enum(["closed", "open", "schedule", "session"]).optional().describe("When the chat starts accepting messages before any live override: closed (default \u2014 visible and silent until opened), open, schedule (at the event time), session (while an analytics session runs)."),
+        visibility: external_exports.enum(["always", "hidden"]).optional()
+      }).optional(),
       promoBanner: external_exports.object({ enabled: external_exports.boolean().optional(), link: external_exports.string().max(1e3).optional(), visibility: external_exports.enum(["always", "hidden"]).optional(), formId: external_exports.string().nullable().optional() }).optional(),
       primaryCta: external_exports.object({ enabled: external_exports.boolean().optional(), visibility: external_exports.enum(["always", "hidden"]).optional(), title: external_exports.string().nullable().optional(), text: external_exports.string().nullable().optional(), buttonLabel: external_exports.string().nullable().optional(), buttonUrl: external_exports.string().nullable().optional(), formId: external_exports.string().nullable().optional() }).optional(),
       videoPlaceholder: external_exports.object({ enabled: external_exports.boolean().optional(), mode: external_exports.enum(["glass", "image"]).optional(), title: external_exports.string().nullable().optional(), subtitle: external_exports.string().nullable().optional(), showTimer: external_exports.boolean().optional() }).optional(),
@@ -118984,6 +119018,8 @@ function registerEventTools(server2) {
     const patch = {};
     if (args.chat?.enabled !== void 0)
       patch["blocks.chat.enabled"] = args.chat.enabled;
+    if (args.chat?.intake !== void 0)
+      patch["blocks.chat.intake"] = args.chat.intake;
     if (args.chat?.visibility !== void 0)
       patch["blocks.chat.visibility"] = args.chat.visibility;
     if (args.promoBanner?.enabled !== void 0)
@@ -119042,6 +119078,12 @@ function registerEventTools(server2) {
     if (args.chat?.visibility !== void 0) {
       hints.push("blocks.chat.visibility was stored but the event page does not read it: the chat panel exists exactly when blocks.chat.enabled is true, and sending is opened or closed live with oko_set_chat_mode. Drop the field.");
     }
+    if (args.chat?.enabled === false) {
+      hints.push('The chat block is now off in setup: it is gone from the page for everyone, together with every message the audience wrote. If the goal was only to stop NEW messages \u2014 which is what "turn off the chat" usually means during or after a webinar \u2014 re-enable it here and use oko_set_chat_mode with mode "off" instead: the block and the whole history stay in place. Worth confirming with the organizer which of the two they meant.');
+    }
+    if (args.chat?.enabled === true && args.chat?.intake === void 0) {
+      hints.push('The chat block is on the page, but message sending stays closed until it is opened: a chat nobody opened is silent by default. Open it now with oko_set_chat_mode mode "public", or set blocks.chat.intake to open / schedule / session so it opens by itself.');
+    }
     const currentBlocks = current.blocks && typeof current.blocks === "object" ? current.blocks : {};
     const bannerHasImage = Boolean(safeString(currentBlocks.promoBanner?.imageUrl) || safeString(currentBlocks.promoBanner?.imageMasterUrl));
     if (args.promoBanner?.enabled === false && bannerHasImage) {
@@ -119339,31 +119381,10 @@ function registerImageTools(server2) {
     const event = await readEvent(eventId, uid, "edit");
     const previous = readImageRef(event, kind, cardId);
     requireConfirm(confirm, "oko_delete_image", { eventId, kind, cardId: cardId ?? null, imageId: previous.imageId });
-    if (kind === "promoBanner") {
-      await updateDoc(doc(firestore, "events", eventId), {
-        "blocks.promoBanner.imageMasterUrl": deleteField(),
-        "blocks.promoBanner.imageUrl": deleteField(),
-        "blocks.promoBanner.imageVariants": deleteField(),
-        "blocks.promoBanner.imageWidth": deleteField(),
-        "blocks.promoBanner.imageHeight": deleteField()
-      });
-    } else if (kind === "videoPlaceholder") {
-      await updateDoc(doc(firestore, "events", eventId), {
-        "blocks.video.placeholder.imageMasterUrl": deleteField(),
-        "blocks.video.placeholder.imageUrl": deleteField(),
-        "blocks.video.placeholder.imageVariants": deleteField(),
-        "blocks.video.placeholder.imageWidth": deleteField(),
-        "blocks.video.placeholder.imageHeight": deleteField()
-      });
-    } else {
-      await updateCardImageInTransaction(eventId, cardId, {
-        imageUrl: null,
-        imageMasterUrl: null,
-        imageVariants: null,
-        imageWidth: null,
-        imageHeight: null
-      });
-    }
+    await clearEventImageInTransaction(eventId, kind, cardId, {
+      imageMasterUrl: previous.imageMasterUrl,
+      imageUrl: previous.imageUrl
+    });
     const cleanup = await deleteStorageUrls(eventId, previous.imageMasterUrl, previous.imageUrl);
     return textResult({
       eventId,
@@ -120030,16 +120051,17 @@ function registerLiveTools(server2) {
   server2.registerTool("oko_set_chat_mode", {
     title: "Set chat mode",
     description: toolDescription({
-      summary: "Open or close chat sending on the public event page.",
+      summary: "Open or close MESSAGE SENDING on the event page. The chat block itself stays where it is.",
       exampleCall: { "eventId": "Kx9pQ2mR7tL4vB8nW3cY", "mode": "off", "confirm": true },
       args: [
         "eventId: event to control.",
-        "mode: public (anyone can send), off (input closed, history stays visible), or null to reset to the product default (public).",
+        "mode: public (anyone can send), off (input closed, history stays visible), or null to fall back to the event's own setting (blocks.chat.intake, closed unless the organizer chose otherwise).",
         "confirm: must be true."
       ],
       returns: "eventId and the effective chat mode.",
-      examples: ['Use mode="off" to pause a chat storm; use mode=null or "public" to reopen.'],
+      examples: ['Use mode="off" to pause a chat storm; use mode="public" to reopen.'],
       notes: [
+        '\u{1F534} "Turn off the chat" means one of TWO different things, and picking the wrong one destroys what people wrote. THIS tool stops new messages: the block stays on the page, history stays readable, nothing is lost. The other one \u2014 oko_configure_blocks with chat.enabled=false \u2014 removes the block from the page together with the whole conversation. When the organizer says "turn off the chat", "close the chat", "stop the chat", "mute the chat" during or after a webinar, they almost always mean THIS tool. Ask before removing the block.',
         'This is the full replacement for the legacy pause via oko_set_block_visibility(block="chat"): prefer oko_set_chat_mode.',
         "There are no other levels: the server has exactly two states, sending open or closed. History is always visible; the mode never restricts who can read or hides anyone's messages."
       ]
@@ -120049,7 +120071,7 @@ function registerLiveTools(server2) {
       // LD5a-2 / A8 (owner decision 03.09): "auth" and "owner" were promised
       // here and enforced nowhere — the rule and every client only check
       // `mode !== "off"`. The contract now says what the server does.
-      mode: external_exports.enum(["public", "off"]).nullable().describe("Chat mode: public or off; null resets the override to the default."),
+      mode: external_exports.enum(["public", "off"]).nullable().describe("Chat mode: public or off; null drops the live override and falls back to the event setting."),
       confirm: external_exports.boolean().optional().describe("Required true to change the live chat mode.")
     },
     outputSchema: basicEventOutputSchema,
@@ -120126,14 +120148,14 @@ function registerNotificationTools(server2) {
       limit(fetchLimit)
     ];
     if (cursor)
-      constraints.splice(1, 0, startAfter(parseTimestampCursor(cursor)));
+      constraints.splice(1, 0, startAfter(...parseTimestampCursor(cursor)));
     const snap = await getDocs(query2(collection(firestore, "userNotifications", uid, "items"), ...constraints));
     const matchingDocs = unreadOnly ? snap.docs.filter((item) => item.data().read !== true) : snap.docs;
     const { page, hasMore: hasMoreInMatches } = pickPage(matchingDocs, max);
     const hasMore = hasMoreInMatches || snap.docs.length >= fetchLimit;
     const cursorSource = hasMoreInMatches ? page.at(-1) : snap.docs.at(-1);
     const notifications = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
-    const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt) : null;
+    const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt, cursorSource?.id) : null;
     return textResult({
       notifications,
       unreadCountOnPage: notifications.filter((item) => item.read !== true).length,
@@ -120459,11 +120481,11 @@ function registerSessionTools(server2) {
       limit(max + 1)
     ];
     if (cursor)
-      constraints.splice(1, 0, startAfter(parseTimestampCursor(cursor)));
+      constraints.splice(1, 0, startAfter(...parseTimestampCursor(cursor)));
     const snap = await getDocs(query2(collection(firestore, "events", eventId, "analyticsSessions"), ...constraints));
     const { page, hasMore } = pickPage(snap.docs, max);
     const sessions = page.map((item) => compactAnalyticsSession({ id: item.id, ...item.data() }, { includeTimeline, timelineLimit, includeSnapshots }));
-    const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().startedAt) : null;
+    const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().startedAt, page.at(-1)?.id) : null;
     return textResult({ sessions, ...cursorMeta(sessions.length, max, hasMore, nextCursor) }, { truncationHint: "Use limit/cursor or keep includeTimeline/includeSnapshots disabled." });
   });
   server2.registerTool("oko_get_session_report", {
@@ -120679,14 +120701,14 @@ function registerTelegramTools(server2) {
       limit(max + 1)
     ];
     if (cursor)
-      constraints.splice(2, 0, startAfter(parseTimestampCursor(cursor)));
+      constraints.splice(2, 0, startAfter(...parseTimestampCursor(cursor)));
     const snap = await getDocs(query2(collection(firestore, "telegramPosts"), ...constraints));
     const matching = status ? snap.docs.filter((item) => item.data().status === status) : snap.docs;
     const { page, hasMore: hasMoreInMatches } = pickPage(matching, max);
     const hasMore = hasMoreInMatches || snap.docs.length >= max + 1;
     const cursorSource = hasMoreInMatches ? page.at(-1) : snap.docs.at(-1);
     const posts = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
-    const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt) : null;
+    const nextCursor = hasMore ? timestampCursorFrom(cursorSource?.data().createdAt, cursorSource?.id) : null;
     return textResult({ posts, ...cursorMeta(posts.length, max, hasMore, nextCursor) });
   });
   server2.registerTool("oko_cancel_telegram_post", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.12.14",
+  "version": "0.12.16",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {