@twistedsignal/raven 0.2.1

package/dist/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import pc from "picocolors";
+import { createRequire } from "node:module";
+import { assetCommand } from "./commands/asset.js";
+import { authCommand } from "./commands/auth.js";
+import { datastoreCommand } from "./commands/datastore.js";
+import { productCommand } from "./commands/product.js";
+import { publishCommand } from "./commands/publish.js";
+import { serverCommand } from "./commands/server.js";
+import { updateCommand } from "./commands/update.js";
+import { CliError, enabledFeatures, setApiKeyOverride } from "./lib/config.js";
+import { examples } from "./lib/help.js";
+import { setJsonMode } from "./lib/output.js";
+import { featuresFor } from "./lib/permissions.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+const program = new Command("raven")
+    .description("A CLI for the Roblox Open Cloud API.")
+    .version(version, "-v, --version")
+    .option("--api-key <key>", "use this API key instead of the saved one")
+    .option("--json", "output raw JSON")
+    .showHelpAfterError()
+    .addHelpText("before", `${pc.bold("Raven")} ${pc.dim(`v${version}`)}\n`)
+    .addHelpText("after", `
+Getting started:
+  Run ${pc.cyan("raven auth")} to log in, then ${pc.cyan("raven <command> -h")} for help with a command.
+${examples(["raven asset upload --path sword.fbx --creator user:123"], ["raven product add -t gamepass -u 123 --name VIP --price 100"], ["raven publish --path game.rbxlx --universe 123 --place 456"], ["raven ds get -u 123 -d Players -k user_1"], ["raven server restart --universe 123"])}
+
+Environment:
+  RAVEN_API_KEY       API key to use instead of the saved one
+  RAVEN_UNIVERSE_ID   default for --universe
+  RAVEN_PLACE_ID      default for --place
+  RAVEN_CREATOR       default for --creator
+
+Docs: ${pc.underline("https://github.com/twistedsignal/raven")}`)
+    .hook("preAction", async (cmd, actionCommand) => {
+    const opts = cmd.optsWithGlobals();
+    setApiKeyOverride(opts.apiKey);
+    setJsonMode(Boolean(opts.json));
+    await assertEnabled(actionCommand);
+});
+program.addCommand(authCommand());
+program.addCommand(assetCommand());
+program.addCommand(productCommand());
+program.addCommand(publishCommand());
+program.addCommand(datastoreCommand());
+program.addCommand(serverCommand());
+program.addCommand(updateCommand(version));
+/** "datastore get" for `raven datastore get`. */
+function commandPath(cmd) {
+    const names = [];
+    for (let c = cmd; c && c !== program; c = c.parent)
+        names.unshift(c.name());
+    return names.join(" ");
+}
+/** Blocks commands that weren't enabled during `raven auth`. */
+async function assertEnabled(cmd) {
+    const path = commandPath(cmd);
+    if (path === "auth" || path.startsWith("auth "))
+        return;
+    const enabled = await enabledFeatures();
+    if (!enabled)
+        return;
+    const type = cmd.opts().type;
+    const features = featuresFor(path, path.startsWith("product") ? type : undefined);
+    if (features.length && !features.some((f) => enabled.includes(f.id))) {
+        const name = `raven ${path}${path.startsWith("product") && type ? ` --type ${type}` : ""}`;
+        throw new CliError(`\`${name}\` is disabled. Run \`raven auth commands\` to enable it.`);
+    }
+}
+/** Marks commands that aren't enabled for the saved key in the help output. */
+function annotateDisabled(cmd, enabled) {
+    for (const sub of cmd.commands) {
+        const path = commandPath(sub);
+        if (path === "auth" || path === "help")
+            continue;
+        const features = featuresFor(path);
+        const on = features.filter((f) => enabled.includes(f.id));
+        if (features.length && !on.length) {
+            sub.description(`${sub.description()} ${pc.dim("(disabled)")}`);
+        }
+        else if (on.length < features.length && on.every((f) => f.productType)) {
+            sub.description(`${sub.description()} ${pc.dim(`(${on.map((f) => f.productType).join(", ")} only)`)}`);
+        }
+        annotateDisabled(sub, enabled);
+    }
+}
+const usingOverride = process.env.RAVEN_API_KEY || process.argv.some((a) => a === "--api-key" || a.startsWith("--api-key="));
+const enabled = usingOverride ? undefined : await enabledFeatures();
+if (enabled)
+    annotateDisabled(program, enabled);
+try {
+    await program.parseAsync();
+}
+catch (err) {
+    if (err instanceof CommanderError)
+        process.exit(err.exitCode);
+    if (err instanceof Error && err.name === "ExitPromptError") {
+        console.error(pc.dim("\nCancelled."));
+        process.exit(130);
+    }
+    if (err instanceof CliError) {
+        console.error(`${pc.red("✖")} ${err.message}`);
+        process.exit(1);
+    }
+    throw err;
+}

package/dist/lib/api.js

@@ -0,0 +1,83 @@
+import { CliError, resolveApiKey } from "./config.js";
+export const BASE_URL = process.env.RAVEN_API_BASE_URL || "https://apis.roblox.com";
+export class ApiError extends CliError {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+const MAX_RETRIES = 3;
+export async function request(method, path, opts = {}) {
+    const url = new URL(path, BASE_URL);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined)
+            url.searchParams.set(k, String(v));
+    }
+    const headers = { ...opts.headers };
+    if (!opts.noAuth)
+        headers["x-api-key"] = opts.apiKey ?? (await resolveApiKey());
+    let body = opts.body;
+    if (opts.json !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(opts.json);
+    }
+    for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+            res = await fetch(url, { method, headers, body });
+        }
+        catch (err) {
+            throw new CliError(`Network error contacting ${url.host}: ${err.message}`);
+        }
+        if ((res.status === 429 || res.status >= 500) && attempt < MAX_RETRIES) {
+            const retryAfter = Number(res.headers.get("retry-after"));
+            const delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** attempt;
+            await sleep(delay);
+            continue;
+        }
+        const text = await res.text();
+        let data = text;
+        if (text && res.headers.get("content-type")?.includes("json")) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                // leave as text
+            }
+        }
+        if (!res.ok)
+            throw new ApiError(res.status, formatError(res.status, data), data);
+        return (text ? data : undefined);
+    }
+}
+function formatError(status, data) {
+    let detail = "";
+    if (data && typeof data === "object") {
+        const d = data;
+        detail =
+            d.message ??
+                d.errorMessage ??
+                d.errors?.[0]?.message ??
+                d.error?.message ??
+                (typeof d.error === "string" ? d.error : "") ??
+                "";
+        const code = typeof d.code === "string" ? d.code : d.errorCode;
+        if (code && typeof code === "string" && detail)
+            detail = `${code}: ${detail}`;
+    }
+    else if (typeof data === "string") {
+        detail = data.trim().slice(0, 300);
+    }
+    const hint = status === 401
+        ? " (is your API key valid? run `raven auth`)"
+        : status === 403
+            ? " (does your API key have the required permission and access to this resource?)"
+            : "";
+    return `Request failed with ${status}${detail ? `: ${detail}` : ""}${hint}`;
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/lib/args.js

@@ -0,0 +1,35 @@
+import { InvalidArgumentError, Option } from "commander";
+export function parseId(value) {
+    if (!/^\d+$/.test(value))
+        throw new InvalidArgumentError("Expected a numeric ID.");
+    return value;
+}
+export function parsePositiveInt(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new InvalidArgumentError("Expected a positive integer.");
+    return n;
+}
+export function parseNumber(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new InvalidArgumentError("Expected a number.");
+    return n;
+}
+/** Accepts `user:123`, `group:456`, or a bare ID (treated as a user). */
+export function parseCreator(value) {
+    const match = /^(?:(user|group):)?(\d+)$/i.exec(value.trim());
+    if (!match)
+        throw new InvalidArgumentError("Expected `user:<id>`, `group:<id>`, or a user ID.");
+    const [, kind, id] = match;
+    return kind?.toLowerCase() === "group" ? { groupId: id } : { userId: id };
+}
+export function universeOption() {
+    return new Option("-u, --universe <id>", "universe (experience) ID")
+        .env("RAVEN_UNIVERSE_ID")
+        .argParser(parseId)
+        .makeOptionMandatory();
+}
+export function placeOption() {
+    return new Option("-p, --place <id>", "place ID").env("RAVEN_PLACE_ID").argParser(parseId).makeOptionMandatory();
+}

package/dist/lib/browser.js

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+/** Best-effort attempt to open a URL in the user's default browser. */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", '""', url]]
+            : ["xdg-open", [url]];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+            child.on("error", () => resolve(false));
+            child.on("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/lib/config.js

@@ -0,0 +1,65 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { FEATURE_IDS } from "./permissions.js";
+export function configDir() {
+    if (process.env.RAVEN_CONFIG_DIR)
+        return process.env.RAVEN_CONFIG_DIR;
+    if (process.platform === "win32" && process.env.APPDATA) {
+        return join(process.env.APPDATA, "raven");
+    }
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "raven");
+}
+export function credentialsPath() {
+    return join(configDir(), "credentials.json");
+}
+export async function loadCredentials() {
+    try {
+        const raw = await readFile(credentialsPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.apiKey ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function saveCredentials(creds) {
+    await mkdir(configDir(), { recursive: true, mode: 0o700 });
+    const path = credentialsPath();
+    await writeFile(path, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+    // writeFile only applies mode on creation, so enforce it on overwrite too.
+    await chmod(path, 0o600).catch(() => { });
+}
+export async function clearCredentials() {
+    const existing = await loadCredentials();
+    await rm(credentialsPath(), { force: true });
+    return existing !== undefined;
+}
+let overrideKey;
+export function setApiKeyOverride(key) {
+    overrideKey = key;
+}
+/** Resolves the API key from --api-key, RAVEN_API_KEY, or the saved credentials. */
+export async function resolveApiKey() {
+    if (overrideKey)
+        return overrideKey;
+    if (process.env.RAVEN_API_KEY)
+        return process.env.RAVEN_API_KEY;
+    const creds = await loadCredentials();
+    if (creds)
+        return creds.apiKey;
+    throw new CliError("You are not logged in. Run `raven auth` to log in, or set RAVEN_API_KEY.");
+}
+/**
+ * The features enabled for the saved key, or undefined if every command is allowed
+ * (a key passed via --api-key / RAVEN_API_KEY, or a login from before features existed).
+ */
+export async function enabledFeatures() {
+    if (overrideKey || process.env.RAVEN_API_KEY)
+        return undefined;
+    const features = (await loadCredentials())?.features;
+    return features?.filter((f) => FEATURE_IDS.includes(f));
+}
+export class CliError extends Error {
+}

package/dist/lib/help.js

@@ -0,0 +1,6 @@
+import pc from "picocolors";
+/** Formats an "Examples:" block for addHelpText. Comments are printed above their command. */
+export function examples(...lines) {
+    const body = lines.map(([c, comment]) => `${comment ? `  ${pc.dim(`# ${comment}`)}\n` : ""}  $ ${c}`);
+    return `\nExamples:\n${body.join("\n")}`;
+}

package/dist/lib/output.js

@@ -0,0 +1,55 @@
+import pc from "picocolors";
+let jsonMode = false;
+export function setJsonMode(value) {
+    jsonMode = value;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+/** Prints raw JSON in --json mode, otherwise runs the human-readable printer. */
+export function output(data, human) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else {
+        human();
+    }
+}
+export function success(msg) {
+    if (!jsonMode)
+        console.log(`${pc.green("✔")} ${msg}`);
+}
+export function info(msg) {
+    if (!jsonMode)
+        console.log(msg);
+}
+export function warn(msg) {
+    console.error(`${pc.yellow("!")} ${msg}`);
+}
+export function field(label, value) {
+    if (value === undefined || value === null || value === "")
+        return;
+    console.log(`  ${pc.dim(label.padEnd(14))} ${value}`);
+}
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Shows a spinner on stderr while `fn` runs. Silent in --json mode or when stderr isn't a TTY. */
+export async function withSpinner(text, fn) {
+    const spinner = { text };
+    const stream = process.stderr;
+    if (jsonMode || !stream.isTTY)
+        return fn(spinner);
+    let frame = 0;
+    const render = () => {
+        stream.write(`\r\x1b[2K${pc.cyan(FRAMES[frame++ % FRAMES.length])} ${spinner.text}`);
+    };
+    stream.write("\x1b[?25l");
+    render();
+    const timer = setInterval(render, 80);
+    try {
+        return await fn(spinner);
+    }
+    finally {
+        clearInterval(timer);
+        stream.write("\r\x1b[2K\x1b[?25h");
+    }
+}

package/dist/lib/permissions.js

@@ -0,0 +1,157 @@
+import pc from "picocolors";
+/** The features you can pick during `raven auth`, and the Open Cloud permissions each one needs. */
+export const FEATURES = [
+    {
+        id: "asset",
+        name: "Assets: upload, update, and roll back",
+        commands: ["asset"],
+        scopes: [["assets", ["Read", "Write"]]],
+    },
+    {
+        id: "gamepass",
+        name: "Game passes",
+        commands: ["product"],
+        productType: "gamepass",
+        scopes: [["game-pass", ["Read", "Write"]]],
+    },
+    {
+        id: "devProduct",
+        name: "Developer products",
+        commands: ["product"],
+        productType: "devProduct",
+        scopes: [["developer-product", ["Read", "Write"]]],
+    },
+    {
+        id: "publish",
+        name: "Publish places",
+        commands: ["publish"],
+        scopes: [["universe-places", ["Write"]]],
+    },
+    {
+        id: "datastore-read",
+        name: "Data stores: list and read",
+        commands: ["datastore list", "datastore get"],
+        scopes: [
+            ["universe-datastores.control", ["List"]],
+            ["universe-datastores.objects", ["List", "Read"]],
+        ],
+    },
+    {
+        id: "datastore-write",
+        name: "Data stores: set and increment",
+        commands: ["datastore set", "datastore increment"],
+        scopes: [["universe-datastores.objects", ["Create", "Update"]]],
+    },
+    {
+        id: "datastore-delete",
+        name: "Data stores: delete",
+        commands: ["datastore delete"],
+        scopes: [["universe-datastores.objects", ["Delete"]]],
+    },
+    {
+        id: "server-restart",
+        name: "Restart servers",
+        commands: ["server restart"],
+        scopes: [["universe", ["Write"]]],
+    },
+    {
+        id: "server-message",
+        name: "Message servers (MessagingService)",
+        commands: ["server message"],
+        scopes: [["universe-messaging-service", ["Publish"]]],
+    },
+];
+export const FEATURE_IDS = FEATURES.map((f) => f.id);
+/** Human-readable command names for a feature, e.g. "datastore list, datastore get". */
+export function featureCommands(f) {
+    return f.productType ? `product --type ${f.productType}` : f.commands.join(", ");
+}
+function covers(featurePath, path) {
+    return path === featurePath || path.startsWith(`${featurePath} `);
+}
+/** Features that unlock the given command path. `productType` narrows `product` commands. */
+export function featuresFor(path, productType) {
+    return FEATURES.filter((f) => f.commands.some((c) => covers(c, path) || covers(path, c)) &&
+        (!productType || !f.productType || f.productType === productType));
+}
+/** Merges the scopes of several features into one list per API system. */
+function mergeScopes(features) {
+    const ORDER = ["List", "Read", "Create", "Update", "Delete", "Write", "Publish"];
+    const merged = new Map();
+    for (const f of features) {
+        for (const [api, ops] of f.scopes) {
+            if (!merged.has(api))
+                merged.set(api, new Set());
+            for (const op of ops)
+                merged.get(api).add(op);
+        }
+    }
+    return [...merged].map(([api, ops]) => [api, [...ops].sort((a, b) => ORDER.indexOf(a) - ORDER.indexOf(b))]);
+}
+/** Prints the permissions to add to the API key for the selected features. */
+export function printPermissionTable(features) {
+    const rows = mergeScopes(features);
+    const width = Math.max(...rows.map(([api]) => api.length)) + 4;
+    console.log(`  ${pc.dim("API system".padEnd(width))}${pc.dim("Operations")}`);
+    for (const [api, ops] of rows)
+        console.log(`  ${pc.bold(api.padEnd(width))}${ops.join(", ")}`);
+}
+/**
+ * Builds a map of API system -> granted operations. Tolerates both
+ * `{ name: "assets", operations: ["read"] }` and `"assets:read"` style values.
+ */
+function grantedMap(granted) {
+    const map = new Map();
+    const add = (api, op) => {
+        const key = api.toLowerCase();
+        if (!map.has(key))
+            map.set(key, new Set());
+        if (op)
+            map.get(key).add(op.toLowerCase());
+    };
+    for (const scope of granted) {
+        const [api, op] = scope.name.split(":");
+        add(api, op);
+        for (const operation of scope.operations ?? [])
+            add(api, operation.split(":").pop());
+    }
+    return map;
+}
+/** Scope names that differ from the API system name shown on the Creator Dashboard. */
+const SCOPE_NAMES = { assets: "asset" };
+/** Returns the permissions a feature needs that the key doesn't have. */
+function missingFor(feature, granted) {
+    const missing = [];
+    for (const [api, ops] of feature.scopes) {
+        const have = granted.get(SCOPE_NAMES[api] ?? api) ?? granted.get(api);
+        const lacking = have ? ops.filter((o) => !have.has(o.toLowerCase())) : ops;
+        if (lacking.length)
+            missing.push(`${api}: ${lacking.join(", ")}`);
+    }
+    return missing;
+}
+/**
+ * Prints the enabled commands, flagging any whose permissions the key appears to be missing.
+ * Returns true if every enabled feature looks fully permitted (or scopes are unknown).
+ */
+export function printEnabledCommands(enabled, granted) {
+    const map = granted?.length ? grantedMap(granted) : undefined;
+    let ok = true;
+    console.log(pc.dim("Enabled commands:"));
+    for (const f of FEATURES) {
+        const label = featureCommands(f);
+        if (!enabled.includes(f.id)) {
+            console.log(`  ${pc.dim(`- ${label} (disabled)`)}`);
+            continue;
+        }
+        const missing = map ? missingFor(f, map) : [];
+        if (missing.length) {
+            ok = false;
+            console.log(`  ${pc.yellow("!")} ${label}  ${pc.yellow(`key is missing ${missing.join("; ")}`)}`);
+        }
+        else {
+            console.log(`  ${pc.green("✔")} ${label}`);
+        }
+    }
+    return ok;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@twistedsignal/raven",
+  "version": "0.2.1",
+  "description": "A CLI for the Roblox Open Cloud API",
+  "license": "MIT",
+  "author": "Twisted Signal",
+  "type": "module",
+  "bin": {
+    "raven": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "roblox",
+    "opencloud",
+    "open-cloud",
+    "cli",
+    "datastore",
+    "assets"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/twistedsignal/raven.git"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.2",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2"
+  },
+  "packageManager": "pnpm@11.28.2"
+}