meyi-cost-server 1.0.0

package/src/cur-discovery/cur-discovery.worker.js

@@ -0,0 +1,57 @@
+import { truthy } from "../lib/cost-utils.js";
+
+export class CurDiscoveryWorker {
+  constructor({ repository, service, logger = console, env = process.env }) {
+    this.repository = repository;
+    this.service = service;
+    this.logger = logger;
+    this.enabled = env.COST_CUR_DISCOVERY_ENABLED === undefined
+      ? true
+      : truthy(env.COST_CUR_DISCOVERY_ENABLED);
+    // Poll more frequently than the per-job retry interval. A worker tick can
+    // occur milliseconds before next_run_at; using the retry interval here
+    // would defer that job for another complete interval.
+    this.pollIntervalMs = Math.max(Number(env.COST_CUR_DISCOVERY_POLL_INTERVAL_MS || 60_000), 10_000);
+    this.batchSize = Math.min(Math.max(Number(env.COST_CUR_DISCOVERY_BATCH_SIZE || 25), 1), 100);
+    this.running = false;
+    this.timer = null;
+    this.initialTimer = null;
+  }
+
+  async tick() {
+    if (!this.enabled || this.running) return;
+    this.running = true;
+    try {
+      await this.repository.seedEligibleJobs();
+      const jobs = await this.repository.dueJobs(this.batchSize);
+      const concurrency = 5;
+      for (let index = 0; index < jobs.length; index += concurrency) {
+        await Promise.all(jobs.slice(index, index + concurrency).map((job) => this.service.run(job)));
+      }
+    } catch (error) {
+      this.logger.error?.("[Cost CUR Discovery] Scheduler tick failed", error);
+    } finally {
+      this.running = false;
+    }
+  }
+
+  start() {
+    if (!this.enabled || this.timer) {
+      if (!this.enabled) this.logger.log?.("[Cost CUR Discovery] Disabled");
+      return;
+    }
+    this.logger.log?.(`[Cost CUR Discovery] Started; poll=${Math.round(this.pollIntervalMs / 1000)}s batch=${this.batchSize}`);
+    this.initialTimer = setTimeout(() => void this.tick(), 1_000);
+    this.initialTimer.unref?.();
+    this.timer = setInterval(() => void this.tick(), this.pollIntervalMs);
+    this.timer.unref?.();
+  }
+
+  stop() {
+    if (this.initialTimer) clearTimeout(this.initialTimer);
+    if (this.timer) clearInterval(this.timer);
+    this.initialTimer = null;
+    this.timer = null;
+    this.logger.log?.("[Cost CUR Discovery] Stopped");
+  }
+}

package/src/cur-discovery/schema.js

@@ -0,0 +1,48 @@
+import { sql } from "drizzle-orm";
+
+export async function installCurDiscoverySchema(db, qSchema) {
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_cur_discovery_jobs (
+    id bigserial PRIMARY KEY,
+    tenant_id text NOT NULL,
+    connection_id text NOT NULL,
+    cur_bucket text NOT NULL,
+    cur_prefix text NOT NULL,
+    cur_region text NOT NULL,
+    tenant_partition text NOT NULL,
+    status text NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING', 'RUNNING', 'WAITING_FOR_DATA', 'WAITING_FOR_TABLE', 'READY', 'FAILED')),
+    attempt_count integer NOT NULL DEFAULT 0,
+    next_run_at timestamptz,
+    last_started_at timestamptz,
+    last_finished_at timestamptz,
+    glue_database text,
+    glue_table text,
+    table_location text,
+    cur_s3_uri text,
+    sample_object_key text,
+    last_data_at timestamptz,
+    last_error text,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (tenant_id, connection_id)
+  )`));
+  // Early CUR builds used uuid here. The discovery API treats tenant IDs as
+  // opaque strings, so normalize upgraded databases to the current schema.
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_cur_discovery_jobs
+    ALTER COLUMN tenant_id TYPE text USING tenant_id::text`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_cur_discovery_jobs_due_idx ON ${qSchema}.cost_cur_discovery_jobs (status, next_run_at)`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_cur_discovery_jobs_tenant_idx ON ${qSchema}.cost_cur_discovery_jobs (tenant_id, connection_id)`));
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_cur_discovery_job_logs (
+    id bigserial PRIMARY KEY,
+    job_id bigint NOT NULL REFERENCES ${qSchema}.cost_cur_discovery_jobs(id) ON DELETE CASCADE,
+    tenant_id text NOT NULL,
+    level text NOT NULL CHECK (level IN ('INFO', 'WARN', 'ERROR')),
+    event text NOT NULL,
+    message text NOT NULL,
+    details jsonb NOT NULL DEFAULT '{}'::jsonb,
+    created_at timestamptz NOT NULL DEFAULT now()
+  )`));
+  await db.execute(sql.raw(`ALTER TABLE ${qSchema}.cost_cur_discovery_job_logs
+    ALTER COLUMN tenant_id TYPE text USING tenant_id::text`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_cur_discovery_job_logs_job_idx ON ${qSchema}.cost_cur_discovery_job_logs (job_id, created_at DESC)`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_cur_discovery_job_logs_tenant_idx ON ${qSchema}.cost_cur_discovery_job_logs (tenant_id, created_at DESC)`));
+}

package/src/lib/cost-utils.js

@@ -0,0 +1,98 @@
+const GROSS_COST_RECORD_TYPES = [
+  "Usage", "Fee", "Tax", "Support", "Upfront", "Recurring", "RIFee",
+  "DiscountedUsage", "SavingsPlanCoveredUsage", "SavingsPlanRecurringFee",
+  "SavingsPlanUpfrontFee",
+];
+
+export const truthy = (value) => ["1", "true", "yes", "on"].includes(String(value || "").toLowerCase());
+export const rows = (result) => Array.isArray(result) ? result : result?.rows || [];
+export const iso = (date) => date.toISOString().slice(0, 10);
+export const amount = (metric) => Number(metric?.Amount || 0);
+export const round = (value) => Math.round((Number(value) + Number.EPSILON) * 100) / 100;
+
+export function safeSchema(value) {
+  const schema = String(value || "meyiconnect");
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema)) throw new Error("Invalid DB schema");
+  return schema;
+}
+
+export function dateRange(query = {}) {
+  const end = query.end ? new Date(`${query.end}T00:00:00Z`) : new Date();
+  const start = query.start ? new Date(`${query.start}T00:00:00Z`) : new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth(), 1));
+  const exclusiveEnd = new Date(end);
+  exclusiveEnd.setUTCDate(exclusiveEnd.getUTCDate() + (query.end ? 1 : 0));
+  if (!query.end) exclusiveEnd.setUTCDate(exclusiveEnd.getUTCDate() + 1);
+  if (!Number.isFinite(start.getTime()) || !Number.isFinite(exclusiveEnd.getTime()) || start >= exclusiveEnd) {
+    const error = new Error("Invalid cost date range");
+    error.statusCode = 400;
+    throw error;
+  }
+  return { Start: iso(start), End: iso(exclusiveEnd) };
+}
+
+export function accountFilter(accountIds) {
+  return accountIds.length ? { Dimensions: { Key: "LINKED_ACCOUNT", Values: accountIds } } : undefined;
+}
+
+export function combineFilters(...values) {
+  const filters = values.flat().filter(Boolean);
+  return filters.length === 0 ? undefined : filters.length === 1 ? filters[0] : { And: filters };
+}
+
+export function listParam(value) {
+  const values = Array.isArray(value) ? value : String(value || "").split(",");
+  return [...new Set(values.map((item) => String(item).trim()).filter(Boolean))].slice(0, 100);
+}
+
+export function grossCostFilter(accountIds, selections = {}) {
+  const filters = [];
+  const accounts = accountFilter(accountIds);
+  if (accounts) filters.push(accounts);
+  filters.push({ Dimensions: { Key: "RECORD_TYPE", Values: GROSS_COST_RECORD_TYPES } });
+  if (selections.services?.length) filters.push({ Dimensions: { Key: "SERVICE", Values: selections.services } });
+  if (selections.regions?.length) filters.push({ Dimensions: { Key: "REGION", Values: selections.regions } });
+  if (selections.accountIds?.length) filters.push({ Dimensions: { Key: "LINKED_ACCOUNT", Values: selections.accountIds } });
+  if (selections.tagKey && selections.tagValues?.length) filters.push({ Tags: { Key: selections.tagKey, Values: selections.tagValues } });
+  return combineFilters(filters);
+}
+
+export function normalizeServiceName(value) {
+  const name = String(value || "Other");
+  return name === "Amazon Elastic Compute Cloud - Compute" || name === "EC2 - Other"
+    ? "Amazon Elastic Compute Cloud"
+    : name;
+}
+
+export function parseGroups(results = [], accountNames = new Map(), groupType) {
+  const totals = new Map();
+  for (const period of results) {
+    for (const group of period.Groups || []) {
+      const rawKey = group.Keys?.join(" / ") || "Other";
+      const key = groupType === "service" ? normalizeServiceName(rawKey) : rawKey;
+      totals.set(key, (totals.get(key) || 0) + amount(group.Metrics?.UnblendedCost));
+    }
+  }
+  const sum = [...totals.values()].reduce((total, value) => total + value, 0);
+  return [...totals.entries()]
+    .filter(([, value]) => Math.abs(value) > 0.000001)
+    .map(([key, value]) => ({ key, label: accountNames.get(key) || key, accountId: groupType === "account" ? key : undefined, amount: round(value), percentage: sum ? round(value / sum * 100) : 0 }))
+    .sort((a, b) => b.amount - a.amount);
+}
+
+export function parseRelationships(results = [], primaryType, relatedType, accountNames = new Map()) {
+  const groupedItems = new Map();
+  for (const period of results) {
+    for (const group of period.Groups || []) {
+      let primary = group.Keys?.[0] || "Other";
+      if (primaryType === "service") primary = normalizeServiceName(primary);
+      const related = group.Keys?.[1] || "Unallocated";
+      if (!groupedItems.has(primary)) groupedItems.set(primary, new Map());
+      const values = groupedItems.get(primary);
+      values.set(related, (values.get(related) || 0) + amount(group.Metrics?.UnblendedCost));
+    }
+  }
+  return new Map([...groupedItems.entries()].map(([key, values]) => [key, [...values.entries()]
+    .map(([value, cost]) => ({ key: value, label: relatedType === "account" ? accountNames.get(value) || value : value, amount: round(cost) }))
+    .filter((item) => Math.abs(item.amount) > 0.000001)
+    .sort((a, b) => b.amount - a.amount)]));
+}

package/src/models/budget.model.js

@@ -0,0 +1,26 @@
+export class CostBudget {
+  constructor({ id, name, amount, currency = "USD", period = "monthly", spent = 0, alertThreshold = 80, provider = "aws", createdAt, updatedAt }) {
+    this.id = id;
+    this.name = name;
+    this.amount = Number(amount);
+    this.currency = currency;
+    this.period = period;
+    this.spent = Number(spent || 0);
+    this.alert_threshold = Number(alertThreshold);
+    this.provider = provider;
+    this.createdAt = createdAt;
+    if (updatedAt !== undefined) this.updatedAt = updatedAt;
+    Object.freeze(this);
+  }
+}
+
+export class BudgetAlertDismissal {
+  constructor({ budgetId, period, status, dismissedAt, dismissed }) {
+    this.budgetId = budgetId;
+    this.period = period;
+    this.status = status;
+    if (dismissedAt !== undefined) this.dismissedAt = dismissedAt;
+    if (dismissed !== undefined) this.dismissed = Boolean(dismissed);
+    Object.freeze(this);
+  }
+}

package/src/models/cur-data-status.model.js

@@ -0,0 +1,16 @@
+export class CurDataStatus {
+  constructor({ configured, required = false, ready = false, state, credentialMode = "saas-runtime", ingestionMode = "central", sourceConfigured = false, lastDataAt = null, recordCount = 0, message = null, discovery = null }) {
+    this.configured = Boolean(configured);
+    this.required = Boolean(required);
+    this.ready = Boolean(ready);
+    this.state = state || (this.ready ? "ready" : this.configured ? "pending" : "not_configured");
+    this.credentialMode = credentialMode;
+    this.ingestionMode = ingestionMode;
+    this.sourceConfigured = Boolean(sourceConfigured);
+    this.lastDataAt = lastDataAt;
+    this.recordCount = Number(recordCount || 0);
+    this.message = message;
+    this.discovery = discovery ? Object.freeze({ ...discovery }) : null;
+    Object.freeze(this);
+  }
+}

package/src/models/cur-ingestion.model.js

@@ -0,0 +1,9 @@
+export class CurIngestionDescriptor {
+  constructor({ tenant, metadata = {}, env = process.env }) {
+    this.mode = String(metadata.curIngestionMode || env.COST_CUR_INGESTION_MODE || "central").trim() || "central";
+    this.sourceConfigured = Boolean(metadata.curSourceBucket);
+    this.sourceRegion = metadata.curSourceRegion || null;
+    this.tenantPartition = String(env.COST_CUR_TENANT_PARTITION || metadata.curTenantPartition || tenant).trim();
+    Object.freeze(this);
+  }
+}

package/src/models/customer-aws-context.model.js

@@ -0,0 +1,20 @@
+const normalizeAccount = (account = {}) => Object.freeze({
+  id: String(account.id || account.aws_account_id || "").trim(),
+  name: String(account.name || account.id || account.aws_account_id || "").trim(),
+  region: String(account.region || "global").trim() || "global",
+  status: String(account.status || "active").trim() || "active",
+});
+
+export class CustomerAwsContext {
+  constructor({ tenant, accounts = [], client, credentials, meta = {}, roleArn, queryEnabled = false, accessMode = "not-configured" }) {
+    this.tenant = String(tenant || "default").trim() || "default";
+    this.accounts = Object.freeze(accounts.map(normalizeAccount).filter((account) => account.id));
+    this.client = client;
+    this.credentials = credentials;
+    this.meta = Object.freeze({ ...meta });
+    this.roleArn = roleArn || undefined;
+    this.queryEnabled = Boolean(queryEnabled);
+    this.accessMode = accessMode;
+    Object.freeze(this);
+  }
+}

package/src/models/saas-cur-context.model.js

@@ -0,0 +1,10 @@
+export class SaasCurContext {
+  constructor({ tenant, config, client, credentialMode, ingestion }) {
+    this.tenant = String(tenant || "default").trim() || "default";
+    this.config = Object.freeze({ ...config });
+    this.client = client;
+    this.credentialMode = credentialMode;
+    this.ingestion = ingestion;
+    Object.freeze(this);
+  }
+}

package/src/plugin.js

@@ -0,0 +1,72 @@
+import { AwsOnboardingRepository } from "./repositories/aws-onboarding.repository.js";
+import { BudgetRepository } from "./repositories/budget.repository.js";
+import { BudgetAlertRepository } from "./repositories/budget-alert.repository.js";
+import { CustomerAwsContextService } from "./services/customer-aws-context.service.js";
+import { SaasAthenaContextService } from "./services/saas-athena-context.service.js";
+import { BudgetService } from "./services/budget.service.js";
+import { BudgetAlertService } from "./services/budget-alert.service.js";
+import { CostExplorerService } from "./services/cost-explorer.service.js";
+import { CurProviderService } from "./services/cur-provider.service.js";
+import { CostController } from "./controllers/cost.controller.js";
+import { BudgetController } from "./controllers/budget.controller.js";
+import { createCostRouter } from "./routes/index.js";
+import { installCostBudgetSchema } from "./schema/cost-budget.schema.js";
+import { installCurDiscoverySchema } from "./cur-discovery/schema.js";
+import { CurDiscoveryRepository } from "./cur-discovery/cur-discovery.repository.js";
+import { CurDiscoveryAws } from "./cur-discovery/cur-discovery.aws.js";
+import { CurDiscoveryService } from "./cur-discovery/cur-discovery.service.js";
+import { CurDiscoveryWorker } from "./cur-discovery/cur-discovery.worker.js";
+import { safeSchema } from "./lib/cost-utils.js";
+
+export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = console } = {}) {
+  if (!db) throw new Error("db is required");
+  const schema = safeSchema(process.env.DB_SCHEMA || "meyiconnect");
+  const qSchema = `"${schema}"`;
+  const defaultTenant = String(process.env.DEFAULT_TENANT_ID || "default").trim() || "default";
+  const onboardingRepository = new AwsOnboardingRepository({ db, schema });
+  const contextService = new CustomerAwsContextService({ repository: onboardingRepository, defaultTenant });
+  const budgetRepository = new BudgetRepository({ db, qSchema });
+  const budgetAlertRepository = new BudgetAlertRepository({ db, qSchema });
+  const budgetService = new BudgetService({ repository: budgetRepository });
+  const budgetAlertService = new BudgetAlertService({ repository: budgetAlertRepository });
+  const explorerService = new CostExplorerService();
+  const athenaContextService = new SaasAthenaContextService();
+  const curProvider = new CurProviderService({ athenaContextService, logger });
+  const discoveryRepository = new CurDiscoveryRepository({ db, schema, qSchema });
+  const discoveryAws = new CurDiscoveryAws();
+  const discoveryIntervalMs = Math.max(Number(process.env.COST_CUR_DISCOVERY_INTERVAL_MS || 3_600_000), 60_000);
+  const discoveryService = new CurDiscoveryService({
+    repository: discoveryRepository,
+    aws: discoveryAws,
+    athenaContextService,
+    logger,
+    intervalMs: discoveryIntervalMs,
+  });
+  const discoveryWorker = new CurDiscoveryWorker({ repository: discoveryRepository, service: discoveryService, logger });
+  const costController = new CostController({ contextService, explorerService, curProvider, discoveryRepository, logger });
+  const budgetController = new BudgetController({ contextService, budgetService, budgetAlertService });
+  const router = createCostRouter({ costController, budgetController }, logger);
+  let mounted = false;
+
+  return {
+    async install() {
+      await installCostBudgetSchema(db, qSchema);
+      await installCurDiscoverySchema(db, qSchema);
+      logger.log?.("[Cost] Database migration verified");
+    },
+    async start() {
+      if (app && !mounted) {
+        app.use(`${apiBaseUri}/cost`, router);
+        mounted = true;
+      }
+      discoveryWorker.start();
+      logger.log?.(`[Cost] Routes active at ${apiBaseUri}/cost/*`);
+    },
+    async stop() {
+      discoveryWorker.stop();
+    },
+    router,
+  };
+}
+
+export default createInsightCost;

package/src/repositories/aws-onboarding.repository.js

@@ -0,0 +1,134 @@
+import { sql } from "drizzle-orm";
+import { rows } from "../lib/cost-utils.js";
+
+export class AwsOnboardingRepository {
+  constructor({ db, schema }) {
+    this.db = db;
+    this.schema = schema;
+    this.connectionsTable = `"${schema}".aws_connections`;
+    this.accountsTable = `"${schema}".aws_accounts`;
+    this.curConfigTable = `"${schema}".cost_cur_config`;
+    this.curDiscoveryTable = `"${schema}".cost_cur_discovery_jobs`;
+  }
+
+  async findCostAccess(tenant) {
+    const relations = rows(await this.db.execute(sql`
+      SELECT
+        to_regclass(${`${this.schema}.aws_connections`}) AS connections_table,
+        to_regclass(${`${this.schema}.aws_accounts`}) AS accounts_table,
+        to_regclass(${`${this.schema}.cost_cur_config`}) AS cur_config_table,
+        to_regclass(${`${this.schema}.cost_cur_discovery_jobs`}) AS cur_discovery_table
+    `))[0] || {};
+
+    if (!relations.connections_table) return { accounts: [], meta: {} };
+
+    const connection = rows(await this.db.execute(sql`
+      SELECT
+        connection_id,
+        role_arn,
+        external_id
+      FROM ${sql.raw(this.connectionsTable)}
+      WHERE tenant_id::text = ${tenant}
+        AND status = 'CONNECTED'
+        AND plugins ? 'Cost'
+        AND COALESCE(verification_checks->>'costAccess', 'false') = 'true'
+      ORDER BY connected_at DESC NULLS LAST, created_at DESC
+      LIMIT 1
+    `))[0];
+
+    if (!connection) return { accounts: [], meta: {} };
+
+    const curConfig = relations.cur_config_table ? rows(await this.db.execute(sql`
+      SELECT export_arn, bucket, prefix, region, tenant_partition, status, last_data_at
+      FROM ${sql.raw(this.curConfigTable)}
+      WHERE tenant_id::text = ${tenant}
+        AND connection_id = ${connection.connection_id}
+      LIMIT 1
+    `))[0] || {} : {};
+
+    const curDiscovery = relations.cur_discovery_table ? rows(await this.db.execute(sql`
+      SELECT id, status, attempt_count, glue_database, glue_table, table_location,
+             cur_s3_uri, last_data_at, last_error, last_started_at, last_finished_at, next_run_at
+      FROM ${sql.raw(this.curDiscoveryTable)}
+      WHERE tenant_id = ${tenant}
+        AND connection_id = ${connection.connection_id}
+      LIMIT 1
+    `))[0] || {} : {};
+
+    const accounts = relations.accounts_table ? rows(await this.db.execute(sql`
+      SELECT account_id, account_name, status
+      FROM ${sql.raw(this.accountsTable)}
+      WHERE tenant_id::text = ${tenant}
+        AND connection_id = ${connection.connection_id}
+        AND LOWER(status) = 'active'
+      ORDER BY account_name
+    `)) : [];
+
+    return {
+      accounts: accounts.map((item) => ({
+        id: item.account_id,
+        name: item.account_name || item.account_id,
+        region: "global",
+        status: item.status,
+      })),
+      meta: {
+        payerRoleArn: connection.role_arn,
+        externalId: connection.external_id,
+        connectionId: connection.connection_id,
+        curExportArn: curConfig.export_arn,
+        curSourceBucket: curConfig.bucket,
+        curSourcePrefix: curConfig.prefix,
+        curSourceRegion: curConfig.region,
+        curTenantPartition: curConfig.tenant_partition || tenant,
+        curIngestionMode: "central",
+        curStatus: curConfig.status,
+        curLastDataAt: curConfig.last_data_at,
+        curDiscoveredTable: curDiscovery.status === "READY" ? curDiscovery.glue_table : undefined,
+        curDiscovery: curDiscovery.id ? {
+          jobId: String(curDiscovery.id),
+          status: curDiscovery.status,
+          attemptCount: Number(curDiscovery.attempt_count || 0),
+          database: curDiscovery.glue_database,
+          table: curDiscovery.glue_table,
+          tableLocation: curDiscovery.table_location,
+          curS3Uri: curDiscovery.cur_s3_uri,
+          lastDataAt: curDiscovery.last_data_at,
+          lastError: curDiscovery.last_error,
+          lastStartedAt: curDiscovery.last_started_at,
+          lastFinishedAt: curDiscovery.last_finished_at,
+          nextRunAt: curDiscovery.next_run_at,
+        } : null,
+      },
+    };
+  }
+
+  async updateCurStatus(tenant, status) {
+    const relation = rows(await this.db.execute(sql`
+      SELECT to_regclass(${`${this.schema}.cost_cur_config`}) AS cur_config_table
+    `))[0];
+    if (!relation?.cur_config_table) return;
+    const curStatus = status.ready
+      ? "READY"
+      : status.state === "pending_data"
+        ? "WAITING_FOR_DATA"
+        : status.state === "unavailable"
+          ? "FAILED"
+          : "PROVISIONING";
+    await this.db.execute(sql`
+      UPDATE ${sql.raw(this.curConfigTable)}
+      SET status = ${curStatus},
+          last_data_at = ${status.lastDataAt || null},
+          verified_at = now(),
+          updated_at = now()
+      WHERE connection_id = (
+        SELECT connection_id
+        FROM ${sql.raw(this.connectionsTable)}
+        WHERE tenant_id::text = ${tenant}
+          AND status = 'CONNECTED'
+          AND plugins ? 'Cost'
+        ORDER BY connected_at DESC NULLS LAST, created_at DESC
+        LIMIT 1
+      )
+    `);
+  }
+}

package/src/repositories/budget-alert.repository.js

@@ -0,0 +1,37 @@
+import { sql } from "drizzle-orm";
+import { rows } from "../lib/cost-utils.js";
+
+export class BudgetAlertRepository {
+  constructor({ db, qSchema }) {
+    this.db = db;
+    this.budgetTable = `${qSchema}.cost_budgets`;
+    this.dismissalTable = `${qSchema}.cost_budget_alert_dismissals`;
+  }
+
+  list(tenantId, userId, period) {
+    return this.db.execute(sql`
+      SELECT budget_id, period, status, dismissed_at
+      FROM ${sql.raw(this.dismissalTable)}
+      WHERE tenant_id = ${tenantId} AND user_id = ${userId} AND period = ${period}
+    `).then(rows);
+  }
+
+  async budgetExists(tenantId, budgetId) {
+    const result = rows(await this.db.execute(sql`
+      SELECT id FROM ${sql.raw(this.budgetTable)}
+      WHERE id = ${budgetId} AND tenant_id = ${tenantId}
+      LIMIT 1
+    `));
+    return result.length > 0;
+  }
+
+  async dismiss({ tenantId, userId, budgetId, period, status }) {
+    await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.dismissalTable)}
+        (tenant_id, user_id, budget_id, period, status)
+      VALUES
+        (${tenantId}, ${userId}, ${budgetId}, ${period}, ${status})
+      ON CONFLICT (tenant_id, user_id, budget_id, period, status) DO NOTHING
+    `);
+  }
+}

package/src/repositories/budget.repository.js

@@ -0,0 +1,33 @@
+import { sql } from "drizzle-orm";
+import { rows } from "../lib/cost-utils.js";
+
+export class BudgetRepository {
+  constructor({ db, qSchema }) {
+    this.db = db;
+    this.table = `${qSchema}.cost_budgets`;
+  }
+
+  list(tenantId) {
+    return this.db.execute(sql`
+      SELECT * FROM ${sql.raw(this.table)}
+      WHERE tenant_id = ${tenantId}
+      ORDER BY created_at DESC
+    `).then(rows);
+  }
+
+  async create({ id, tenantId, name, amount, currency, period, alertThreshold }) {
+    await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.table)}
+        (id, tenant_id, name, amount, currency, period, alert_threshold)
+      VALUES
+        (${id}, ${tenantId}, ${name}, ${amount}, ${currency}, ${period}, ${alertThreshold})
+    `);
+  }
+
+  async delete(tenantId, id) {
+    await this.db.execute(sql`
+      DELETE FROM ${sql.raw(this.table)}
+      WHERE id = ${id} AND tenant_id = ${tenantId}
+    `);
+  }
+}

package/src/routes/index.js

@@ -0,0 +1,22 @@
+import { Router } from "express";
+
+export function createCostRouter({ costController, budgetController }, logger = console) {
+  const router = Router();
+  router.get("/accounts", costController.accounts.bind(costController));
+  router.get("/overview", costController.overview.bind(costController));
+  router.get("/filter-options", costController.filterOptions.bind(costController));
+  router.get("/reports", costController.reports.bind(costController));
+  router.get("/tags", costController.tags.bind(costController));
+  router.get("/data-status", costController.dataStatus.bind(costController));
+  router.get("/cur-discovery", costController.curDiscovery.bind(costController));
+  router.get("/budgets", budgetController.list.bind(budgetController));
+  router.post("/budgets", budgetController.create.bind(budgetController));
+  router.delete("/budgets/:id", budgetController.delete.bind(budgetController));
+  router.get("/budget-alert-dismissals", budgetController.listDismissals.bind(budgetController));
+  router.post("/budget-alert-dismissals", budgetController.dismissAlert.bind(budgetController));
+  router.use((error, _req, res, _next) => {
+    logger.error?.("[Cost] Request failed", error);
+    res.status(error.statusCode || 502).json({ error: error.message || "AWS Cost Explorer request failed", code: error.name });
+  });
+  return router;
+}

package/src/schema/cost-budget.schema.js

@@ -0,0 +1,9 @@
+import { sql } from "drizzle-orm";
+
+export async function installCostBudgetSchema(db, qSchema) {
+  await db.execute(sql.raw(`CREATE SCHEMA IF NOT EXISTS ${qSchema}`));
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_budgets (id text PRIMARY KEY, tenant_id text NOT NULL, name text NOT NULL, amount numeric(18,2) NOT NULL, currency text NOT NULL DEFAULT 'USD', period text NOT NULL DEFAULT 'monthly', spent numeric(18,2) NOT NULL DEFAULT 0, alert_threshold numeric(5,2) NOT NULL DEFAULT 80, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now(), UNIQUE (tenant_id, name))`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_budgets_tenant_idx ON ${qSchema}.cost_budgets (tenant_id)`));
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_budget_alert_dismissals (tenant_id text NOT NULL, user_id text NOT NULL, budget_id text NOT NULL REFERENCES ${qSchema}.cost_budgets(id) ON DELETE CASCADE, period text NOT NULL, status text NOT NULL CHECK (status IN ('near_limit', 'over_budget')), dismissed_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (tenant_id, user_id, budget_id, period, status))`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_budget_alert_dismissals_user_idx ON ${qSchema}.cost_budget_alert_dismissals (tenant_id, user_id, period)`));
+}

package/src/services/aws-context.service.js

@@ -0,0 +1 @@
+export { CustomerAwsContextService as AwsContextService } from "./customer-aws-context.service.js";

package/src/services/budget-alert.service.js

@@ -0,0 +1,47 @@
+import { BudgetAlertDismissal } from "../models/budget.model.js";
+const validPeriod = (value) => /^\d{4}-(0[1-9]|1[0-2])$/.test(String(value || ""));
+const validStatus = (value) => value === "near_limit" || value === "over_budget";
+
+export class BudgetAlertService {
+  constructor({ repository }) {
+    this.repository = repository;
+  }
+
+  async listDismissals(tenantId, userId, period) {
+    if (!userId) {
+      const error = new Error("Authenticated user is required");
+      error.statusCode = 401;
+      throw error;
+    }
+    if (!validPeriod(period)) {
+      const error = new Error("period must use YYYY-MM format");
+      error.statusCode = 400;
+      throw error;
+    }
+    const result = await this.repository.list(tenantId, userId, period);
+    return result.map((item) => new BudgetAlertDismissal({ budgetId: item.budget_id, period: item.period, status: item.status, dismissedAt: item.dismissed_at }));
+  }
+
+  async dismiss(tenantId, userId, payload = {}) {
+    const budgetId = String(payload.budgetId || "").trim();
+    const period = String(payload.period || "").trim();
+    const status = String(payload.status || "").trim();
+    if (!userId) {
+      const error = new Error("Authenticated user is required");
+      error.statusCode = 401;
+      throw error;
+    }
+    if (!budgetId || !validPeriod(period) || !validStatus(status)) {
+      const error = new Error("budgetId, a YYYY-MM period, and a valid status are required");
+      error.statusCode = 400;
+      throw error;
+    }
+    if (!await this.repository.budgetExists(tenantId, budgetId)) {
+      const error = new Error("Budget not found");
+      error.statusCode = 404;
+      throw error;
+    }
+    await this.repository.dismiss({ tenantId, userId, budgetId, period, status });
+    return new BudgetAlertDismissal({ budgetId, period, status, dismissed: true });
+  }
+}