@okostream/mcp 0.18.0 → 0.18.2

package/README.md

@@ -101,7 +101,8 @@ A new page is a draft: viewers of its public URL see "not published".
   the ledger of the organizer behind the key (scope `wallet:read`, included in
   the `operator` and `full` presets, not in `readOnly`). Keys created before that scope existed get `SCOPE_REQUIRED` and
   need a new key. A page in a shared workspace is paid from the workspace
-  owner's wallet, which is theirs to read.
+  owner's wallet: its balance is told, in the previews and refusals, to whoever
+  may spend from it; its grants and ledger are the owner's to read.
 - **Payment and terms are web-only.** Plans and lumens are bought, and terms
   accepted, only in the OKO web cabinet, and no MCP tool collects a password,
   card or bank details, or agreement to terms on anyone's behalf.

package/dist/server.js

@@ -116320,7 +116320,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.18.0";
+var OKO_MCP_VERSION = "0.18.2";
 
 // build/auth.js
 var state = null;
@@ -119581,7 +119581,7 @@ function sessionOutlookWarnings(outlook) {
   if (outlook.lumens.enoughForPlan === false && outlook.lumens.neededForPlan !== null) {
     warnings.push({
       code: "session_lumens_not_enough_for_plan",
-      message: `A session that runs to the end of its plan costs about ${outlook.lumens.neededForPlan} lumens (1 per minute, taken when it ends). The wallet that pays for this workspace holds less: the session would be stopped when the lumens run out. Its owner can top it up. Lumens are checked at Start (a wallet at zero refuses it) and every minute while it runs.`
+      message: `A session that runs to the end of its plan costs about ${outlook.lumens.neededForPlan} lumens (1 per minute, taken when it ends). ` + (typeof outlook.lumens.available === "number" ? `The wallet that pays for this workspace holds ${outlook.lumens.available}, which is less: ` : "The wallet that pays for this workspace holds less: ") + "the session would be stopped when the lumens run out. Its owner can top it up. Lumens are checked at Start (a wallet at zero refuses it) and every minute while it runs."
     });
   }
   return warnings;
@@ -122386,8 +122386,9 @@ function telegramPostRefusalResult(eventId, postId, error3, callerUid) {
       eventId,
       postId,
       needed,
-      // The wallet belongs to the payer: its balance is told to the payer only.
-      ...callerIsPayer && typeof info.available === "number" ? { available: info.available } : {},
+      // The server tells the balance to whoever may spend from the wallet (the payer and a member who may send: decision
+      // 2026-09-30) — this side relays what it was told, whoever the caller is.
+      ...typeof info.available === "number" ? { available: info.available } : {},
       callerIsPayer,
       message: text || `OKO refused to send the Telegram post: the wallet that pays for this event holds fewer than ${needed} lumens. The post was not sent and nothing was charged.`,
       whatToDo: [
@@ -122853,7 +122854,7 @@ function registerWalletTools(server2) {
       ],
       notes: [
         "Needs the wallet:read scope. A key created before that scope existed gets SCOPE_REQUIRED and its scopes cannot be changed: the organizer creates a new key in the OKO cabinet.",
-        "Shows only the wallet of the organizer behind the key. A page in a shared workspace is paid from the WORKSPACE OWNER's wallet: the publish, session and Telegram previews name that payer, and the owner's balance is theirs to read, not this key's.",
+        "Shows only the wallet of the organizer behind the key. A page in a shared workspace is paid from the WORKSPACE OWNER's wallet: the publish, session and Telegram previews and refusals name that payer and tell its balance to whoever may spend from it (publish, start a session, send posts); the owner's grants and ledger are theirs to read, not this key's.",
         "This tool cannot buy, grant, top up or spend lumens. Plans, lumens and payment details belong to the OKO web cabinet only; never ask the organizer for card data or a password.",
         "Refusals of the paid tools use the same codes as the web: ENTITLEMENT_REQUIRED (the plan does not include the feature) and INSUFFICIENT_TOKENS (not enough lumens); PLATFORM_REJECTED_READ here means the platform refused the read."
       ]
@@ -122957,6 +122958,7 @@ function workspaceRefusalResult(tool, error3, subject = {}) {
 }
 
 // build/tools/workspaces.js
+var INVITE_EMAIL_PATTERN = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]{1,64}@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/;
 function registerWorkspaceTools(server2) {
   server2.registerTool("oko_list_workspaces", {
     title: "List workspaces",
@@ -123197,8 +123199,8 @@ function registerWorkspaceTools(server2) {
     description: toolDescription({
       summary: "List workspace invite links for a workspace owned by the organizer.",
       args: ["workspaceId: workspace owned by the organizer."],
-      returns: "invites array with code, claim status, permissions, and inviteUrl.",
-      examples: ["Use before revoking or sharing an invite code."]
+      returns: "invites array with code, claim status, permissions, and inviteUrl; for an invite created with an email also mailStatus (queued | sent | not_sent) and, when not_sent, mailReason (rate_limited | address | not_allowed | undeliverable) \u2014 what the platform did with the letter. No mailStatus on an invite with an email means the platform has not reported yet: do not read it as sent. sent means the provider accepted the letter, not that it was delivered.",
+      examples: ["Use before revoking or sharing an invite code, and to check whether the platform's letter went out."]
     }),
     inputSchema: { workspaceId: external_exports.string().min(1) },
     outputSchema: external_exports.object({ workspaceId: external_exports.string(), invites: external_exports.array(unknownRecordSchema), count: external_exports.number().int().nonnegative() }).passthrough(),
@@ -123270,20 +123272,23 @@ function registerWorkspaceTools(server2) {
   server2.registerTool("oko_create_workspace_invite", {
     title: "Create workspace invite",
     description: toolDescription({
-      summary: "Create a workspace invite for a known OKO workspace.",
+      summary: "Create a workspace invite for a known OKO workspace. When `email` is given, OKO Stream itself emails the invitation to that address: an external effect, not a note.",
       args: [
         "workspaceId: workspace owned by the authenticated organizer.",
         "code: optional invite code, 16-64 chars; omitted means generated (recommended).",
-        "email: optional intended recipient email.",
+        "email: optional email of the invitee, one plain address (`name@domain`). When given, the PLATFORM sends the invitation letter to it \u2014 the workspace name and the invite link, in the language of the account that owns that address when there is one and it has a language, otherwise in the inviter's language, otherwise English; the `comment` is never put into the letter. A letter cannot be recalled: confirm the exact address with the workspace owner first. Omit it to get only the link.",
         // The schema is `workspacePermissionsSchema`: nine booleans, all
         // required, no extra keys. "optional whitelist" read as "send the
         // ones you want", and every such call was rejected by validation
         // before it reached the platform.
         "permissions: required object of all nine workspace permission booleans (createEvents, editSetup, deleteEvents, controlLive, moderateChat, startSession, viewAnalytics, downloadReports, sendNotifications) \u2014 every key must be present, extra keys are rejected; set false for the ones the invitee should not get.",
-        "confirm: must be true."
+        "confirm: must be true. Without it the call is refused with a preview that names the address the platform would email."
       ],
-      returns: "workspaceId, invite code, inviteUrl, and created=true.",
-      examples: ["Use only after confirming the recipient and permission set with the workspace owner."]
+      returns: "workspaceId, invite code, inviteUrl, created=true, and emailRequested=true when an address was given: the platform queues the letter AFTER the invite exists, and this result does not say the letter was delivered \u2014 what became of it is mailStatus on the invite, read with oko_list_workspace_invites a moment later.",
+      examples: ["Use only after confirming the recipient and permission set with the workspace owner."],
+      notes: [
+        "The invite itself and its inviteUrl are always created and always work. The LETTER is held to limits and is checked again just before it goes out: at most 1 letter an hour for one workspace and address, 3 a day to one address, 20 a day per inviter; and none if the invite was revoked or accepted meanwhile, or the plan has no free seat. When no letter goes out the invite stays valid: pass inviteUrl on yourself \u2014 mailStatus not_sent says so (mailReason not_allowed means the invite cannot be accepted right now, so passing the link on would not help either)."
+      ]
     }),
     inputSchema: {
       workspaceId: external_exports.string().min(1),
@@ -123295,25 +123300,31 @@ function registerWorkspaceTools(server2) {
       // deliberately stays 4: they accept codes that ALREADY exist, including
       // the historical six-character ones.
       code: external_exports.string().min(16).max(MAX_WORKSPACE_INVITE_CODE_LENGTH).optional(),
-      email: external_exports.string().email().optional(),
+      email: external_exports.string().max(254).regex(INVITE_EMAIL_PATTERN, "One plain email address (name@domain), no names, lists or spaces.").optional().describe("Optional. When given, OKO Stream emails the invitation to this address."),
       comment: external_exports.string().max(500).default(""),
       permissions: workspacePermissionsSchema,
-      confirm: external_exports.boolean().optional()
+      confirm: external_exports.boolean().optional().describe("Required true. With an email, true also means the workspace owner has confirmed that address.")
     },
-    outputSchema: external_exports.object({ workspaceId: external_exports.string(), code: external_exports.string(), inviteUrl: external_exports.string().url(), created: external_exports.boolean() }).passthrough(),
+    outputSchema: external_exports.object({ workspaceId: external_exports.string(), code: external_exports.string(), inviteUrl: external_exports.string().url(), created: external_exports.boolean(), emailRequested: external_exports.boolean().optional() }).passthrough(),
     annotations: writeTool
   }, async (args) => {
     const { uid } = await authed(["workspace:write"]);
     const workspace = await readWorkspaceForOwner(args.workspaceId, uid);
     if (!isSharedWorkspaceId(args.workspaceId))
       throw new Error(personalWorkspaceLimitMessage("creating invites"));
-    requireConfirm(args.confirm, "oko_create_workspace_invite", { workspaceId: args.workspaceId, code: args.code, email: args.email });
+    requireConfirm(args.confirm, "oko_create_workspace_invite", {
+      workspaceId: args.workspaceId,
+      code: args.code,
+      email: args.email,
+      ...args.email ? { platformEmailsThisAddress: true } : {}
+    });
     const code = (args.code?.trim() || randomInviteCode()).toUpperCase();
     const url = inviteUrl(code);
+    const email2 = args.email?.trim() ?? "";
     await setDoc(doc(firestore, "workspaceInvites", code), {
       workspaceId: args.workspaceId,
       workspaceName: safeString(workspace.name, "Workspace"),
-      email: args.email ?? "",
+      email: email2,
       comment: args.comment,
       permissions: normalizeWorkspacePermissions(args.permissions),
       createdBy: uid,
@@ -123321,7 +123332,7 @@ function registerWorkspaceTools(server2) {
       claimed: false,
       claimedBy: null
     });
-    return textResult({ workspaceId: args.workspaceId, code, inviteUrl: url, created: true });
+    return textResult({ workspaceId: args.workspaceId, code, inviteUrl: url, created: true, ...email2 ? { emailRequested: true } : {} });
   });
 }
 

package/package.json

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