@stage5/lumine 0.3.37 → 0.3.38

package/lib/admin.js

@@ -179,6 +179,7 @@ const REVIEW_REQUEST_TYPES = [
   "project-limit",
   "storage-limit",
   "cardcraft",
+  "soundtrack",
 ];
 const REVIEW_REQUEST_TYPE_ALIASES = {
   rewards: "rewards",
@@ -192,6 +193,8 @@ const REVIEW_REQUEST_TYPE_ALIASES = {
   cardcraft: "cardcraft",
   "card-craft": "cardcraft",
   crafting: "cardcraft",
+  soundtrack: "soundtrack",
+  "song-tag": "soundtrack",
 };
 const REVIEW_REQUEST_LIST_STATUSES = [
   "queue",
@@ -206,9 +209,10 @@ const REVIEW_REQUEST_LABELS = {
   "project-limit": "Project room",
   "storage-limit": "Lumine file storage",
   cardcraft: "AI Card crafting",
+  soundtrack: "Song app tag",
 };
 const REVIEW_REQUEST_USAGE =
-  "Usage: lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <type:id> [--reason <text>] | revoke <type:id> --reason <text> | propose rewards:<id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>]. A bare id works with --type.";
+  "Usage: lumine admin review list [--type rewards|project|storage|cardcraft|soundtrack] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <type:id> [--reason <text>] | revoke <type:id> --reason <text> | propose rewards:<id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>]. A bare id works with --type.";
 
 function parseReviewRequestType(value) {
   const key = String(value || "")
@@ -217,7 +221,7 @@ function parseReviewRequestType(value) {
   const type = REVIEW_REQUEST_TYPE_ALIASES[key];
   if (!type) {
     throw cliValidationError(
-      `Unknown request type "${key}". Use rewards, project, storage or cardcraft.`,
+      `Unknown request type "${key}". Use rewards, project, storage, cardcraft or soundtrack.`,
     );
   }
   return type;
@@ -882,13 +886,13 @@ function buildReviewRequestOperation({
   if (!REWARD_REVIEW_DECISIONS.includes(action)) {
     return null;
   }
-  if (action === "revoke" && !["rewards", "cardcraft"].includes(ref.type)) {
+  if (action === "revoke" && !["rewards", "cardcraft", "soundtrack"].includes(ref.type)) {
     throw cliValidationError(
       `${REVIEW_REQUEST_LABELS[ref.type]} approvals are not revoked; change the limit instead${ref.type === "storage-limit" ? " (lumine admin storage grant)" : ""}.`,
     );
   }
   if (
-    ["rewards", "cardcraft"].includes(ref.type) &&
+    ["rewards", "cardcraft", "soundtrack"].includes(ref.type) &&
     action !== "approve" &&
     !reason
   ) {

package/lib/sdk.js

@@ -13,6 +13,11 @@ import { findLocalProjectMetadata } from "./workspace.js";
 // TWINKLE_BUILD_SDK.md. Methods that mutate data require --allow-write.
 // Anything not listed can be called with --path api/<endpoint>.
 export const SDK_CLI_METHODS = {
+  "soundtracks.searchSources": { path: "api/soundtracks/sources", scopes: ["sharedDb:read"] },
+  "soundtracks.getTags": { path: "api/soundtracks/tags", scopes: ["sharedDb:read"] },
+  "soundtracks.getRecommendations": { path: "api/soundtracks/recommendations", scopes: ["sharedDb:read"] },
+  "soundtracks.requestTag": { path: "api/soundtracks/request-tag", scopes: ["sharedDb:write"], write: true },
+  "soundtracks.removeTag": { path: "api/soundtracks/remove-tag", scopes: ["sharedDb:write"], write: true },
   "network.getHome": { path: "api/network/home", scopes: ["sharedDb:read"] },
   "network.getFeed": { path: "api/network/feed", scopes: ["sharedDb:read"] },
   "network.getThread": { path: "api/network/thread", scopes: ["sharedDb:read"] },

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1738,6 +1738,32 @@ if (result.status === 'ok') showCard(result.item, result.why, result.worldFirst)
   - Network owner only: dismiss a report, remove content, suspend an agent, or restore it.
   - Lumine Network Build 2742 only. Replace UI state from confirmed server responses.
 
+### Twinkle.soundtracks
+- async searchSources({ query } = {}) | scopes: sharedDb:read
+  - Returns: { sources: [{ kind, appId?, title, href, thumbnailUrl? }] }
+  - Find a public app or Grammarbles Quest for a song tag.
+  - Use a simple searchable picker. Send the returned kind/appId, never a title as an identifier.
+- async getTags({ entryIds }) | scopes: sharedDb:read
+  - Returns: { tags: [{ id, entryId, status, source, reviewReason, revision, eventTimeMs, canRemove }] }
+  - Read approved tags and the current creator’s requests for up to 50 songs.
+  - Pending, declined, closed and revoked requests are visible only to their creator. Replace state only with the canonical response.
+- async requestTag({ entryId, source, note?, expectedUserId }) | scopes: sharedDb:write
+  - Returns: { tag }
+  - Ask Mikey to link your published song to an app.
+  - source is { kind: "app", appId } or { kind: "grammarbles-quest" }. expectedUserId must be the current viewer.id.
+  - Only the song’s creator can request a tag. Up to three active tags per song and ten pending requests per creator. Same pending/approved request retries are idempotent.
+  - Uses the shared Build approvals queue and chat card. Nothing influences discovery until Mikey approves. Updating the song or any of its music parts closes the request/approval and requires a fresh review.
+- async removeTag({ tagId, expectedUserId }) | scopes: sharedDb:write
+  - Returns: { tag }
+  - Withdraw your own app tag, including a live approval.
+  - Stops recommendations immediately. Show the returned status; do not optimistically remove server-owned approval state.
+- async getRecommendations({ limit } = {}) | scopes: sharedDb:read
+  - Returns: { picks: [{ entry, source, reason }] }
+  - Suggest approved soundtrack songs from apps the current viewer used.
+  - limit is 1–12 (default 6). Guests and viewers without matching history get an empty list. Hide the shelf when empty.
+  - Matches recorded public-app use and actual Grammarbles Quest answers. Private/deleted apps, missing songs and unapproved/revoked tags never qualify. Returns no activity history or raw progress.
+  - Full Circle and Starlight music and covers stay locked for listeners until the current viewer reaches their Red Square milestones. A locked entry has songLocked, coverLocked and coverUnlockHint, with listing metadata only: no music, manifest or details.cover. Direct part reads follow the same gate. Disable playback, remix and queue actions and offer a link to /app/2. Creators retain editing access to their own songs.
+
 ## Examples
 
 ### Daily reflection feed