@bitmagic/cli 0.1.71 → 0.1.72

package/README.md

@@ -185,8 +185,8 @@ browser reloads itself on every change and the assets panel shows each generatio
 
 | Command | What it does |
 |---|---|
-| `bitmagic login [--env <env>]` | Device-code auth against Auth0; stores credentials per environment. |
-| `bitmagic subscribe [--no-wait]` | Start the Bitmagic Pro subscription the CLI requires; opens checkout and waits for it. |
+| `bitmagic login [--env <env>] [--ref <campaign>]` | Device-code auth against Auth0; stores credentials per environment. `--ref` is set by a landing page's prompt and passed on to the Bitmagic Pro page for attribution. |
+| `bitmagic subscribe [--no-wait] [--ref <campaign>]` | Start the Bitmagic Pro subscription the CLI requires; opens checkout and waits for it. |
 | `bitmagic usage [--days N]` | Where this account's sparks went, and what Pro allowance is left. |
 | `bitmagic allowance [--allow-sparks \| --block-sparks]` | The two Pro allowance windows, and whether your purchased sparks may fund work once they run out. `--allow-sparks` needs a real terminal — it authorises spending your money, so an agent cannot run it for you. |
 | `bitmagic logout [--env <env>]` | Remove stored credentials for an environment. |

package/dist/auth/subscribe-flow.d.ts

@@ -56,6 +56,8 @@ export interface SubscribeOptions {
     noOpen?: boolean;
     /** Skip the wait entirely and return as soon as checkout is open. */
     noWait?: boolean;
+    /** The campaign that sent the creator (`--ref`), passed on to the storefront. See storefrontUrlFor. */
+    ref?: string;
 }
 export interface SubscribeResult {
     /** True when Pro was confirmed active before we returned. */
@@ -88,8 +90,15 @@ export interface SubscribeResult {
  * there is no session to resume it comes straight back and nothing is shown.
  * The portal treats a bare `cli=1` as the same request, so every CLI already
  * installed is fixed by the portal deploy alone — this only states it.
+ *
+ * `ref` names the paid campaign whose landing page handed the creator the
+ * prompt that ran `bitmagic login --ref <campaign>`. The storefront reports it
+ * to analytics (portal/src/campaign-ref.ts): the prompt is the one thing that
+ * reliably crosses from the landing page's browser to wherever this opens. Only
+ * a short slug is passed on; anything else is dropped rather than refused,
+ * because a marketing tag must never stand between a creator and signing in.
  */
-export declare function storefrontUrlFor(subscribeUrl: string, userId: string): string;
+export declare function storefrontUrlFor(subscribeUrl: string, userId: string, ref?: string): string;
 /**
  * Explain that Pro is required, open the storefront, and wait for it to land.
  *

package/dist/auth/subscribe-flow.js

@@ -82,10 +82,19 @@ export function fetchWhoami(environment, token, deps) {
  * there is no session to resume it comes straight back and nothing is shown.
  * The portal treats a bare `cli=1` as the same request, so every CLI already
  * installed is fixed by the portal deploy alone — this only states it.
+ *
+ * `ref` names the paid campaign whose landing page handed the creator the
+ * prompt that ran `bitmagic login --ref <campaign>`. The storefront reports it
+ * to analytics (portal/src/campaign-ref.ts): the prompt is the one thing that
+ * reliably crosses from the landing page's browser to wherever this opens. Only
+ * a short slug is passed on; anything else is dropped rather than refused,
+ * because a marketing tag must never stand between a creator and signing in.
  */
-export function storefrontUrlFor(subscribeUrl, userId) {
+export function storefrontUrlFor(subscribeUrl, userId, ref) {
     const separator = subscribeUrl.includes('?') ? '&' : '?';
-    return `${subscribeUrl}${separator}cli=1&signin=1&u=${encodeURIComponent(userId)}`;
+    const slug = ref?.trim().toLowerCase();
+    const campaign = slug && /^[a-z0-9][a-z0-9-]{0,31}$/.test(slug) ? `&ref=${slug}` : '';
+    return `${subscribeUrl}${separator}cli=1&signin=1&u=${encodeURIComponent(userId)}${campaign}`;
 }
 /**
  * Explain that Pro is required, open the storefront, and wait for it to land.
@@ -98,7 +107,7 @@ export async function runSubscribeFlow(environment, token, me, output, options =
     // An api-server too old to serve a storefront still has to be able to sell a
     // subscription, so fall back to minting Checkout the way this flow used to.
     const url = me.subscribeUrl
-        ? storefrontUrlFor(me.subscribeUrl, me.userId)
+        ? storefrontUrlFor(me.subscribeUrl, me.userId, options.ref)
         : (await apiPost(environment, '/api/cli/v1/pro/checkout', token, {}, { fetch: deps.fetch })).url;
     output.info('');
     output.info('The Bitmagic CLI needs Bitmagic Pro.');
@@ -126,7 +135,7 @@ export async function runSubscribeFlow(environment, token, me, output, options =
         // A transient failure mid-poll must not end the flow — the creator may
         // still be typing their card in. Only a definitive "yes" stops the loop.
         // This answers for a redeemed voucher too: `pro` is entitlement, not billing.
-        let current = null;
+        let current;
         try {
             current = await fetchWhoami(environment, token, deps);
         }

package/dist/auth/subscribe-flow.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscribe-flow.js","sourceRoot":"","sources":["../../src/auth/subscribe-flow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subscribe-flow.js","sourceRoot":"","sources":["../../src/auth/subscribe-flow.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -42,6 +42,10 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
         };
+        readonly ref: {
+            readonly type: "string";
+            readonly description: "The campaign that sent you, passed on to the Bitmagic Pro page. Set by a landing page's prompt.";
+        };
     }>;
     logout: CommandDef<{
         readonly env: {
@@ -94,6 +98,10 @@ declare const rawCommands: {
             readonly type: "boolean";
             readonly description: "Print the result as JSON on stdout; all progress goes to stderr.";
         };
+        readonly ref: {
+            readonly type: "string";
+            readonly description: "The campaign that sent you, passed on to the Bitmagic Pro page. Set by a landing page's prompt.";
+        };
     }>;
     usage: CommandDef<{
         readonly days: {

package/dist/commands/generate.d.ts

@@ -221,25 +221,6 @@ export interface MusicRunResult {
     file?: string;
     bytes?: number;
 }
-/**
- * `generate music` is the one `generate` lane with two outputs a creator may want separately: the
- * world.json asset (the default — what a game plays as its bed) and the MP3 file (`--out`, what a
- * video editor or `bitmagic trailer make` wants). `--no-world` keeps the asset out of the game
- * for the file-only case, so a trailer bed is not registered as a track the game never plays.
- *
- * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
- * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
- * "world.json is unchanged" failure contract are the same as every other lane's.
- */
-export declare function runMusicGeneration(options: {
-    body: Record<string, unknown>;
-    /** Save the MP3 here (relative to the current directory). */
-    out?: string;
-    /** Apply the asset to world.json. The default; `--no-world` turns it off. */
-    world: boolean;
-    json: boolean;
-    deps?: GenerateRunDeps;
-}): Promise<MusicRunResult>;
 export interface SpeechRunResult {
     speechUrl: string;
     originalUrl: string;
@@ -250,18 +231,7 @@ export interface SpeechRunResult {
     file?: string;
     bytes?: number;
 }
-/**
- * `generate speech` has the same two-outputs shape as `generate music`, and for a sharper reason:
- * the world.json asset is a line an NPC speaks (`engine.playSound`), while the MP3 is the input
- * `tools/lipsync/make_line.py --audio` needs to cut mouth cues from. A creator rigging a talking
- * character wants the file and NOT the asset, so `--no-world` is a first-class path here rather
- * than an escape hatch.
- *
- * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
- * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
- * "world.json is unchanged" failure contract are the same as every other lane's.
- */
-export declare function runSpeechGeneration(options: {
+export interface AudioRunOptions {
     body: Record<string, unknown>;
     /** Save the MP3 here (relative to the current directory). */
     out?: string;
@@ -269,7 +239,22 @@ export declare function runSpeechGeneration(options: {
     world: boolean;
     json: boolean;
     deps?: GenerateRunDeps;
-}): Promise<SpeechRunResult>;
+}
+/**
+ * `generate music` is the one `generate` lane with two outputs a creator may want separately: the
+ * world.json asset (the default — what a game plays as its bed) and the MP3 file (`--out`, what a
+ * video editor or `bitmagic trailer make` wants). `--no-world` keeps the asset out of the game
+ * for the file-only case, so a trailer bed is not registered as a track the game never plays.
+ */
+export declare function runMusicGeneration(options: AudioRunOptions): Promise<MusicRunResult>;
+/**
+ * `generate speech` has the same two-outputs shape as `generate music`, and for a sharper reason:
+ * the world.json asset is a line an NPC speaks (`engine.playSound`), while the MP3 is the input
+ * `tools/lipsync/make_line.py --audio` needs to cut mouth cues from. A creator rigging a talking
+ * character wants the file and NOT the asset, so `--no-world` is a first-class path here rather
+ * than an escape hatch.
+ */
+export declare function runSpeechGeneration(options: AudioRunOptions): Promise<SpeechRunResult>;
 /**
  * Refuses `--voxel-grid` alongside `--mesh`, rather than ignoring it.
  *

package/dist/commands/generate.js

@@ -24,7 +24,6 @@ import { smartObjectSpecSchema, formatZodIssues } from '@bitmagic/asset-core';
 import { DEFAULT_MASTER_GRID, generateAndInstallProp } from '../generate/prop.js';
 import { generateAndInstallVehicle } from '../generate/vehicle.js';
 import { generateAndInstallModel } from '../generate/model.js';
-import { downloadMusicFile } from '../generate/music.js';
 import { downloadAudioFile } from '../generate/audio-file.js';
 import { MUSIC_MAX_SECONDS, MUSIC_MIN_SECONDS, SPEECH_MAX_CHARS, SPEECH_VOICES, VIDEO_MAX_SECONDS, VIDEO_MIN_SECONDS, } from '@bitmagic/asset-core';
 import { generateAndInstallAnimationFromVideo, isLocomotionState, isVideoToMotionModel, } from '../generate/animation-from-video.js';
@@ -567,24 +566,24 @@ export async function requestAssetWithJobRecord(type, label, body, runDeps, onSu
     });
 }
 /**
- * `generate music` is the one `generate` lane with two outputs a creator may want separately: the
- * world.json asset (the default — what a game plays as its bed) and the MP3 file (`--out`, what a
- * video editor or `bitmagic trailer make` wants). `--no-world` keeps the asset out of the game
- * for the file-only case, so a trailer bed is not registered as a track the game never plays.
+ * The lane both audio generators share: request, apply (or deliberately not), download (or not).
  *
- * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
- * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
- * "world.json is unchanged" failure contract are the same as every other lane's.
+ * Neither can go through {@link runAssetGeneration} — that always applies the patches and never
+ * downloads — so both share {@link requestAssetWithJobRecord} instead, which is what keeps the
+ * request, the job record and the "world.json is unchanged" failure contract identical to every
+ * other lane's. Written once because the two differed only in nouns, and a message about a
+ * generation that was billed and then half-lost is the last thing a creator reads.
  */
-export async function runMusicGeneration(options) {
+async function runAudioGeneration(lane, options) {
     const output = createOutput(options.json);
     const runDeps = options.deps ?? defaultDeps(options.json);
     const outPath = options.out === undefined ? undefined : path.resolve(options.out);
-    const result = await requestAssetWithJobRecord('music', 'music', options.body, runDeps, async (outcome, worldPath, log) => {
-        if (!outcome.music) {
-            throw new CliError('The server reported the music as generated but sent no track URLs. world.json is unchanged.');
+    const shared = await requestAssetWithJobRecord(lane.type, lane.type, options.body, runDeps, async (outcome, worldPath, log) => {
+        const urls = lane.read(outcome);
+        if (!urls) {
+            throw new CliError(`The server reported the ${lane.noun} as generated but sent ${lane.missingUrls}. world.json is unchanged.`);
         }
-        const { music } = outcome;
+        const generated = `Generated ${lane.noun} (${urls.durationSeconds.toFixed(1)}s): ${outcome.message}`;
         let patchesApplied = 0;
         if (options.world) {
             let applyResult;
@@ -592,120 +591,88 @@ export async function runMusicGeneration(options) {
                 applyResult = applyPatchesToWorld(worldPath, outcome.patches);
             }
             catch (error) {
-                throw decoratedError(error, (message) => `Generated music successfully, but could not write it into world.json: ${message} `
-                    + 'world.json is unchanged — the track was generated (and may have been billed) but is not '
-                    + `yet in your project. It is at ${music.originalUrl}.`);
+                throw decoratedError(error, (message) => `Generated ${lane.noun} successfully, but could not write it into world.json: ${message} `
+                    + `world.json is unchanged — ${lane.output.toLowerCase()} was generated (and may have been billed) `
+                    + `but is not yet in your project. It is at ${urls.originalUrl}.`);
             }
             patchesApplied = applyResult.applied;
-            log(`Generated music (${music.durationSeconds.toFixed(1)}s): ${outcome.message}`);
+            log(generated);
             for (const line of applyResult.summary)
                 runDeps.log(`  - ${line}`);
             runDeps.log(worldUpdatedLine(patchesApplied));
         }
         else {
-            log(`Generated music (${music.durationSeconds.toFixed(1)}s): ${outcome.message}`);
+            log(generated);
             runDeps.log('world.json is unchanged (--no-world).');
         }
         let bytes;
         if (outPath !== undefined) {
             try {
-                bytes = await downloadMusicFile(music.originalUrl, outPath, runDeps.fetch);
+                bytes = await downloadAudioFile(urls.originalUrl, outPath, runDeps.fetch, lane.fileLabel);
             }
             catch (error) {
-                // The asset is generated, billed, and (unless --no-world) already in world.json; only the
-                // local copy is missing, and the message has to say so or the creator regenerates.
-                throw decoratedError(error, (message) => `${message} The track was generated${options.world ? ' and is in world.json' : ''}; only saving `
+                // The asset is generated, billed, and (unless --no-world) already in world.json; only
+                // the local copy is missing, and the message has to say so or the creator regenerates.
+                throw decoratedError(error, (message) => `${message} ${lane.output} was generated${options.world ? ' and is in world.json' : ''}; only saving `
                     + 'the local copy failed.');
             }
             runDeps.log(`Saved ${outPath} (${Math.round(bytes / 1024)} KB).`);
         }
         return {
-            musicUrl: music.musicUrl,
-            originalUrl: music.originalUrl,
-            musicId: music.musicId,
-            durationSeconds: music.durationSeconds,
+            ...urls,
             patchesApplied,
             ...(outPath !== undefined ? { file: outPath } : {}),
             ...(bytes !== undefined ? { bytes } : {}),
         };
     });
-    output.result({ ok: true, kind: 'music', ...result });
+    const result = lane.rename(shared);
+    output.result({ ok: true, kind: lane.type, ...result });
     if (options.world) {
-        runDeps.log(`Play it from game code with engine.playMusic('${result.musicId}').`);
+        runDeps.log(lane.playHint(shared.id));
         runDeps.log(DEV_VIEW_RELOADS);
     }
     return result;
 }
+/**
+ * `generate music` is the one `generate` lane with two outputs a creator may want separately: the
+ * world.json asset (the default — what a game plays as its bed) and the MP3 file (`--out`, what a
+ * video editor or `bitmagic trailer make` wants). `--no-world` keeps the asset out of the game
+ * for the file-only case, so a trailer bed is not registered as a track the game never plays.
+ */
+export function runMusicGeneration(options) {
+    return runAudioGeneration({
+        type: 'music',
+        noun: 'music',
+        output: 'The track',
+        missingUrls: 'no track URLs',
+        fileLabel: 'track',
+        read: ({ music }) => (music
+            ? { url: music.musicUrl, originalUrl: music.originalUrl, id: music.musicId, durationSeconds: music.durationSeconds }
+            : undefined),
+        rename: ({ url, id, ...rest }) => ({ ...rest, musicUrl: url, musicId: id }),
+        playHint: (musicId) => `Play it from game code with engine.playMusic('${musicId}').`,
+    }, options);
+}
 /**
  * `generate speech` has the same two-outputs shape as `generate music`, and for a sharper reason:
  * the world.json asset is a line an NPC speaks (`engine.playSound`), while the MP3 is the input
  * `tools/lipsync/make_line.py --audio` needs to cut mouth cues from. A creator rigging a talking
  * character wants the file and NOT the asset, so `--no-world` is a first-class path here rather
  * than an escape hatch.
- *
- * Cannot go through {@link runAssetGeneration} because that always applies the patches and never
- * downloads; it shares {@link requestAssetWithJobRecord} so the request, the job record and the
- * "world.json is unchanged" failure contract are the same as every other lane's.
  */
-export async function runSpeechGeneration(options) {
-    const output = createOutput(options.json);
-    const runDeps = options.deps ?? defaultDeps(options.json);
-    const outPath = options.out === undefined ? undefined : path.resolve(options.out);
-    const result = await requestAssetWithJobRecord('speech', 'speech', options.body, runDeps, async (outcome, worldPath, log) => {
-        if (!outcome.speech) {
-            throw new CliError('The server reported the speech as generated but sent no audio URLs. world.json is unchanged.');
-        }
-        const { speech } = outcome;
-        let patchesApplied = 0;
-        if (options.world) {
-            let applyResult;
-            try {
-                applyResult = applyPatchesToWorld(worldPath, outcome.patches);
-            }
-            catch (error) {
-                throw decoratedError(error, (message) => `Generated speech successfully, but could not write it into world.json: ${message} `
-                    + 'world.json is unchanged — the line was generated (and may have been billed) but is not '
-                    + `yet in your project. It is at ${speech.originalUrl}.`);
-            }
-            patchesApplied = applyResult.applied;
-            log(`Generated speech (${speech.durationSeconds.toFixed(1)}s): ${outcome.message}`);
-            for (const line of applyResult.summary)
-                runDeps.log(`  - ${line}`);
-            runDeps.log(worldUpdatedLine(patchesApplied));
-        }
-        else {
-            log(`Generated speech (${speech.durationSeconds.toFixed(1)}s): ${outcome.message}`);
-            runDeps.log('world.json is unchanged (--no-world).');
-        }
-        let bytes;
-        if (outPath !== undefined) {
-            try {
-                bytes = await downloadAudioFile(speech.originalUrl, outPath, runDeps.fetch, 'line');
-            }
-            catch (error) {
-                // The line is generated, billed, and (unless --no-world) already in world.json; only the
-                // local copy is missing, and the message has to say so or the creator regenerates.
-                throw decoratedError(error, (message) => `${message} The line was generated${options.world ? ' and is in world.json' : ''}; only saving `
-                    + 'the local copy failed.');
-            }
-            runDeps.log(`Saved ${outPath} (${Math.round(bytes / 1024)} KB).`);
-        }
-        return {
-            speechUrl: speech.speechUrl,
-            originalUrl: speech.originalUrl,
-            speechId: speech.speechId,
-            durationSeconds: speech.durationSeconds,
-            patchesApplied,
-            ...(outPath !== undefined ? { file: outPath } : {}),
-            ...(bytes !== undefined ? { bytes } : {}),
-        };
-    });
-    output.result({ ok: true, kind: 'speech', ...result });
-    if (options.world) {
-        runDeps.log(`Play it from game code with engine.playSound('${result.speechId}').`);
-        runDeps.log(DEV_VIEW_RELOADS);
-    }
-    return result;
+export function runSpeechGeneration(options) {
+    return runAudioGeneration({
+        type: 'speech',
+        noun: 'speech',
+        output: 'The line',
+        missingUrls: 'no audio URLs',
+        fileLabel: 'line',
+        read: ({ speech }) => (speech
+            ? { url: speech.speechUrl, originalUrl: speech.originalUrl, id: speech.speechId, durationSeconds: speech.durationSeconds }
+            : undefined),
+        rename: ({ url, id, ...rest }) => ({ ...rest, speechUrl: url, speechId: id }),
+        playHint: (speechId) => `Play it from game code with engine.playSound('${speechId}').`,
+    }, options);
 }
 /**
  * Refuses `--voxel-grid` alongside `--mesh`, rather than ignoring it.