@hasna/microservices 0.0.4 → 0.0.6

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

@@ -42,12 +42,13 @@ export interface Subscriber {
   plan_id: string;
   customer_name: string;
   customer_email: string;
-  status: "trialing" | "active" | "past_due" | "canceled" | "expired";
+  status: "trialing" | "active" | "past_due" | "canceled" | "expired" | "paused";
   started_at: string;
   trial_ends_at: string | null;
   current_period_start: string;
   current_period_end: string | null;
   canceled_at: string | null;
+  resume_at: string | null;
   metadata: Record<string, unknown>;
   created_at: string;
   updated_at: string;
@@ -64,6 +65,7 @@ interface SubscriberRow {
   current_period_start: string;
   current_period_end: string | null;
   canceled_at: string | null;
+  resume_at: string | null;
   metadata: string;
   created_at: string;
   updated_at: string;
@@ -80,7 +82,7 @@ function rowToSubscriber(row: SubscriberRow): Subscriber {
 export interface SubscriptionEvent {
   id: string;
   subscriber_id: string;
-  type: "created" | "upgraded" | "downgraded" | "canceled" | "renewed" | "payment_failed";
+  type: "created" | "upgraded" | "downgraded" | "canceled" | "renewed" | "payment_failed" | "paused" | "resumed" | "trial_extended";
   occurred_at: string;
   details: Record<string, unknown>;
 }
@@ -582,7 +584,7 @@ export function getMrr(): number {
     ), 0) as mrr
     FROM subscribers s
     JOIN plans p ON s.plan_id = p.id
-    WHERE s.status IN ('active', 'trialing', 'past_due')
+    WHERE s.status IN ('active', 'trialing', 'past_due') AND s.status != 'paused'
   `).get() as { mrr: number };
   return Math.round(row.mrr * 100) / 100;
 }
@@ -653,6 +655,7 @@ export function getSubscriberStats(): {
   past_due: number;
   canceled: number;
   expired: number;
+  paused: number;
 } {
   const db = getDatabase();
   const rows = db.prepare(`
@@ -666,6 +669,7 @@ export function getSubscriberStats(): {
     past_due: 0,
     canceled: 0,
     expired: 0,
+    paused: 0,
   };
 
   for (const row of rows) {
@@ -690,3 +694,563 @@ export function countSubscribers(): number {
   const row = db.prepare("SELECT COUNT(*) as count FROM subscribers").get() as { count: number };
   return row.count;
 }
+
+// --- Subscription Pause/Resume ---
+
+export function pauseSubscriber(id: string, resumeDate?: string): Subscriber | null {
+  const db = getDatabase();
+  const subscriber = getSubscriber(id);
+  if (!subscriber) return null;
+  if (subscriber.status === "canceled" || subscriber.status === "expired") return null;
+
+  const resumeAt = resumeDate || null;
+
+  db.prepare(
+    `UPDATE subscribers SET status = 'paused', resume_at = ?, updated_at = datetime('now') WHERE id = ?`
+  ).run(resumeAt, id);
+
+  recordEvent(id, "paused", { resume_at: resumeAt });
+
+  return getSubscriber(id);
+}
+
+export function resumeSubscriber(id: string): Subscriber | null {
+  const db = getDatabase();
+  const subscriber = getSubscriber(id);
+  if (!subscriber) return null;
+  if (subscriber.status !== "paused") return null;
+
+  db.prepare(
+    `UPDATE subscribers SET status = 'active', resume_at = NULL, updated_at = datetime('now') WHERE id = ?`
+  ).run(id);
+
+  recordEvent(id, "resumed", {});
+
+  return getSubscriber(id);
+}
+
+// --- Trial Extension ---
+
+export function extendTrial(id: string, days: number): Subscriber | null {
+  const db = getDatabase();
+  const subscriber = getSubscriber(id);
+  if (!subscriber) return null;
+
+  let baseDate: Date;
+  if (subscriber.trial_ends_at) {
+    baseDate = new Date(subscriber.trial_ends_at.replace(" ", "T") + "Z");
+  } else {
+    baseDate = new Date();
+  }
+
+  baseDate.setDate(baseDate.getDate() + days);
+  const newTrialEnd = baseDate.toISOString().replace("T", " ").replace("Z", "").split(".")[0];
+
+  db.prepare(
+    `UPDATE subscribers SET trial_ends_at = ?, status = 'trialing', updated_at = datetime('now') WHERE id = ?`
+  ).run(newTrialEnd, id);
+
+  recordEvent(id, "trial_extended", { days, new_trial_ends_at: newTrialEnd });
+
+  return getSubscriber(id);
+}
+
+// --- Dunning ---
+
+export interface DunningAttempt {
+  id: string;
+  subscriber_id: string;
+  attempt_number: number;
+  status: "pending" | "retrying" | "failed" | "recovered";
+  next_retry_at: string | null;
+  created_at: string;
+}
+
+interface DunningRow {
+  id: string;
+  subscriber_id: string;
+  attempt_number: number;
+  status: string;
+  next_retry_at: string | null;
+  created_at: string;
+}
+
+function rowToDunning(row: DunningRow): DunningAttempt {
+  return {
+    ...row,
+    status: row.status as DunningAttempt["status"],
+  };
+}
+
+export interface CreateDunningInput {
+  subscriber_id: string;
+  attempt_number?: number;
+  status?: DunningAttempt["status"];
+  next_retry_at?: string;
+}
+
+export function createDunning(input: CreateDunningInput): DunningAttempt {
+  const db = getDatabase();
+  const id = crypto.randomUUID();
+  const attemptNumber = input.attempt_number || 1;
+  const status = input.status || "pending";
+  const nextRetryAt = input.next_retry_at || null;
+
+  db.prepare(
+    `INSERT INTO dunning_attempts (id, subscriber_id, attempt_number, status, next_retry_at)
+     VALUES (?, ?, ?, ?, ?)`
+  ).run(id, input.subscriber_id, attemptNumber, status, nextRetryAt);
+
+  return getDunning(id)!;
+}
+
+export function getDunning(id: string): DunningAttempt | null {
+  const db = getDatabase();
+  const row = db.prepare("SELECT * FROM dunning_attempts WHERE id = ?").get(id) as DunningRow | null;
+  return row ? rowToDunning(row) : null;
+}
+
+export interface ListDunningOptions {
+  subscriber_id?: string;
+  status?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export function listDunning(options: ListDunningOptions = {}): DunningAttempt[] {
+  const db = getDatabase();
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (options.subscriber_id) {
+    conditions.push("subscriber_id = ?");
+    params.push(options.subscriber_id);
+  }
+
+  if (options.status) {
+    conditions.push("status = ?");
+    params.push(options.status);
+  }
+
+  let sql = "SELECT * FROM dunning_attempts";
+  if (conditions.length > 0) {
+    sql += " WHERE " + conditions.join(" AND ");
+  }
+  sql += " ORDER BY created_at DESC";
+
+  if (options.limit) {
+    sql += " LIMIT ?";
+    params.push(options.limit);
+  }
+  if (options.offset) {
+    sql += " OFFSET ?";
+    params.push(options.offset);
+  }
+
+  const rows = db.prepare(sql).all(...params) as DunningRow[];
+  return rows.map(rowToDunning);
+}
+
+export interface UpdateDunningInput {
+  status?: DunningAttempt["status"];
+  next_retry_at?: string | null;
+}
+
+export function updateDunning(id: string, input: UpdateDunningInput): DunningAttempt | null {
+  const db = getDatabase();
+  const existing = getDunning(id);
+  if (!existing) return null;
+
+  const sets: string[] = [];
+  const params: unknown[] = [];
+
+  if (input.status !== undefined) {
+    sets.push("status = ?");
+    params.push(input.status);
+  }
+  if (input.next_retry_at !== undefined) {
+    sets.push("next_retry_at = ?");
+    params.push(input.next_retry_at);
+  }
+
+  if (sets.length === 0) return existing;
+
+  params.push(id);
+
+  db.prepare(
+    `UPDATE dunning_attempts SET ${sets.join(", ")} WHERE id = ?`
+  ).run(...params);
+
+  return getDunning(id);
+}
+
+// --- Bulk Import/Export ---
+
+export interface BulkImportSubscriberInput {
+  plan_id: string;
+  customer_name: string;
+  customer_email: string;
+  status?: Subscriber["status"];
+  trial_ends_at?: string;
+  current_period_end?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function bulkImportSubscribers(data: BulkImportSubscriberInput[]): Subscriber[] {
+  const results: Subscriber[] = [];
+  for (const item of data) {
+    const subscriber = createSubscriber(item);
+    results.push(subscriber);
+  }
+  return results;
+}
+
+export function exportSubscribers(format: "csv" | "json" = "json"): string {
+  const subscribers = listSubscribers();
+
+  if (format === "json") {
+    return JSON.stringify(subscribers, null, 2);
+  }
+
+  // CSV format
+  if (subscribers.length === 0) return "";
+
+  const headers = [
+    "id", "plan_id", "customer_name", "customer_email", "status",
+    "started_at", "trial_ends_at", "current_period_start", "current_period_end",
+    "canceled_at", "resume_at", "created_at", "updated_at",
+  ];
+
+  const csvRows = [headers.join(",")];
+  for (const sub of subscribers) {
+    const row = headers.map((h) => {
+      const val = sub[h as keyof Subscriber];
+      if (val === null || val === undefined) return "";
+      if (typeof val === "object") return JSON.stringify(val).replace(/,/g, ";");
+      return String(val).includes(",") ? `"${String(val)}"` : String(val);
+    });
+    csvRows.push(row.join(","));
+  }
+  return csvRows.join("\n");
+}
+
+export function parseImportCsv(csvContent: string): BulkImportSubscriberInput[] {
+  const lines = csvContent.trim().split("\n");
+  if (lines.length < 2) return [];
+
+  const headers = lines[0].split(",").map((h) => h.trim());
+  const results: BulkImportSubscriberInput[] = [];
+
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(",").map((v) => v.trim().replace(/^"|"$/g, ""));
+    const record: Record<string, string> = {};
+    for (let j = 0; j < headers.length; j++) {
+      record[headers[j]] = values[j] || "";
+    }
+
+    if (!record["plan_id"] || !record["customer_name"] || !record["customer_email"]) continue;
+
+    results.push({
+      plan_id: record["plan_id"],
+      customer_name: record["customer_name"],
+      customer_email: record["customer_email"],
+      status: (record["status"] as Subscriber["status"]) || undefined,
+      trial_ends_at: record["trial_ends_at"] || undefined,
+      current_period_end: record["current_period_end"] || undefined,
+    });
+  }
+
+  return results;
+}
+
+// --- LTV Calculation ---
+
+export interface LtvResult {
+  subscriber_id: string;
+  customer_name: string;
+  customer_email: string;
+  plan_name: string;
+  plan_price: number;
+  plan_interval: string;
+  months_active: number;
+  ltv: number;
+}
+
+export function getLtv(): { subscribers: LtvResult[]; average_ltv: number } {
+  const db = getDatabase();
+  const rows = db.prepare(`
+    SELECT
+      s.id as subscriber_id,
+      s.customer_name,
+      s.customer_email,
+      s.started_at,
+      s.canceled_at,
+      s.status,
+      p.name as plan_name,
+      p.price as plan_price,
+      p.interval as plan_interval
+    FROM subscribers s
+    JOIN plans p ON s.plan_id = p.id
+    ORDER BY s.customer_name
+  `).all() as {
+    subscriber_id: string;
+    customer_name: string;
+    customer_email: string;
+    started_at: string;
+    canceled_at: string | null;
+    status: string;
+    plan_name: string;
+    plan_price: number;
+    plan_interval: string;
+  }[];
+
+  const results: LtvResult[] = [];
+  let totalLtv = 0;
+
+  for (const row of rows) {
+    const startDate = new Date(row.started_at.replace(" ", "T") + "Z");
+    const endDate = row.canceled_at
+      ? new Date(row.canceled_at.replace(" ", "T") + "Z")
+      : new Date();
+
+    const monthsDiff = Math.max(
+      1,
+      (endDate.getFullYear() - startDate.getFullYear()) * 12 +
+        (endDate.getMonth() - startDate.getMonth())
+    );
+
+    let monthlyPrice: number;
+    if (row.plan_interval === "monthly") {
+      monthlyPrice = row.plan_price;
+    } else if (row.plan_interval === "yearly") {
+      monthlyPrice = row.plan_price / 12;
+    } else {
+      // lifetime — one-time payment
+      monthlyPrice = 0;
+    }
+
+    const ltv = row.plan_interval === "lifetime"
+      ? row.plan_price
+      : Math.round(monthlyPrice * monthsDiff * 100) / 100;
+
+    results.push({
+      subscriber_id: row.subscriber_id,
+      customer_name: row.customer_name,
+      customer_email: row.customer_email,
+      plan_name: row.plan_name,
+      plan_price: row.plan_price,
+      plan_interval: row.plan_interval,
+      months_active: monthsDiff,
+      ltv,
+    });
+
+    totalLtv += ltv;
+  }
+
+  const averageLtv = results.length > 0
+    ? Math.round((totalLtv / results.length) * 100) / 100
+    : 0;
+
+  return { subscribers: results, average_ltv: averageLtv };
+}
+
+// --- NRR (Net Revenue Retention) ---
+
+export interface NrrResult {
+  month: string;
+  start_mrr: number;
+  expansion: number;
+  contraction: number;
+  churn: number;
+  nrr: number;
+}
+
+export function getNrr(month: string): NrrResult {
+  const db = getDatabase();
+
+  // Parse the month (YYYY-MM format)
+  const [year, mon] = month.split("-").map(Number);
+  const monthStart = `${year}-${String(mon).padStart(2, "0")}-01 00:00:00`;
+  const nextMonth = mon === 12 ? `${year + 1}-01-01 00:00:00` : `${year}-${String(mon + 1).padStart(2, "0")}-01 00:00:00`;
+
+  // Start MRR: sum of active subscribers at start of month (those created before month start and not canceled before it)
+  const startMrrRow = db.prepare(`
+    SELECT COALESCE(SUM(
+      CASE
+        WHEN p.interval = 'monthly' THEN p.price
+        WHEN p.interval = 'yearly' THEN p.price / 12.0
+        ELSE 0
+      END
+    ), 0) as mrr
+    FROM subscribers s
+    JOIN plans p ON s.plan_id = p.id
+    WHERE s.started_at < ?
+      AND (s.canceled_at IS NULL OR s.canceled_at >= ?)
+      AND s.status != 'paused'
+  `).get(monthStart, monthStart) as { mrr: number };
+  const startMrr = Math.round(startMrrRow.mrr * 100) / 100;
+
+  // Expansion: MRR from upgrades during this month
+  const expansionRow = db.prepare(`
+    SELECT COALESCE(SUM(
+      CASE
+        WHEN new_p.interval = 'monthly' THEN new_p.price - CASE WHEN old_p.interval = 'monthly' THEN old_p.price WHEN old_p.interval = 'yearly' THEN old_p.price / 12.0 ELSE 0 END
+        WHEN new_p.interval = 'yearly' THEN new_p.price / 12.0 - CASE WHEN old_p.interval = 'monthly' THEN old_p.price WHEN old_p.interval = 'yearly' THEN old_p.price / 12.0 ELSE 0 END
+        ELSE 0
+      END
+    ), 0) as expansion
+    FROM events e
+    JOIN subscribers s ON e.subscriber_id = s.id
+    JOIN plans new_p ON json_extract(e.details, '$.new_plan_id') = new_p.id
+    JOIN plans old_p ON json_extract(e.details, '$.old_plan_id') = old_p.id
+    WHERE e.type = 'upgraded'
+      AND e.occurred_at >= ? AND e.occurred_at < ?
+  `).get(monthStart, nextMonth) as { expansion: number };
+  const expansion = Math.max(0, Math.round(expansionRow.expansion * 100) / 100);
+
+  // Contraction: MRR lost from downgrades during this month
+  const contractionRow = db.prepare(`
+    SELECT COALESCE(SUM(
+      CASE
+        WHEN old_p.interval = 'monthly' THEN old_p.price - CASE WHEN new_p.interval = 'monthly' THEN new_p.price WHEN new_p.interval = 'yearly' THEN new_p.price / 12.0 ELSE 0 END
+        WHEN old_p.interval = 'yearly' THEN old_p.price / 12.0 - CASE WHEN new_p.interval = 'monthly' THEN new_p.price WHEN new_p.interval = 'yearly' THEN new_p.price / 12.0 ELSE 0 END
+        ELSE 0
+      END
+    ), 0) as contraction
+    FROM events e
+    JOIN subscribers s ON e.subscriber_id = s.id
+    JOIN plans new_p ON json_extract(e.details, '$.new_plan_id') = new_p.id
+    JOIN plans old_p ON json_extract(e.details, '$.old_plan_id') = old_p.id
+    WHERE e.type = 'downgraded'
+      AND e.occurred_at >= ? AND e.occurred_at < ?
+  `).get(monthStart, nextMonth) as { contraction: number };
+  const contraction = Math.max(0, Math.round(contractionRow.contraction * 100) / 100);
+
+  // Churn: MRR lost from cancellations during this month
+  const churnRow = db.prepare(`
+    SELECT COALESCE(SUM(
+      CASE
+        WHEN p.interval = 'monthly' THEN p.price
+        WHEN p.interval = 'yearly' THEN p.price / 12.0
+        ELSE 0
+      END
+    ), 0) as churn
+    FROM subscribers s
+    JOIN plans p ON s.plan_id = p.id
+    WHERE s.status = 'canceled'
+      AND s.canceled_at >= ? AND s.canceled_at < ?
+  `).get(monthStart, nextMonth) as { churn: number };
+  const churnMrr = Math.round(churnRow.churn * 100) / 100;
+
+  // NRR = (start_mrr + expansion - contraction - churn) / start_mrr * 100
+  const nrr = startMrr > 0
+    ? Math.round(((startMrr + expansion - contraction - churnMrr) / startMrr) * 100 * 100) / 100
+    : 0;
+
+  return {
+    month,
+    start_mrr: startMrr,
+    expansion,
+    contraction,
+    churn: churnMrr,
+    nrr,
+  };
+}
+
+// --- Cohort Analysis ---
+
+export interface CohortRow {
+  cohort: string;
+  total: number;
+  retained: number;
+  retention_rate: number;
+}
+
+export function getCohortReport(months: number = 6): CohortRow[] {
+  const db = getDatabase();
+  const now = new Date();
+  const results: CohortRow[] = [];
+
+  for (let i = months - 1; i >= 0; i--) {
+    const cohortDate = new Date(now.getFullYear(), now.getMonth() - i, 1);
+    const cohortStart = `${cohortDate.getFullYear()}-${String(cohortDate.getMonth() + 1).padStart(2, "0")}-01 00:00:00`;
+    const cohortEnd = cohortDate.getMonth() === 11
+      ? `${cohortDate.getFullYear() + 1}-01-01 00:00:00`
+      : `${cohortDate.getFullYear()}-${String(cohortDate.getMonth() + 2).padStart(2, "0")}-01 00:00:00`;
+    const cohortLabel = `${cohortDate.getFullYear()}-${String(cohortDate.getMonth() + 1).padStart(2, "0")}`;
+
+    // Total subscribers who signed up in this cohort month
+    const totalRow = db.prepare(`
+      SELECT COUNT(*) as count FROM subscribers
+      WHERE started_at >= ? AND started_at < ?
+    `).get(cohortStart, cohortEnd) as { count: number };
+
+    // Retained: those from this cohort who are still active/trialing/past_due (not canceled/expired)
+    const retainedRow = db.prepare(`
+      SELECT COUNT(*) as count FROM subscribers
+      WHERE started_at >= ? AND started_at < ?
+        AND status IN ('active', 'trialing', 'past_due', 'paused')
+    `).get(cohortStart, cohortEnd) as { count: number };
+
+    const retentionRate = totalRow.count > 0
+      ? Math.round((retainedRow.count / totalRow.count) * 100 * 100) / 100
+      : 0;
+
+    results.push({
+      cohort: cohortLabel,
+      total: totalRow.count,
+      retained: retainedRow.count,
+      retention_rate: retentionRate,
+    });
+  }
+
+  return results;
+}
+
+// --- Plan Comparison ---
+
+export interface PlanComparison {
+  plan1: Plan;
+  plan2: Plan;
+  price_diff: number;
+  price_diff_pct: number;
+  features_only_in_plan1: string[];
+  features_only_in_plan2: string[];
+  common_features: string[];
+  interval_match: boolean;
+}
+
+export function comparePlans(id1: string, id2: string): PlanComparison | null {
+  const plan1 = getPlan(id1);
+  const plan2 = getPlan(id2);
+  if (!plan1 || !plan2) return null;
+
+  const features1 = new Set(plan1.features);
+  const features2 = new Set(plan2.features);
+
+  const commonFeatures = plan1.features.filter((f) => features2.has(f));
+  const onlyIn1 = plan1.features.filter((f) => !features2.has(f));
+  const onlyIn2 = plan2.features.filter((f) => !features1.has(f));
+
+  const priceDiff = Math.round((plan2.price - plan1.price) * 100) / 100;
+  const priceDiffPct = plan1.price > 0
+    ? Math.round(((plan2.price - plan1.price) / plan1.price) * 100 * 100) / 100
+    : 0;
+
+  return {
+    plan1,
+    plan2,
+    price_diff: priceDiff,
+    price_diff_pct: priceDiffPct,
+    features_only_in_plan1: onlyIn1,
+    features_only_in_plan2: onlyIn2,
+    common_features: commonFeatures,
+    interval_match: plan1.interval === plan2.interval,
+  };
+}
+
+// --- Expiring Renewals (alias for listExpiring with explicit name) ---
+
+export function getExpiringRenewals(days: number = 7): Subscriber[] {
+  return listExpiring(days);
+}