@stage5/lumine 0.2.87 → 0.2.88

package/lib/sdk.js

@@ -28,6 +28,13 @@ export const SDK_CLI_METHODS = {
   "minecraft.getZeroBuilds": { path: "api/minecraft/zero/builds", scopes: ["content:read"] },
   "minecraft.getPeople": { path: "api/minecraft/people", scopes: ["content:read"] },
   "minecraft.setPlayerRole": { path: "api/minecraft/people/role", scopes: ["content:write"], write: true },
+  "minecraft.getChat": { path: "api/minecraft/chat", scopes: ["content:read"] },
+  "minecraft.getChatHistory": { path: "api/minecraft/chat/history", scopes: ["content:read"] },
+  "minecraft.sendChat": { path: "api/minecraft/chat/send", scopes: ["content:write"], write: true },
+  "minecraft.muteChatUser": { path: "api/minecraft/chat/mute", scopes: ["content:write"], write: true },
+  "minecraft.getMyLink": { path: "api/minecraft/link", scopes: ["content:read"] },
+  "minecraft.createLinkCode": { path: "api/minecraft/link/code", scopes: ["content:write"], write: true },
+  "minecraft.unlinkMinecraft": { path: "api/minecraft/link/unlink", scopes: ["content:write"], write: true },
   "subjects.getMySubjects": { path: "api/content/my-subjects", scopes: ["content:read"] },
   "subjects.search": { path: "api/content/subjects/search", scopes: ["content:read"] },
   "subjects.getSubject": { path: "api/content/subject", scopes: ["content:read"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.87",
+  "version": "0.2.88",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.49.0
-Updated: 2026-09-23
-Generated: 2026-09-23T16:01:40.924Z
+Version: 1.51.0
+Updated: 2026-09-24
+Generated: 2026-09-24T00:08:02.260Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -787,12 +787,13 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - limit is 1-50 (default 10). kind filters to helper or workshop builds.
   - Example: const { builds } = await Twinkle.minecraft.getZeroBuilds({ limit: 10, kind: 'workshop' });
 - async getPeople() | scopes: content:read
-  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', groups, op, online, banned, protected, firstSeenAt, lastSeenAt, isZero }], roles }
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', groups, op, online, banned, protected, firstSeenAt, lastSeenAt, isZero, twinkle: { userId, username } | null }], roles }
   - Everyone who has joined the server with their in-game role, for the server owner's role management screen.
   - Only the server owner, in an app they own, gets the list; everyone else gets { canManage: false, people: [] } without an error, so hide the feature when canManage is false.
   - Roles: visitor (play and chat), member (/tpa, /home, /back, may ask Zero to build), builder (member + /fly and creative/survival), moderator (builder + teleport others, CoreProtect rollback, /kick). op: true players are server operators and have every power regardless of role.
   - protected: true players (the owner and Zero's account) can't be changed from the app. Sorted online first, then most recently seen.
   - Not cached; call on screen open or after a change, not on a timer.
+  - twinkle is the Twinkle account linked to that player with /link, or null.
   - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); if (!canManage) hidePeopleTab();
 - async setPlayerRole({ uuid, role }) | scopes: content:write
   - Returns: { player: { uuid, name, role, op } }
@@ -801,6 +802,49 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - role is visitor, member, builder or moderator. 400 codes: minecraft_bad_uuid, minecraft_bad_role, minecraft_protected_player, minecraft_unknown_player. 503 minecraft_unavailable while the server restarts.
   - Every change is logged on the server and emailed to the owner; the player is told in game.
   - Example: await Twinkle.minecraft.setPlayerRole({ uuid: person.uuid, role: 'builder' });
+- async getChat({ since } = {}) | scopes: content:read
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], latestSeq, online, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
+  - Live server chat after a sequence number: player chat, Zero, messages sent from the web, joins, leaves and deaths.
+  - Without since (or 0) it returns the newest 50 events, oldest first. Pass since = latestSeq from the previous response to get only new events. Poll every 2-3 seconds while the chat is visible; stop when hidden.
+  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death. Private messages are never included.
+  - name is a Minecraft username for chat/join/leave/death, and a Twinkle username for web.
+  - viewer.canModerate is true only for the server owner; mutedUserIds is filled only for them.
+  - Example: let since = 0; async function poll() { const { events, latestSeq } = await Twinkle.minecraft.getChat({ since }); since = latestSeq; render(events); } setInterval(poll, 2500);
+- async getChatHistory({ before, limit, query, includeArchived } = {}) | scopes: content:read
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
+  - Older server chat, newest first, for scrolling back or searching past days.
+  - before is the nextBefore cursor from the previous page; omit it to start from the newest. limit 1-100 (default 50). query searches message text and names (60 chars).
+  - Chat from before the web chat bridge existed (imported from server logs) is archived: only the server owner can include it with includeArchived: true; others never receive it.
+  - Example: const page = await Twinkle.minecraft.getChatHistory({ limit: 50 }); const older = await Twinkle.minecraft.getChatHistory({ before: page.nextBefore });
+- async sendChat({ text }) | scopes: content:write
+  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived } }
+  - Send a chat message from the app into the Minecraft server; players see it as [Web] <your Twinkle username>.
+  - Signed-in viewers only. text is trimmed to 200 characters. About one message per 2.5 seconds and 10 per minute per person: 429 with code minecraft_chat_rate_limited and retryAfterMs.
+  - 403 minecraft_chat_forbidden for accounts banned from chat; 400 minecraft_muted when the server owner muted them from web chat.
+  - Send only on a user action (Enter or Send); never automatically.
+  - Example: await Twinkle.minecraft.sendChat({ text: 'Hi from the website!' });
+- async muteChatUser({ userId, muted }) | scopes: content:write
+  - Returns: { userId, muted }
+  - Server owner only: stop (or allow again) a Twinkle user sending web chat into the server.
+  - Server owner only, in an app they own; others get 403 with code minecraft_roles_forbidden. muted defaults to true.
+  - Example: await Twinkle.minecraft.muteChatUser({ userId: event.userId, muted: true });
+- async getMyLink() | scopes: content:read
+  - Returns: { links: [{ uuid, name, linkedAt }], pending: { code, expiresAt } | null }
+  - The Minecraft accounts linked to the signed-in viewer's Twinkle account, and any unused link code.
+  - Always the caller's own account. A viewer may link several Minecraft accounts (e.g. Java and Bedrock); each Minecraft account belongs to one Twinkle user.
+  - Poll every few seconds only while showing a code and waiting for the player to type /link in game.
+  - Example: const { links } = await Twinkle.minecraft.getMyLink(); const myMinecraftName = links[0]?.name;
+- async createLinkCode() | scopes: content:write
+  - Returns: { code, expiresAt, command }
+  - Get a one-time code the viewer types in game as /link CODE to connect that Minecraft account to their Twinkle account.
+  - Signed-in viewers only. Codes last 10 minutes, work once, and a new code replaces the old one. About 5 codes per 10 minutes: 429 minecraft_link_rate_limited.
+  - The player sees a confirmation in game; getMyLink() then lists the account.
+  - Example: const { command } = await Twinkle.minecraft.createLinkCode(); showText(`Type ${command} in Minecraft`);
+- async unlinkMinecraft({ uuid }) | scopes: content:write
+  - Returns: { removed }
+  - Remove one of the viewer's own linked Minecraft accounts.
+  - Only the viewer's own links; removed is false when there was nothing to remove.
+  - Example: await Twinkle.minecraft.unlinkMinecraft({ uuid: link.uuid });
 
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none