updateday 0.0.0-stage → 0.2.0

package/dist/state.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+let logSink = null;
+export function setLogSink(sink) {
+    logSink = sink;
+}
+export function loadState(path, updateAt) {
+    if (existsSync(path)) {
+        const state = JSON.parse(readFileSync(path, "utf8"));
+        if (state.updateAt === updateAt) {
+            return state;
+        }
+        const swapOpen = state.swap?.swapped && !state.swap.finished;
+        if (swapOpen || state.prices.some((price) => !price.restored || (price.taggedName && !price.nameRestored))) {
+            throw new Error(`State file ${path} is from a different update and still has unrestored sale prices. Run "restore" first.`);
+        }
+    }
+    return { updateAt, done: {}, prices: [], log: [] };
+}
+export function saveState(path, state) {
+    const temp = `${path}.tmp`;
+    writeFileSync(temp, JSON.stringify(state, null, "\t"));
+    renameSync(temp, path);
+}
+export function logLine(state, message) {
+    const line = `${new Date().toISOString()}  ${message}`;
+    state.log.push(line);
+    console.log(line);
+    logSink?.(message);
+}

package/dist/swap.js

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { OpenCloudError } from "./openCloud.js";
+import { logLine, saveState } from "./state.js";
+const PUBLIC_I18N = "https://gameinternationalization.roblox.com/v1";
+const TEMP_PREFERENCE = ["th", "vi", "pl", "id", "tr", "it", "ko", "ja", "fr", "de", "pt", "ru", "es", "zh-hant", "zh-hans"];
+const UPLOAD_GAP_MS = 250;
+const UPLOAD_CONCURRENCY = 4;
+const APPROVAL_POLL_MS = 5000;
+const APPROVAL_MAX_MS = 150 * 1000;
+const SETTLE_POLLS = 20;
+const SETTLE_POLL_MS = 3000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function publicJson(path) {
+    const response = await fetch(PUBLIC_I18N + path);
+    if (!response.ok) {
+        throw new Error(`Couldn't read ${path} (${response.status})`);
+    }
+    return response.json();
+}
+export async function sourceLanguage(universeId) {
+    return String((await publicJson(`/source-language/games/${universeId}`)).languageCode);
+}
+export async function supportedLanguages(universeId) {
+    const json = await publicJson(`/supported-languages/games/${universeId}`);
+    return (json?.data ?? []).map((item) => String(item.languageCode)).filter(Boolean);
+}
+export function pickTemp(source, supported, preferred) {
+    if (preferred) {
+        if (preferred === source) {
+            throw new Error(`swapLanguage can't be the game's source language (${source})`);
+        }
+        return preferred;
+    }
+    const candidates = supported.filter((code) => code !== source);
+    const ranked = TEMP_PREFERENCE.find((code) => candidates.includes(code));
+    if (!ranked && candidates.length === 0) {
+        throw new Error("The game supports only one language; add one in Creator Hub (Localization) so the countdown can use the language swap");
+    }
+    return ranked ?? candidates[candidates.length - 1];
+}
+async function waitForSource(universeId, expected) {
+    for (let attempt = 0; attempt < SETTLE_POLLS; attempt++) {
+        if ((await sourceLanguage(universeId).catch(() => "")) === expected) {
+            return true;
+        }
+        await sleep(SETTLE_POLL_MS);
+    }
+    return false;
+}
+async function saveExistingIcons(cloud, source, folder) {
+    const saved = {};
+    const list = await cloud.listIcons();
+    for (const icon of list?.data ?? []) {
+        if (icon.languageCode === source || !icon.imageUrl) {
+            continue;
+        }
+        const response = await fetch(icon.imageUrl);
+        if (!response.ok) {
+            throw new Error(`Couldn't save the existing ${icon.languageCode} icon before the swap`);
+        }
+        mkdirSync(folder, { recursive: true });
+        const file = join(folder, `${icon.languageCode}.png`);
+        writeFileSync(file, Buffer.from(await response.arrayBuffer()));
+        saved[icon.languageCode] = file;
+    }
+    return saved;
+}
+export async function startSwap(cloud, state, statePath, preferredTemp) {
+    if (state.swap?.swapped) {
+        return state.swap;
+    }
+    const originalSource = await sourceLanguage(cloud.universeId);
+    const supported = await supportedLanguages(cloud.universeId);
+    const temp = pickTemp(originalSource, supported, preferredTemp);
+    const languages = [originalSource, ...supported.filter((code) => code !== originalSource && code !== temp)];
+    const folder = join(dirname(statePath), "updateday-saved-icons", String(cloud.universeId));
+    const savedIcons = await saveExistingIcons(cloud, originalSource, folder);
+    state.swap = { originalSource, temp, languages, savedIcons, swapped: false, removed: [], restoredSaved: [], finished: false };
+    saveState(statePath, state);
+    await cloud.setSourceLanguage(temp);
+    state.swap.swapped = true;
+    saveState(statePath, state);
+    logLine(state, `  source language ${originalSource} -> ${temp}; icons go to ${languages.length} languages`);
+    if (!(await waitForSource(cloud.universeId, temp))) {
+        logLine(state, `  warning: Roblox still reports the old source language`);
+    }
+    return state.swap;
+}
+async function uploadOne(cloud, code, imageFor) {
+    try {
+        await cloud.setIcon(await imageFor(code), code);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForApproval(cloud, codes) {
+    const started = Date.now();
+    let states = {};
+    while (Date.now() - started < APPROVAL_MAX_MS) {
+        states = {};
+        for (const icon of (await cloud.listIcons().catch(() => null))?.data ?? []) {
+            states[icon.languageCode] = icon.state;
+        }
+        if (codes.every((code) => states[code] === "Approved" || states[code] === "Rejected")) {
+            break;
+        }
+        await sleep(APPROVAL_POLL_MS);
+    }
+    return states;
+}
+export async function uploadAll(cloud, state, imageFor) {
+    const swap = state.swap;
+    const started = Date.now();
+    const failed = [];
+    const queue = [...swap.languages];
+    const worker = async () => {
+        for (let code = queue.shift(); code; code = queue.shift()) {
+            if (!(await uploadOne(cloud, code, imageFor))) {
+                failed.push(code);
+            }
+            await sleep(UPLOAD_GAP_MS);
+        }
+    };
+    await Promise.all(Array.from({ length: UPLOAD_CONCURRENCY }, worker));
+    if (failed.includes(swap.originalSource) && !(await uploadOne(cloud, swap.originalSource, imageFor))) {
+        throw new Error(`Couldn't set the ${swap.originalSource} countdown icon`);
+    }
+    if (failed.length > 0) {
+        logLine(state, `  icon not set for: ${failed.filter((code) => code !== swap.originalSource).join(", ")}`);
+    }
+    const uploaded = swap.languages.filter((code) => !failed.includes(code) || code === swap.originalSource);
+    const states = await waitForApproval(cloud, uploaded);
+    const seconds = Math.round((Date.now() - started) / 1000);
+    const rejected = uploaded.filter((code) => states[code] === "Rejected");
+    const pending = uploaded.filter((code) => states[code] !== "Approved" && states[code] !== "Rejected");
+    if (rejected.length > 0) {
+        logLine(state, `  Roblox REJECTED the icon for: ${rejected.join(", ")}`);
+    }
+    if (pending.length > 0) {
+        logLine(state, `  still in review after ${seconds}s for: ${pending.join(", ")}; raise uploadLeadSeconds`);
+    }
+    else {
+        logLine(state, `  icons approved ${seconds}s after upload started`);
+    }
+}
+async function deleteIcon(cloud, code) {
+    try {
+        await cloud.deleteIcon(code);
+    }
+    catch (error) {
+        if (!(error instanceof OpenCloudError && error.status === 404)) {
+            throw error;
+        }
+    }
+}
+export async function finishSwap(cloud, state, statePath) {
+    const swap = state.swap;
+    if (!swap || swap.finished) {
+        return;
+    }
+    if (swap.swapped) {
+        for (const code of swap.languages) {
+            if (swap.removed.includes(code)) {
+                continue;
+            }
+            await deleteIcon(cloud, code);
+            swap.removed.push(code);
+            saveState(statePath, state);
+            await sleep(UPLOAD_GAP_MS);
+        }
+        for (const [code, file] of Object.entries(swap.savedIcons)) {
+            if (swap.restoredSaved.includes(code) || !existsSync(file)) {
+                continue;
+            }
+            await cloud.setIcon(new Blob([new Uint8Array(readFileSync(file))], { type: "image/png" }), code);
+            swap.restoredSaved.push(code);
+            saveState(statePath, state);
+        }
+        await cloud.setSourceLanguage(swap.originalSource);
+        if (!(await waitForSource(cloud.universeId, swap.originalSource))) {
+            throw new Error(`Source language didn't switch back to ${swap.originalSource}; run restore again`);
+        }
+        const leftover = ((await cloud.listIcons())?.data ?? []).filter((icon) => icon.languageCode !== swap.originalSource && swap.languages.includes(icon.languageCode) && !swap.savedIcons[icon.languageCode]);
+        if (leftover.length > 0) {
+            throw new Error(`Countdown icons still set for: ${leftover.map((icon) => icon.languageCode).join(", ")}`);
+        }
+    }
+    swap.finished = true;
+    saveState(statePath, state);
+    logLine(state, `  source language back to ${swap.originalSource}; countdown icons removed`);
+}

package/dist/zip.js

@@ -0,0 +1,82 @@
+const LOCAL_HEADER = 0x04034b50;
+const CENTRAL_HEADER = 0x02014b50;
+const END_RECORD = 0x06054b50;
+const VERSION = 20;
+const UTF8_FLAG = 0x0800;
+const DOS_EPOCH_YEAR = 1980;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+export function crc32(data) {
+    let crc = 0xffffffff;
+    for (const byte of data) {
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function dosTime(date) {
+    const time = (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2);
+    const day = ((date.getFullYear() - DOS_EPOCH_YEAR) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+    return { time, day };
+}
+function localHeader(name, entry, crc, stamp) {
+    const header = Buffer.alloc(30);
+    header.writeUInt32LE(LOCAL_HEADER, 0);
+    header.writeUInt16LE(VERSION, 4);
+    header.writeUInt16LE(UTF8_FLAG, 6);
+    header.writeUInt16LE(0, 8);
+    header.writeUInt16LE(stamp.time, 10);
+    header.writeUInt16LE(stamp.day, 12);
+    header.writeUInt32LE(crc, 14);
+    header.writeUInt32LE(entry.data.length, 18);
+    header.writeUInt32LE(entry.data.length, 22);
+    header.writeUInt16LE(name.length, 26);
+    header.writeUInt16LE(0, 28);
+    return header;
+}
+function centralHeader(name, entry, crc, stamp, offset) {
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(CENTRAL_HEADER, 0);
+    header.writeUInt16LE(VERSION, 4);
+    header.writeUInt16LE(VERSION, 6);
+    header.writeUInt16LE(UTF8_FLAG, 8);
+    header.writeUInt16LE(0, 10);
+    header.writeUInt16LE(stamp.time, 12);
+    header.writeUInt16LE(stamp.day, 14);
+    header.writeUInt32LE(crc, 16);
+    header.writeUInt32LE(entry.data.length, 20);
+    header.writeUInt32LE(entry.data.length, 24);
+    header.writeUInt16LE(name.length, 28);
+    header.writeUInt32LE(offset, 42);
+    return header;
+}
+export function zip(entries, date = new Date()) {
+    const stamp = dosTime(date);
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name, "utf8");
+        const crc = crc32(entry.data);
+        const local = localHeader(name, entry, crc, stamp);
+        parts.push(local, name, entry.data);
+        central.push(centralHeader(name, entry, crc, stamp, offset), name);
+        offset += local.length + name.length + entry.data.length;
+    }
+    const directory = Buffer.concat(central);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(END_RECORD, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...parts, directory, end]);
+}

package/docs/AGENTS.md

@@ -0,0 +1,123 @@
+# UpdateDay for AI agents
+
+This page is written for AI agents (and the people setting them up). UpdateDay runs a Roblox game's update day:
+countdown icons and titles, a sale, an event, in-game warnings and server restarts. Its MCP server lets you read
+and change the plan, check it, preview icons and run it, all with the user's own API key.
+
+## Setup
+
+Run it from the folder that holds the plan (`updateday.json`):
+
+```bash
+npx updateday mcp updateday.json
+```
+
+Claude Code:
+
+```bash
+claude mcp add updateday -e UPDATEDAY_API_KEY=your-key -- npx updateday mcp /path/to/updateday.json
+```
+
+Claude Desktop, Cursor and other clients (`mcpServers` in their config file):
+
+```json
+{
+	"mcpServers": {
+		"updateday": {
+			"command": "npx",
+			"args": ["updateday", "mcp", "/path/to/updateday.json"],
+			"env": {
+				"UPDATEDAY_API_KEY": "the Open Cloud API key",
+				"UPDATEDAY_DISCORD_WEBHOOK": "optional Discord webhook link for alerts"
+			}
+		}
+	}
+}
+```
+
+If `updateday.json` doesn't exist yet, create it with at least `universeId` and `updateAt` (see the example below).
+
+## Tools
+
+| Tool | What it does | Changes the live game? |
+|---|---|---|
+| `get_plan` | The raw plan file plus a summary of every game: update time, countdown, sale, event, alerts | No |
+| `change_plan` | Changes the plan with a JSON merge patch. The result is checked before it's saved | No (the plan file only) |
+| `get_schedule` | Every step of the update day in order, with its time and whether it already ran | No |
+| `check_plan` | Pre-flight: key permissions, times, files, icons, sale items, moderation, alerts | No |
+| `preview_icon` | Renders one countdown icon as an image (stage: `24h`, `1h`, `5m`, `now`, `final` …) | No |
+| `list_sale_items` | The game's passes and developer products with prices | No |
+| `get_history` | What UpdateDay did and when, newest first | No |
+| `run_due_steps` | Runs every step that is due now. Defaults to a dry run | **Yes**, with `dry_run: false` and `confirm: true` |
+| `restore_everything` | Undo: every price, name, title and icon back to normal | **Yes**, needs `confirm: true` |
+
+Every tool takes an optional `game` (name or universe ID). Leave it out to cover every game in the plan.
+
+## How to work with it
+
+1. **Read first.** Call `get_plan`, then `check_plan`. Lines with level `bad` must be fixed. `warn` is worth telling
+   the user about; `info` is just information.
+2. **Change the plan with small patches.** `change_plan` takes an [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)
+   merge patch: objects merge, arrays and plain values replace, and `null` removes a key.
+3. **Show before you act.** Use `preview_icon` and `get_schedule` to show the user what will happen, and confirm the
+   update time *with its time zone* before saving it.
+4. **Ask before anything live.** Only call `run_due_steps` with `dry_run: false` or `restore_everything` once the user
+   has said yes in this conversation. Pass `confirm: true` only then.
+5. **Times are ISO 8601 with a time zone**, e.g. `2026-11-07T18:00:00Z`. Turn "Saturday 6pm my time" into UTC and say
+   which time you used.
+
+The plan is a file, so changes made through MCP also show up in the setup page (`npx updateday ui`), and the other
+way round.
+
+## Plan examples
+
+A minimal plan:
+
+```json
+{ "universeId": 1234567890, "name": "My Game", "updateAt": "2026-11-07T18:00:00Z" }
+```
+
+Patches for common requests:
+
+```jsonc
+// "Move the update to Saturday 6 PM UTC"
+{ "updateAt": "2026-11-07T18:00:00Z" }
+
+// "30% off everything for 48 hours, with a tag on the names"
+{ "sale": { "percentOff": 30, "durationHours": 48, "gamePasses": "all", "developerProducts": "all", "nameTag": "[{percent}% OFF]" } }
+
+// "Only put game passes 111 and 222 on sale"
+{ "sale": { "gamePasses": [111, 222], "developerProducts": [] } }
+
+// "Countdown in the title too, and call it Update 5 afterwards"
+{ "title": { "afterFormat": "{name} [UPDATE 5]" } }
+
+// "Pixel hourglass, a bit bigger, and say LIVE! at NOW"
+{ "countdown": { "style": "pixel", "hourglassSize": 0.74, "labels": { "now": "LIVE!" } } }
+
+// "Skip the 5 and 4 hour stages"
+{ "countdown": { "skip": ["5h", "4h"] } }
+
+// "Warn players 10, 5 and 1 minutes before, and restart old servers"
+{ "broadcast": { "topic": "UpdateDay", "marks": ["10m", "5m", "1m"] }, "restartServers": { "bleedOffMinutes": 5 } }
+
+// "Do this every week"
+{ "repeat": { "every": "week" } }
+
+// "Turn the sale off"
+{ "sale": null }
+```
+
+Every setting is described in the [guide](GUIDE.md).
+
+## Things to know
+
+- **The main game icon can't be set with an API key.** With `"iconMethod": "reminder"` (the default) the user uploads
+  each finished icon themselves when reminded. With `"languageSwap"` it's automatic. Explain this if the user expects
+  the icon to change by itself.
+- **Sales and titles are always undone.** Originals are saved before anything changes. `restore_everything` puts them
+  back at any time, and running it twice is safe.
+- **Nothing runs on its own from MCP.** `run_due_steps` does one check, like a single tick. To run a whole update day,
+  the user starts it in the setup page, with `npx updateday watch`, or with GitHub Actions.
+- **Keys never go in the plan file.** They come from environment variables (`UPDATEDAY_API_KEY`, or the variable a
+  game names in `apiKeyEnv`).

package/docs/COVERAGE.md

@@ -0,0 +1,50 @@
+# Open Cloud coverage
+
+Checked 2026-10-28 against Roblox's published OpenAPI spec
+(`Roblox/creator-docs` → `content/en-us/reference/cloud/openapi.json`).
+
+Everything UpdateDay does uses an **Open Cloud API key** (`x-api-key`). No cookie,
+no Connect/OAuth app and no server of ours.
+
+| Feature | Endpoint | Scope | Stability |
+|---|---|---|---|
+| Game icon (countdown) | `POST /legacy-game-internationalization/v1/game-icon/games/{universeId}/language-codes/{lang}` (multipart `Files`) | `legacy-universe:manage` | Experimental |
+| Game page thumbnails | `POST .../game-thumbnails/games/{universeId}/language-codes/{lang}/image`, `.../images/order`, `DELETE .../images/{imageId}` | `legacy-universe:manage` | Experimental |
+| Game name / description | `PATCH /legacy-game-internationalization/v1/name-description/games/{universeId}` | `legacy-universe:manage` | Experimental |
+| Name / description (alt) | `PATCH /cloud/v2/universes/{u}/places/{rootPlace}?updateMask=displayName,description` | `universe.place:write` | Stable |
+| Game pass sale | `PATCH /game-passes/v1/universes/{u}/game-passes/{id}` (multipart `price`) | `game-pass:read`, `game-pass:write` | Beta |
+| Dev product sale | `PATCH /developer-products/v2/universes/{u}/developer-products/{id}` (multipart `price`) | `developer-product:read`, `developer-product:write` | Beta |
+| Roblox event | `POST /virtual-events/v3/universes/{u}/game-events` | `universe.event:write` | Experimental |
+| Player data | `/cloud/v2/universes/{u}/data-stores/{store}/entries/{key}` (`If-Match` etag) | `universe-datastores.objects:*` | Stable |
+| Publish place at update time | `POST /universes/v1/{u}/places/{p}/versions?versionType=Published` | `universe-places:write` | Beta |
+| Restart / bleed-off servers | `POST /cloud/v2/universes/{u}:restartServers` | `universe:write` | Stable |
+| In-game broadcast | `POST /cloud/v2/universes/{u}:publishMessage` | `universe-messaging-service:publish` | Stable |
+| Player notifications | `POST /cloud/v2/users/{userId}/notifications` | `user.user-notification:write` | Stable |
+
+## Caveats
+
+- **Experimental endpoints** (icon, thumbnails, name/description, events) can change
+  without notice. They're wrapped in one place (`src/openCloud.ts`) so a break is a
+  one-file fix.
+- **Silent no-ops:** Roblox notes that a key missing a scope may return success
+  without applying a change. Every write in UpdateDay is followed by a read-back.
+- **Event thumbnails:** the create body takes a `thumbnails` array, but the spec
+  doesn't document its item shape. Needs a live test.
+- **Language code:** the icon / name endpoints are per language. Writing the
+  game's source language (usually `en`) updates the primary icon / name. Needs a live
+  test to confirm.
+- **Rate limits:** about 3 writes/sec for dev products, 5/sec for passes, and 30/min for place
+  publishing. Bulk sales are throttled.
+
+## Live findings (2026-10-28, private test game)
+
+- **Main icon:** the API key can't set the source-language icon (error 26). The source-language swap works:
+  switch the source, upload the icon for the old source language, delete it before switching back.
+- **Name / description:** `PATCH /cloud/v2/universes/{u}/places/{rootPlace}` with `universe.place:write`
+  changes the public name and description.
+- **Automatic translation:** Roblox auto-translates a new description into every supported language
+  within seconds. Restoring the source description to *empty* does **not** clear those translations;
+  they have to be blanked per language with `PATCH .../name-description/games/{u}`. Any name or
+  description change must check the translations after restoring.
+- **Sales:** passes and products PATCH + read-back work; 28 items took about 33 s each way.
+- **Events:** creation works on a private game.