@facelessad/cli 1.0.0 → 1.0.2

package/README.md

@@ -9,8 +9,8 @@ facelessad tools                # what can be made
 facelessad create --tool motion-graphics --url https://your-product.com --wait
 ```
 
-Nine commands: `login`, `create`, `status`, `list`, `download`, `estimate`,
-`tools`, `voices`, `balance`. Every command accepts `--json` for scripting;
+Ten commands: `login`, `create`, `status`, `list`, `download`, `estimate`,
+`tools`, `voices`, `brands`, `balance`. Every command accepts `--json` for scripting;
 `create`/`estimate` accept `--dry-run` (print the request body without
 sending) and `--file body.json` (a base body that flags override).
 
@@ -18,9 +18,35 @@ The key is stored in `~/.facelessad/config.json` with mode 0600. The
 environment variable `FACELESSAD_API_KEY` always wins — that is the way CI
 should authenticate. `FACELESSAD_API_URL` overrides the API base.
 
-`--wait` polls and prints phase + elapsed time; for long-running builds a
-webhook is the better tool — a stuck shell is a stuck CI job. See
-https://facelessad.com/developers → Webhooks.
+`--wait` polls and prints phase + elapsed time, and stops watching after 6
+hours (`--timeout <seconds>` changes that; `--timeout 0` waits with no
+limit). **Stopping the wait never cancels the build** — API videos run on a
+bulk lane that can take hours when the queue is busy, and they keep going. A video whose status is
+`draft` is not building and will never finish on its own, so `--wait`
+stops on it immediately instead of polling forever. For long-running
+builds a webhook is still the better tool — a stuck shell is a stuck CI
+job. See https://facelessad.com/developers → Webhooks.
+
+## Flag spellings (1.0.1)
+
+Both spellings are accepted, because the older ones appeared on the
+developers page and live on in scripts:
+
+| also accepted | canonical |
+|---|---|
+| `--brand` | `--brand-name` |
+| `--color`, `--colour` | `--brand-color` |
+| `--voice-id` | `--voice` |
+| `--voice-gender` | `--gender` |
+| `--no-voice-over` | `--no-voice` |
+| `--no-captions` | `--captions false` |
+| `--no-music` | `--music false` |
+| `-o` | `--out` |
+
+`--no-brand-kit` and `--no-winners` now work; before 1.0.1 they were
+accepted on the command line and silently dropped, so the video was built
+with the Brand Kit anyway. **An unknown flag is now an error** rather than
+something quietly ignored — that silence is what hid the whole problem.
 
 Errors are printed with the API's own wording and exit code 1. The machine
 code (e.g. `unknown_style`) follows the message.

package/index.js

@@ -2,7 +2,7 @@
 /**
  * @facelessad/cli — FacelessAd from the terminal.
  *
- * Nine commands, each one /api/v1 call. Zero dependencies: Node 18 ships
+ * Ten commands, each one /api/v1 call. Zero dependencies: Node 18 ships
  * fetch, and a tool that stores an API key is a bad place for a dependency
  * tree.
  *
@@ -30,17 +30,43 @@ const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
 
 // ────────────────────────── arg parsing ──────────────────────────
 
+/**
+ * Onko token lippu eikä arvo? Pitkä `--x` tai yhden kirjaimen lyhyt `-o`.
+ *
+ * 1.0.1 KORJAUS: tämä oli aiemmin pelkkä `startsWith('--')`, jolloin
+ * lyhytlippu meni edellisen lipun ARVOKSI. `create --dry-run -o x.json`
+ * asetti `flags['dry-run'] = '-o'`, ja koska tarkistus on `=== true`,
+ * kuivaharjoitus ei laukennut vaan komento loi oikean videon ja veloitti
+ * creditit. Lievempi mutta yleisempi osuma oli
+ * `download 5 --json -o out.mp4`, jossa molemmat liput katosivat hiljaa.
+ *
+ * Yhden kirjaimen rajaus on tarkoituksellinen: `--offset -5` toimii yhä,
+ * koska `-5` ei ole lippu, ja `--text "-leading dash"` samoin.
+ */
+const looksLikeFlag = (t) => t.startsWith('--') || /^-[A-Za-z]$/.test(t);
+
 const rawArgs = process.argv.slice(2);
 const cmd = rawArgs[0] && !rawArgs[0].startsWith('-') ? rawArgs[0] : (rawArgs.includes('--version') || rawArgs.includes('-v') ? 'version' : 'help');
 const flags = {};
 const positional = [];
+const badShort = [];
 for (let i = cmd === 'help' || cmd === 'version' ? 0 : 1; i < rawArgs.length; i++) {
   const a = rawArgs[i];
+  // 1.0.1: -o <file> on dokumentoitu facelessad.com/developers -sivulla ja
+  // päätyi aiemmin positional-listaan, jolloin tiedostonimi jäi huomiotta
+  // ja lataus tallentui oletusnimellä. Lyhytliput käsitellään nyt erikseen.
+  if (a === '-o') {
+    if (i + 1 < rawArgs.length && !looksLikeFlag(rawArgs[i + 1])) flags.out = rawArgs[++i];
+    else flags.out = true;
+    continue;
+  }
+  if (a === '-v') { continue; }                       // versio luetaan jo cmd-tunnistuksessa
+  if (/^-[A-Za-z]$/.test(a)) { badShort.push(a); continue; }
   if (a.startsWith('--')) {
     const eq = a.indexOf('=');
     if (eq !== -1) {
       flags[a.slice(2, eq)] = a.slice(eq + 1);
-    } else if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+    } else if (i + 1 < rawArgs.length && !looksLikeFlag(rawArgs[i + 1])) {
       flags[a.slice(2)] = rawArgs[++i];
     } else {
       flags[a.slice(2)] = true;
@@ -49,6 +75,49 @@ for (let i = cmd === 'help' || cmd === 'version' ? 0 : 1; i < rawArgs.length; i+
     positional.push(a);
   }
 }
+
+/**
+ * 1.0.1 — ALIAKSET. Tämän paketin lippunimet ajautuivat erilleen siitä mitä
+ * facelessad.com/developers tuottaa: sivu kirjoitti --brand, --color,
+ * --voice-id, --voice-gender, --no-voice-over, --no-captions ja --no-music,
+ * joita tämä tiedosto ei lukenut. Koska tuntematon lippu meni hiljaa
+ * roskiin, kopioitu komento ONNISTUI ja teki videon väärillä asetuksilla:
+ * ääni päällä vaikka käyttäjä pyysi ilman, brändinimi ja väri kokonaan pois.
+ * Sivu korjattiin, mutta vanhat komennot elävät skripteissä ja
+ * muistiinpanoissa — siksi molemmat kirjoitusasut hyväksytään täällä.
+ */
+const ALIASES = {
+  'brand': 'brand-name',
+  'color': 'brand-color',
+  'colour': 'brand-color',
+  'voice-id': 'voice',
+  'voice-gender': 'gender',
+  'no-voice-over': 'no-voice',
+  'product-image-url': 'product-image',
+};
+for (const [from, to] of Object.entries(ALIASES)) {
+  if (flags[from] !== undefined && flags[to] === undefined) flags[to] = flags[from];
+  delete flags[from];
+}
+// --no-captions / --no-music ovat kieltomuotoja arvollisista lipuista.
+if (flags['no-captions'] === true) { flags.captions = 'false'; delete flags['no-captions']; }
+if (flags['no-music'] === true) { flags.music = 'false'; delete flags['no-music']; }
+
+/**
+ * 1.0.1 — TUNTEMATON LIPPU ON VIRHE. Tämä on se ominaisuus jonka puute teki
+ * lippujen ajautumisesta näkymätöntä: aiemmin väärin kirjoitettu lippu ei
+ * tuottanut mitään palautetta, ja käyttäjä sai videon jota ei tilannut.
+ * Nyt komento pysähtyy ennen kuin mitään veloitetaan.
+ */
+const KNOWN_FLAGS = new Set([
+  'tool', 'url', 'text', 'duration', 'aspect', 'language', 'style', 'style-hint',
+  'structure', 'hook', 'video-mode', 'brand-color', 'brand-name', 'cta', 'name',
+  'voice', 'gender', 'no-voice', 'music', 'sfx', 'captions', 'product-image',
+  'no-brand-kit', 'no-winners', 'brand-kit',
+  'file', 'dry-run', 'wait', 'timeout', 'json', 'out', 'limit', 'offset', 'version',
+]);
+const unknownFlags = Object.keys(flags).filter((f) => !KNOWN_FLAGS.has(f)).map((f) => '--' + f).concat(badShort);
+
 const asJson = flags.json === true || flags.json === 'true';
 
 // ────────────────────────── config / auth ──────────────────────────
@@ -111,6 +180,22 @@ function out(data, human) {
   }
 }
 
+/**
+ * 1.0.1: numeeriset liput. `parseInt('abc')` on NaN, ja JSON.stringify tekee
+ * siitä `null` — palvelin ohittaa null-arvon ja käyttää oletusta. Eli
+ * `--brand-kit abc` olisi tuottanut hiljaa OLETUSBRÄNDIN ja `--duration abc`
+ * oletuskeston, ilman mitään ilmoitusta. Sama hiljainen korvaus jota koko tämä
+ * versio on korjaamassa; kelpaamaton luku on virhe.
+ */
+function num(flag, raw) {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n)) {
+    die('--' + flag + ' must be a whole number, got "' + raw + '"', 'invalid_number');
+  }
+  return n;
+}
+
 // ────────────────────────── request body from flags ──────────────────────────
 
 /**
@@ -130,7 +215,7 @@ function buildBody() {
     if (flags.url !== undefined) body.materials.landing_page_url = String(flags.url);
     if (flags.text !== undefined) body.materials.text = String(flags.text);
   }
-  set('duration', flags.duration !== undefined ? parseInt(flags.duration, 10) : undefined);
+  set('duration', num('duration', flags.duration));
   set('aspect_ratio', flags.aspect !== undefined ? String(flags.aspect) : undefined);
   set('language', flags.language !== undefined ? String(flags.language) : undefined);
   set('style', flags.style !== undefined ? String(flags.style) : undefined);
@@ -143,10 +228,17 @@ function buildBody() {
   set('cta', flags.cta !== undefined ? String(flags.cta) : undefined);
   set('name', flags.name !== undefined ? String(flags.name) : undefined);
   set('product_image_url', flags['product-image'] !== undefined ? String(flags['product-image']) : undefined);
+  // 1.0.1 (§640): kumpi brändi. Ilman tätä API otti aina tilin oletusbrändin.
+  set('brand_kit_id', num('brand-kit', flags['brand-kit']));
   if (flags.music !== undefined) body.music = flags.music === true || flags.music === 'true';
   if (flags.sfx !== undefined) body.sfx = flags.sfx === true || flags.sfx === 'true';
   if (flags.captions !== undefined) body.captions = flags.captions === true || flags.captions === 'true';
   if (flags['no-voice'] === true) body.voice_over = false;
+  // 1.0.1: nämä kaksi puuttuivat kokonaan. facelessad.com/developers tuotti
+  // niille lippuja joita tämä tiedosto ei lukenut, joten "älä käytä brand
+  // kittiä" -pyyntö meni hiljaa roskiin ja API:n oletus (true) voitti.
+  if (flags['no-brand-kit'] === true) body.use_brand_kit = false;
+  if (flags['no-winners'] === true) body.use_winners = false;
   if (flags.voice !== undefined || flags.gender !== undefined) {
     if (typeof flags.voice === 'string' && flags.gender === undefined) {
       body.voice = flags.voice;
@@ -216,6 +308,17 @@ const commands = {
     out(d, (d.tools || []).map((t) => '  ' + t.id.padEnd(18) + dim(t.name || '')).join('\n') + '\n\nDetails: facelessad tools --tool <id>');
   },
 
+  async brands() {
+    const d = await call('GET', '/api/v1/brand-kits');
+    out(d, (d.brandKits || []).map((k) =>
+      '  ' + String(k.id).padEnd(6) + (k.name || '').padEnd(24)
+      + dim(k.filled + '/32 answered'
+        + (k.isDefault ? ' · default' : '')
+        + (k.hasColor ? ' · colour' : '')
+        + (k.hasLogo ? ' · logo' : ''))
+    ).join('\n') || '  (no brands yet)');
+  },
+
   async voices() {
     const q = new URLSearchParams();
     if (flags.language) q.set('language', String(flags.language));
@@ -253,8 +356,9 @@ const commands = {
 
   async list() {
     const q = new URLSearchParams();
-    if (flags.limit) q.set('limit', String(flags.limit));
-    if (flags.offset) q.set('offset', String(flags.offset));
+    const lim = num('limit', flags.limit), off = num('offset', flags.offset);
+    if (lim !== undefined) q.set('limit', String(lim));
+    if (off !== undefined) q.set('offset', String(off));
     const d = await call('GET', '/api/v1/videos' + (q.size ? '?' + q : ''));
     out(d, (d.videos || []).map((v) => '  ' + String(v.id).padEnd(8) + v.status.padEnd(10) + (v.tool || '').padEnd(18) + dim(v.name || '')).join('\n') || '  (no videos yet)');
   },
@@ -278,6 +382,7 @@ Commands:
   login                       Save and verify your API key (~/.facelessad, 0600)
   balance                     Plan and credit balance
   tools [--tool <id>]         Tool registry — styles, structures, durations
+  brands                      Your brands and their ids (for --brand-kit)
   voices [--language --gender]Curated voice pool
   estimate <create-flags>     Upper-bound credit cost, without creating
   create --tool <id> ...      Create a video (returns an id immediately)
@@ -289,8 +394,19 @@ Create flags:
   --tool --url --text --duration --aspect --language --style --style-hint
   --structure --hook --video-mode --brand-color --brand-name --cta --name
   --voice --gender --no-voice --music --sfx --captions --product-image
+  --no-brand-kit --no-winners --brand-kit <id> (see: facelessad brands)
   --file body.json (base body; flags override)   --dry-run (print, don't send)
 
+--wait stops watching after 6 hours; --timeout <seconds> changes that and
+--timeout 0 waits with no limit. Stopping the wait never cancels the build.
+A video in "draft" is not building and is never waited on. For overnight
+runs a webhook beats leaving a terminal open — see ${API}/developers.
+
+Accepted spellings: --brand = --brand-name, --color = --brand-color,
+--voice-id = --voice, --voice-gender = --gender, --no-voice-over = --no-voice,
+--no-captions = --captions false, --no-music = --music false, -o = --out.
+An unknown flag is an error, not something quietly ignored.
+
 Every command accepts --json. FACELESSAD_API_KEY wins over the saved key
 (use it in CI); long builds are better served by a webhook than --wait —
 see ${API}/developers.
@@ -298,16 +414,76 @@ see ${API}/developers.
   },
 };
 
+/**
+ * 1.0.2 — kaksi siistimistä ihmisluettavaan tulosteeseen.
+ *
+ * 1. VAIHE PIILOON KUN VALMIS. Rivi luki "done (render_queued)", mikä näyttää
+ *    ristiriitaiselta. Se ei ole vika: final-render menee omaan jonoonsa eikä
+ *    sen valmistuminen kirjoita terminaalivaihetta Redisiin (§471 rakentaa
+ *    jonokaton laskennan tämän varaan), joten `phase` jää viimeiseen
+ *    kirjoitettuun arvoon. `status` on silti oikein. Kun ajo on päättynyt,
+ *    vaihe ei kerro mitään hyödyllistä, joten sitä ei näytetä.
+ * 2. PRESIGNED-URL EI IHMISELLE. Se on ~500 merkkiä ja rivittyy terminaalissa
+ *    lukukelvottomaksi, eikä sitä voi lyhentää — allekirjoitus on osa URLia ja
+ *    katkaistu linkki ei toimi. Ihmiselle näytetään komento joka hakee saman
+ *    tiedoston; koneelle `--json` kantaa `url`-kentän ennallaan.
+ */
 function statusLine(d) {
+  const done = d.status === 'done' || d.status === 'failed' || d.status === 'draft';
   let s = 'Video ' + d.id + ': ' + bold(d.status);
-  if (d.phase) s += ' ' + dim('(' + d.phase + ')');
-  if (d.url) s += '\nURL (valid ~1 h): ' + d.url;
+  if (d.phase && !done) s += ' ' + dim('(' + d.phase + ')');
+  if (d.url) s += '\n' + dim('Download: ') + 'facelessad download ' + d.id + ' --out ad.mp4'
+    + '\n' + dim('(the direct link is in --json output; it expires in ~1 h)');
   if (d.error) s += '\n' + d.error;
   return s;
 }
 
+/**
+ * 1.0.1 — kaksi korjausta odotussilmukkaan.
+ *
+ * 1. AIKAKATTO. Silmukka oli `for(;;)` ilman ulospääsyä muuten kuin
+ *    done/failed. Jos video jäi mihin tahansa muuhun tilaan, komento jäi
+ *    pyörimään ikuisesti — CI-ajossa se on jumittunut job, ei virhe.
+ * 2. `draft` ON TERMINAALINEN. Palvelin palauttaa sen kansiolle joka ei
+ *    rakennu eikä valmistu itsestään (appissa aloitettu luonnos, tai ajo
+ *    jonka etenemistieto on vanhentunut). Sitä ei ole mitään mieltä odottaa.
+ *    Aiemmin palvelin palautti tässä tilanteessa dokumentoimattoman arvon
+ *    `active`, joka ei ollut done eikä failed — eli juuri se tapaus joka
+ *    jäädytti silmukan.
+ *
+ * Oletuskatto on 30 min; --timeout <sekuntia> muuttaa sen. Aikakatto poistuu
+ * koodilla 1, koska pipeline ei saa jatkaa videolla jota ei ole.
+ */
+/**
+ * 1.0.2 — aikakatto uusiksi. 1.0.1:n 30 min oli liian tiukka: API-ajot menevät
+ * bulk-kaistalle joka etenee vasta kun käyttöliittymän jonot ovat tyhjät, ja
+ * kuvamallit ovat ajoittain hyvin hitaita. Yön yli jonottaminen on
+ * nimenomainen tuotelupaus, eikä odotuskomennon oletus saa olla sitä vastaan.
+ *
+ * Oletus on nyt 6 h ja `--timeout 0` odottaa rajattomasti. Rajaton on
+ * SALLITTU mutta ei oletus: 1.0.0:n ikuinen silmukka oli vika koska se ei
+ * ollut kenenkään valinta — nyt se on.
+ *
+ * Aikakatto EI peruuta buildia. Se lopettaa vain odottamisen, ja viesti sanoo
+ * sen. Yön yli -ajoihin oikea työkalu on silti webhook, ei auki jätetty pääte.
+ */
+const WAIT_TIMEOUT_DEFAULT = 21600;
+const POLL_SECONDS = 5;
+
 async function waitFor(id) {
   const started = Date.now();
+  // 1.0.1: --timeout luetaan sellaisenaan. Ensimmäinen versio tästä pakotti
+  // lattian 30 s:aan, jolloin `--timeout 12` odotti 30 s eikä kertonut siitä
+  // — sama hiljainen ylikirjoitus jota tämä paketti on täynnä korjaamassa.
+  // Nyt kelpaamaton arvo on VIRHE ja kelvollinen tehdään sellaisenaan.
+  let limit = WAIT_TIMEOUT_DEFAULT;
+  if (flags.timeout !== undefined && flags.timeout !== true) {
+    limit = Number(flags.timeout);
+    if (!Number.isFinite(limit) || (limit !== 0 && limit < POLL_SECONDS)) {
+      die('--timeout must be 0 (wait forever) or at least ' + POLL_SECONDS + ' seconds', 'invalid_timeout');
+    }
+  }
+  const noLimit = limit === 0;
   let last = '';
   for (;;) {
     const d = await call('GET', '/api/v1/videos/' + encodeURIComponent(id));
@@ -323,7 +499,22 @@ async function waitFor(id) {
       else { process.stderr.write('Error: video ' + id + ' failed' + (d.error ? ': ' + d.error : '') + '\n'); }
       process.exit(1);
     }
-    await new Promise((r) => setTimeout(r, 5000));
+    if (d.status === 'draft') {
+      const msg = 'Video ' + id + ' is a draft — it is not building and will not finish on its own. '
+        + 'Open it in the app, or start a new build.';
+      if (asJson) { process.stdout.write(JSON.stringify(d) + '\n'); }
+      else { process.stderr.write('Error: ' + msg + '\n'); }
+      process.exit(1);
+    }
+    if (!noLimit && elapsed + POLL_SECONDS > limit) {
+      const msg = 'Stopped waiting for video ' + id + ' after ' + elapsed + 's (last status: ' + d.status
+        + (d.phase ? ' — ' + d.phase : '') + '). The build was NOT cancelled and is still running — '
+        + 'check it with: facelessad status ' + id + '   (or wait longer with --timeout 0)';
+      if (asJson) { process.stdout.write(JSON.stringify({ ...d, ok: false, code: 'wait_timeout' }) + '\n'); }
+      else { process.stderr.write('Error: ' + msg + '\n' + dim('wait_timeout') + '\n'); }
+      process.exit(1);
+    }
+    await new Promise((r) => setTimeout(r, POLL_SECONDS * 1000));
   }
 }
 
@@ -331,4 +522,11 @@ async function waitFor(id) {
 
 const fn = commands[cmd];
 if (!fn) die('Unknown command "' + cmd + '". Run: facelessad help', 'unknown_command');
+// 1.0.1: tarkistus ennen komennon ajoa — help ja version saavat mennä läpi,
+// jotta väärin kirjoitetun lipun jälkeen pääsee lukemaan mitkä ovat oikein.
+if (unknownFlags.length && cmd !== 'help' && cmd !== 'version') {
+  die('Unknown flag' + (unknownFlags.length > 1 ? 's' : '') + ': '
+    + unknownFlags.join(' ')
+    + '. Run: facelessad help', 'unknown_flag');
+}
 fn().catch((e) => die(e.message || String(e), 'unexpected'));

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "@facelessad/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Create faceless video ads from your terminal or build scripts — the FacelessAd command line.",
   "license": "MIT",
   "type": "module",
-  "bin": { "facelessad": "index.js" },
-  "files": ["index.js", "README.md"],
-  "engines": { "node": ">=18" },
-  "keywords": ["facelessad", "video", "ads", "ai", "cli"],
+  "bin": {
+    "facelessad": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "facelessad",
+    "video",
+    "ads",
+    "ai",
+    "cli"
+  ],
   "homepage": "https://facelessad.com/developers"
 }