@okostream/mcp 0.20.0 → 0.21.0

package/README.md

@@ -141,7 +141,9 @@ Refusals are explicit and never require guessing:
   window it bought (the result carries `windowStart`, `windowEnd` and the next
   steps); a date outside the window, a cleared date, or any date on a page whose
   show is over is refused. `oko_update_event` may also return `warnings` (advice,
-  never a refusal).
+  never a refusal). It also sets the page's look: `pageTheme` (`auto`, `light`, `dark`) and `pageAccent`,
+  the color of buttons and links — nine palette colors are free on every plan; a custom `#rrggbb` is a Pro
+  and Max right (on other plans it is stored and the page shows the default color until the plan allows it).
 - `WORKSPACE_LIMIT`, `SEATS_FULL`, `ENTITLEMENT_REQUIRED` — the plan of the
   workspace owner does not hold another shared workspace, another member, or
   the capability at all. A refused invitation stays valid. Plans are bought only
@@ -184,6 +186,10 @@ always works. The result's `sourceVia` says who fetched the image.
   costs 10 lumens each for that show: the tool answers with the quote first and
   writes only after `confirm=true`; unpublishing later does not return these
   top-ups.
+  A block exists on the page only while it is enabled; `visibility: "hidden"` is
+  the default an enabled block starts in, and the live switch shows or hides an
+  enabled block during the show. To prepare a banner and reveal it later, enable
+  it hidden (`{"promoBanner": {"enabled": true, "visibility": "hidden"}}`).
   The live control room is a paid option of a published page (50 lumens, Pro
   and above) bought in the analytics screen, not through MCP.
 - Operate live audience controls, chat, moderation, and analytics sessions.

package/dist/server.js

@@ -119137,7 +119137,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.20.0";
+var OKO_MCP_VERSION = "0.21.0";
 
 // build/auth.js
 var state = null;
@@ -122308,6 +122308,19 @@ function registerChatTools(server2) {
   });
 }
 
+// build/pageAccent.js
+var PAGE_THEMES = ["auto", "light", "dark"];
+var PAGE_ACCENT_KEYS = ["sky", "blue", "violet", "pink", "orange", "amber", "green", "teal", "graphite"];
+var HEX6 = /^#[0-9a-fA-F]{6}$/;
+function parsePageAccent(value) {
+  const text = value.trim();
+  if (PAGE_ACCENT_KEYS.includes(text))
+    return text;
+  if (HEX6.test(text))
+    return text.toLowerCase();
+  throw new Error(`pageAccent must be one of ${PAGE_ACCENT_KEYS.join(", ")} or a color like "#0a7fa3" (six hex digits); got ${JSON.stringify(value)}.`);
+}
+
 // build/tools/publication.js
 var SERVER_REFUSAL_CODES = /* @__PURE__ */ new Set(["ENTITLEMENT_REQUIRED", "INSUFFICIENT_TOKENS", "WORKSPACE_INACTIVE"]);
 function refusal2(eventId, body, tool = "oko_publish_event") {
@@ -123030,6 +123043,71 @@ async function readLiveLayer(eventId, data, nowMs) {
   return { live, hints };
 }
 
+// build/tools/blockOffAdvice.js
+var BLOCK_LEVELS_SENTENCE = "Three levels: `enabled` decides whether the block exists on the page at all; `visibility` (always | hidden) is the default it starts in; the live override (oko_set_block_visibility, the analytics buttons) shows or hides an ENABLED block during the show \u2014 on a disabled block it does nothing.";
+var PREPARING_FIELDS = {
+  promoBanner: ["visibility", "link", "formId", "pollId"],
+  primaryCta: ["visibility", "title", "text", "buttonLabel", "buttonUrl", "formId", "pollId"]
+};
+function touches(patch, fields) {
+  return Boolean(patch) && fields.some((field2) => patch[field2] !== void 0);
+}
+function disabledBlockHints(args, storedBlocks) {
+  const hints = [];
+  const names = { promoBanner: "promo banner", primaryCta: "CTA" };
+  for (const key of ["promoBanner", "primaryCta"]) {
+    const patch = args[key];
+    if (!touches(patch, PREPARING_FIELDS[key]))
+      continue;
+    const enabledAfter = patch?.enabled !== void 0 ? patch.enabled === true : asRecord(storedBlocks[key]).enabled === true;
+    if (enabledAfter)
+      continue;
+    hints.push(`The ${names[key]} is still OFF in setup (enabled is not true), so viewers will not see it at all and a live show from analytics cannot reveal it \u2014 its visibility is only the default of an enabled block. To keep it on the page but hidden until the moment, set enabled together with visibility: oko_configure_blocks {"${key}": {"enabled": true, "visibility": "hidden"}}, then show it live with oko_set_block_visibility. On a published page turning a paid block on is charged first and needs confirm \u2014 quote it to the organizer.`);
+  }
+  return hints;
+}
+function disabledCardsHint(args, storedEnabled) {
+  const preparing = args.visibility !== void 0 || Array.isArray(args.items) && args.items.length > 0;
+  const enabledAfter = args.enabled !== void 0 ? args.enabled === true : storedEnabled;
+  if (!preparing || enabledAfter)
+    return [];
+  return [
+    'The cards block is still OFF in setup (enabled is not true), so viewers will not see the cards at all and a live show from analytics cannot reveal them \u2014 visibility is only the default of an enabled block. To keep them on the page but hidden until the moment, call oko_configure_cards {"enabled": true, "visibility": "hidden"}, then show them live with oko_set_block_visibility block "cards". On a published page turning the block on is a paid top-up and needs confirm \u2014 quote it to the organizer.'
+  ];
+}
+function disabledOverrideHint(block, visible) {
+  const enable = block === "cards" ? 'oko_configure_cards {"enabled": true, "visibility": "hidden"}' : block === "banner" ? 'oko_configure_blocks {"promoBanner": {"enabled": true, "visibility": "hidden"}}' : block === "cta" ? 'oko_configure_blocks {"primaryCta": {"enabled": true, "visibility": "hidden"}}' : block === "placeholder" ? 'oko_configure_blocks {"videoPlaceholder": {"enabled": true}}' : 'oko_configure_blocks {"chat": {"enabled": true}}';
+  return `The ${block} block is OFF in setup: it does not exist on the page, so ${visible === null ? "there is nothing for this override to reset" : "this live override was stored but viewers see nothing"}. Enable it first (${enable} \u2014 hidden by default if it should appear later), then use this tool at the moment of the show.`;
+}
+function preparedButOffFindings(blocks, cards) {
+  const out = [];
+  const tail = " Viewers will not see it, and it cannot be shown live; enable it (hidden by default if it should appear later): ";
+  const promo = asRecord(blocks.promoBanner);
+  if (promo.enabled !== true && (safeString(promo.imageUrl).trim() || safeString(promo.imageMasterUrl).trim() || safeString(promo.link).trim())) {
+    out.push({
+      code: "promo_prepared_but_off",
+      path: "blocks.promoBanner.enabled",
+      message: "The promo banner has an image or link prepared but is OFF in setup." + tail + 'oko_configure_blocks {"promoBanner": {"enabled": true, "visibility": "hidden"}}.'
+    });
+  }
+  const cta = asRecord(blocks.primaryCta);
+  if (cta.enabled !== true && (safeString(cta.title).trim() || safeString(cta.text).trim() || safeString(cta.buttonUrl).trim())) {
+    out.push({
+      code: "cta_prepared_but_off",
+      path: "blocks.primaryCta.enabled",
+      message: "The CTA has a title, text or button URL prepared but is OFF in setup." + tail + 'oko_configure_blocks {"primaryCta": {"enabled": true, "visibility": "hidden"}}.'
+    });
+  }
+  if (!cards.enabled && cards.items.length > 0) {
+    out.push({
+      code: "cards_prepared_but_off",
+      path: "blocks.cards.enabled",
+      message: "The cards block has cards prepared but is OFF in setup." + tail + 'oko_configure_cards {"enabled": true, "visibility": "hidden"}.'
+    });
+  }
+  return out;
+}
+
 // build/tools/setupValidation.js
 function scheduleWindowPassedByPlan(event, eventDateMs, rawDurationMinutes, nowMs) {
   if (event.analyticsSessionMode !== "schedule")
@@ -123142,9 +123220,10 @@ function validateEventSetup(eventId, event, nowMs = Date.now()) {
     } else if (safeString(promo.imageMasterUrl).trim() && !readImageVariants(promo.imageVariants)) {
       add(warnings, "promo_variants_pending", "blocks.promoBanner.imageVariants", "Promo banner image variants are not ready yet.");
     }
-  } else if (safeString(promo.imageUrl).trim() || safeString(promo.imageMasterUrl).trim()) {
-    add(suggestions, "promo_disabled_with_image", "blocks.promoBanner.enabled", 'Promo banner has an uploaded image but is disabled in setup, so viewers never see it. Enable it with oko_configure_blocks promoBanner.enabled=true; to hide it only during the live show, keep it enabled and use oko_set_block_visibility block "banner" visible=false.');
   }
+  const cardsForLint = readCardsConfig(event);
+  for (const finding of preparedButOffFindings(blocks, cardsForLint))
+    add(warnings, finding.code, finding.path, finding.message);
   const cta = asRecord(blocks.primaryCta);
   if (cta.enabled === true) {
     checkFormBinding("blocks.primaryCta.formId", cta.formId);
@@ -123562,6 +123641,7 @@ function registerEventTools(server2) {
       notes: [
         "billing (server-owned) is the publication record. Blocks and the control room paid AFTER publication are listed in billing.additions (one element per block or per control room, with the source payEventExtras or reconcile) and billing.controlRoom: true once the control room is paid; the show's paid set is billing.invoice plus billing.additions. Never write it.",
         "blocks.promoBanner.visibility, blocks.primaryCta.visibility, blocks.cards.visibility and blocks.video.placeholder.enabled are SETUP values \u2014 the default a block starts with. A live override (oko_set_block_visibility, or the organizer's switch in analytics) replaces it without touching setup, so these fields do not say what viewers see now: `live.<block>.visibleNow` does, with `decidedBy` naming the layer that decided. oko_get_live_state shows the raw overrides (ctrl.bannerVisible and so on).",
+        "meta.pageTheme and meta.pageAccent are the page's look AS STORED (absent = auto and sky). A custom hex in meta.pageAccent is painted only while the plan that pays for the page holds the right (Pro and Max); otherwise the page shows sky \u2014 this tool does not say which, so for a custom color on an unknown plan read oko_wallet.",
         "blocks.chat: the panel exists exactly when blocks.chat.enabled is true (false HIDES the panel; messages are kept for 90 days and come back when it is enabled again). Message intake is ONE live state \u2014 oko_set_chat_mode reads and writes it; blocks.chat.intake is only the STARTING state an untouched event has (closed by default, or open), and blocks.chat.openOnSessionStart / closeOnSessionEnd are two triggers that flip that same state when an analytics session starts or ends. blocks.chat.mode and blocks.chat.visibility are legacy and read by nobody \u2014 ignore those two."
       ]
     }),
@@ -123681,7 +123761,7 @@ function registerEventTools(server2) {
     description: toolDescription({
       summary: "Update safe top-level event/setup metadata fields.",
       exampleCall: { "eventId": "Kx9pQ2mR7tL4vB8nW3cY", "title": "Autumn product webinar (rescheduled)", "eventDate": "2026-09-12T07:00:00.000Z", "speakerName": "Jane Doe", "description": "", "durationMinutes": 60 },
-      args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned, sessionMode, durationMinutes, sessionStartAt, sessionEndAt."],
+      args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned, sessionMode, durationMinutes, sessionStartAt, sessionEndAt, pageTheme, pageAccent."],
       returns: "event id, the list of Firestore fields updated, and session warnings (plan versus event time, lumens versus plan, a plan with no sessions).",
       examples: ["Use for title/date/speaker/video edits; use oko_configure_blocks for blocks and forms."],
       notes: [
@@ -123690,6 +123770,7 @@ function registerEventTools(server2) {
         "sessionStartAt/sessionEndAt: pass BOTH ISO datetimes to set a session time different from the show's, or pass null for both to follow the event time again. A session plan that differs from the event time is reported as a warning (moving eventDate does not move an explicit plan).",
         "Setting sessionMode 'schedule' on a page with no date, or clearing the date of a page in 'schedule', in one call is refused (nothing could start from it); a page born with the auto start on and no date yet is normal and can be edited freely.",
         'On a published page eventDate moves only INSIDE the show window bought at publication (from a day before the event date to two days after it): a date inside is written; a date outside, a cleared date, or any date on a page that shows "held"/\u041F\u0440\u043E\u0432\u0435\u0434\u0435\u043D\u043E is refused with errorCode EVENT_DATE_LOCKED, windowStart/windowEnd and whatToDo \u2014 every other field in the same call still goes through if eventDate is dropped from it. For a date outside the window: oko_unpublish_event (refunds, only before the window opens and only for a page that was charged), change the date, oko_publish_event (new charge); or duplicate the page with oko_duplicate_event for the new date. A draft or an unpublished page moves freely.',
+        `pageTheme (auto | light | dark) is how the viewer page is painted: auto follows each viewer's system, light and dark look the same for everyone. pageAccent is the color of the page's buttons and links: one of the nine palette colors (sky, blue, violet, pink, orange, amber, green, teal, graphite) or a custom "#rrggbb". The nine palette colors are free on every plan. A custom hex is a right of the Pro and Max plans (of the plan that pays for the page): on a plan without it the value is still stored, but the page shows the default color (sky) until the plan allows it \u2014 the choice is not lost. The color applies to buttons and links in both the light and the dark theme and is adjusted for readability (a custom color is lightened or darkened as needed, keeping its hue). Both are read back as stored in oko_get_event, meta.pageTheme and meta.pageAccent; "sky" is the default.`,
         "The result may carry warnings (never a refusal), each { code, message }: about the date \u2014 the show would start inside the window but not fit into it, or the date is already behind us while sessionMode is 'schedule' (the scheduler then starts the analytics session right away) \u2014 and about the session (see above)."
       ]
     }),
@@ -123704,7 +123785,9 @@ function registerEventTools(server2) {
       sessionMode: external_exports.enum(["manual", "schedule"]).optional().describe("Automatic start of the analytics session: 'schedule' starts it by itself at the start of the session plan (the default of a new page), 'manual' leaves the start to oko_start_session. The session always ends at the end of its plan."),
       durationMinutes: external_exports.number().int().min(15).max(1440).optional().describe("Event duration in minutes (15-1440); with eventDate it is the default session plan."),
       sessionStartAt: external_exports.string().datetime().nullable().optional().describe("Start of the session plan (ISO datetime), or null to follow the event time. Pass together with sessionEndAt."),
-      sessionEndAt: external_exports.string().datetime().nullable().optional().describe("End of the session plan (ISO datetime), or null to follow the event time. Pass together with sessionStartAt.")
+      sessionEndAt: external_exports.string().datetime().nullable().optional().describe("End of the session plan (ISO datetime), or null to follow the event time. Pass together with sessionStartAt."),
+      pageTheme: external_exports.enum(PAGE_THEMES).optional().describe("How the viewer page is painted: auto (follows each viewer's system, the default), light or dark."),
+      pageAccent: external_exports.string().max(16).optional().describe(`Color of the page's buttons and links: sky (the default), blue, violet, pink, orange, amber, green, teal, graphite \u2014 free on every plan \u2014 or a custom "#rrggbb" (Pro and Max; on other plans stored, page shows sky).`)
     },
     outputSchema: updateOutputSchema,
     annotations: writeTool
@@ -123712,7 +123795,7 @@ function registerEventTools(server2) {
     const requiredScopes = /* @__PURE__ */ new Set();
     if (args.title !== void 0 || args.pinned !== void 0)
       requiredScopes.add("events:write");
-    if (args.videoUrl !== void 0 || args.eventDate !== void 0 || args.speakerName !== void 0 || args.description !== void 0 || args.sessionMode !== void 0 || args.durationMinutes !== void 0 || args.sessionStartAt !== void 0 || args.sessionEndAt !== void 0) {
+    if (args.videoUrl !== void 0 || args.eventDate !== void 0 || args.speakerName !== void 0 || args.description !== void 0 || args.sessionMode !== void 0 || args.durationMinutes !== void 0 || args.sessionStartAt !== void 0 || args.sessionEndAt !== void 0 || args.pageTheme !== void 0 || args.pageAccent !== void 0) {
       requiredScopes.add("setup:write");
     }
     if (requiredScopes.size === 0)
@@ -123739,6 +123822,10 @@ function registerEventTools(server2) {
     }
     if (args.pinned !== void 0)
       patch.pinned = args.pinned;
+    if (args.pageTheme !== void 0)
+      patch["meta.pageTheme"] = args.pageTheme;
+    if (args.pageAccent !== void 0)
+      patch["meta.pageAccent"] = parsePageAccent(args.pageAccent);
     if (args.sessionMode !== void 0)
       patch.analyticsSessionMode = args.sessionMode;
     if (args.durationMinutes !== void 0)
@@ -123772,7 +123859,7 @@ function registerEventTools(server2) {
   server2.registerTool("oko_configure_blocks", {
     title: "Configure event blocks",
     description: toolDescription({
-      summary: "Configure supported event setup blocks, forms, polls, and Telegram channel ids.",
+      summary: "Configure supported event setup blocks, forms, polls, and Telegram channel ids. " + BLOCK_LEVELS_SENTENCE + ' To upload now and show later, set {"promoBanner": {"enabled": true, "visibility": "hidden"}} (visibility alone leaves a disabled block off the page), then call oko_set_block_visibility at the moment.',
       exampleCall: { "eventId": "Kx9pQ2mR7tL4vB8nW3cY", "chat": { "enabled": true }, "promoBanner": { "enabled": false }, "primaryCta": { "enabled": true, "title": "Get the slides", "buttonLabel": "Download", "buttonUrl": "https://example.com/slides" }, "videoPlaceholder": { "enabled": true, "mode": "glass", "showTimer": true, "title": "The webinar starts at 14:00", "subtitle": "Moscow time" } },
       args: [
         "eventId: event to edit.",
@@ -123927,6 +124014,7 @@ function registerEventTools(server2) {
     if (args.promoBanner?.enabled === true && !bannerHasImage) {
       hints.push(`The promo banner is enabled but has no image yet: upload one with oko_upload_image kind "promoBanner". ${IMAGE_ADVICE.promoBanner}`);
     }
+    hints.push(...disabledBlockHints(args, currentBlocks));
     if (args.chat?.enabled !== void 0 || args.promoBanner?.enabled !== void 0 || args.primaryCta?.enabled !== void 0 || args.videoPlaceholder?.enabled !== void 0) {
       hints.push("Setup toggles (enabled) decide whether a block exists on the page and persist; live overrides (oko_set_block_visibility) show or hide an enabled block temporarily during the show. Uploading an image never enables a block.");
     }
@@ -124059,6 +124147,7 @@ function registerEventTools(server2) {
         warnings.push("The ids shown for those positions are provisional (generated on read) and were NOT stored: oko_upload_image and oko_delete_image will not accept them. Save the cards first by passing items to oko_configure_cards \u2014 the saved ids are the ones to use.");
       }
     }
+    const hints = [...paid.hints ?? [], ...disabledCardsHint(args, readCardsConfig(event).enabled)];
     return textResult({
       eventId: args.eventId,
       updated: Object.keys(patch),
@@ -124069,7 +124158,7 @@ function registerEventTools(server2) {
       preservedImageCardIds,
       warnings,
       ...paid.payment ? { payment: paid.payment } : {},
-      ...paid.hints ? { hints: paid.hints } : {}
+      ...hints.length ? { hints } : {}
     });
   });
 }
@@ -125165,7 +125254,7 @@ function registerLiveTools(server2) {
   server2.registerTool("oko_set_block_visibility", {
     title: "Set live block visibility",
     description: toolDescription({
-      summary: "Set or reset a live RTDB visibility override for a public event block.",
+      summary: "Set or reset a live RTDB visibility override for a public event block. " + BLOCK_LEVELS_SENTENCE + ' For "upload now, show later": oko_configure_blocks {"promoBanner": {"enabled": true, "visibility": "hidden"}} first, then this tool with block "banner", visible true at the moment.',
       exampleCall: { "eventId": "Kx9pQ2mR7tL4vB8nW3cY", "block": "placeholder", "visible": true, "confirm": true },
       args: ["eventId: event to control.", "block: chat, banner, cta, cards, or placeholder.", "visible: true/false, or null to reset override.", "confirm: must be true."],
       returns: "eventId, block, and effective override value.",
@@ -125199,7 +125288,7 @@ function registerLiveTools(server2) {
       placeholder: setupBlocks.video?.placeholder?.enabled === true
     };
     const chatHint = visible === null ? "Live control cleared: message intake follows the starting state (blocks.chat.intake)." : visible ? "Message sending is open (chat mode public); the panel was not touched." : "Message sending is paused (chat mode off); history stays visible, the panel was not touched.";
-    const hints = !setupEnabled[block] ? [`The ${block} block is disabled in setup, so this live override has no visible effect until it is enabled (${block === "cards" ? "oko_configure_cards enabled=true" : "oko_configure_blocks"}).`] : block === "chat" ? [chatHint] : [visible === null ? "Override removed: the block follows its setup visibility again." : `Live override applied on top of setup; visible=null returns the ${block} block to its setup default.`];
+    const hints = !setupEnabled[block] ? [disabledOverrideHint(block, visible)] : block === "chat" ? [chatHint] : [visible === null ? "Override removed: the block follows its setup visibility again." : `Live override applied on top of setup; visible=null returns the ${block} block to its setup default.`];
     if (controlRoom)
       hints.push(String(controlRoom.note));
     const paths = {
@@ -126833,7 +126922,7 @@ function registerWalletTools(server2) {
         "limit: ledger rows per page, default 20, max 50, newest first.",
         "cursor: nextCursor returned by the previous page. The plan and the grants come with the first page only; the balance with every page."
       ],
-      returns: `billingUrl (the cabinet's Billing page), plan on the first page (tier core|pro|max|legacy, status active|past_due|canceled_at_period_end|expired, source lava|operator|legacy-exit|transition-b|smoke or null, periodEnd and graceUntil as ISO times or null; plan is null when the organizer has no plan) with planRead ok|unreadable (unreadable: the plan could not be read, so null means unknown, not no plan), hasWallet, balance (whole lumens, null when the organizer has no wallet yet), unit "lumens", grants on the first page (id, bucket plan|rollover|topup, amount, remaining, expiresAt, createdAt), ledger rows (id, kind grant|charge|refund|expire|settlement, amount, delta, balanceAfter, by, at, eventId, showId, workspaceId, postId, sessionId, minutes, forgiven), unreadableGrants/unreadableLedgerRows (rows that did not read: say so, never hide them) and cursor pagination metadata.`,
+      returns: `billingUrl (the cabinet's Billing page), plan on the first page (tier core|pro|max|legacy, status active|past_due|canceled_at_period_end|expired, source lava|tribute|operator|legacy-exit|transition-b|smoke or null, periodEnd and graceUntil as ISO times or null; plan is null when the organizer has no plan) with planRead ok|unreadable (unreadable: the plan could not be read, so null means unknown, not no plan), hasWallet, balance (whole lumens, null when the organizer has no wallet yet), unit "lumens", grants on the first page (id, bucket plan|rollover|topup, amount, remaining, expiresAt, createdAt), ledger rows (id, kind grant|charge|refund|expire|settlement, amount, delta, balanceAfter, by, at, eventId, showId, workspaceId, postId, sessionId, minutes, forgiven), unreadableGrants/unreadableLedgerRows (rows that did not read: say so, never hide them) and cursor pagination metadata.`,
       examples: [
         "Use before publishing a page or starting a session when the organizer asks how many lumens are left or what was charged.",
         "Use to explain a charge or a refund: every ledger row names what paid (eventId, sessionId, postId) and the balance after it."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {
@@ -55,8 +55,13 @@
     "firebase": "^12.16.0",
     "ipaddr.js": "2.4.0",
     "openai": "^6.46.0",
-    "typescript": "^5.9.3",
+    "typescript": "~6.0.3",
     "undici": "7.30.1",
     "zod": "^3.25.76"
+  },
+  "allowScripts": {
+    "@firebase/util@1.15.3": true,
+    "esbuild@0.24.2": true,
+    "protobufjs@7.6.6": true
   }
 }