@raster-app/cli 0.3.2 → 0.4.0

package/README.md

@@ -22,7 +22,7 @@ npx -p @raster-app/cli raster whoami
 raster auth login
 ```
 
-`raster auth login` signs you in over OAuth (no API key needed). When a browser is available — an interactive session with a display — it opens a **browser authorization-code flow** with a local loopback redirect; otherwise, over SSH or on a headless machine, it falls back to the **device authorization grant**, printing a short code and a URL you approve in a browser on any device. Pass `--browser` or `--device` to force either.
+`raster auth login` signs you in over OAuth (no API key needed). When a browser is available, it opens a **browser authorization-code flow** with a local loopback redirect; otherwise, over SSH or on a headless machine, it falls back to the **device authorization grant**, printing a short code and a URL you approve in a browser on any device. Pass `--browser` or `--device` to force either.
 
 OAuth tokens (access + refresh) are stored in `~/.config/raster/config.json` with owner-only permissions. The CLI refreshes the access token automatically before it expires and rotates the refresh token; when the saved login can no longer be refreshed, it asks you to run `raster auth login` again.
 
@@ -90,13 +90,14 @@ Show the organizations, plan, and libraries the current credential can access. A
 | Command | Description | Example |
 | --- | --- | --- |
 | `raster assets ls` | List assets; filter with `--tag` (up to 5), page with `--page`/`--page-size`. | `raster assets ls --library brand --tag sunset` |
-| `raster assets get <assetId>` | Show one asset's metadata. | `raster assets get asset_123` |
+| `raster assets get <assetId>` | Show one asset's metadata — including its variants, and duration plus stream details for video. | `raster assets get asset_123` |
 | `raster assets search <query>` | Search across the organization (`--library` scopes to one). | `raster assets search "golden hour"` |
 | `raster assets download <assetId>` | Download the file (`-o` path, `--force` to overwrite). | `raster assets download asset_123 -o photo.png` |
-| `raster assets upload <files...>` | Upload local files (batched at 20 per request). | `raster assets upload ./photos/*.png` |
+| `raster assets upload <files...>` | Upload local files (batched at 20 per request). Pass `--parent <assetId>` to attach a single image as a variant of an existing asset. | `raster assets upload ./photos/*.png` |
 | `raster assets rm <assetIds...>` | Move assets to trash (`--yes` skips the prompt). | `raster assets rm asset_123 asset_456` |
 | `raster assets describe <assetId> --text <text>` | Set an asset's description. | `raster assets describe asset_123 --text "Hero shot"` |
 | `raster assets transfer <assetIds...> --to <libraryId>` | Move assets to another library. | `raster assets transfer asset_123 --to archive` |
+| `raster assets promote <assetId> --variant <variantId>` | Make a variant the asset's default — the pixels change at the same URL, and the old default is kept as a variant. | `raster assets promote asset_123 --variant asset_456` |
 
 ### `tags`
 

package/dist/index.js

@@ -16337,11 +16337,11 @@ config(en_default());
 // package.json
 var package_default = {
   name: "@raster-app/cli",
-  version: "0.3.2",
+  version: "0.4.0",
   description: "Command-line client for the Raster API",
   license: "Apache-2.0",
   type: "module",
-  homepage: "https://docs.raster.app/api/cli",
+  homepage: "https://raster.app/docs/api/cli",
   engines: {
     node: ">=20"
   },
@@ -16372,7 +16372,7 @@ var package_default = {
 };
 
 // src/api/version.ts
-var API_VERSION = "2026-05-20";
+var API_VERSION = "2026-07-08";
 var DEFAULT_BASE_URL = "https://api.raster.app";
 
 // src/commands/assets.ts
@@ -16981,6 +16981,10 @@ import { join } from "node:path";
 var MAX_UPLOAD_FILES = 20;
 var MAX_TAGS_PER_QUERY = 5;
 var MAX_DELETE_IDS = 100;
+var MAX_TRANSFER_IDS = 100;
+var MAX_TAG_IDS = 100;
+var MAX_TAGS_PER_CALL = 20;
+var MAX_DESCRIPTION_LENGTH = 2000;
 var VISIBLE_KEY_PREFIX_LENGTH = 6;
 function maskApiKey(key) {
   return `${key.slice(0, VISIBLE_KEY_PREFIX_LENGTH)}…`;
@@ -16998,15 +17002,25 @@ function isErrnoException(error51) {
 var CONTENT_TYPES_BY_EXTENSION = {
   avif: "image/avif",
   bmp: "image/bmp",
+  fig: "application/x-figma",
   gif: "image/gif",
   heic: "image/heic",
+  heif: "image/heif",
+  ico: "image/x-icon",
   jpeg: "image/jpeg",
   jpg: "image/jpeg",
   png: "image/png",
   svg: "image/svg+xml",
   tif: "image/tiff",
   tiff: "image/tiff",
-  webp: "image/webp"
+  webp: "image/webp",
+  avi: "video/x-msvideo",
+  m4v: "video/mp4",
+  mov: "video/quicktime",
+  mp4: "video/mp4",
+  mpeg: "video/mpeg",
+  mpg: "video/mpeg",
+  wmv: "video/x-ms-wmv"
 };
 var FALLBACK_CONTENT_TYPE = "application/octet-stream";
 function contentTypeForFilename(filename) {
@@ -17560,14 +17574,21 @@ async function createCommandContext(globals, overrides = {}) {
   };
   const baseUrl = validateBaseUrl(env.RASTER_API_BASE_URL ?? DEFAULT_BASE_URL);
   const baseFetch = overrides.fetch ?? globalThis.fetch;
-  const credential = await resolveActiveCredential({
+  const { credential, sessionExpired } = await resolveActiveCredential({
     flagKey: globals.apiKey,
     env,
     config: config2,
     fetch: instrumentFetch(baseFetch, output, null),
     now: now()
   });
+  if (sessionExpired) {
+    note(output, "Your saved login could not be refreshed and has been cleared.");
+    if (config2.apiKey) {
+      note(output, "The API key stored in config is not used automatically. Pass --api-key, or set RASTER_API_KEY, to use it.");
+    }
+  }
   const apiKey = credential?.kind === "apiKey" ? { key: credential.key, source: credential.source } : null;
+  const notAuthenticated = () => new AuthSetupError(authErrorMessage(sessionExpired));
   const bearer = credentialBearer(credential);
   const instrumentedFetch = instrumentFetch(baseFetch, output, bearer ? maskApiKey(bearer) : null);
   const clientFactory = (clientOverrides) => createApiClient({
@@ -17578,9 +17599,8 @@ async function createCommandContext(globals, overrides = {}) {
   let viewerPromise = null;
   const loadViewer = () => {
     if (!viewerPromise) {
-      if (!credential) {
-        throw new AuthSetupError("Not authenticated. Run `raster auth login` or set RASTER_API_KEY.");
-      }
+      if (!credential)
+        throw notAuthenticated();
       viewerPromise = unwrapResult(() => clientFactory().GET("/me", { params: { header: VERSION_HEADER } }));
     }
     return viewerPromise;
@@ -17629,6 +17649,7 @@ async function createCommandContext(globals, overrides = {}) {
     isInteractive: overrides.isInteractive ?? process.stdin.isTTY === true,
     credential,
     apiKey,
+    sessionExpired,
     bearerToken: bearer,
     fetch: instrumentedFetch,
     clientFactory,
@@ -17663,7 +17684,7 @@ function credentialBearer(credential) {
 async function resolveActiveCredential(options) {
   const credential = resolveCredential({ flagKey: options.flagKey, env: options.env, config: options.config });
   if (credential?.kind !== "oauth")
-    return credential;
+    return { credential, sessionExpired: false };
   const session = await ensureFreshOAuthSession({
     tokens: credential.tokens,
     env: options.env,
@@ -17672,13 +17693,9 @@ async function resolveActiveCredential(options) {
     now: options.now
   });
   if (session.status === "reauth-required") {
-    return resolveCredential({
-      flagKey: options.flagKey,
-      env: options.env,
-      config: { ...options.config, oauth: undefined }
-    });
+    return { credential: null, sessionExpired: true };
   }
-  return { kind: "oauth", tokens: session.tokens };
+  return { credential: { kind: "oauth", tokens: session.tokens }, sessionExpired: false };
 }
 function instrumentFetch(baseFetch, output, maskedKey) {
   return async (input, init) => {
@@ -17696,15 +17713,18 @@ function instrumentFetch(baseFetch, output, maskedKey) {
     }
   };
 }
+function authErrorMessage(sessionExpired) {
+  return sessionExpired ? "Your saved login expired. Run `raster auth login` to sign in again." : "Not authenticated. Run `raster auth login` or set RASTER_API_KEY.";
+}
 function requireAuth(context) {
   if (context.credential)
     return context.credential;
-  throw new AuthSetupError("Not authenticated. Run `raster auth login` or set RASTER_API_KEY.");
+  throw new AuthSetupError(authErrorMessage(context.sessionExpired));
 }
 function requireBearer(context) {
   if (context.bearerToken)
     return context.bearerToken;
-  throw new AuthSetupError("Not authenticated. Run `raster auth login` or set RASTER_API_KEY.");
+  throw new AuthSetupError(authErrorMessage(context.sessionExpired));
 }
 async function executeCommand(context, action) {
   try {
@@ -17786,7 +17806,10 @@ async function getAssetCommand(context, assetId) {
     printJson(context, asset);
     return;
   }
-  renderRecord(context, [
+  renderRecord(context, assetRecordFields(asset));
+}
+function assetRecordFields(asset) {
+  const fields = [
     { label: "id", value: asset.id },
     { label: "name", value: asset.name ?? "" },
     { label: "type", value: asset.contentType ?? "" },
@@ -17795,7 +17818,39 @@ async function getAssetCommand(context, assetId) {
     { label: "tags", value: (asset.tags ?? []).filter((tag) => tag !== null).join(",") },
     { label: "description", value: asset.description ?? "" },
     { label: "url", value: asset.url ?? "" }
-  ]);
+  ];
+  const push = (label, value) => {
+    if (value)
+      fields.push({ label, value });
+  };
+  push("app url", asset.appUrl);
+  push("duration", formatDuration(asset.duration));
+  push("parent", asset.parentId);
+  const variants = (asset.variants ?? []).filter((variant) => variant !== null);
+  if (variants.length > 0) {
+    fields.push({ label: "variants", value: variants.map((variant) => variant.id).join(",") });
+  }
+  push("approval", asset.approval?.state);
+  const capture = asset.metadata?.capture;
+  push("captured", capture?.recordedAt);
+  push("device", [capture?.make, capture?.model].filter(Boolean).join(" "));
+  const video = asset.metadata?.video;
+  if (video) {
+    push("codec", video.codec);
+    push("frame rate", video.frameRate ? `${video.frameRate} fps` : "");
+    push("audio", video.hasAudio ? [video.audioCodec, video.audioLayout].filter(Boolean).join(" ") || "yes" : "none");
+  }
+  return fields;
+}
+function formatDuration(seconds) {
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0)
+    return "";
+  const whole = Math.round(seconds);
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor(whole % 3600 / 60);
+  const remainder = whole % 60;
+  const padded = (value) => String(value).padStart(2, "0");
+  return hours > 0 ? `${hours}:${padded(minutes)}:${padded(remainder)}` : `${minutes}:${padded(remainder)}`;
 }
 async function fetchAsset(context, assetId) {
   const organizationId = await context.resolveOrg();
@@ -17862,9 +17917,15 @@ async function downloadAssetCommand(context, assetId, options) {
 var uploadedAssetsSchema = exports_external.object({
   assets: exports_external.array(exports_external.looseObject({ id: exports_external.string().optional(), name: exports_external.string().nullish() }))
 });
-async function uploadAssetsCommand(context, files) {
+var uploadOptionsSchema = exports_external.object({
+  parent: exports_external.string().min(1).optional()
+});
+async function uploadAssetsCommand(context, files, options = {}) {
   if (files.length === 0)
     throw new UsageError("Provide at least one file to upload.");
+  if (options.parent && files.length !== 1) {
+    throw new ValidationError("--parent uploads a single file. Pass exactly one path.");
+  }
   const bearer = requireBearer(context);
   const organizationId = await context.resolveOrg();
   const libraryId = await context.resolveLibrary();
@@ -17882,6 +17943,8 @@ async function uploadAssetsCommand(context, files) {
       }
       formData.append("files", new Blob([bytes], { type: contentTypeForFilename(filePath) }), basename(filePath));
     }
+    if (options.parent)
+      formData.append("parentId", options.parent);
     if (batches.length > 1) {
       note(context, `Uploading batch ${batchIndex + 1}/${batches.length} (${batch.length} files)…`);
     }
@@ -17897,7 +17960,11 @@ async function uploadAssetsCommand(context, files) {
     printJson(context, payloads.length === 1 ? payloads[0] : payloads);
     return;
   }
-  note(context, `Uploaded ${uploadedNames.length} asset(s).`);
+  if (options.parent) {
+    note(context, `Uploaded ${uploadedNames.length} variant of ${options.parent}.`);
+  } else {
+    note(context, `Uploaded ${uploadedNames.length} asset(s).`);
+  }
   for (const name of uploadedNames) {
     context.stdout(`${name}
 `);
@@ -17934,7 +18001,7 @@ async function removeAssetsCommand(context, assetIds, options) {
   note(context, `Moved ${assetIds.length} asset(s) to trash.`);
 }
 var describeOptionsSchema = exports_external.object({
-  text: exports_external.string().min(1)
+  text: exports_external.string().min(1).max(MAX_DESCRIPTION_LENGTH)
 });
 async function describeAssetCommand(context, assetId, options) {
   requireAuth(context);
@@ -17960,6 +18027,9 @@ var transferOptionsSchema = exports_external.object({
 async function transferAssetsCommand(context, assetIds, options) {
   if (assetIds.length === 0)
     throw new UsageError("Provide at least one asset id.");
+  if (assetIds.length > MAX_TRANSFER_IDS) {
+    throw new ValidationError(`At most ${MAX_TRANSFER_IDS} asset ids are supported per call.`);
+  }
   requireAuth(context);
   const organizationId = await context.resolveOrg();
   const libraryId = await context.resolveLibrary();
@@ -17974,15 +18044,34 @@ async function transferAssetsCommand(context, assetIds, options) {
   }
   note(context, `Transferred ${assetIds.length} asset(s) to library ${options.to}.`);
 }
+var promoteOptionsSchema = exports_external.object({
+  variant: exports_external.string().min(1)
+});
+async function promoteVariantCommand(context, assetId, options) {
+  requireAuth(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
+  const client = context.clientFactory();
+  const result = await unwrapResult(() => client.POST("/organizations/{organizationId}/libraries/{libraryId}/assets/{assetId}/promote", {
+    params: { path: { organizationId, libraryId, assetId }, header: VERSION_HEADER },
+    body: { variantId: options.variant }
+  }));
+  if (context.json) {
+    printJson(context, result);
+    return;
+  }
+  note(context, `Promoted variant ${result.promotedVariantId}; ${result.demotedVariantId} is kept as a variant. ` + "The swap completes a moment later — re-fetch the asset to see it.");
+}
 function registerAssetCommands(program2, runAction) {
   const assets = program2.command("assets").description("Work with assets in a library");
   assets.command("ls").description("List assets in the library").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").option("--tag <tag...>", "Filter by tag (repeatable, up to 5)").action((options, command) => runAction(command, (context) => listAssetsCommand(context, parseOptions(listOptionsSchema, options))));
   assets.command("get").description("Show a single asset").argument("<assetId>", "Asset id").action((assetId, _options, command) => runAction(command, (context) => getAssetCommand(context, assetId)));
   assets.command("search").description("Search assets across the organization (pass --library to scope to one)").argument("<query>", "Search query").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").action((query, options, command) => runAction(command, (context) => searchAssetsCommand(context, query, parseOptions(searchOptionsSchema, options))));
   assets.command("download").description("Download an asset's file").argument("<assetId>", "Asset id").option("-o, --output <path>", "Target file path").option("--force", "Overwrite the target file if it exists").action((assetId, options, command) => runAction(command, (context) => downloadAssetCommand(context, assetId, parseOptions(downloadOptionsSchema, options))));
-  assets.command("upload").description("Upload local files as assets").argument("<files...>", "Local file paths").action((files, _options, command) => runAction(command, (context) => uploadAssetsCommand(context, files)));
+  assets.command("upload").description("Upload local files as assets").argument("<files...>", "Local file paths").option("--parent <assetId>", "Attach a single image as a variant of this asset").action((files, options, command) => runAction(command, (context) => uploadAssetsCommand(context, files, parseOptions(uploadOptionsSchema, options))));
   assets.command("rm").description("Move assets to trash (recoverable)").argument("<assetIds...>", "Asset ids").option("--yes", "Skip the confirmation prompt").action((assetIds, options, command) => runAction(command, (context) => removeAssetsCommand(context, assetIds, parseOptions(removeOptionsSchema, options))));
   assets.command("describe").description("Set an asset's description").argument("<assetId>", "Asset id").requiredOption("--text <description>", "Description text").action((assetId, options, command) => runAction(command, (context) => describeAssetCommand(context, assetId, parseOptions(describeOptionsSchema, options))));
+  assets.command("promote").description("Make one of an asset's variants its default (same URL, new pixels)").argument("<assetId>", "Asset id").requiredOption("--variant <variantId>", "Variant to promote").action((assetId, options, command) => runAction(command, (context) => promoteVariantCommand(context, assetId, parseOptions(promoteOptionsSchema, options))));
   assets.command("transfer").description("Move assets to another library").argument("<assetIds...>", "Asset ids to move").requiredOption("--to <libraryId>", "Target library id").action((assetIds, options, command) => runAction(command, (context) => transferAssetsCommand(context, assetIds, parseOptions(transferOptionsSchema, options))));
 }
 
@@ -18376,10 +18465,10 @@ async function logoutCommand(context) {
 async function statusCommand(context) {
   if (!context.credential) {
     if (context.json) {
-      printJson(context, { authenticated: false });
+      printJson(context, { authenticated: false, sessionExpired: context.sessionExpired });
       return;
     }
-    note(context, "Not authenticated. Run `raster auth login`.");
+    note(context, context.sessionExpired ? "Your saved login expired. Run `raster auth login` to sign in again." : "Not authenticated. Run `raster auth login`.");
     return;
   }
   if (context.credential.kind === "oauth") {
@@ -18598,9 +18687,18 @@ async function listTagsCommand(context, options) {
 var mutateOptionsSchema = exports_external.object({
   tag: exports_external.array(exports_external.string().min(1)).min(1)
 });
-async function tagAssetsCommand(context, assetIds, options) {
+function assertWithinTagCeilings(assetIds, tags) {
   if (assetIds.length === 0)
     throw new UsageError("Provide at least one asset id.");
+  if (assetIds.length > MAX_TAG_IDS) {
+    throw new ValidationError(`At most ${MAX_TAG_IDS} asset ids are supported per call.`);
+  }
+  if (tags.length > MAX_TAGS_PER_CALL) {
+    throw new ValidationError(`At most ${MAX_TAGS_PER_CALL} tags are supported per call.`);
+  }
+}
+async function tagAssetsCommand(context, assetIds, options) {
+  assertWithinTagCeilings(assetIds, options.tag);
   requireAuth(context);
   const organizationId = await context.resolveOrg();
   const libraryId = await context.resolveLibrary();
@@ -18616,8 +18714,7 @@ async function tagAssetsCommand(context, assetIds, options) {
   note(context, `Tagged ${assetIds.length} asset(s) with ${options.tag.join(", ")}.`);
 }
 async function untagAssetsCommand(context, assetIds, options) {
-  if (assetIds.length === 0)
-    throw new UsageError("Provide at least one asset id.");
+  assertWithinTagCeilings(assetIds, options.tag);
   requireAuth(context);
   const organizationId = await context.resolveOrg();
   const libraryId = await context.resolveLibrary();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@raster-app/cli",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Command-line client for the Raster API",
   "license": "Apache-2.0",
   "type": "module",
-  "homepage": "https://docs.raster.app/api/cli",
+  "homepage": "https://raster.app/docs/api/cli",
   "engines": {
     "node": ">=20"
   },