@twistedsignal/raven 0.2.1 → 0.3.0

package/README.md

@@ -7,16 +7,14 @@ A CLI for the [Roblox Open Cloud API](https://create.roblox.com/docs/cloud). Upl
 Requires Node.js 20 or newer.
 
 ```bash
-npm install -g https://github.com/twistedsignal/raven/archive/refs/heads/main.tar.gz
+npm install -g @twistedsignal/raven
 ```
 
-> `npm install -g github:twistedsignal/raven` currently leaves a broken install on npm 11 (npm links the package to a temporary clone and then deletes it), so use the tarball URL above.
-
-To update, run:
+To update to the latest published version, run:
 
 ```bash
-raven update          # install the latest version
-raven update --check  # just check whether there's a new one
+raven update
+raven update --check  # check without installing
 ```
 
 Or from source:
@@ -28,7 +26,7 @@ pnpm install && pnpm build
 npm link
 ```
 
-The compiled `dist/` is committed so installing from GitHub doesn't need a build step. If you change anything in `src/`, run `pnpm build` and commit `dist/` with it; CI fails if it's out of date.
+If you change anything in `src/`, run `pnpm build` and commit `dist/` with it; CI fails if it's out of date.
 
 ## Logging in
 

package/dist/commands/asset.js

@@ -2,6 +2,7 @@ import { Command, InvalidArgumentError, Option } from "commander";
 import pc from "picocolors";
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
+import { downloadAsset } from "../lib/download.js";
 import { request, sleep } from "../lib/api.js";
 import { parseCreator, parseId, parsePositiveInt } from "../lib/args.js";
 import { CliError } from "../lib/config.js";
@@ -75,7 +76,16 @@ function printAsset(asset) {
         field("URL", pc.underline(`https://create.roblox.com/store/asset/${asset.assetId}`));
 }
 export function assetCommand() {
-    const asset = new Command("asset").description("upload, update, and roll back assets").addHelpText("after", examples(["raven asset upload --path sword.fbx --creator user:123", "type is inferred from the extension"], ["raven asset upload --path logo.png --type Decal --name Logo --creator group:456"], ["raven asset update --id 987 --path sword_v2.fbx", "upload a new version"], ["raven asset rollback --id 987 --to 3"], ["raven asset versions --id 987"]));
+    const asset = new Command("asset").description("download, upload, update, and roll back assets").addHelpText("after", examples(["raven asset upload --path sword.fbx --creator user:123", "type is inferred from the extension"], ["raven asset upload --path logo.png --type Decal --name Logo --creator group:456"], ["raven asset update --id 987 --path sword_v2.fbx", "upload a new version"], ["raven asset rollback --id 987 --to 3"], ["raven asset versions --id 987"]));
+    asset
+        .command("download")
+        .description("download asset content using Legacy Assets Manage permission")
+        .requiredOption("--id <id>", "asset ID", parseId)
+        .requiredOption("--output <file>", "destination file")
+        .action(async (opts) => {
+        const result = await withSpinner("Downloading asset…", () => downloadAsset(opts.id, opts.output));
+        output(result, () => success(`Downloaded ${result.assetId} to ${result.path} (${result.bytes} bytes)`));
+    });
     asset
         .command("upload")
         .description("upload a new asset")

package/dist/commands/auth.js

@@ -1,4 +1,4 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { checkbox, password } from "@inquirer/prompts";
 import pc from "picocolors";
 import { createInterface } from "node:readline/promises";
@@ -145,6 +145,23 @@ In CI, set RAVEN_API_KEY instead of running \`raven auth\`. All commands are
 enabled when using RAVEN_API_KEY or --api-key.`)
         .action(login);
     auth.command("commands").description("choose which commands are enabled").action(changeCommands);
+    auth
+        .command("enable")
+        .description("enable one command feature without opening a prompt")
+        .addOption(new Option("--feature <feature>", "feature to enable").choices(FEATURE_IDS).makeOptionMandatory())
+        .action(async (opts) => {
+        if (process.env.RAVEN_API_KEY) {
+            output({ enabled: opts.feature }, () => success("Environment keys already enable every command."));
+            return;
+        }
+        const creds = await loadCredentials();
+        if (!creds)
+            throw new CliError("No saved key. Run `raven auth` or set RAVEN_API_KEY.");
+        const features = creds.features ?? FEATURE_IDS;
+        if (!features.includes(opts.feature))
+            await saveCredentials({ ...creds, features: [...features, opts.feature] });
+        output({ enabled: opts.feature }, () => success(`Enabled ${opts.feature}. The key still needs its API permissions.`));
+    });
     auth
         .command("status")
         .description("show the saved API key and enabled commands")

package/dist/commands/update.js

@@ -7,19 +7,18 @@ import { fileURLToPath } from "node:url";
 import { CliError } from "../lib/config.js";
 import { examples } from "../lib/help.js";
 import { info, success, withSpinner } from "../lib/output.js";
-const REPO = "twistedsignal/raven";
-const PACKAGE_JSON_URL = `https://raw.githubusercontent.com/${REPO}/main/package.json`;
-const TARBALL_URL = `https://github.com/${REPO}/archive/refs/heads/main.tar.gz`;
+const PACKAGE = "@twistedsignal/raven";
+const LATEST_URL = "https://registry.npmjs.org/@twistedsignal%2Fraven/latest";
 async function latestVersion() {
     let res;
     try {
-        res = await fetch(PACKAGE_JSON_URL, { headers: { "cache-control": "no-cache" } });
+        res = await fetch(LATEST_URL, { headers: { "cache-control": "no-cache" } });
     }
     catch (err) {
-        throw new CliError(`Couldn't reach GitHub: ${err.message}`);
+        throw new CliError(`Couldn't reach npm: ${err.message}`);
     }
     if (!res.ok)
-        throw new CliError(`Couldn't check for updates (GitHub returned ${res.status}).`);
+        throw new CliError(`Couldn't check for updates (npm returned ${res.status}).`);
     return (await res.json()).version;
 }
 /** Returns >0 if a is newer than b. */
@@ -39,11 +38,12 @@ function installRoot() {
 }
 /** Picks the install command matching the package manager Raven was installed with. */
 function installCommand(root) {
+    const latest = `${PACKAGE}@latest`;
     if (/[\\/]\.?pnpm[\\/]/.test(root))
-        return ["pnpm", ["add", "-g", TARBALL_URL]];
+        return ["pnpm", ["add", "-g", latest]];
     if (/[\\/]\.bun[\\/]/.test(root))
-        return ["bun", ["add", "-g", TARBALL_URL]];
-    return ["npm", ["install", "-g", TARBALL_URL]];
+        return ["bun", ["add", "-g", latest]];
+    return ["npm", ["install", "-g", latest]];
 }
 function run(cmd, args) {
     return new Promise((resolve, reject) => {

package/dist/lib/api.js

@@ -27,7 +27,7 @@ export async function request(method, path, opts = {}) {
     for (let attempt = 0;; attempt++) {
         let res;
         try {
-            res = await fetch(url, { method, headers, body });
+            res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(opts.timeout ?? 30_000), redirect: opts.noRedirect ? "error" : "follow" });
         }
         catch (err) {
             throw new CliError(`Network error contacting ${url.host}: ${err.message}`);
@@ -35,7 +35,8 @@ export async function request(method, path, opts = {}) {
         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);
+            await res.body?.cancel();
+            await sleep(Math.min(delay, 10_000));
             continue;
         }
         const text = await res.text();

package/dist/lib/download.js

@@ -0,0 +1,86 @@
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CliError } from "./config.js";
+import { ApiError, request, sleep } from "./api.js";
+const MAX_BYTES = 128 * 1024 * 1024;
+const TIMEOUT = 30_000;
+/** Download CDN bytes separately: the API key must never accompany this request. */
+export async function fetchBytes(location) {
+    const url = new URL(location);
+    if (url.protocol !== "https:" && !(process.env.RAVEN_API_BASE_URL && url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
+        throw new CliError("Asset delivery returned an insecure download URL.");
+    }
+    for (let attempt = 0;; attempt++) {
+        let response;
+        try {
+            response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT) });
+        }
+        catch {
+            throw new CliError(`Could not download asset from ${url.host}; the request failed or timed out.`);
+        }
+        if ((response.status === 429 || response.status >= 500) && attempt < 3) {
+            await response.body?.cancel();
+            const retryAfter = Number(response.headers.get("retry-after"));
+            await sleep(Math.min(10_000, retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** attempt));
+            continue;
+        }
+        if (!response.ok)
+            throw new CliError(`Asset download returned HTTP ${response.status}.`);
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new CliError("Asset download was empty.");
+        const chunks = [];
+        let length = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                length += value.byteLength;
+                if (length > MAX_BYTES)
+                    throw new CliError("Asset exceeds the 128 MB download limit.");
+                chunks.push(value);
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => { });
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError("Asset download was interrupted or timed out.");
+        }
+        if (!length)
+            throw new CliError("Asset download was empty.");
+        return Buffer.concat(chunks, length);
+    }
+}
+export async function downloadAsset(assetId, outputPath) {
+    let delivery;
+    try {
+        delivery = await request("GET", `/asset-delivery-api/v1/assetId/${assetId}`, { timeout: TIMEOUT, noRedirect: true });
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 403) {
+            throw new CliError("Asset delivery denied access. Add Legacy Assets > Manage (legacy-asset:manage) to your key, and check access to this asset.");
+        }
+        throw error;
+    }
+    const location = delivery?.location ?? delivery?.locations?.[0]?.location;
+    if (typeof location !== "string")
+        throw new CliError("Asset delivery did not return a download location.");
+    const bytes = await fetchBytes(location);
+    const path = resolve(outputPath);
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, bytes, { flag: "wx" });
+        await rename(temporary, path);
+    }
+    catch {
+        throw new CliError(`Could not write asset to ${path}.`);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return { assetId, path, bytes: bytes.byteLength };
+}

package/dist/lib/permissions.js

@@ -4,9 +4,15 @@ export const FEATURES = [
     {
         id: "asset",
         name: "Assets: upload, update, and roll back",
-        commands: ["asset"],
+        commands: ["asset upload", "asset update", "asset rollback", "asset get", "asset versions"],
         scopes: [["assets", ["Read", "Write"]]],
     },
+    {
+        id: "asset-download",
+        name: "Assets: download content",
+        commands: ["asset download"],
+        scopes: [["legacy-asset", ["Manage"]]],
+    },
     {
         id: "gamepass",
         name: "Game passes",
@@ -76,7 +82,7 @@ export function featuresFor(path, 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 ORDER = ["List", "Read", "Create", "Update", "Delete", "Write", "Publish", "Manage"];
     const merged = new Map();
     for (const f of features) {
         for (const [api, ops] of f.scopes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twistedsignal/raven",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A CLI for the Roblox Open Cloud API",
   "license": "MIT",
   "author": "Twisted Signal",