@hasna/microservices 0.0.3 → 0.0.5

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

@@ -0,0 +1,93 @@
+/**
+ * Database connection for microservice-ads
+ */
+
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { MIGRATIONS } from "./migrations.js";
+
+let _db: Database | null = null;
+
+function getDbPath(): string {
+  // Environment variable override
+  if (process.env["MICROSERVICES_DIR"]) {
+    return join(process.env["MICROSERVICES_DIR"], "microservice-ads", "data.db");
+  }
+
+  // Check for .microservices in current or parent directories
+  let dir = resolve(process.cwd());
+  while (true) {
+    const candidate = join(dir, ".microservices", "microservice-ads", "data.db");
+    const msDir = join(dir, ".microservices");
+    if (existsSync(msDir)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Global fallback
+  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  return join(home, ".microservices", "microservice-ads", "data.db");
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(resolve(filePath));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function getDatabase(): Database {
+  if (_db) return _db;
+
+  const dbPath = getDbPath();
+  ensureDir(dbPath);
+
+  _db = new Database(dbPath);
+  _db.exec("PRAGMA journal_mode = WAL");
+  _db.exec("PRAGMA foreign_keys = ON");
+
+  // Create migrations table
+  _db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+
+  // Apply pending migrations
+  const applied = _db
+    .query("SELECT id FROM _migrations ORDER BY id")
+    .all() as { id: number }[];
+  const appliedIds = new Set(applied.map((r) => r.id));
+
+  for (const migration of MIGRATIONS) {
+    if (appliedIds.has(migration.id)) continue;
+
+    _db.exec("BEGIN");
+    try {
+      _db.exec(migration.sql);
+      _db.prepare("INSERT INTO _migrations (id, name) VALUES (?, ?)").run(
+        migration.id,
+        migration.name
+      );
+      _db.exec("COMMIT");
+    } catch (error) {
+      _db.exec("ROLLBACK");
+      throw new Error(
+        `Migration ${migration.id} (${migration.name}) failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  return _db;
+}
+
+export function closeDatabase(): void {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}

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

@@ -0,0 +1,60 @@
+export interface MigrationEntry {
+  id: number;
+  name: string;
+  sql: string;
+}
+
+export const MIGRATIONS: MigrationEntry[] = [
+  {
+    id: 1,
+    name: "initial_schema",
+    sql: `
+      CREATE TABLE IF NOT EXISTS campaigns (
+        id TEXT PRIMARY KEY,
+        platform TEXT NOT NULL CHECK (platform IN ('google', 'meta', 'linkedin', 'tiktok')),
+        name TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'active', 'paused', 'completed')),
+        budget_daily REAL NOT NULL DEFAULT 0,
+        budget_total REAL NOT NULL DEFAULT 0,
+        spend REAL NOT NULL DEFAULT 0,
+        impressions INTEGER NOT NULL DEFAULT 0,
+        clicks INTEGER NOT NULL DEFAULT 0,
+        conversions INTEGER NOT NULL DEFAULT 0,
+        roas REAL NOT NULL DEFAULT 0,
+        start_date TEXT,
+        end_date TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        metadata TEXT NOT NULL DEFAULT '{}'
+      );
+
+      CREATE TABLE IF NOT EXISTS ad_groups (
+        id TEXT PRIMARY KEY,
+        campaign_id TEXT NOT NULL REFERENCES campaigns(id) ON DELETE CASCADE,
+        name TEXT NOT NULL,
+        targeting TEXT NOT NULL DEFAULT '{}',
+        status TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'active', 'paused', 'completed')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS ads (
+        id TEXT PRIMARY KEY,
+        ad_group_id TEXT NOT NULL REFERENCES ad_groups(id) ON DELETE CASCADE,
+        headline TEXT NOT NULL,
+        description TEXT,
+        creative_url TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'active', 'paused', 'completed')),
+        metrics TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_campaigns_platform ON campaigns(platform);
+      CREATE INDEX IF NOT EXISTS idx_campaigns_status ON campaigns(status);
+      CREATE INDEX IF NOT EXISTS idx_campaigns_name ON campaigns(name);
+      CREATE INDEX IF NOT EXISTS idx_ad_groups_campaign ON ad_groups(campaign_id);
+      CREATE INDEX IF NOT EXISTS idx_ad_groups_status ON ad_groups(status);
+      CREATE INDEX IF NOT EXISTS idx_ads_ad_group ON ads(ad_group_id);
+      CREATE INDEX IF NOT EXISTS idx_ads_status ON ads(status);
+    `,
+  },
+];

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

@@ -0,0 +1,39 @@
+/**
+ * microservice-ads — Ad campaign management microservice
+ */
+
+export {
+  createCampaign,
+  getCampaign,
+  listCampaigns,
+  updateCampaign,
+  deleteCampaign,
+  pauseCampaign,
+  resumeCampaign,
+  countCampaigns,
+  getCampaignStats,
+  getSpendByPlatform,
+  getPlatforms,
+  createAdGroup,
+  getAdGroup,
+  listAdGroups,
+  deleteAdGroup,
+  createAd,
+  getAd,
+  listAds,
+  deleteAd,
+  type Campaign,
+  type CreateCampaignInput,
+  type UpdateCampaignInput,
+  type ListCampaignsOptions,
+  type Platform,
+  type CampaignStatus,
+  type AdGroup,
+  type CreateAdGroupInput,
+  type Ad,
+  type CreateAdInput,
+  type CampaignStats,
+  type SpendByPlatform,
+} from "./db/campaigns.js";
+
+export { getDatabase, closeDatabase } from "./db/database.js";

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

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  createCampaign,
+  getCampaign,
+  listCampaigns,
+  updateCampaign,
+  deleteCampaign,
+  pauseCampaign,
+  resumeCampaign,
+  getCampaignStats,
+  getSpendByPlatform,
+  getPlatforms,
+  createAdGroup,
+  listAdGroups,
+  createAd,
+  listAds,
+  bulkPause,
+  bulkResume,
+  getRankedCampaigns,
+  checkBudgetStatus,
+  comparePlatforms,
+  exportCampaigns,
+  cloneCampaign,
+  getBudgetRemaining,
+  getAdGroupStats,
+} from "../db/campaigns.js";
+
+const server = new McpServer({
+  name: "microservice-ads",
+  version: "0.0.1",
+});
+
+const PlatformEnum = z.enum(["google", "meta", "linkedin", "tiktok"]);
+const StatusEnum = z.enum(["draft", "active", "paused", "completed"]);
+
+// --- Campaigns ---
+
+server.registerTool(
+  "create_campaign",
+  {
+    title: "Create Campaign",
+    description: "Create a new ad campaign.",
+    inputSchema: {
+      platform: PlatformEnum,
+      name: z.string(),
+      status: StatusEnum.optional(),
+      budget_daily: z.number().optional(),
+      budget_total: z.number().optional(),
+      start_date: z.string().optional(),
+      end_date: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+    },
+  },
+  async (params) => {
+    const campaign = createCampaign(params);
+    return { content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "get_campaign",
+  {
+    title: "Get Campaign",
+    description: "Get a campaign by ID.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const campaign = getCampaign(id);
+    if (!campaign) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_campaigns",
+  {
+    title: "List Campaigns",
+    description: "List campaigns with optional filters.",
+    inputSchema: {
+      platform: PlatformEnum.optional(),
+      status: StatusEnum.optional(),
+      search: z.string().optional(),
+      limit: z.number().optional(),
+    },
+  },
+  async (params) => {
+    const campaigns = listCampaigns(params);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ campaigns, count: campaigns.length }, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "update_campaign",
+  {
+    title: "Update Campaign",
+    description: "Update an existing campaign.",
+    inputSchema: {
+      id: z.string(),
+      platform: PlatformEnum.optional(),
+      name: z.string().optional(),
+      status: StatusEnum.optional(),
+      budget_daily: z.number().optional(),
+      budget_total: z.number().optional(),
+      spend: z.number().optional(),
+      impressions: z.number().optional(),
+      clicks: z.number().optional(),
+      conversions: z.number().optional(),
+      roas: z.number().optional(),
+      start_date: z.string().optional(),
+      end_date: z.string().optional(),
+      metadata: z.record(z.unknown()).optional(),
+    },
+  },
+  async ({ id, ...input }) => {
+    const campaign = updateCampaign(id, input);
+    if (!campaign) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "delete_campaign",
+  {
+    title: "Delete Campaign",
+    description: "Delete a campaign by ID.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const deleted = deleteCampaign(id);
+    return { content: [{ type: "text", text: JSON.stringify({ id, deleted }) }] };
+  }
+);
+
+server.registerTool(
+  "pause_campaign",
+  {
+    title: "Pause Campaign",
+    description: "Pause an active campaign.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const campaign = pauseCampaign(id);
+    if (!campaign) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "resume_campaign",
+  {
+    title: "Resume Campaign",
+    description: "Resume a paused campaign.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const campaign = resumeCampaign(id);
+    if (!campaign) {
+      return { content: [{ type: "text", text: `Campaign '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(campaign, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "campaign_stats",
+  {
+    title: "Campaign Stats",
+    description: "Get aggregate campaign statistics.",
+    inputSchema: {},
+  },
+  async () => {
+    const stats = getCampaignStats();
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "spend_by_platform",
+  {
+    title: "Spend by Platform",
+    description: "Get total spend broken down by platform.",
+    inputSchema: {},
+  },
+  async () => {
+    const spend = getSpendByPlatform();
+    return { content: [{ type: "text", text: JSON.stringify(spend, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_platforms",
+  {
+    title: "List Platforms",
+    description: "List platforms that have campaigns.",
+    inputSchema: {},
+  },
+  async () => {
+    const platforms = getPlatforms();
+    return { content: [{ type: "text", text: JSON.stringify(platforms, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_providers",
+  {
+    title: "List Providers",
+    description: "List all supported ad providers.",
+    inputSchema: {},
+  },
+  async () => {
+    const providers = ["google", "meta", "linkedin", "tiktok"];
+    return { content: [{ type: "text", text: JSON.stringify(providers, null, 2) }] };
+  }
+);
+
+// --- Ad Groups ---
+
+server.registerTool(
+  "create_ad_group",
+  {
+    title: "Create Ad Group",
+    description: "Create a new ad group within a campaign.",
+    inputSchema: {
+      campaign_id: z.string(),
+      name: z.string(),
+      targeting: z.record(z.unknown()).optional(),
+      status: StatusEnum.optional(),
+    },
+  },
+  async (params) => {
+    const adGroup = createAdGroup(params);
+    return { content: [{ type: "text", text: JSON.stringify(adGroup, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_ad_groups",
+  {
+    title: "List Ad Groups",
+    description: "List ad groups, optionally filtered by campaign.",
+    inputSchema: {
+      campaign_id: z.string().optional(),
+    },
+  },
+  async ({ campaign_id }) => {
+    const adGroups = listAdGroups(campaign_id);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ ad_groups: adGroups, count: adGroups.length }, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+// --- Ads ---
+
+server.registerTool(
+  "create_ad",
+  {
+    title: "Create Ad",
+    description: "Create a new ad within an ad group.",
+    inputSchema: {
+      ad_group_id: z.string(),
+      headline: z.string(),
+      description: z.string().optional(),
+      creative_url: z.string().optional(),
+      status: StatusEnum.optional(),
+      metrics: z.record(z.unknown()).optional(),
+    },
+  },
+  async (params) => {
+    const ad = createAd(params);
+    return { content: [{ type: "text", text: JSON.stringify(ad, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_ads",
+  {
+    title: "List Ads",
+    description: "List ads, optionally filtered by ad group.",
+    inputSchema: {
+      ad_group_id: z.string().optional(),
+    },
+  },
+  async ({ ad_group_id }) => {
+    const ads = listAds(ad_group_id);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ ads, count: ads.length }, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+// --- 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();
+  await server.connect(transport);
+  console.error("microservice-ads MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/microservices/microservice-contracts/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hasna/microservice-contracts",
+  "version": "0.0.1",
+  "description": "Contract and agreement management microservice with SQLite — manage contracts, clauses, and reminders",
+  "type": "module",
+  "bin": {
+    "microservice-contracts": "./src/cli/index.ts",
+    "microservice-contracts-mcp": "./src/mcp/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "commander": "^12.1.0",
+    "zod": "^3.24.0"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}