@sprid/cli 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.3 - 2026-09-23
+
+- Posts and reviews have refs: `BND-78` is post 78 of the account keyed BND,
+  `BND-R4` is review 4 of the app keyed BND. Every command that takes a post id
+  takes its ref, and `sprid reviews draft|reply` take a review ref. `sprid
+  status` and the review mail print refs, which older versions refuse.
+- `sprid reviews reply` reads the one review it replies to, so a review
+  older than the latest hundred can be answered from its draft.
+- `sprid account avatar <account> [file|url]` sets an account's avatar; with
+  no source it uses the app's own icon. `sprid init` reports the avatar it set.
+
 ## 0.1.2 - 2026-09-22
 
 - Published as `@sprid/cli`. The command is still `sprid`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/commands/family.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { extname, resolve } from "node:path";
 import { UsageError } from "../args.mjs";
 import { resolveProfile } from "../profiles.mjs";
 
@@ -88,9 +88,39 @@ export async function account(ctx) {
         .api()
         .patch(`/api/accounts/${positiveId(raw)}`, objectFile(ctx)),
     );
+  else if (verb === "avatar") return accountAvatar(ctx, raw, ctx.positionals[2]);
   else
     throw new UsageError(
-      "sprid account create|update [id] --file payload.json",
+      "sprid account create|update [id] --file payload.json | sprid account avatar <account> [file|url]",
     );
   return 0;
 }
+
+const AVATAR_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+
+// The account's avatar: what Sprid's mails and the account.avatarUrl template
+// binding draw. No source = the app's own icon, looked up by the server.
+async function accountAvatar(ctx, ref, source) {
+  if (!ref) throw new UsageError("sprid account avatar <account> [file|url]");
+  const account = encodeURIComponent(String(ref));
+  if (!source || /^https?:\/\//i.test(source)) {
+    const result = await ctx.api().post(`/api/accounts/${account}/avatar/from-url`, source ? { url: source } : {});
+    if (ctx.flags.json) ctx.out(result);
+    else ctx.print(`Avatar set from ${result.source} (${result.size}): ${result.avatarUrl}`);
+    return 0;
+  }
+  const path = resolve(ctx.cwd, source);
+  const ext = extname(path).toLowerCase();
+  const contentType = AVATAR_TYPES[ext];
+  if (!contentType) throw new UsageError("The avatar must be a PNG, JPEG or WebP file. SVG and ICO do not render in mail clients.");
+  const bytes = readFileSync(path);
+  if (bytes.length > 5 * 1024 * 1024) throw new UsageError("The avatar file is over 5 MB. Export the icon at 512 or 1024 px.");
+  const api = ctx.api();
+  const { uploadUrl, key } = await api.post(`/api/accounts/${account}/avatar/upload-url`, { contentType });
+  const put = await (ctx.fetch ?? fetch)(uploadUrl, { method: "PUT", headers: { "content-type": contentType }, body: bytes, redirect: "error", signal: AbortSignal.timeout(60000) });
+  if (!put.ok) throw new Error(`Uploading the avatar failed (${put.status}).`);
+  const result = await api.post(`/api/accounts/${account}/avatar/confirm`, { key });
+  if (ctx.flags.json) ctx.out(result);
+  else ctx.print(`Avatar set from ${source}: ${result.avatarUrl}`);
+  return 0;
+}

package/src/commands/init.mjs

@@ -128,6 +128,7 @@ export async function init(ctx) {
   ctx.print(`  ${C.ok(OK)} ${existing ? "Updated" : "Created"} App Profile ${C.bold(profile.slug)} (${profile.name}) from ${source}`);
   const set = PROFILE_FIELDS.filter((k) => k !== "slug" && k !== "name" && profile[k]).map((k) => [k, profile[k]]);
   if (set.length) ctx.print(table(set, { indent: "    " }));
+  if (profile.avatar) ctx.print(`  ${C.ok(OK)} Avatar for ${profile.avatar.accounts.join(", ")} from the ${profile.avatar.source} icon (${profile.avatar.size})`);
   if (missing.length) {
     ctx.print("  Still missing:");
     ctx.print(table(missing.map((m) => [`${NONE} ${m.label.split(" · ")[0]}`, C.dim("→"), m.cli]), { indent: "    " }));

package/src/commands/reviews.mjs

@@ -70,18 +70,24 @@ export function renderReview(r) {
   return lines.join("\n");
 }
 
+// A review is named by its row id (41) or its ref (BND-R41); the server
+// resolves either, so the CLI only checks the shape.
 function needId(arg, usage) {
-  const id = Number(arg);
-  if (!Number.isInteger(id) || id <= 0) throw new UsageError(usage);
-  return id;
+  const id = String(arg ?? "").trim();
+  if (/^[1-9]\d*$/.test(id)) return Number(id); // --json keeps printing a number
+  if (/^[A-Za-z][A-Za-z0-9]{1,4}-[Rr]\d+$/.test(id)) return id.toUpperCase();
+  throw new UsageError(usage);
 }
 
+/** `BND-R41` as is; a bare row id as `#41`. */
+const label = (id) => (/^\d+$/.test(String(id)) ? `#${id}` : String(id));
+
 async function draft(ctx, arg) {
-  const id = needId(arg, "sprid reviews draft <id>");
-  const res = await ctx.api().post(`/api/store-reviews/${id}/draft`);
+  const id = needId(arg, "sprid reviews draft <id|ref>");
+  const res = await ctx.api().post(`/api/store-reviews/${encodeURIComponent(id)}/draft`);
   if (ctx.json) ctx.out(res);
   else {
-    ctx.print(`  Draft for review #${id}:`);
+    ctx.print(`  Draft for review ${label(id)}:`);
     ctx.print(`  ${res.draftReply ?? ""}`);
     ctx.print(C.dim(`  Send it: sprid reviews reply ${id}   (edit first: --text "…")`));
   }
@@ -89,15 +95,18 @@ async function draft(ctx, arg) {
 }
 
 async function reply(ctx, arg) {
-  const id = needId(arg, "sprid reviews reply <id> [--text …] [--yes]");
-  // No GET /api/store-reviews/:id exists; the list (max 100, newest first) is
-  // the lookup. Good enough for a reply, which is about a recent review.
-  const rows = await fetchReviews(ctx, { limit: 100 });
-  const row = rows.find((r) => r.id === id);
+  const id = needId(arg, "sprid reviews reply <id|ref> [--text …] [--yes]");
+  // The one review, by id or ref. Any age, not only the latest hundred.
+  let row = null;
+  try {
+    row = (await ctx.api().get(`/api/store-reviews/${encodeURIComponent(id)}`)).review ?? null;
+  } catch (err) {
+    if (!(err instanceof ApiError) || err.status !== 404) throw err;
+  }
   let text = ctx.flags.text && ctx.flags.text !== true ? String(ctx.flags.text) : null;
   if (!text) {
-    if (!row) throw new ApiError(404, `Review #${id} is not among the latest 100${ctx.flags.app ? ` for ${ctx.flags.app}` : ""}; pass --text to reply anyway.`);
-    if (!row.draftReply) throw new UsageError(`Review #${id} has no draft. Run \`sprid reviews draft ${id}\` or pass --text.`);
+    if (!row) throw new ApiError(404, `Review ${label(id)} was not found; pass --text to reply anyway.`);
+    if (!row.draftReply) throw new UsageError(`Review ${label(id)} has no draft. Run \`sprid reviews draft ${id}\` or pass --text.`);
     text = row.draftReply;
   }
   const source = row?.source ?? null;
@@ -113,13 +122,13 @@ async function reply(ctx, arg) {
       if (ctx.json) {
         ctx.out({ ok: false, error: msg, id, text, store: source, limit });
       } else {
-        ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+        ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review ${label(row?.ref ?? id)}:`);
         ctx.print(`  ${text}`);
         ctx.warn(`  ✗ ${msg}`);
       }
       return 2;
     }
-    ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review #${id}:`);
+    ctx.print(`  Will send to ${STORE_LABEL[source] ?? "the store"}${limit ? ` (${text.length}/${limit} chars)` : ""} for review ${label(row?.ref ?? id)}:`);
     if (row) ctx.print(C.dim(`  re: ${stars(row.rating)} ${truncate([row.title, row.body].filter(Boolean).join(" · "), 120)}`));
     ctx.print("");
     ctx.print(`  ${text}`);
@@ -131,9 +140,9 @@ async function reply(ctx, arg) {
     }
   }
 
-  const res = await ctx.api().post(`/api/store-reviews/${id}/reply`, { text });
+  const res = await ctx.api().post(`/api/store-reviews/${encodeURIComponent(id)}/reply`, { text });
   if (ctx.json) ctx.out({ ok: true, id, text, review: res.review ?? null });
-  else ctx.print(`  ${C.ok(OK)} Reply sent for review #${id}${source ? ` on ${STORE_LABEL[source]}` : ""}.`);
+  else ctx.print(`  ${C.ok(OK)} Reply sent for review ${label(row?.ref ?? id)}${source ? ` on ${STORE_LABEL[source]}` : ""}.`);
   return 0;
 }
 

package/src/commands/studio.mjs

@@ -11,10 +11,12 @@ async function payload(ctx) {
 }
 export async function remotePost(ctx) {
   const [verb, ref] = ctx.positionals;
-  const id = ctx.flags.id ?? ref;
+  let id = ctx.flags.id ?? ref;
   if (!['create', 'get', 'update', 'deliveries', 'handoff'].includes(verb) && !(verb === 'preview' && ctx.flags.id)) return false;
-  if (verb !== 'create' && !/^[1-9]\d*$/.test(String(id))) throw new UsageError('Supply the positive server post ID. Local preview slugs remain unchanged.');
+  // The server post id (271) or its ref (BND-78); the server resolves either.
+  if (verb !== 'create' && !/^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/.test(String(id))) throw new UsageError('Supply the server post ID or its ref, such as 271 or BND-78. Local preview slugs remain unchanged.');
   const api = ctx.api();
+  if (verb !== 'create') id = encodeURIComponent(String(id).toUpperCase());
   const result = verb === 'create' ? await api.post('/api/studio/posts', await payload(ctx))
     : verb === 'update' ? await api.patch(`/api/posts/${id}`, await payload(ctx))
     : verb === 'preview' ? await api.get(`/api/studio/posts/${id}/preview`)

package/src/docs/commands.mjs

@@ -29,7 +29,7 @@ export const COMMAND_GROUPS = [
     ['media', 'sprid media job <UUID>', 'Read saved upload results or creation progress without repeating the operation.'],
     ['media', 'sprid media init|build|register|check|push|preview …', 'Run the existing local media pipeline. Historical sprid post invocations remain supported.'],
     ['post', 'sprid post create --file <draft.json>', 'Create a shared draft from ordered asset references and a stable requestId. Never publishes.'],
-    ['post', 'sprid post get <postId>', 'Read the shared post and its slides.'],
+    ['post', 'sprid post get <postId>', 'Read the shared post and its slides. Every <postId> here takes the number or the post\'s ref, such as BND-142.'],
     ['post', 'sprid post update <postId> --file <changes.json>', 'Apply the existing post-update contract to a shared draft.'],
     ['post', 'sprid post preview --id <postId>', 'Preview a shared post. Without --id, historical local preview arguments are unchanged.'],
     ['post', 'sprid post deliveries <postId>', 'Read scheduled, failed and delivered publications with platform receipts.'],
@@ -47,6 +47,7 @@ export const COMMAND_GROUPS = [
   ] },
   { title: 'Apps and market editions', entries: [
     ['account', 'sprid account create|update [id] --file payload.json', 'Create an app content account or update its identity. Creation requires workspaceId, appProfileId, name and slug; market, locale, persona and timezone are explicit.'],
+    ['account', 'sprid account avatar <account> [file|url]', 'Set the avatar Sprid’s mails and templates draw. No source uses the app’s icon: App Store artwork, else the website’s manifest or touch icon. A file must be PNG, JPEG or WebP; a 1024 px app icon from the repo is the best source.'],
     ['apps', 'sprid apps', 'List apps with their content accounts and workspace IDs.'],
     ['insights', 'sprid insights --app <slug> [--account <slug>] [--days N]', 'Read app results once, with social content optionally narrowed to one account.'],
     ['family', 'sprid family compare --app <slug> [--days N]', 'Compare themes at matched post age with sample counts and channel baselines.'],