@hasna/microservices 0.0.4 → 0.0.6

package/microservices/microservice-subscriptions/src/cli/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { Command } from "commander";
+import { readFileSync, writeFileSync } from "node:fs";
 import {
   createPlan,
   getPlan,
@@ -19,6 +20,20 @@ import {
   getChurnRate,
   listExpiring,
   getSubscriberStats,
+  pauseSubscriber,
+  resumeSubscriber,
+  extendTrial,
+  createDunning,
+  listDunning,
+  updateDunning,
+  bulkImportSubscribers,
+  exportSubscribers,
+  parseImportCsv,
+  getLtv,
+  getNrr,
+  getCohortReport,
+  comparePlans,
+  getExpiringRenewals,
 } from "../db/subscriptions.js";
 
 const program = new Command();
@@ -281,8 +296,308 @@ subCmd
     }
   });
 
+// --- Pause / Resume ---
+
+subCmd
+  .command("pause")
+  .description("Pause a subscription")
+  .argument("<id>", "Subscriber ID")
+  .option("--resume-date <date>", "Scheduled resume date (YYYY-MM-DD)")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const subscriber = pauseSubscriber(id, opts.resumeDate);
+    if (!subscriber) {
+      console.error(`Subscriber '${id}' not found or cannot be paused.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(subscriber, null, 2));
+    } else {
+      console.log(`Paused subscription for ${subscriber.customer_name}`);
+      if (subscriber.resume_at) console.log(`  Scheduled resume: ${subscriber.resume_at}`);
+    }
+  });
+
+subCmd
+  .command("resume")
+  .description("Resume a paused subscription")
+  .argument("<id>", "Subscriber ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const subscriber = resumeSubscriber(id);
+    if (!subscriber) {
+      console.error(`Subscriber '${id}' not found or not paused.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(subscriber, null, 2));
+    } else {
+      console.log(`Resumed subscription for ${subscriber.customer_name}`);
+    }
+  });
+
+// --- Trial Extension ---
+
+subCmd
+  .command("extend-trial")
+  .description("Extend a subscriber's trial period")
+  .argument("<id>", "Subscriber ID")
+  .requiredOption("--days <days>", "Number of days to extend")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const subscriber = extendTrial(id, parseInt(opts.days));
+    if (!subscriber) {
+      console.error(`Subscriber '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(subscriber, null, 2));
+    } else {
+      console.log(`Extended trial for ${subscriber.customer_name} by ${opts.days} days`);
+      console.log(`  New trial end: ${subscriber.trial_ends_at}`);
+    }
+  });
+
+// --- Bulk Import/Export ---
+
+subCmd
+  .command("import")
+  .description("Bulk import subscribers from a CSV file")
+  .requiredOption("--file <path>", "Path to CSV file")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const csvContent = readFileSync(opts.file, "utf-8");
+    const data = parseImportCsv(csvContent);
+    const imported = bulkImportSubscribers(data);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ imported: imported.length, subscribers: imported }, null, 2));
+    } else {
+      console.log(`Imported ${imported.length} subscriber(s) from ${opts.file}`);
+      for (const s of imported) {
+        console.log(`  ${s.customer_name} <${s.customer_email}> (${s.id})`);
+      }
+    }
+  });
+
+subCmd
+  .command("export")
+  .description("Export subscribers")
+  .option("--format <format>", "Output format (csv/json)", "csv")
+  .option("--file <path>", "Output file path (prints to stdout if omitted)")
+  .action((opts) => {
+    const output = exportSubscribers(opts.format as "csv" | "json");
+    if (opts.file) {
+      writeFileSync(opts.file, output, "utf-8");
+      console.log(`Exported to ${opts.file}`);
+    } else {
+      console.log(output);
+    }
+  });
+
+// --- Dunning ---
+
+const dunningCmd = program
+  .command("dunning")
+  .description("Dunning attempt management");
+
+dunningCmd
+  .command("list")
+  .description("List dunning attempts")
+  .option("--subscriber <id>", "Filter by subscriber ID")
+  .option("--status <status>", "Filter by status")
+  .option("--limit <n>", "Limit results", "20")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const attempts = listDunning({
+      subscriber_id: opts.subscriber,
+      status: opts.status,
+      limit: parseInt(opts.limit),
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(attempts, null, 2));
+    } else {
+      if (attempts.length === 0) {
+        console.log("No dunning attempts found.");
+        return;
+      }
+      for (const a of attempts) {
+        console.log(`  [${a.created_at}] #${a.attempt_number} ${a.status} — subscriber: ${a.subscriber_id}`);
+        if (a.next_retry_at) console.log(`    Next retry: ${a.next_retry_at}`);
+      }
+      console.log(`\n${attempts.length} attempt(s)`);
+    }
+  });
+
+dunningCmd
+  .command("create")
+  .description("Create a dunning attempt")
+  .requiredOption("--subscriber <id>", "Subscriber ID")
+  .option("--attempt <n>", "Attempt number", "1")
+  .option("--status <status>", "Status", "pending")
+  .option("--next-retry <date>", "Next retry date")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const attempt = createDunning({
+      subscriber_id: opts.subscriber,
+      attempt_number: parseInt(opts.attempt),
+      status: opts.status,
+      next_retry_at: opts.nextRetry,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(attempt, null, 2));
+    } else {
+      console.log(`Created dunning attempt #${attempt.attempt_number} for subscriber ${attempt.subscriber_id}`);
+    }
+  });
+
+dunningCmd
+  .command("update")
+  .description("Update a dunning attempt")
+  .argument("<id>", "Dunning attempt ID")
+  .option("--status <status>", "New status")
+  .option("--next-retry <date>", "Next retry date")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const input: Record<string, unknown> = {};
+    if (opts.status) input.status = opts.status;
+    if (opts.nextRetry !== undefined) input.next_retry_at = opts.nextRetry;
+
+    const attempt = updateDunning(id, input);
+    if (!attempt) {
+      console.error(`Dunning attempt '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(attempt, null, 2));
+    } else {
+      console.log(`Updated dunning attempt ${attempt.id} — status: ${attempt.status}`);
+    }
+  });
+
 // --- Analytics ---
 
+program
+  .command("ltv")
+  .description("Show lifetime value per subscriber and average")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const result = getLtv();
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.subscribers.length === 0) {
+        console.log("No subscribers found.");
+        return;
+      }
+      console.log("Lifetime Value Report:");
+      for (const s of result.subscribers) {
+        console.log(`  ${s.customer_name} <${s.customer_email}> — $${s.ltv.toFixed(2)} (${s.months_active}mo on ${s.plan_name})`);
+      }
+      console.log(`\nAverage LTV: $${result.average_ltv.toFixed(2)}`);
+    }
+  });
+
+program
+  .command("nrr")
+  .description("Calculate net revenue retention for a month")
+  .requiredOption("--month <month>", "Month in YYYY-MM format")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const result = getNrr(opts.month);
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`NRR for ${result.month}:`);
+      console.log(`  Start MRR: $${result.start_mrr.toFixed(2)}`);
+      console.log(`  Expansion: +$${result.expansion.toFixed(2)}`);
+      console.log(`  Contraction: -$${result.contraction.toFixed(2)}`);
+      console.log(`  Churn: -$${result.churn.toFixed(2)}`);
+      console.log(`  NRR: ${result.nrr.toFixed(2)}%`);
+    }
+  });
+
+program
+  .command("cohort-report")
+  .description("Show cohort retention analysis")
+  .option("--months <n>", "Number of months to analyze", "6")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const report = getCohortReport(parseInt(opts.months));
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      if (report.length === 0) {
+        console.log("No cohort data available.");
+        return;
+      }
+      console.log("Cohort Retention Report:");
+      console.log("  Cohort     | Total | Retained | Retention");
+      console.log("  -----------|-------|----------|----------");
+      for (const c of report) {
+        console.log(`  ${c.cohort}   | ${String(c.total).padStart(5)} | ${String(c.retained).padStart(8)} | ${c.retention_rate.toFixed(1)}%`);
+      }
+    }
+  });
+
+planCmd
+  .command("compare")
+  .description("Compare two plans side by side")
+  .argument("<id1>", "First plan ID")
+  .argument("<id2>", "Second plan ID")
+  .option("--json", "Output as JSON", false)
+  .action((id1, id2, opts) => {
+    const result = comparePlans(id1, id2);
+    if (!result) {
+      console.error("One or both plans not found.");
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Plan Comparison:`);
+      console.log(`  ${result.plan1.name} vs ${result.plan2.name}`);
+      console.log(`  Price: $${result.plan1.price}/${result.plan1.interval} vs $${result.plan2.price}/${result.plan2.interval}`);
+      console.log(`  Price diff: $${result.price_diff} (${result.price_diff_pct > 0 ? "+" : ""}${result.price_diff_pct}%)`);
+      console.log(`  Interval match: ${result.interval_match ? "Yes" : "No"}`);
+      if (result.common_features.length) console.log(`  Common features: ${result.common_features.join(", ")}`);
+      if (result.features_only_in_plan1.length) console.log(`  Only in ${result.plan1.name}: ${result.features_only_in_plan1.join(", ")}`);
+      if (result.features_only_in_plan2.length) console.log(`  Only in ${result.plan2.name}: ${result.features_only_in_plan2.join(", ")}`);
+    }
+  });
+
+program
+  .command("expiring-renewals")
+  .description("List subscribers with renewals expiring soon")
+  .option("--days <days>", "Days ahead to check", "7")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const expiring = getExpiringRenewals(parseInt(opts.days));
+
+    if (opts.json) {
+      console.log(JSON.stringify(expiring, null, 2));
+    } else {
+      if (expiring.length === 0) {
+        console.log(`No renewals expiring in the next ${opts.days} days.`);
+        return;
+      }
+      for (const s of expiring) {
+        console.log(`  ${s.customer_name} <${s.customer_email}> — renews ${s.current_period_end}`);
+      }
+      console.log(`\n${expiring.length} upcoming renewal(s)`);
+    }
+  });
+
 program
   .command("mrr")
   .description("Get monthly recurring revenue")

package/microservices/microservice-subscriptions/src/db/migrations.ts

@@ -54,4 +54,72 @@ export const MIGRATIONS: MigrationEntry[] = [
       CREATE INDEX IF NOT EXISTS idx_events_occurred ON events(occurred_at);
     `,
   },
+  {
+    id: 2,
+    name: "add_paused_status_and_dunning",
+    sql: `
+      -- Recreate subscribers table with 'paused' in CHECK constraint
+      CREATE TABLE subscribers_new (
+        id TEXT PRIMARY KEY,
+        plan_id TEXT NOT NULL REFERENCES plans(id) ON DELETE RESTRICT,
+        customer_name TEXT NOT NULL,
+        customer_email TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('trialing', 'active', 'past_due', 'canceled', 'expired', 'paused')),
+        started_at TEXT NOT NULL DEFAULT (datetime('now')),
+        trial_ends_at TEXT,
+        current_period_start TEXT NOT NULL DEFAULT (datetime('now')),
+        current_period_end TEXT,
+        canceled_at TEXT,
+        resume_at TEXT,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      INSERT INTO subscribers_new (id, plan_id, customer_name, customer_email, status, started_at, trial_ends_at, current_period_start, current_period_end, canceled_at, metadata, created_at, updated_at)
+        SELECT id, plan_id, customer_name, customer_email, status, started_at, trial_ends_at, current_period_start, current_period_end, canceled_at, metadata, created_at, updated_at
+        FROM subscribers;
+
+      DROP TABLE subscribers;
+      ALTER TABLE subscribers_new RENAME TO subscribers;
+
+      CREATE INDEX IF NOT EXISTS idx_subscribers_plan ON subscribers(plan_id);
+      CREATE INDEX IF NOT EXISTS idx_subscribers_email ON subscribers(customer_email);
+      CREATE INDEX IF NOT EXISTS idx_subscribers_status ON subscribers(status);
+      CREATE INDEX IF NOT EXISTS idx_subscribers_period_end ON subscribers(current_period_end);
+
+      -- Add 'paused' and 'resumed' to events type CHECK
+      CREATE TABLE events_new (
+        id TEXT PRIMARY KEY,
+        subscriber_id TEXT NOT NULL REFERENCES subscribers(id) ON DELETE CASCADE,
+        type TEXT NOT NULL CHECK (type IN ('created', 'upgraded', 'downgraded', 'canceled', 'renewed', 'payment_failed', 'paused', 'resumed', 'trial_extended')),
+        occurred_at TEXT NOT NULL DEFAULT (datetime('now')),
+        details TEXT NOT NULL DEFAULT '{}'
+      );
+
+      INSERT INTO events_new (id, subscriber_id, type, occurred_at, details)
+        SELECT id, subscriber_id, type, occurred_at, details
+        FROM events;
+
+      DROP TABLE events;
+      ALTER TABLE events_new RENAME TO events;
+
+      CREATE INDEX IF NOT EXISTS idx_events_subscriber ON events(subscriber_id);
+      CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+      CREATE INDEX IF NOT EXISTS idx_events_occurred ON events(occurred_at);
+
+      -- Dunning attempts table
+      CREATE TABLE IF NOT EXISTS dunning_attempts (
+        id TEXT PRIMARY KEY,
+        subscriber_id TEXT NOT NULL REFERENCES subscribers(id) ON DELETE CASCADE,
+        attempt_number INTEGER NOT NULL DEFAULT 1,
+        status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'retrying', 'failed', 'recovered')),
+        next_retry_at TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_dunning_subscriber ON dunning_attempts(subscriber_id);
+      CREATE INDEX IF NOT EXISTS idx_dunning_status ON dunning_attempts(status);
+    `,
+  },
 ];