@hasna/microservices 0.0.4 → 0.0.5

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

@@ -12,6 +12,15 @@ import {
   getCampaignStats,
   getSpendByPlatform,
   getPlatforms,
+  bulkPause,
+  bulkResume,
+  getRankedCampaigns,
+  checkBudgetStatus,
+  comparePlatforms,
+  exportCampaigns,
+  cloneCampaign,
+  getBudgetRemaining,
+  getAdGroupStats,
 } from "../db/campaigns.js";
 import {
   createAdGroup,
@@ -218,6 +227,118 @@ campaignCmd
     }
   });
 
+// 1. Bulk pause/resume
+campaignCmd
+  .command("bulk-pause")
+  .description("Pause all active campaigns on a platform")
+  .requiredOption("--platform <platform>", "Platform (google/meta/linkedin/tiktok)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const result = bulkPause(opts.platform);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Paused ${result.updated_count} campaign(s) on ${result.platform}`);
+    }
+  });
+
+campaignCmd
+  .command("bulk-resume")
+  .description("Resume all paused campaigns on a platform")
+  .requiredOption("--platform <platform>", "Platform (google/meta/linkedin/tiktok)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const result = bulkResume(opts.platform);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Resumed ${result.updated_count} campaign(s) on ${result.platform}`);
+    }
+  });
+
+// 3. Budget alerts
+campaignCmd
+  .command("check-budget")
+  .description("Check budget status for a campaign")
+  .argument("<id>", "Campaign ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const status = checkBudgetStatus(id);
+    if (!status) {
+      console.error(`Campaign '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(status, null, 2));
+    } else {
+      console.log(`Budget Status: ${status.campaign_name}`);
+      console.log(`  Over budget: ${status.over_budget ? "YES" : "No"}`);
+      console.log(`  Daily remaining: $${status.daily_remaining}`);
+      console.log(`  Total remaining: $${status.total_remaining}`);
+      console.log(`  % used: ${status.pct_used}%`);
+      console.log(`  Days active: ${status.days_active}`);
+      console.log(`  Expected spend: $${status.expected_spend}`);
+    }
+  });
+
+// 5. CSV export
+campaignCmd
+  .command("export")
+  .description("Export campaigns to CSV or JSON")
+  .option("--format <format>", "Format (csv/json)", "csv")
+  .action((opts) => {
+    const output = exportCampaigns(opts.format);
+    console.log(output);
+  });
+
+// 6. Campaign cloning
+campaignCmd
+  .command("clone")
+  .description("Clone a campaign with all ad groups and ads")
+  .argument("<id>", "Campaign ID to clone")
+  .requiredOption("--name <name>", "New campaign name")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const cloned = cloneCampaign(id, opts.name);
+    if (!cloned) {
+      console.error(`Campaign '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(cloned, null, 2));
+    } else {
+      console.log(`Cloned campaign: ${cloned.name} (${cloned.id})`);
+    }
+  });
+
+// 7. Budget remaining
+campaignCmd
+  .command("budget-remaining")
+  .description("Show budget remaining for a campaign")
+  .argument("<id>", "Campaign ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const remaining = getBudgetRemaining(id);
+    if (!remaining) {
+      console.error(`Campaign '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(remaining, null, 2));
+    } else {
+      console.log(`Budget Remaining: ${remaining.campaign_name}`);
+      console.log(`  Daily budget: $${remaining.budget_daily}`);
+      console.log(`  Total budget: $${remaining.budget_total}`);
+      console.log(`  Spend: $${remaining.spend}`);
+      console.log(`  Daily remaining: $${remaining.daily_remaining}`);
+      console.log(`  Total remaining: $${remaining.total_remaining}`);
+      console.log(`  Days remaining at current rate: ${remaining.days_remaining_at_daily_rate}`);
+    }
+  });
+
 // --- Ad Groups ---
 
 const adGroupCmd = program
@@ -269,6 +390,35 @@ adGroupCmd
     }
   });
 
+// 8. Ad group stats
+adGroupCmd
+  .command("stats")
+  .description("Show aggregated stats for an ad group")
+  .argument("<id>", "Ad group ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const stats = getAdGroupStats(id);
+    if (!stats) {
+      console.error(`Ad group '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(stats, null, 2));
+    } else {
+      console.log(`Ad Group Stats: ${stats.ad_group_name}`);
+      console.log(`  Campaign: ${stats.campaign_id}`);
+      console.log(`  Total ads: ${stats.total_ads}`);
+      console.log(`  Active ads: ${stats.active_ads}`);
+      if (Object.keys(stats.metrics).length > 0) {
+        console.log("  Aggregated metrics:");
+        for (const [key, value] of Object.entries(stats.metrics)) {
+          console.log(`    ${key}: ${value}`);
+        }
+      }
+    }
+  });
+
 // --- Ads ---
 
 const adCmd = program
@@ -327,8 +477,26 @@ adCmd
 program
   .command("stats")
   .description("Show campaign statistics")
+  .option("--sort-by <metric>", "Sort campaigns by metric (roas/ctr/spend)")
+  .option("--limit <n>", "Limit ranked results", "10")
   .option("--json", "Output as JSON", false)
   .action((opts) => {
+    // 2. Performance ranking via --sort-by
+    if (opts.sortBy) {
+      const ranked = getRankedCampaigns(opts.sortBy, parseInt(opts.limit));
+      if (opts.json) {
+        console.log(JSON.stringify(ranked, null, 2));
+      } else {
+        console.log(`Campaigns ranked by ${opts.sortBy}:`);
+        for (let i = 0; i < ranked.length; i++) {
+          const c = ranked[i];
+          const ctr = c.impressions > 0 ? ((c.clicks / c.impressions) * 100).toFixed(2) : "0.00";
+          console.log(`  ${i + 1}. ${c.name} [${c.platform}] — ROAS: ${c.roas}, CTR: ${ctr}%, Spend: $${c.spend}`);
+        }
+      }
+      return;
+    }
+
     const stats = getCampaignStats();
 
     if (opts.json) {
@@ -345,6 +513,36 @@ program
     }
   });
 
+// 4. Cross-platform comparison
+program
+  .command("compare-platforms")
+  .description("Compare ROAS/CPA/spend across platforms side-by-side")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const comparison = comparePlatforms();
+
+    if (opts.json) {
+      console.log(JSON.stringify(comparison, null, 2));
+    } else {
+      if (comparison.length === 0) {
+        console.log("No platform data.");
+        return;
+      }
+      console.log("Platform Comparison:");
+      console.log("  Platform     | Campaigns | Spend        | ROAS  | CTR    | CPA");
+      console.log("  -------------|-----------|--------------|-------|--------|-------");
+      for (const p of comparison) {
+        const platform = p.platform.padEnd(12);
+        const campaigns = String(p.campaign_count).padEnd(9);
+        const spend = `$${p.total_spend.toFixed(2)}`.padEnd(12);
+        const roas = p.avg_roas.toFixed(2).padEnd(5);
+        const ctr = `${p.avg_ctr.toFixed(2)}%`.padEnd(6);
+        const cpa = p.avg_cpa > 0 ? `$${p.avg_cpa.toFixed(2)}` : "N/A";
+        console.log(`  ${platform} | ${campaigns} | ${spend} | ${roas} | ${ctr} | ${cpa}`);
+      }
+    }
+  });
+
 program
   .command("spend")
   .description("Show spend by platform")

package/microservices/microservice-ads/src/db/campaigns.ts

@@ -491,3 +491,307 @@ export function getPlatforms(): string[] {
   ).all() as { platform: string }[];
   return rows.map((r) => r.platform);
 }
+
+// --- QoL Features ---
+
+// 1. Bulk pause/resume by platform
+export interface BulkUpdateResult {
+  updated_count: number;
+  platform: Platform;
+  new_status: CampaignStatus;
+}
+
+export function bulkPause(platform: Platform): BulkUpdateResult {
+  const db = getDatabase();
+  const result = db.prepare(
+    "UPDATE campaigns SET status = 'paused', updated_at = datetime('now') WHERE platform = ? AND status = 'active'"
+  ).run(platform);
+  return { updated_count: result.changes, platform, new_status: "paused" };
+}
+
+export function bulkResume(platform: Platform): BulkUpdateResult {
+  const db = getDatabase();
+  const result = db.prepare(
+    "UPDATE campaigns SET status = 'active', updated_at = datetime('now') WHERE platform = ? AND status = 'paused'"
+  ).run(platform);
+  return { updated_count: result.changes, platform, new_status: "active" };
+}
+
+// 2. Performance ranking
+export type RankMetric = "roas" | "ctr" | "spend";
+
+export function getRankedCampaigns(sortBy: RankMetric = "roas", limit: number = 10): Campaign[] {
+  const db = getDatabase();
+  let orderExpr: string;
+
+  switch (sortBy) {
+    case "roas":
+      orderExpr = "roas DESC";
+      break;
+    case "ctr":
+      // CTR = clicks / impressions (handle division by zero)
+      orderExpr = "CASE WHEN impressions > 0 THEN CAST(clicks AS REAL) / impressions ELSE 0 END DESC";
+      break;
+    case "spend":
+      orderExpr = "spend DESC";
+      break;
+    default:
+      orderExpr = "roas DESC";
+  }
+
+  const rows = db.prepare(
+    `SELECT * FROM campaigns ORDER BY ${orderExpr} LIMIT ?`
+  ).all(limit) as CampaignRow[];
+  return rows.map(rowToCampaign);
+}
+
+// 3. Budget alerts
+export interface BudgetStatus {
+  campaign_id: string;
+  campaign_name: string;
+  over_budget: boolean;
+  daily_remaining: number;
+  total_remaining: number;
+  pct_used: number;
+  days_active: number;
+  expected_spend: number;
+}
+
+export function checkBudgetStatus(id: string): BudgetStatus | null {
+  const campaign = getCampaign(id);
+  if (!campaign) return null;
+
+  const now = new Date();
+  let daysActive = 1;
+
+  if (campaign.start_date) {
+    const start = new Date(campaign.start_date);
+    const diffMs = now.getTime() - start.getTime();
+    daysActive = Math.max(1, Math.ceil(diffMs / (1000 * 60 * 60 * 24)));
+  }
+
+  const expectedSpend = campaign.budget_daily * daysActive;
+  const overBudget = campaign.budget_total > 0
+    ? campaign.spend > campaign.budget_total
+    : campaign.spend > expectedSpend;
+
+  const dailySpentToday = daysActive > 0 ? campaign.spend / daysActive : campaign.spend;
+  const dailyRemaining = Math.max(0, campaign.budget_daily - dailySpentToday);
+
+  const totalRemaining = campaign.budget_total > 0
+    ? Math.max(0, campaign.budget_total - campaign.spend)
+    : Math.max(0, expectedSpend - campaign.spend);
+
+  const pctUsed = campaign.budget_total > 0
+    ? (campaign.spend / campaign.budget_total) * 100
+    : expectedSpend > 0 ? (campaign.spend / expectedSpend) * 100 : 0;
+
+  return {
+    campaign_id: id,
+    campaign_name: campaign.name,
+    over_budget: overBudget,
+    daily_remaining: Math.round(dailyRemaining * 100) / 100,
+    total_remaining: Math.round(totalRemaining * 100) / 100,
+    pct_used: Math.round(pctUsed * 100) / 100,
+    days_active: daysActive,
+    expected_spend: Math.round(expectedSpend * 100) / 100,
+  };
+}
+
+// 4. Cross-platform comparison
+export interface PlatformComparison {
+  platform: Platform;
+  campaign_count: number;
+  total_spend: number;
+  total_impressions: number;
+  total_clicks: number;
+  total_conversions: number;
+  avg_roas: number;
+  avg_ctr: number;
+  avg_cpa: number;
+}
+
+export function comparePlatforms(): PlatformComparison[] {
+  const db = getDatabase();
+  const rows = db.prepare(`
+    SELECT
+      platform,
+      COUNT(*) as campaign_count,
+      COALESCE(SUM(spend), 0) as total_spend,
+      COALESCE(SUM(impressions), 0) as total_impressions,
+      COALESCE(SUM(clicks), 0) as total_clicks,
+      COALESCE(SUM(conversions), 0) as total_conversions,
+      COALESCE(AVG(CASE WHEN roas > 0 THEN roas END), 0) as avg_roas,
+      CASE WHEN SUM(impressions) > 0
+        THEN CAST(SUM(clicks) AS REAL) / SUM(impressions) * 100
+        ELSE 0
+      END as avg_ctr,
+      CASE WHEN SUM(conversions) > 0
+        THEN SUM(spend) / SUM(conversions)
+        ELSE 0
+      END as avg_cpa
+    FROM campaigns
+    GROUP BY platform
+    ORDER BY total_spend DESC
+  `).all() as PlatformComparison[];
+  return rows;
+}
+
+// 5. CSV export
+export function exportCampaigns(format: "csv" | "json" = "csv"): string {
+  const campaigns = listCampaigns();
+
+  if (format === "json") {
+    return JSON.stringify(campaigns, null, 2);
+  }
+
+  // CSV format
+  const headers = [
+    "id", "platform", "name", "status", "budget_daily", "budget_total",
+    "spend", "impressions", "clicks", "conversions", "roas",
+    "start_date", "end_date", "created_at", "updated_at",
+  ];
+
+  const rows = campaigns.map((c) =>
+    headers.map((h) => {
+      const val = c[h as keyof Campaign];
+      if (val === null || val === undefined) return "";
+      if (typeof val === "object") return JSON.stringify(val);
+      const str = String(val);
+      // Escape CSV fields that contain commas or quotes
+      if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+        return `"${str.replace(/"/g, '""')}"`;
+      }
+      return str;
+    }).join(",")
+  );
+
+  return [headers.join(","), ...rows].join("\n");
+}
+
+// 6. Campaign cloning
+export function cloneCampaign(id: string, newName: string): Campaign | null {
+  const original = getCampaign(id);
+  if (!original) return null;
+
+  const db = getDatabase();
+
+  // Clone the campaign itself (reset metrics)
+  const cloned = createCampaign({
+    platform: original.platform,
+    name: newName,
+    status: "draft",
+    budget_daily: original.budget_daily,
+    budget_total: original.budget_total,
+    start_date: original.start_date || undefined,
+    end_date: original.end_date || undefined,
+    metadata: original.metadata,
+  });
+
+  // Clone ad groups and their ads
+  const adGroups = listAdGroups(id);
+  for (const ag of adGroups) {
+    const clonedGroup = createAdGroup({
+      campaign_id: cloned.id,
+      name: ag.name,
+      targeting: ag.targeting,
+      status: "draft",
+    });
+
+    const ads = listAds(ag.id);
+    for (const ad of ads) {
+      createAd({
+        ad_group_id: clonedGroup.id,
+        headline: ad.headline,
+        description: ad.description || undefined,
+        creative_url: ad.creative_url || undefined,
+        status: "draft",
+        metrics: {},
+      });
+    }
+  }
+
+  return getCampaign(cloned.id)!;
+}
+
+// 7. Budget remaining (reuses checkBudgetStatus but provides a focused view)
+export interface BudgetRemaining {
+  campaign_id: string;
+  campaign_name: string;
+  budget_daily: number;
+  budget_total: number;
+  spend: number;
+  daily_remaining: number;
+  total_remaining: number;
+  days_remaining_at_daily_rate: number;
+}
+
+export function getBudgetRemaining(id: string): BudgetRemaining | null {
+  const campaign = getCampaign(id);
+  if (!campaign) return null;
+
+  const now = new Date();
+  let daysActive = 1;
+  if (campaign.start_date) {
+    const start = new Date(campaign.start_date);
+    const diffMs = now.getTime() - start.getTime();
+    daysActive = Math.max(1, Math.ceil(diffMs / (1000 * 60 * 60 * 24)));
+  }
+
+  const avgDailySpend = campaign.spend / daysActive;
+  const dailyRemaining = Math.max(0, campaign.budget_daily - avgDailySpend);
+  const totalRemaining = campaign.budget_total > 0
+    ? Math.max(0, campaign.budget_total - campaign.spend)
+    : 0;
+  const daysRemainingAtRate = avgDailySpend > 0 && campaign.budget_total > 0
+    ? Math.floor(totalRemaining / avgDailySpend)
+    : 0;
+
+  return {
+    campaign_id: id,
+    campaign_name: campaign.name,
+    budget_daily: campaign.budget_daily,
+    budget_total: campaign.budget_total,
+    spend: campaign.spend,
+    daily_remaining: Math.round(dailyRemaining * 100) / 100,
+    total_remaining: Math.round(totalRemaining * 100) / 100,
+    days_remaining_at_daily_rate: daysRemainingAtRate,
+  };
+}
+
+// 8. Ad group stats — aggregate metrics for ads in a group
+export interface AdGroupStats {
+  ad_group_id: string;
+  ad_group_name: string;
+  campaign_id: string;
+  total_ads: number;
+  active_ads: number;
+  metrics: Record<string, number>;
+}
+
+export function getAdGroupStats(adGroupId: string): AdGroupStats | null {
+  const adGroup = getAdGroup(adGroupId);
+  if (!adGroup) return null;
+
+  const ads = listAds(adGroupId);
+  const activeAds = ads.filter((a) => a.status === "active").length;
+
+  // Aggregate numeric metrics from all ads
+  const aggregated: Record<string, number> = {};
+  for (const ad of ads) {
+    for (const [key, value] of Object.entries(ad.metrics)) {
+      if (typeof value === "number") {
+        aggregated[key] = (aggregated[key] || 0) + value;
+      }
+    }
+  }
+
+  return {
+    ad_group_id: adGroupId,
+    ad_group_name: adGroup.name,
+    campaign_id: adGroup.campaign_id,
+    total_ads: ads.length,
+    active_ads: activeAds,
+    metrics: aggregated,
+  };
+}

package/microservices/microservice-ads/src/mcp/index.ts

@@ -18,6 +18,15 @@ import {
   listAdGroups,
   createAd,
   listAds,
+  bulkPause,
+  bulkResume,
+  getRankedCampaigns,
+  checkBudgetStatus,
+  comparePlatforms,
+  exportCampaigns,
+  cloneCampaign,
+  getBudgetRemaining,
+  getAdGroupStats,
 } from "../db/campaigns.js";
 
 const server = new McpServer({
@@ -307,6 +316,157 @@ server.registerTool(
   }
 );
 
+// --- QoL Tools ---
+
+// 1. Bulk pause/resume
+server.registerTool(
+  "bulk_pause_campaigns",
+  {
+    title: "Bulk Pause Campaigns",
+    description: "Pause all active campaigns on a specific platform.",
+    inputSchema: {
+      platform: PlatformEnum,
+    },
+  },
+  async ({ platform }) => {
+    const result = bulkPause(platform);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "bulk_resume_campaigns",
+  {
+    title: "Bulk Resume Campaigns",
+    description: "Resume all paused campaigns on a specific platform.",
+    inputSchema: {
+      platform: PlatformEnum,
+    },
+  },
+  async ({ platform }) => {
+    const result = bulkResume(platform);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// 2. Performance ranking
+server.registerTool(
+  "ranked_campaigns",
+  {
+    title: "Ranked Campaigns",
+    description: "Get campaigns ranked by a performance metric (roas, ctr, or spend).",
+    inputSchema: {
+      sort_by: z.enum(["roas", "ctr", "spend"]).optional(),
+      limit: z.number().optional(),
+    },
+  },
+  async ({ sort_by, limit }) => {
+    const campaigns = getRankedCampaigns(sort_by || "roas", limit || 10);
+    return { content: [{ type: "text", text: JSON.stringify(campaigns, null, 2) }] };
+  }
+);
+
+// 3. Budget alerts
+server.registerTool(
+  "check_budget",
+  {
+    title: "Check Budget Status",
+    description: "Check if a campaign is over budget and get remaining budget details.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const status = checkBudgetStatus(id);
+    if (!status) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
+  }
+);
+
+// 4. Cross-platform comparison
+server.registerTool(
+  "compare_platforms",
+  {
+    title: "Compare Platforms",
+    description: "Compare ROAS, CPA, and spend across all platforms side-by-side.",
+    inputSchema: {},
+  },
+  async () => {
+    const comparison = comparePlatforms();
+    return { content: [{ type: "text", text: JSON.stringify(comparison, null, 2) }] };
+  }
+);
+
+// 5. CSV export
+server.registerTool(
+  "export_campaigns",
+  {
+    title: "Export Campaigns",
+    description: "Export all campaigns in CSV or JSON format.",
+    inputSchema: {
+      format: z.enum(["csv", "json"]).optional(),
+    },
+  },
+  async ({ format }) => {
+    const output = exportCampaigns(format || "csv");
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+
+// 6. Campaign cloning
+server.registerTool(
+  "clone_campaign",
+  {
+    title: "Clone Campaign",
+    description: "Clone a campaign with all its ad groups and ads.",
+    inputSchema: {
+      id: z.string(),
+      new_name: z.string(),
+    },
+  },
+  async ({ id, new_name }) => {
+    const cloned = cloneCampaign(id, new_name);
+    if (!cloned) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(cloned, null, 2) }] };
+  }
+);
+
+// 7. Budget remaining
+server.registerTool(
+  "budget_remaining",
+  {
+    title: "Budget Remaining",
+    description: "Show daily and total budget remaining for a campaign.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const remaining = getBudgetRemaining(id);
+    if (!remaining) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(remaining, null, 2) }] };
+  }
+);
+
+// 8. Ad group stats
+server.registerTool(
+  "ad_group_stats",
+  {
+    title: "Ad Group Stats",
+    description: "Get aggregated metrics for all ads within an ad group.",
+    inputSchema: { ad_group_id: z.string() },
+  },
+  async ({ ad_group_id }) => {
+    const stats = getAdGroupStats(ad_group_id);
+    if (!stats) {
+      return { content: [{ type: "text", text: `Ad group '${ad_group_id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
 // --- Start ---
 async function main() {
   const transport = new StdioServerTransport();