@okostream/mcp 0.12.10 → 0.12.12

package/dist/server.js

@@ -116291,7 +116291,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.12.10";
+var OKO_MCP_VERSION = "0.12.12";
 
 // build/auth.js
 var state = null;
@@ -116416,9 +116416,8 @@ async function exchangeApiKey() {
     }
     throw status === 401 ? new OkoAuthError("invalid_key", "OKO API key is invalid or revoked. Create a fresh key in the OKO MCP install center and replace OKO_API_KEY.") : new OkoAuthError("unavailable", [
       `OKO organizer authentication failed with HTTP ${status}.`,
-      serverRefusalNote(errorBody),
-      "Check your connection and try again."
-    ].filter(Boolean).join(" "));
+      serverRefusalNote(errorBody) ?? "Check your connection and try again."
+    ].join(" "));
   }
   const data = await response.json();
   if (typeof data.customToken !== "string") {
@@ -116631,6 +116630,20 @@ var EVENT_ACCESS_FIELD_BY_MODE = {
   moderate: "chatModerators",
   notify: "notificationSenders"
 };
+var EVENT_ACCESS_COMPOSITION_FIELDS = [
+  ...Object.values(EVENT_ACCESS_FIELD_BY_MODE),
+  "moderators",
+  "participantUids"
+];
+function eventDocumentForOutput(data) {
+  const projected = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (EVENT_ACCESS_COMPOSITION_FIELDS.includes(key))
+      continue;
+    projected[key] = value;
+  }
+  return projected;
+}
 function grantAllowsMode(data, mode) {
   const field2 = EVENT_ACCESS_FIELD_BY_MODE[mode];
   return asRecord(data.capabilities)[field2] === true;
@@ -117195,16 +117208,43 @@ async function updateCardImageInTransaction(eventId, cardId, patch) {
     });
   });
 }
-async function writeEventPatchWithCards(eventId, basePatch, buildItems) {
+function descendPath(root, segments) {
+  let current = root;
+  for (const segment of segments) {
+    if (current === null || typeof current !== "object")
+      return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function valueAfterPatch(fresh, patch, path) {
+  if (Object.prototype.hasOwnProperty.call(patch, path))
+    return patch[path];
+  const segments = path.split(".");
+  for (let cut = segments.length - 1; cut > 0; cut--) {
+    const ancestor = segments.slice(0, cut).join(".");
+    if (!Object.prototype.hasOwnProperty.call(patch, ancestor))
+      continue;
+    return descendPath(patch[ancestor], segments.slice(cut));
+  }
+  return descendPath(fresh, segments);
+}
+function scheduleMissesDate(sessionMode, eventDate) {
+  return sessionMode === "schedule" && !eventDate;
+}
+async function writeEventPatchWithCards(eventId, basePatch, buildItems, validate = null) {
   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 fresh = snap.data();
     const patch = { ...basePatch };
     if (buildItems) {
-      patch["blocks.cards.items"] = buildItems(snap.data());
+      patch["blocks.cards.items"] = buildItems(fresh);
     }
+    if (validate)
+      validate(fresh, patch);
     if (Object.keys(patch).length === 0)
       return;
     transaction.update(eventRef, patch);
@@ -118425,6 +118465,9 @@ function validateEventSetup(eventId, event) {
   } else if (eventDateMs < Date.now() - 60 * 60 * 1e3) {
     add(warnings, "date_in_past", "meta.eventDate", "Configured webinar date appears to be in the past.");
   }
+  if (scheduleMissesDate(event.analyticsSessionMode, meta2.eventDate)) {
+    add(errors, "schedule_missing_date", "analyticsSessionMode", "Session mode is 'schedule' but meta.eventDate is empty, so OKO can never start or end the session automatically and the reminder is never sent. Set eventDate, or switch sessionMode to 'manual' \u2014 oko_update_event accepts both fields in one call.");
+  }
   const duplicateFormIds = /* @__PURE__ */ new Set();
   const seenFormIds = /* @__PURE__ */ new Set();
   forms.forEach((form, index) => {
@@ -118540,6 +118583,55 @@ function telegramBlocksPatch(args) {
     "telegram.channelIds": args.telegramChannelIds
   };
 }
+function assertScheduleHasDate(fresh, patch) {
+  const missing = scheduleMissesDate(valueAfterPatch(fresh, patch, "analyticsSessionMode"), valueAfterPatch(fresh, patch, "meta.eventDate"));
+  if (!missing)
+    return;
+  throw new Error("sessionMode 'schedule' requires meta.eventDate: without a date OKO can never start the session automatically. Set eventDate in the same call, or switch sessionMode to 'manual' in the same call to clear the date.");
+}
+var BLOCK_FORM_BINDING_FIELDS = [
+  "blocks.promoBanner.formId",
+  "blocks.primaryCta.formId"
+];
+function formIdSet(formsValue) {
+  return new Set((Array.isArray(formsValue) ? formsValue : []).map((form) => typeof form?.id === "string" ? form.id : null).filter((id) => Boolean(id)));
+}
+function formBindingsAfterPatch(fresh, patch) {
+  const bindings = [];
+  for (const field2 of BLOCK_FORM_BINDING_FIELDS) {
+    const value = valueAfterPatch(fresh, patch, field2);
+    if (typeof value === "string" && value)
+      bindings.push({ field: field2, formId: value });
+  }
+  const cards = valueAfterPatch(fresh, patch, "blocks.cards.items");
+  if (Array.isArray(cards)) {
+    cards.forEach((card, index) => {
+      const formId = card && typeof card === "object" && !Array.isArray(card) ? card.formId : null;
+      if (typeof formId === "string" && formId) {
+        bindings.push({ field: `blocks.cards.items[${index}].formId`, formId });
+      }
+    });
+  }
+  return bindings;
+}
+function assertFormBindingsExist(fresh, patch) {
+  const formsAfter = formIdSet(valueAfterPatch(fresh, patch, "forms"));
+  for (const field2 of BLOCK_FORM_BINDING_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(patch, field2))
+      continue;
+    const value = patch[field2];
+    if (typeof value === "string" && value && !formsAfter.has(value)) {
+      throw new Error(`${field2}: form "${value}" not found in event.forms. Create the form in the same call (or beforehand) \u2014 a button bound to a missing form does nothing for viewers.`);
+    }
+  }
+  const formsBefore = formIdSet(valueAfterPatch(fresh, {}, "forms"));
+  const orphaned = formBindingsAfterPatch(fresh, patch).filter((binding) => !formsAfter.has(binding.formId) && formsBefore.has(binding.formId));
+  if (orphaned.length === 0)
+    return;
+  const listed = orphaned.map((binding) => `${binding.field} -> "${binding.formId}"`).join(", ");
+  const cardsAffected = orphaned.some((binding) => binding.field.startsWith("blocks.cards."));
+  throw new Error(`This call removes a form that buttons still point at: ${listed}. A button bound to a missing form does nothing for viewers, so the removal is refused while something still points at it. Unbind them first: pass promoBanner: {formId: null} and/or primaryCta: {formId: null} in this same call` + (cardsAffected ? ", and clear the card bindings with oko_configure_cards before removing the form." : "."));
+}
 function configureBlocksScopes(args) {
   return Object.keys(telegramBlocksPatch(args)).length > 0 ? ["setup:write", "telegram:write"] : ["setup:write"];
 }
@@ -118552,7 +118644,7 @@ function registerEventTools(server2) {
         "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.',
+        'detail: "compact" (default) returns the light card projection; "full" returns event documents without the access composition, same shape as oko_get_event.',
         "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.",
@@ -118600,7 +118692,10 @@ function registerEventTools(server2) {
       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()) }] : []);
+        events = eventDocuments.flatMap((item) => item.exists() ? [{
+          id: item.id,
+          ...serialize(eventDocumentForOutput(item.data()))
+        }] : []);
       } else {
         events = pageItems.map((item) => {
           const data = serialize(item.data());
@@ -118620,7 +118715,7 @@ function registerEventTools(server2) {
     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.",
+      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."
@@ -118632,7 +118727,11 @@ function registerEventTools(server2) {
   }, async ({ eventId }) => {
     const { uid } = await authed(["events:read"]);
     const data = await readEvent(eventId, uid, "read");
-    return textResult({ id: eventId, ...serialize(data), ...eventLinks(eventId) });
+    return textResult({
+      id: eventId,
+      ...serialize(eventDocumentForOutput(data)),
+      ...eventLinks(eventId)
+    });
   });
   server2.registerTool("oko_validate_event_setup", {
     title: "Validate event setup",
@@ -118719,7 +118818,8 @@ function registerEventTools(server2) {
       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."
+        "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.",
+        "sessionMode 'schedule' and eventDate travel together: setting the mode without a date, or clearing the date while the mode stays, is refused. Change both in one call."
       ]
     }),
     inputSchema: {
@@ -118745,13 +118845,7 @@ function registerEventTools(server2) {
     if (requiredScopes.size === 0)
       throw new Error("Provide at least one field to update.");
     const { uid } = await authed([...requiredScopes]);
-    const current = await readEvent(args.eventId, uid, "edit");
-    if (args.sessionMode === "schedule") {
-      const dateAfterPatch = args.eventDate !== void 0 ? args.eventDate : current.meta?.eventDate ?? null;
-      if (!dateAfterPatch) {
-        throw new Error("sessionMode 'schedule' requires meta.eventDate: without a date OKO can never start the session automatically. Set eventDate in the same call, or keep sessionMode 'manual'.");
-      }
-    }
+    await readEvent(args.eventId, uid, "edit");
     const patch = {};
     if (args.title !== void 0)
       patch.title = args.title.trim();
@@ -118776,7 +118870,7 @@ function registerEventTools(server2) {
       patch.analyticsSessionMode = args.sessionMode;
     if (args.durationMinutes !== void 0)
       patch["meta.durationMinutes"] = args.durationMinutes;
-    await updateDoc(doc(firestore, "events", args.eventId), patch);
+    await writeEventPatchWithCards(args.eventId, patch, null, assertScheduleHasDate);
     return textResult({ id: args.eventId, updated: Object.keys(patch) });
   });
   server2.registerTool("oko_configure_blocks", {
@@ -118787,7 +118881,7 @@ function registerEventTools(server2) {
       args: [
         "eventId: event to edit.",
         "chat/promoBanner/primaryCta/videoPlaceholder: optional block patches.",
-        "forms: replaces configured lead forms when provided.",
+        "forms: replaces configured lead forms when provided; removing a form that a button still points at is refused.",
         "telegramChannelIds: replaces configured Telegram channels when provided; needs the telegram:write scope AND the notification permission on the event, and is refused before anything is written when either is missing."
       ],
       returns: "event id and the list of Firestore fields updated.",
@@ -118797,7 +118891,8 @@ function registerEventTools(server2) {
         "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.',
         "Setup toggle vs live override: enabled=false removes a block from the page for everyone and persists (its uploaded image stays); oko_set_block_visibility hides or shows an enabled block temporarily and is the tool for the live show. Uploading an image never enables a block.",
-        "telegramChannelIds is the only field here that is not a page setting: it decides which channel carries this event's messages, and the automatic reminder goes out under the event owner's name. Omit the field to configure blocks with setup:write alone; pass it only with a key that holds telegram:write and for an organizer who may send notifications for this event."
+        "telegramChannelIds is the only field here that is not a page setting: it decides which channel carries this event's messages, and the automatic reminder goes out under the event owner's name. Omit the field to configure blocks with setup:write alone; pass it only with a key that holds telegram:write and for an organizer who may send notifications for this event.",
+        "forms and the buttons bound to them travel together in both directions: binding a button to a form that does not exist is refused, and so is replacing forms in a way that removes a form the banner, the CTA or a card button still points at. Unbind in the same call with promoBanner/primaryCta formId:null; card bindings are cleared with oko_configure_cards first. A binding that was already broken before the call is not touched and does not block it."
       ]
     }),
     inputSchema: {
@@ -118874,17 +118969,7 @@ function registerEventTools(server2) {
         }))
       }));
     Object.assign(patch, telegramPatch);
-    const formsAfterPatch = patch.forms ?? current.forms;
-    const knownFormIds = new Set((Array.isArray(formsAfterPatch) ? formsAfterPatch : []).map((form) => typeof form?.id === "string" ? form.id : null).filter((id) => Boolean(id)));
-    for (const [field2, value] of [
-      ["blocks.promoBanner.formId", patch["blocks.promoBanner.formId"]],
-      ["blocks.primaryCta.formId", patch["blocks.primaryCta.formId"]]
-    ]) {
-      if (typeof value === "string" && value && !knownFormIds.has(value)) {
-        throw new Error(`${field2}: form "${value}" not found in event.forms. Create the form in the same call (or beforehand) \u2014 a button bound to a missing form does nothing for viewers.`);
-      }
-    }
-    await updateDoc(doc(firestore, "events", args.eventId), patch);
+    await writeEventPatchWithCards(args.eventId, patch, null, assertFormBindingsExist);
     const hints = [];
     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.");
@@ -119759,6 +119844,7 @@ function registerLiveTools(server2) {
       examples: ["Use visible=false to hide the CTA live; use visible=null to return to setup defaults."],
       notes: [
         "block=chat with visible=false PAUSES message input: viewers keep seeing the chat history but cannot send. It does not hide the chat panel.",
+        "Chat is the only block whose override the SERVER enforces: it is written as the chat mode and mirrored into the chat security rules, so a paused chat refuses messages from every client. The other four overrides are page presentation only \u2014 they change what viewers see, not what the server accepts.",
         "Live overrides sit on top of setup: a block disabled in setup (oko_configure_blocks enabled=false) stays absent whatever the override; visible=null returns an enabled block to its setup default. Use overrides for the live show, setup toggles for permanent changes."
       ]
     }),
@@ -119813,10 +119899,10 @@ function registerLiveTools(server2) {
   server2.registerTool("oko_refresh_viewers", {
     title: "Refresh viewers",
     description: toolDescription({
-      summary: "Trigger a live viewer refresh tick for an event.",
+      summary: "Refresh what viewers see: recount the online viewers and make open event pages re-read their config.",
       args: ["eventId: event whose viewers should refresh.", "confirm: must be true."],
-      returns: "eventId and refreshed=true.",
-      examples: ["Use after a setup/live change if viewers should reload state immediately."]
+      returns: "eventId, refreshed=true, and online \u2014 the recounted number of viewers present.",
+      examples: ["Use after a setup/live change if viewers should reload state immediately.", "Use when the online counter looks wrong: it is recounted from the actual presence nodes."]
     }),
     inputSchema: { eventId: eventIdField, confirm: external_exports.boolean().optional().describe("Required true to refresh connected viewers.") },
     outputSchema: basicEventOutputSchema,
@@ -119825,8 +119911,13 @@ function registerLiveTools(server2) {
     const { uid } = await authed(["live:control"]);
     await readEvent(eventId, uid, "live");
     requireConfirm(confirm, "oko_refresh_viewers", { eventId });
-    await runTransaction(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), (current) => (current ?? 0) + 1);
-    return textResult({ eventId, refreshed: true });
+    const resyncPresence = httpsCallable(functions, "resyncPresence");
+    const [resynced] = await Promise.all([
+      resyncPresence({ eventId }),
+      runTransaction(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), (current) => (current ?? 0) + 1)
+    ]);
+    const online = typeof resynced.data?.online === "number" ? resynced.data.online : null;
+    return textResult({ eventId, refreshed: true, online });
   });
   server2.registerTool("oko_set_live_badge", {
     title: "Set live badge",

package/package.json

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