@helix3/helix-cli 0.1.13-helix3.81 → 0.1.13-helix3.82

package/dist/index.js

@@ -788,6 +788,255 @@ achievement
         fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+// --- helix product ---------------------------------------------------------
+// The registry `Helix.purchase` sells from: a world can only sell what its
+// creator registered here, and registering was API/website-only until these
+// commands. ORDER, the INVERSE of achievements: publish the world FIRST — the
+// creator registry lists Published worlds only, and nobody can buy inside a
+// world they cannot enter. Worlds are named by SLUG, products by their key.
+const product = program
+    .command('product')
+    .description("Register and manage a world's in-world products (what Helix.purchase sells). Publish the world FIRST — unlike achievements, a product only counts once the world is Published");
+function renderProduct(p, indent = '  ') {
+    // An authored-grants product's stored type is server-DERIVED — the effect list is the truth,
+    // so the "your world applies it" hint only fits legacy consumables.
+    const lines = [
+        `${indent}price:    ${p.priceLix} LIX${p.isFree ? ' — free "Claim"' : ''}`,
+        `${indent}type:     ${p.type}${p.type === 'consumable' && !p.grants ? ' — your world applies the effect on a Granted result' : ''}`,
+    ];
+    // The key is how world code names it; without one the uuid is the only handle.
+    lines.push(`${indent}buy as:   ${p.key ? `pkey:${p.key}` : `${p.id} (no key — register with --key next time)`}`);
+    if (p.grants) {
+        const effects = p.grants.map((g) => g.kind === 'item'
+            ? `item ${g.itemId}${(g.quantity ?? 1) > 1 ? ` ×${g.quantity}` : ''}`
+            : g.kind === 'pass'
+                ? `pass ${g.passKey ?? p.key ?? '(product key)'}${g.durationSeconds ? ` for ${g.durationSeconds}s` : ''}`
+                : `currency ${g.code} +${g.amount}`);
+        lines.push(`${indent}grants:   ${effects.length ? effects.join(', ') : 'nothing — a tip jar'}`);
+    }
+    else if (p.itemId) {
+        lines.push(`${indent}grants:   item ${p.itemId}`);
+    }
+    if (p.maxPerUser !== null)
+        lines.push(`${indent}max/user: ${p.maxPerUser}`);
+    if (!p.active)
+        lines.push(`${indent}active:   no — off sale, existing owners keep theirs`);
+    lines.push(`${indent}id:       ${p.id}`);
+    return lines;
+}
+// The effect list arrives as one JSON string. Only "is it an array" is checked
+// here — every shape rule belongs to the vocabulary, which reports them together.
+function parseGrantsFlag(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        fail(`✖ --grants must be a JSON array of effects — that is not valid JSON (${detail})`);
+    }
+    if (!Array.isArray(parsed)) {
+        fail('✖ --grants must be a JSON array of effects, e.g. \'[{"kind":"currency","code":"coin","amount":500}]\' (several = a bundle, [] = a tip jar)');
+    }
+    return parsed;
+}
+product
+    .command('register')
+    .description('Register a purchasable product on one of your PUBLISHED worlds — one round trip, live as soon as it returns')
+    .argument('<world-slug>', 'the world that sells it')
+    .requiredOption('--title <title>', 'name the purchase popup shows the player (max 120 chars)')
+    .requiredOption('--price <lix>', 'price in LIX; 0 registers a free "Claim" (a confirmation, no spend)')
+    .option('--type <type>', `what the purchase does: ${lib_1.WORLD_PRODUCT_TYPES.join(' | ')} — required unless you author --grants`)
+    .option('--grants <json>', `JSON array of what the purchase hands over, instead of --type/--item-id: item | pass | currency, max ${lib_1.MAX_GRANT_EFFECTS} ` +
+    "(e.g. '[{\"kind\":\"currency\",\"code\":\"coin\",\"amount\":500}]'; [] = a tip jar). Fixed at registration")
+    .option('--key <key>', 'stable slug world code buys as `pkey:<key>` (max 64 chars, lowercase a-z0-9_-); it cannot be renamed later')
+    .option('--description <text>', 'what the player is buying')
+    .option('--item-id <uuid>', 'the universal item handed over — REQUIRED for item_grant and non_consumable, refused for consumable')
+    .option('--max-per-user <n>', 'cap on how many one player may own (whole number >= 1)')
+    .option('--dry-run', 'validate everything locally and print what WOULD be sent; no network, works logged out')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, opts) => {
+    const registration = {
+        worldSlug,
+        key: opts.key,
+        title: opts.title,
+        description: opts.description,
+        priceLix: Number(opts.price),
+        type: opts.type,
+        itemId: opts.itemId,
+        grants: opts.grants !== undefined ? parseGrantsFlag(opts.grants) : undefined,
+        maxPerUser: opts.maxPerUser !== undefined ? parseWholeNumber(opts.maxPerUser, '--max-per-user') : undefined,
+    };
+    // Stops before ANY network call, so it works logged out — the point is to
+    // check the vocabulary and the type/item coherence, not the account.
+    if (opts.dryRun) {
+        try {
+            const plan = (0, lib_1.planProductRegistration)(registration);
+            if (opts.json) {
+                console.log(JSON.stringify({ dryRun: true, worldSlug, fields: plan.fields, warnings: plan.warnings }, null, 2));
+                return;
+            }
+            console.log('✔ Dry run — nothing sent.');
+            console.log(`  POST /api/v1/iwp/products (worldId of "${worldSlug}")`);
+            console.log(`  body:   ${JSON.stringify(plan.fields, null, 2).replace(/\n/g, '\n          ')}`);
+            for (const warning of plan.warnings)
+                console.log(`  • ${warning}`);
+            if (!(0, lib_1.authStatus)().loggedIn)
+                console.log('  • not logged in — run `helix login` before the real registration');
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to register:\n${mismatch}`);
+    try {
+        const { product: created, warnings } = await (0, lib_1.registerProduct)(registration, creds, {
+            onProgress: (msg) => !opts.json && console.log(msg),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ product: created, warnings }, null, 2));
+            return;
+        }
+        console.log(`✔ Registered "${created.title}" on ${worldSlug}`);
+        for (const line of renderProduct(created))
+            console.log(line);
+        for (const warning of warnings)
+            console.log(`  ⚠ ${warning}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('list')
+    .description("List a world's registered products, or — with no slug — every PUBLISHED world of yours and what it sells")
+    .argument('[world-slug]', 'the world that sells them; omit for all your published worlds')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, opts) => {
+    const creds = requireAuth();
+    try {
+        if (!worldSlug) {
+            const worlds = await (0, lib_1.listProductWorlds)(creds);
+            if (opts.json) {
+                console.log(JSON.stringify(worlds, null, 2));
+                return;
+            }
+            if (worlds.length === 0) {
+                console.log('You have no published worlds — `helix publish` one first; a product on a draft world is unbuyable.');
+                return;
+            }
+            for (const world of worlds) {
+                console.log(`\n${world.slug} — "${world.title}" (${world.products.length} product${world.products.length === 1 ? '' : 's'})`);
+                for (const row of world.products) {
+                    console.log(`  ${row.key ?? row.id} — "${row.title}" · ${row.priceLix} LIX · ${row.type}${row.active ? '' : ' [INACTIVE]'}`);
+                }
+            }
+            return;
+        }
+        const rows = await (0, lib_1.listProducts)(worldSlug, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(`No products registered on "${worldSlug}" yet — register one with: helix product register ${worldSlug} --title … --type … --price …`);
+            return;
+        }
+        console.log(`${rows.length} product${rows.length === 1 ? '' : 's'} on ${worldSlug}:`);
+        for (const row of rows) {
+            console.log(`\n  ${row.key ?? row.id} — "${row.title}"${row.active ? '' : ' [INACTIVE]'}`);
+            console.log(`    ${row.priceLix} LIX · ${row.type}${row.itemId ? ` · grants ${row.itemId}` : ''}${row.maxPerUser !== null ? ` · max ${row.maxPerUser}/user` : ''}`);
+        }
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('update')
+    .description('Patch a registered product. The key and the type are fixed at registration — world code buys the key, and changing what a purchase hands over would re-label every copy already sold')
+    .argument('<world-slug>', 'the world that sells it')
+    .argument('<product>', 'the product key (or its uuid, if you registered it without a key)')
+    .option('--title <title>', 'new title')
+    .option('--description <text>', 'new description')
+    .option('--price <lix>', 'new price in LIX; 0 makes it a free "Claim"')
+    .option('--max-per-user <n>', 'new per-player ownership cap (whole number >= 1)')
+    .option('--active <true|false>', 'false takes it off sale — existing owners keep theirs, nobody new can buy it')
+    .option('--dry-run', 'validate the patch locally and print what WOULD be sent; no network, works logged out')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, ref, opts) => {
+    const patch = {
+        title: opts.title,
+        description: opts.description,
+        priceLix: opts.price !== undefined ? Number(opts.price) : undefined,
+        maxPerUser: opts.maxPerUser !== undefined ? parseWholeNumber(opts.maxPerUser, '--max-per-user') : undefined,
+        active: opts.active !== undefined ? parseBooleanFlag(opts.active, '--active') : undefined,
+    };
+    if (opts.dryRun) {
+        try {
+            const body = (0, lib_1.buildProductUpdate)(patch);
+            if (opts.json) {
+                console.log(JSON.stringify({ dryRun: true, worldSlug, product: ref, patch: body }, null, 2));
+                return;
+            }
+            console.log('✔ Dry run — nothing sent.');
+            console.log(`  PATCH /api/v1/iwp/products/<id of "${ref}" on ${worldSlug}>`);
+            console.log(`  body:  ${JSON.stringify(body, null, 2).replace(/\n/g, '\n         ')}`);
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to update:\n${mismatch}`);
+    try {
+        const updated = await (0, lib_1.updateProduct)(worldSlug, ref, patch, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        console.log(`✔ Updated "${updated.title}" on ${worldSlug}`);
+        for (const line of renderProduct(updated))
+            console.log(line);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+product
+    .command('set-active')
+    .description('Put a product on sale or take it off. The row stays either way, so past purchases and their grants keep resolving')
+    .argument('<world-slug>', 'the world that sells it')
+    .argument('<product>', 'the product key (or its uuid)')
+    .argument('<true|false>', 'true puts it on sale, false takes it off')
+    .option('--json', 'machine-readable output')
+    .action(async (worldSlug, ref, value, opts) => {
+    const active = parseBooleanFlag(value, '<true|false>');
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to change what a world sells:\n${mismatch}`);
+    try {
+        const updated = await (0, lib_1.setProductActive)(worldSlug, ref, active, creds);
+        if (opts.json) {
+            console.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        console.log(`✔ "${updated.title}" is ${updated.active ? 'ON SALE' : 'off sale'} on ${worldSlug}`);
+        for (const line of renderProduct(updated))
+            console.log(line);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 // --- helix assets ----------------------------------------------------------
 // Operational asset work lives here. MCP surfaces may point agents at these
 // commands, but they must not reimplement Vault, Dreamer, download, or receipt