@stage5/lumine 0.3.5 → 0.3.6

package/lib/sdk.js

@@ -214,6 +214,16 @@ export const SDK_CLI_METHODS = {
     scopes: ["rewards:claim"], readOnly: true,
     mapArgs: (args) => ({ ruleId: args.ruleId, cursor: args.cursor, limit: args.limit }),
   },
+  "rewards.interpretAnswer": {
+    path: "api/rewards/interpret-answer", special: "rewards", operation: "interpret-answer",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: (args) => ({ challengeId: args.challengeId, text: args.text }),
+  },
+  "rewards.getChallengeBoard": {
+    path: "api/rewards/challenge-board", special: "rewards", operation: "challenge-board",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: () => ({}),
+  },
   "rewards.getArchivedProblem": {
     path: "api/rewards/archived-problem", special: "rewards", operation: "archived-problem",
     scopes: ["rewards:claim"], readOnly: true,

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.63.0
 Updated: 2026-09-28
-Generated: 2026-09-30T09:55:20.738Z
+Generated: 2026-10-03T04:47:01.454Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -81,8 +81,9 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
 
 ### Twinkle.viewer
 - async get() | scopes: none
-  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest }
+  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest, ageTier }
   - Cached; use refresh() to re-fetch.
+  - ageTier is 'kid', 'teen' or 'adult', taken from the viewer's Teenager and Adult achievements (granted once an admin approves their birthdate). Guests and viewers without either achievement are 'kid'. It is a display and default-selection hint computed by the Twinkle page; do not treat it as a server-side permission.
 - async refresh() | scopes: none
   - Returns: Viewer info
   - Forces a fresh fetch from the parent.
@@ -1515,6 +1516,21 @@ world.updatePresence({ x, y, z, facing });
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.
   - available says which boards this app's approved rules can pay: show a Coins board only when available.coins is true (an app whose rules pay XP only has no Coins standings). me is the signed-in viewer's own standing even when they fall outside the page, or null when they earned nothing in the period.
   - Drafts and previews return mode 'preview' with no entries. Use Twinkle.leaderboards for app-defined scores; use this for real XP and Coins earned.
+- await Twinkle.rewards.interpretAnswer({ challengeId, text }) | scopes: rewards:claim
+  - Returns: { mode: "live" | "preview", understood: boolean, value: number | null, source: "plain" | "model" }
+  - Read a learner's free-form answer text into the single number they meant, so they can answer in any format.
+  - For numeric-quiz bounties. Call it only when the typed text is not already a plain number or fraction (check that locally); a plain number returns source 'plain' with no model call. Then pass the returned value to claim({ challengeId, answers: [value] }). A small model reads the text and the platform pays for it, so the learner's AI Energy is never charged.
+  - understood: false means the text had no single clear number (several alternatives, no number, or a calculation). Tell the learner in friendly words to type just the number. This is not a wrong answer and does not use a try.
+  - The reader is given the puzzle text only to learn the requested answer format (unit, fraction/decimal/percent, which of several numbers answers the question), never the answer key, and never calculates or converts units: it only reads what was written, and the number it returns must be one the learner actually typed. Typed expressions like 5+8 are intentionally not evaluated.
+  - Requires an open challenge of the learner's own (build_reward_challenge_not_open, HTTP 409 otherwise). Limit: 120 characters (build_reward_answer_text_invalid, 400), rate limited to a burst of 4 then one read every 5 seconds (build_reward_throttled, 429). build_reward_answer_reader_unavailable (503) means the reader is down: ask the learner to type just the number.
+  - Drafts and owner previews return mode 'preview' and need no open challenge.
+- await Twinkle.rewards.getChallengeBoard() | scopes: rewards:claim
+  - Returns: { mode: "live", dayKey, puzzles: [{ ruleId, title, setKey, rating, solvers, failers, failures, daysStanding, status: "untouched" | "undefeated" | "defeated" }], topSolvers: [{ rank, userId, username, profilePicUrl, rating, solves, hardestSolve: { ruleId, setKey, rating } | null }], recentSolves: [{ id, userId, username, ruleId, setKey, tier: "solved" | "first-solve" | "hard-won" | "legendary", attempt, firstSolve, failersBefore, failuresBefore, daysStanding, puzzleRating, at }], me: { rating, solves, rank } | null } | { mode: "preview", puzzles: [], topSolvers: [], recentSolves: [], me: null, message }
+  - Front-page difficulty board for until-earned quiz bounties: what is being tried and failed, who is rated highest, and the latest defeats.
+  - Computed by Twinkle from its own receipts and attempts, never from anything the app submits. Puzzles are Elo-rated against players: a player's first miss on a puzzle is a win for the puzzle, a solve is a win for the player, and repeat misses by one player never stack.
+  - puzzles lists today's set for each until-earned rule. status 'undefeated' means someone tried and nobody has solved it yet; show it as a standing challenge. failers is how many different players missed it; failures is total wrong answers.
+  - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later.
+  - No questions, answers, guides or private work are ever returned. Names are the same public names the XP leaderboard shows; other players who missed a puzzle are counted, never named. Drafts and previews return mode 'preview' with empty lists.
 - await Twinkle.rewards.getTimeline({ ruleId?, cursor?, limit? } = {}) | scopes: rewards:claim
   - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
   - Browse confirmed solves of retired until-earned quiz bounties, newest first.