@stage5/lumine 0.2.87 → 0.2.89

package/lib/sdk.js

@@ -28,6 +28,29 @@ 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 },
+  "minecraft.getDesigns": { path: "api/minecraft/designs", scopes: ["content:read"] },
+  "minecraft.getDesign": { path: "api/minecraft/design", scopes: ["content:read"] },
+  "minecraft.saveDesign": { path: "api/minecraft/designs/save", scopes: ["content:write"], write: true },
+  "minecraft.updateDesign": { path: "api/minecraft/designs/update", scopes: ["content:write"], write: true },
+  "minecraft.deleteDesign": { path: "api/minecraft/designs/delete", scopes: ["content:write"], write: true },
+  "minecraft.checkPlacement": { path: "api/minecraft/placement/check", scopes: ["content:read"] },
+  "minecraft.buildDesign": { path: "api/minecraft/placement/build", scopes: ["content:write"], write: true },
+  "minecraft.stopZero": { path: "api/minecraft/zero/stop", scopes: ["content:write"], write: true },
+  "minecraft.undoBuild": { path: "api/minecraft/zero/undo", scopes: ["content:write"], write: true },
+  "minecraft.getSnaps": { path: "api/minecraft/snaps", scopes: ["content:read"] },
+  "minecraft.getSnap": { path: "api/minecraft/snap", scopes: ["content:read"] },
+  "minecraft.deleteSnap": { path: "api/minecraft/snaps/delete", scopes: ["content:write"], write: true },
+  "minecraft.getServerLogs": { path: "api/minecraft/logs", scopes: ["content:read"] },
+  "minecraft.getArrivalPoints": { path: "api/minecraft/homes", scopes: ["content:read"] },
+  "minecraft.setArrivalPoint": { path: "api/minecraft/homes/set", scopes: ["content:write"], write: true },
+  "minecraft.clearArrivalPoint": { path: "api/minecraft/homes/clear", 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.89",
   "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.55.0
+Updated: 2026-09-24
+Generated: 2026-09-24T11:41:42.326Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -787,13 +787,14 @@ 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 }
-  - 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.
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
+  - Everyone who has joined the server with their in-game rank, for a player directory; the server owner also gets the full records for role management.
+  - Every viewer gets the list. Only the server owner, in an app they own, gets canManage: true with full records (groups, bans, exact first/last seen); everyone else gets canManage: false and the public view: banned players left out, and seen is a rough bucket instead of exact times. Show role controls only when canManage is true.
   - 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.
-  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); if (!canManage) hidePeopleTab();
+  - twinkle is the Twinkle account linked to that player with /link, or null.
+  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); renderDirectory(people, { editable: canManage });
 - async setPlayerRole({ uuid, role }) | scopes: content:write
   - Returns: { player: { uuid, name, role, op } }
   - Change a player's in-game role; it applies immediately, even while they are online.
@@ -801,6 +802,150 @@ 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 });
+- async getDesigns({ query } = {}) | scopes: content:read
+  - Returns: { designs: [{ id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }], access: { rank, linked, canOrder, canModerate, isOwner } | null }
+  - Zero's design library: published designs plus the viewer's own private ones.
+  - Built-in designs (redstone devices and so on) have no author and are public.
+  - previewUrl is an image set with updateDesign, or null.
+  - access says what this viewer may do: canOrder shows placement tools (builders, moderators, the owner).
+  - Example: const { designs } = await Twinkle.minecraft.getDesigns({ query: 'castle' });
+- async getDesign({ id }) | scopes: content:read
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }, size: [w, h, d], palette: [blockState], cells: number[] }
+  - A design's blocks for a 3D preview.
+  - cells is a flat list of [x, y, z, paletteIndex] numbers; air is left out. palette entries are block states like "oak_stairs[facing=north,half=bottom]".
+  - Private designs are only returned to their designer.
+  - Example: const { size, palette, cells } = await Twinkle.minecraft.getDesign({ id: 'harbor_house' }); for (let i = 0; i < cells.length; i += 4) addCube(cells[i], cells[i + 1], cells[i + 2], palette[cells[i + 3]]);
+- async saveDesign({ id, name, summary, category, tags, visibility, parts }) | scopes: content:write
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt } }
+  - Save a design (or a new version of your design) from blueprint parts.
+  - parts use Zero's blueprint shapes: box, hollow_box, walls, floor, line, block, cylinder, sphere, gable_roof, pyramid_roof; offsets x = east, y = up, z = south; later parts override earlier ones (carve doors/windows with "air"). Up to 60,000 blocks and 96 blocks in each direction.
+  - category is building, decor, farm or path. visibility private (default) or public. Saving the same id again adds a version; only its designer can do that. Rejections come back as 400 minecraft_studio_rejected with a readable message.
+  - Who may: the server owner, and any signed-in viewer with a linked Minecraft account (Twinkle.minecraft.createLinkCode + /link); others get 403 minecraft_not_linked. Designs are private unless visibility is 'public'. Players have a limit on how many designs they keep.
+  - Example: await Twinkle.minecraft.saveDesign({ id: 'harbor_house', name: 'Harbor house', category: 'building', visibility: 'private', parts: [{ shape: 'floor', from: [0, 0, 0], to: [8, 0, 6], block: 'stone_bricks' }, { shape: 'walls', from: [0, 1, 0], to: [8, 4, 6], block: 'spruce_planks' }] });
+- async updateDesign({ id, visibility, previewUrl, name, summary }) | scopes: content:write
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt } }
+  - Publish or unpublish a design, set its preview image, or rename it.
+  - previewUrl is typically a Twinkle.files upload of a rendered preview.
+  - Who may: a design's own designer; moderators (by linked account) and the server owner may change or delete anyone's.
+  - Example: await Twinkle.minecraft.updateDesign({ id: 'harbor_house', visibility: 'public' });
+- async deleteDesign({ id }) | scopes: content:write
+  - Returns: { deleted }
+  - Remove one of your designs from the library.
+  - Built-in designs can't be deleted.
+  - Who may: a design's own designer; moderators (by linked account) and the server owner may change or delete anyone's.
+  - Example: await Twinkle.minecraft.deleteDesign({ id: 'old_test' });
+- async checkPlacement({ designId, world, x, z, y?, facing?: 'north'|'east'|'south'|'west' }) | scopes: content:read
+  - Returns: { check: { clear, reasons, world, facing, anchor, bounds: { min, max }, ground: { y, min, max, water }, builtBlocks, builtSamples, placedBy: [{ name, blocks }], design } }
+  - Check a building site for a design: where it would sit and whether it would touch anyone's builds.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - The footprint is centred on x/z and turned to face facing; without y it sits on the ground. clear is false when built (non-natural) blocks stand in the footprint or 3 blocks around it, the ground is very uneven, or it would leave the world; reasons explains. placedBy lists players CoreProtect recorded placing blocks there.
+  - Call on a user action (drop or rotate), not while dragging.
+  - Example: const { check } = await Twinkle.minecraft.checkPlacement({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' }); outline.color = check.clear ? 'green' : 'red';
+- async buildDesign({ ...placement, force }) | scopes: content:write
+  - Returns: { jobId, check, priority }
+  - Order Zero to build a design at a site; he switches to creative and builds it before other work.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Follow progress with getZero() (currentBuild) and getZeroBuilds().
+  - Builders: one order waiting or building at a time, published designs or their own, and orders wait in the normal queue (priority false). Moderators: up to 3 orders, ahead of other work. The owner: no limit. force (build on a site that isn't clear) is owner-only.
+  - Example: const { jobId } = await Twinkle.minecraft.buildDesign({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' });
+- async stopZero() | scopes: content:write
+  - Returns: { stopped, message }
+  - Stop the build Zero is doing right now (placed blocks stay).
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
+  - Example: await Twinkle.minecraft.stopZero();
+- async undoBuild({ jobId }) | scopes: content:write
+  - Returns: { undone, title, message }
+  - Undo one of Zero's builds, putting back what was there before.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
+  - Example: await Twinkle.minecraft.undoBuild({ jobId });
+- async getSnaps({ before, limit, uuid } = {}) | scopes: content:read
+  - Returns: { snaps: [{ id, takenAt, name, uuid, world, x, y, z, caption, blocks, players, twinkleUserId }] }
+  - The /snap Gallery: 3D scenes players took in game with /snap, newest first.
+  - Every viewer gets the list. before is a time in ms (the takenAt of the last snap you have) for paging; limit 1-60 (default 30); uuid filters to one player's snaps.
+  - Example: const { snaps } = await Twinkle.minecraft.getSnaps({ limit: 30 });
+- async getSnap({ id }) | scopes: content:read
+  - Returns: { scene: { version, id, at, by, caption, origin: [x, y, z], size: [w, h, d], palette, count, blocks, light, biomes: { palette, grid }, camera: { x, y, z, yaw, pitch, fov }, world: { name, environment, time, moonPhase, storm, thunder }, players: [{ name, uuid, x, y, z, yaw, pitch, bodyYaw, pose, sneaking, self, zero, slim, skin }] } }
+  - One snap's scene, to render in 3D from where it was taken.
+  - blocks is base64 of 5 bytes per visible block: x, y, z (relative to origin) and the palette index as a big-endian uint16. palette entries are block states like oak_stairs[facing=east,half=bottom,shape=straight,waterlogged=false].
+  - light is base64 of 7 bytes per block, in the same order: the light each face receives (+x, -x, +y, -y, +z, -z) and the block's own cell, each sky << 4 | block (0-15).
+  - biomes.grid is base64 of one byte per column (x-major: index = x * depth + z) into biomes.palette (biome ids like plains, cherry_grove).
+  - camera is in world coordinates (subtract origin for scene space); yaw 0 looks toward +z (south), 90 toward -x; pitch is positive looking down. world.time is the tick of day (0 sunrise, 6000 noon, 18000 midnight).
+  - players[].skin is a data: URL of the 64x64 skin PNG when known; slim means the thin-armed model.
+  - Scenes are large (up to a few MB); fetch one at a time.
+  - Example: const { scene } = await Twinkle.minecraft.getSnap({ id });
+- async deleteSnap({ id }) | scopes: content:write
+  - Returns: { deleted }
+  - Delete a snap from the Gallery.
+  - Who may: the player who took it (by a linked Minecraft account), moderators, and the server owner. Others get 403 minecraft_snap_forbidden.
+  - Example: await Twinkle.minecraft.deleteSnap({ id });
+- async getArrivalPoints() | scopes: content:read
+  - Returns: { accounts: [{ uuid, name, online, world, worldLabel, points: [{ world, label, x, y, z, savedAt }] }] }
+  - The viewer's private arrival points: where the Twinkle Gate portals drop their linked Minecraft account in each world.
+  - Only the caller's own linked accounts; 400 minecraft_not_linked when none is linked.
+  - online/world tell whether setArrivalPoint can use the player's current spot right now.
+  - Example: const { accounts } = await Twinkle.minecraft.getArrivalPoints();
+- async setArrivalPoint({ uuid } = {}) | scopes: content:write
+  - Returns: { uuid, name, world, worldLabel, points }
+  - Save where the viewer's Minecraft player is standing right now as their arrival point in that world (the Twinkle Gate portal to that world lands them there).
+  - The player must be online; the spot is their current position, never typed coordinates (so nobody can land inside places they could not walk to).
+  - 400 minecraft_arrival_rejected when not online or the spot is unsafe (no floor, no room, lava); uuid picks one of several linked accounts.
+  - Example: const { worldLabel } = await Twinkle.minecraft.setArrivalPoint();
+- async clearArrivalPoint({ world, uuid }) | scopes: content:write
+  - Returns: { cleared, points }
+  - Remove the viewer's arrival point in a world (back to the shared arrival).
+  - world is a world id such as world, world1, world3, world_nether.
+  - Example: await Twinkle.minecraft.clearArrivalPoint({ world: 'world3' });
+- async getServerLogs({ days, kinds, query, limit } = {}) | scopes: content:read
+  - Returns: { total, lines: [{ at, kind: 'join'|'leave'|'kick'|'command'|'warn'|'error'|'zero'|'server', level, text }] }
+  - The Minecraft server log for the server owner: joins, kicks, commands, warnings, errors and Zero's lines, newest first, IP addresses removed.
+  - Server owner only, in an app they own; everyone else gets 403 minecraft_roles_forbidden.
+  - days 1-7 (default 1); kinds any of join, leave, kick, command, warn, error, zero, server (default all); query filters by text; limit 1-1000 (default 300). Chat is not included (getChat and getChatHistory have it).
+  - Example: const { lines } = await Twinkle.minecraft.getServerLogs({ days: 2, kinds: ['kick', 'error'] });
 
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none