@optima-chat/dev-skills 0.7.33 → 0.7.36

package/bin/helpers/plugin/set-paid.ts

@@ -0,0 +1,69 @@
+import { callSkills, validateEnv } from '../billing-http';
+import { confirmIfProd } from '../confirm-prompt';
+
+interface SetPaidArgs {
+  slug: string;
+  paid: boolean;
+  yes: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): SetPaidArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin set-paid --slug <slug> --paid true|false [options]
+
+Required:
+  --slug <slug>
+  --paid true|false    Sets Plugin.isPaid (the user-facing paid/free gate)
+
+Optional:
+  --yes                Skip prod confirmation prompt (no-op on stage)
+  --env stage|prod     (default: stage)
+
+Note: salesUrl is NOT settable here (skills PATCH is strict; salesUrl is
+publish-time-only via plugin.json metadata). When isPaid=true and salesUrl is
+null, the 402 falls back to sales.optima.onl.`);
+    process.exit(0);
+  }
+  const out: Partial<SetPaidArgs> = { env: 'stage', yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--paid':
+        if (next !== 'true' && next !== 'false') throw new Error('--paid must be true or false');
+        out.paid = next === 'true'; i++; break;
+      case '--yes': out.yes = true; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  if (out.paid === undefined) throw new Error('--paid required (true|false)');
+  return out as SetPaidArgs;
+}
+
+export async function runSetPaid(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  await confirmIfProd(
+    args.env,
+    `Action: set isPaid=${args.paid} on plugin '${args.slug}' (${args.env.toUpperCase()})`,
+    args.yes,
+  );
+
+  console.log(`\n💰 Setting isPaid=${args.paid} on ${args.slug} (${args.env.toUpperCase()})...`);
+  const res = await callSkills(
+    args.env,
+    'PATCH',
+    `/api/admin/plugins/${encodeURIComponent(args.slug)}`,
+    { isPaid: args.paid },
+  );
+  console.log(`✓ Updated plugin (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+  if (args.paid) {
+    console.log(`\nℹ️  Reminder: ensure a billing Product + channel exists for '${args.slug}' (optima-product) or users will 402 with no purchase path. salesUrl is publish-time-only (currently shown above).`);
+  }
+}

package/bin/helpers/plugin/show.ts

@@ -0,0 +1,42 @@
+import { callSkills, validateEnv } from '../billing-http';
+
+interface ShowArgs {
+  slug: string;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ShowArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-plugin show --slug <slug> [options]
+
+Required:
+  --slug <slug>
+
+Optional:
+  --env stage|prod   (default: stage)
+
+Note: reads the public GET /api/plugins/:slug — shows isPaid, salesUrl, and
+descriptive fields, but NOT defaultForUser / status / trustLevel (public
+endpoint omits them). Returns 404 for non-ACTIVE plugins.`);
+    process.exit(0);
+  }
+  const out: Partial<ShowArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--slug': out.slug = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.slug) throw new Error('--slug required');
+  return out as ShowArgs;
+}
+
+export async function runShow(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const res = await callSkills(args.env, 'GET', `/api/plugins/${encodeURIComponent(args.slug)}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/plugin.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { runShow } from './plugin/show';
+import { runSetPaid } from './plugin/set-paid';
+import { runSetDefault } from './plugin/set-default';
+
+function printHelp() {
+  console.log(`Usage: optima-plugin <subcommand> [options]
+
+Subcommands:
+  show          Show a plugin's marketplace state (isPaid, salesUrl, ... ACTIVE plugins only)
+  set-paid      Flip a plugin's isPaid flag (the user-facing paid/free gate)
+  set-default   Flip a plugin's defaultForUser flag
+
+Run 'optima-plugin <subcommand> --help' for subcommand-specific options.`);
+}
+
+async function main() {
+  const [, , subcommand, ...rest] = process.argv;
+  if (!subcommand || subcommand === '-h' || subcommand === '--help') { printHelp(); process.exit(0); }
+  switch (subcommand) {
+    case 'show': await runShow(rest); break;
+    case 'set-paid': await runSetPaid(rest); break;
+    case 'set-default': await runSetDefault(rest); break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/bin/helpers/product/add-channel.ts

@@ -0,0 +1,78 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface AddChannelArgs {
+  key: string;
+  provider: string;
+  stripePriceId: string;
+  priceCents: number;
+  currency: string;
+  enabled?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): AddChannelArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product add-channel --key <productKey> --provider STRIPE --stripe-price-id <price_xxx> --price-cents N --currency USD [options]
+
+Required:
+  --key <productKey>
+  --provider STRIPE                v1 CLI accepts only STRIPE (schema supports more)
+  --stripe-price-id <price_xxx>    Pre-created in Stripe Dashboard; wire-mapped to externalProductId
+  --price-cents N                  MUST be > 0; should match Stripe Price's unit_amount (NOT verified)
+  --currency USD                   Should match Stripe Price's currency (NOT verified)
+
+Optional:
+  --enabled true|false             default: true
+  --metadata '<json>'
+  --env stage|prod                 (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<AddChannelArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--provider': out.provider = next; i++; break;
+      case '--stripe-price-id': out.stripePriceId = next; i++; break;
+      case '--price-cents': out.priceCents = parseInt(next, 10); i++; break;
+      case '--currency': out.currency = next; i++; break;
+      case '--enabled': out.enabled = next === 'true'; i++; break;
+      case '--metadata': out.metadata = JSON.parse(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.key) throw new Error('--key required');
+  if (!out.provider) throw new Error('--provider required');
+  if (out.provider !== 'STRIPE') throw new Error(`v1 CLI accepts only --provider STRIPE (got ${out.provider})`);
+  if (!out.stripePriceId) throw new Error('--stripe-price-id required');
+  if (out.priceCents === undefined || !Number.isFinite(out.priceCents)) throw new Error('--price-cents required (integer)');
+  if (out.priceCents <= 0) throw new Error('--price-cents must be > 0');
+  if (!out.currency) throw new Error('--currency required');
+  return out as AddChannelArgs;
+}
+
+export async function runAddChannel(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const body: Record<string, unknown> = {
+    provider: args.provider,
+    externalProductId: args.stripePriceId,
+    priceCents: args.priceCents,
+    currency: args.currency,
+  };
+  if (args.enabled !== undefined) body.enabled = args.enabled;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  console.log(`\n💳 Adding ${args.provider} channel to ${args.key} on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(
+    args.env,
+    'POST',
+    `/api/billing/admin/products/${encodeURIComponent(args.key)}/channels`,
+    body,
+  );
+  console.log(`✓ Created Channel (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/create.ts

@@ -0,0 +1,96 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface CreateArgs {
+  key: string;
+  plugins: string[];
+  type: string;
+  name?: string;
+  description?: string;
+  refundWindowDays?: number;
+  refundProrateMaxDays?: number;
+  bundledPlanId?: string;
+  bundledDurationDays?: number;
+  revokeBundledOnRefund?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): CreateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product create --key <productKey> --plugins <slug1,slug2,...> --type <ProductType> [options]
+
+Required:
+  --key <productKey>             Unique slug
+  --plugins <slug1,slug2,...>    Comma-separated, >=1 plugin slug
+  --type <ProductType>           Only ONE_SHOT_SKILL accepted by v1 CLI policy
+
+Optional:
+  --name "..."                   Convenience flag, folded into metadata.name
+  --description "..."            Convenience flag, folded into metadata.description
+  --refund-window-days N
+  --refund-prorate-max-days N
+  --bundled-plan-id <planId>     (joint with --bundled-duration-days)
+  --bundled-duration-days N
+  --revoke-bundled-on-refund true|false
+  --metadata '<json>'            JSON object stored in product.metadata
+  --env stage|prod               (default: stage)`);
+    process.exit(0);
+  }
+
+  const out: Partial<CreateArgs> = { env: 'stage', revokeBundledOnRefund: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--plugins': out.plugins = next.split(',').map((s) => s.trim()).filter(Boolean); i++; break;
+      case '--type': out.type = next; i++; break;
+      case '--name': out.name = next; i++; break;
+      case '--description': out.description = next; i++; break;
+      case '--refund-window-days': out.refundWindowDays = parseInt(next, 10); i++; break;
+      case '--refund-prorate-max-days': out.refundProrateMaxDays = parseInt(next, 10); i++; break;
+      case '--bundled-plan-id': out.bundledPlanId = next; i++; break;
+      case '--bundled-duration-days': out.bundledDurationDays = parseInt(next, 10); i++; break;
+      case '--revoke-bundled-on-refund': out.revokeBundledOnRefund = next === 'true'; i++; break;
+      case '--metadata': out.metadata = JSON.parse(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+
+  if (!out.key) throw new Error('--key required');
+  if (!out.plugins || out.plugins.length === 0) throw new Error('--plugins required (>=1 slug)');
+  if (!out.type) throw new Error('--type required');
+  if (out.type !== 'ONE_SHOT_SKILL') {
+    throw new Error(`v1 CLI accepts only --type ONE_SHOT_SKILL (got ${out.type}). See spec §5.1.`);
+  }
+  if ((out.bundledPlanId == null) !== (out.bundledDurationDays == null)) {
+    throw new Error('--bundled-plan-id and --bundled-duration-days must be set together');
+  }
+  return out as CreateArgs;
+}
+
+export async function runCreate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+
+  const body: Record<string, unknown> = {
+    productKey: args.key,
+    type: args.type,
+    pluginSlugs: args.plugins,
+  };
+  if (args.name !== undefined) body.name = args.name;
+  if (args.description !== undefined) body.description = args.description;
+  if (args.refundWindowDays !== undefined) body.refundWindowDays = args.refundWindowDays;
+  if (args.refundProrateMaxDays !== undefined) body.refundProrateMaxDays = args.refundProrateMaxDays;
+  if (args.bundledPlanId !== undefined) body.bundledPlanId = args.bundledPlanId;
+  if (args.bundledDurationDays !== undefined) body.bundledDurationDays = args.bundledDurationDays;
+  if (args.revokeBundledOnRefund !== undefined) body.revokeBundledOnRefund = args.revokeBundledOnRefund;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  console.log(`\n🎁 Creating product ${args.key} (${args.plugins.length} plugin(s)) on ${args.env.toUpperCase()}...`);
+
+  const res = await callBilling(args.env, 'POST', '/api/billing/admin/products', body);
+  console.log(`✓ Created Product (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/show.ts

@@ -0,0 +1,43 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ShowArgs {
+  key: string;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ShowArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product show --key <productKey> [options]
+
+Required:
+  --key <productKey>
+
+Optional:
+  --env stage|prod                 (default: stage)
+
+Note: returns the bare Product row only — productPlugins and channels arrays
+are NOT included (billing's GET /api/internal/products/:key is a plain
+findUnique with no include). To inspect channels/plugins today, query the DB
+directly via optima-query-db. Tracked as follow-up in spec §7.`);
+    process.exit(0);
+  }
+  const out: Partial<ShowArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.key) throw new Error('--key required');
+  return out as ShowArgs;
+}
+
+export async function runShow(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const res = await callBilling(args.env, 'GET', `/api/internal/products/${encodeURIComponent(args.key)}`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/toggle-channel.ts

@@ -0,0 +1,56 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface ToggleArgs {
+  key: string;
+  provider: string;
+  enabled: boolean;
+  env: string;
+}
+
+function parseArgs(argv: string[]): ToggleArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product toggle-channel --key <productKey> --provider STRIPE --enabled true|false [options]
+
+Required:
+  --key <productKey>
+  --provider STRIPE                v1 CLI accepts only STRIPE
+  --enabled true|false
+
+Optional:
+  --env stage|prod                 (default: stage)`);
+    process.exit(0);
+  }
+  const out: Partial<ToggleArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--provider': out.provider = next; i++; break;
+      case '--enabled':
+        if (next !== 'true' && next !== 'false') throw new Error('--enabled must be true or false');
+        out.enabled = next === 'true'; i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.key) throw new Error('--key required');
+  if (!out.provider) throw new Error('--provider required');
+  if (out.provider !== 'STRIPE') throw new Error(`v1 CLI accepts only --provider STRIPE (got ${out.provider})`);
+  if (out.enabled === undefined) throw new Error('--enabled required');
+  return out as ToggleArgs;
+}
+
+export async function runToggleChannel(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  console.log(`\n🔁 Setting ${args.provider} channel enabled=${args.enabled} on ${args.key} (${args.env.toUpperCase()})...`);
+  const res = await callBilling(
+    args.env,
+    'PATCH',
+    `/api/billing/admin/products/${encodeURIComponent(args.key)}/channels/${args.provider}`,
+    { enabled: args.enabled },
+  );
+  console.log(`✓ Channel updated (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product/update.ts

@@ -0,0 +1,72 @@
+import { callBilling, validateEnv } from '../billing-http';
+
+interface UpdateArgs {
+  key: string;
+  refundWindowDays?: number | null;
+  refundProrateMaxDays?: number | null;
+  bundledPlanId?: string | null;
+  bundledDurationDays?: number | null;
+  revokeBundledOnRefund?: boolean;
+  metadata?: Record<string, unknown>;
+  env: string;
+}
+
+function parseArgs(argv: string[]): UpdateArgs {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    console.log(`Usage: optima-product update --key <productKey> [options]
+
+Required:
+  --key <productKey>
+
+Optional (PATCH — only included fields are updated):
+  --refund-window-days N | null
+  --refund-prorate-max-days N | null
+  --bundled-plan-id <planId> | null    (joint with --bundled-duration-days)
+  --bundled-duration-days N | null
+  --revoke-bundled-on-refund true|false
+  --metadata '<json>'                   FULL REPLACE — Prisma does not deep-merge JSON
+  --env stage|prod                      (default: stage)
+
+Note: productKey, type, and pluginSlugs are immutable post-create. To change plugin
+membership, create a new Product with a new key.`);
+    process.exit(0);
+  }
+  const out: Partial<UpdateArgs> = { env: 'stage' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    const parseNullable = (v: string): number | null => v === 'null' ? null : parseInt(v, 10);
+    switch (a) {
+      case '--key': out.key = next; i++; break;
+      case '--refund-window-days': out.refundWindowDays = parseNullable(next); i++; break;
+      case '--refund-prorate-max-days': out.refundProrateMaxDays = parseNullable(next); i++; break;
+      case '--bundled-plan-id': out.bundledPlanId = next === 'null' ? null : next; i++; break;
+      case '--bundled-duration-days': out.bundledDurationDays = parseNullable(next); i++; break;
+      case '--revoke-bundled-on-refund': out.revokeBundledOnRefund = next === 'true'; i++; break;
+      case '--metadata': out.metadata = JSON.parse(next); i++; break;
+      case '--env': out.env = next; i++; break;
+      default: throw new Error(`Unknown arg: ${a}`);
+    }
+  }
+  if (!out.key) throw new Error('--key required');
+  return out as UpdateArgs;
+}
+
+export async function runUpdate(argv: string[]): Promise<void> {
+  const args = parseArgs(argv);
+  validateEnv(args.env);
+  const body: Record<string, unknown> = {};
+  if (args.refundWindowDays !== undefined) body.refundWindowDays = args.refundWindowDays;
+  if (args.refundProrateMaxDays !== undefined) body.refundProrateMaxDays = args.refundProrateMaxDays;
+  if (args.bundledPlanId !== undefined) body.bundledPlanId = args.bundledPlanId;
+  if (args.bundledDurationDays !== undefined) body.bundledDurationDays = args.bundledDurationDays;
+  if (args.revokeBundledOnRefund !== undefined) body.revokeBundledOnRefund = args.revokeBundledOnRefund;
+  if (args.metadata !== undefined) body.metadata = args.metadata;
+
+  if (Object.keys(body).length === 0) throw new Error('At least one updatable field must be passed');
+
+  console.log(`\n✏️  Updating product ${args.key} on ${args.env.toUpperCase()}...`);
+  const res = await callBilling(args.env, 'PATCH', `/api/billing/admin/products/${encodeURIComponent(args.key)}`, body);
+  console.log(`✓ Updated Product (HTTP ${res.status}):`);
+  console.log(JSON.stringify(res.body, null, 2));
+}

package/bin/helpers/product.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { runCreate } from './product/create';
+import { runUpdate } from './product/update';
+import { runAddChannel } from './product/add-channel';
+import { runToggleChannel } from './product/toggle-channel';
+import { runShow } from './product/show';
+
+const SUBCOMMANDS = ['create', 'update', 'add-channel', 'toggle-channel', 'show'] as const;
+
+function printHelp() {
+  console.log(`Usage: optima-product <subcommand> [options]
+
+Subcommands:
+  create           Create a Product bundling 1+ plugin slugs
+  update           Patch refund policy / metadata on an existing Product
+  add-channel      Attach a payment channel (Stripe Price ID) to a Product
+  toggle-channel   Enable/disable an existing channel
+  show             Show a Product's bare row (note: does NOT include plugins/channels)
+
+Run 'optima-product <subcommand> --help' for subcommand-specific options.`);
+}
+
+async function main() {
+  const [, , subcommand, ...rest] = process.argv;
+  if (!subcommand || subcommand === '-h' || subcommand === '--help') {
+    printHelp();
+    process.exit(0);
+  }
+  switch (subcommand) {
+    case 'create': await runCreate(rest); break;
+    case 'update': await runUpdate(rest); break;
+    case 'add-channel': await runAddChannel(rest); break;
+    case 'toggle-channel': await runToggleChannel(rest); break;
+    case 'show': await runShow(rest); break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});