@meyicloud/meyi-cost-server 1.4.1

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-analysis.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { round } from "./cost-utils.js";
+
+const text = (value, max = 1200) => String(value || "").trim().slice(0, max);
+const severity = (value) => ["low", "medium", "high"].includes(value) ? value : "medium";
+
+function median(values) {
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+function deltaRows(current = [], previous = [], limit = 8) {
+  const before = new Map(previous.map((item) => [item.label, Number(item.amount || 0)]));
+  return current.slice(0, limit).map((item) => {
+    const currentAmount = Number(item.amount || 0);
+    const previousAmount = before.get(item.label) || 0;
+    return {
+      label: text(item.label, 160),
+      current: round(currentAmount),
+      previous: round(previousAmount),
+      change: round(currentAmount - previousAmount),
+      changePercentage: previousAmount > 0 ? round((currentAmount - previousAmount) / previousAmount * 100) : null,
+      sharePercentage: Number.isFinite(Number(item.percentage)) ? round(Number(item.percentage)) : null,
+    };
+  }).sort((a, b) => Math.abs(b.change) - Math.abs(a.change));
+}
+
+export function buildCostFacts({ current, previous }) {
+  const currentTotal = round(current.totalCost || 0);
+  const previousTotal = round(previous.totalCost || 0);
+  const change = round(currentTotal - previousTotal);
+  const changePercentage = previousTotal > 0 ? round(change / previousTotal * 100) : null;
+  const historicalTotals = (current.trends || [])
+    .filter((item) => String(item.month || "") < String(current.period?.Start || ""))
+    .map((item) => Number(item.amount || 0))
+    .filter((value) => value > 0);
+  const baseline = median(historicalTotals);
+  const currentVsBaseline = baseline && baseline > 0 ? round((currentTotal - baseline) / baseline * 100) : null;
+  const serviceChanges = deltaRows(current.topServices, previous.topServices);
+  const accountChanges = deltaRows(current.topAccounts, previous.topAccounts, 6);
+  const topServiceShare = Number(current.topServices?.[0]?.percentage || 0);
+  const calculatedSignals = [];
+
+  if (changePercentage != null && Math.abs(changePercentage) >= 10) {
+    calculatedSignals.push({
+      severity: Math.abs(changePercentage) >= 25 ? "high" : "medium",
+      kind: "period_change",
+      message: `Spend ${changePercentage > 0 ? "increased" : "decreased"} ${Math.abs(changePercentage)}% compared with the preceding period.`,
+    });
+  }
+  if (currentVsBaseline != null && currentVsBaseline >= 25 && historicalTotals.length >= 3) {
+    calculatedSignals.push({ severity: "high", kind: "baseline_anomaly", message: `Spend is ${currentVsBaseline}% above the historical monthly median.` });
+  }
+  if (topServiceShare >= 50) {
+    calculatedSignals.push({ severity: "medium", kind: "service_concentration", message: `${text(current.topServices[0]?.label, 160)} represents ${round(topServiceShare)}% of spend.` });
+  }
+
+  return {
+    period: current.period,
+    comparisonPeriod: previous.period,
+    currency: current.currency || "USD",
+    dataSource: current.dataSource,
+    currentTotal,
+    previousTotal,
+    change,
+    changePercentage,
+    activeAccounts: Number(current.activeAccounts || 0),
+    activeResources: current.activeResources == null ? null : Number(current.activeResources),
+    historyMonths: historicalTotals.length,
+    historicalMonthlyMedian: baseline == null ? null : round(baseline),
+    currentVsBaselinePercentage: currentVsBaseline,
+    serviceChanges,
+    accountChanges,
+    topRegions: (current.topRegions || []).slice(0, 6).map((item) => ({ label: text(item.label, 160), amount: round(item.amount || 0), sharePercentage: round(item.percentage || 0) })),
+    calculatedSignals,
+    limitations: historicalTotals.length < 3 ? ["Fewer than three non-zero monthly data points are available, so anomaly confidence is limited."] : [],
+  };
+}
+
+export function redactFactsForModel(facts) {
+  return {
+    ...facts,
+    accountChanges: facts.accountChanges.map((item, index) => ({ ...item, label: `Account ${index + 1}` })),
+  };
+}
+
+export function analysisFingerprint(facts, modelId) {
+  return createHash("sha256").update(JSON.stringify({ facts, modelId })).digest("hex");
+}
+
+export function parseAnalysisResponse(value) {
+  const raw = String(value || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new Error("The AI response did not contain a JSON object");
+  const parsed = JSON.parse(raw.slice(start, end + 1));
+  const summary = text(parsed.summary, 3000);
+  const findings = Array.isArray(parsed.findings) ? parsed.findings.slice(0, 6).map((item) => ({
+    severity: severity(item?.severity),
+    title: text(item?.title, 160),
+    explanation: text(item?.explanation, 1000),
+    evidence: text(item?.evidence, 500),
+    estimatedImpact: Number.isFinite(Number(item?.estimatedImpact)) ? round(Number(item.estimatedImpact)) : null,
+  })).filter((item) => item.title && item.explanation) : [];
+  const recommendations = Array.isArray(parsed.recommendations) ? parsed.recommendations.slice(0, 6).map((item) => ({
+    priority: Math.min(Math.max(Number(item?.priority) || 2, 1), 3),
+    title: text(item?.title, 160),
+    action: text(item?.action, 800),
+    rationale: text(item?.rationale, 600),
+  })).filter((item) => item.title && item.action) : [];
+  const limitations = Array.isArray(parsed.limitations) ? parsed.limitations.slice(0, 5).map((item) => text(item, 400)).filter(Boolean) : [];
+  if (!summary || !findings.length || !recommendations.length) throw new Error("The AI response was missing required analysis fields");
+  return { summary, findings, recommendations, limitations };
+}

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/lib/llm-provider.js

@@ -0,0 +1,239 @@
+import { BedrockRuntimeClient, ConverseCommand } from "@aws-sdk/client-bedrock-runtime";
+
+/**
+ * One calling convention over the LLM providers the Cost plugin supports.
+ *
+ * Bedrock authenticates with SigV4 and is subject to account-level model
+ * access; the direct Anthropic and OpenAI providers authenticate with an API
+ * key and are not. That difference is the whole reason this abstraction exists
+ * - a deployment blocked on Bedrock model access can still run analysis
+ * against a key.
+ *
+ * Every provider takes the same call shape and returns { text }. Nothing above
+ * this file knows which one answered.
+ */
+
+export const PROVIDER_BEDROCK = "bedrock";
+export const PROVIDER_ANTHROPIC = "anthropic";
+export const PROVIDER_OPENAI = "openai";
+
+const ANTHROPIC_VERSION = "2023-06-01";
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Provider names arrive from a database row that a human filled in through a
+ * dropdown ("AWS Bedrock", "Anthropic", "OpenAI"), so normalise loosely rather
+ * than demanding an exact token.
+ */
+export function normalizeProviderName(value) {
+  const name = String(value || "").trim().toLowerCase();
+  if (!name) return PROVIDER_BEDROCK;
+  if (name.includes("bedrock")) return PROVIDER_BEDROCK;
+  if (name.includes("anthropic") || name.includes("claude")) return PROVIDER_ANTHROPIC;
+  if (name.includes("openai") || name.includes("gpt")) return PROVIDER_OPENAI;
+  return name;
+}
+
+function providerError(message, { name = "CostAiProviderError", statusCode = 502, cause } = {}) {
+  const error = new Error(message);
+  error.name = name;
+  error.statusCode = statusCode;
+  if (cause) error.cause = cause;
+  return error;
+}
+
+/**
+ * Read an HTTP error body without letting a provider's error text leak a key
+ * back to the caller. Bodies are truncated: some providers echo request context.
+ */
+async function readErrorBody(response) {
+  try {
+    const text = await response.text();
+    return String(text || "").slice(0, 500);
+  } catch {
+    return "";
+  }
+}
+
+async function postJson(url, { headers, body, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (error.name === "AbortError") {
+      throw providerError(`The model did not respond within ${Math.round(timeoutMs / 1000)}s`, { name: "CostAiTimeoutError", statusCode: 504 });
+    }
+    throw providerError(`Could not reach the model endpoint: ${error.message}`, { cause: error });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Shared by both Bedrock auth modes: Converse wire shape in, plain text out.
+ *
+ * Undefined sampling parameters are omitted rather than sent as null. Claude
+ * Haiku 4.5 and Sonnet 4.5 reject a request that carries both temperature and
+ * topP - "cannot both be specified for this model" - so the caller sends one.
+ */
+function converseRequestBody({ system, messages, maxTokens, temperature, topP }) {
+  const inferenceConfig = { maxTokens };
+  if (temperature !== undefined && temperature !== null) inferenceConfig.temperature = temperature;
+  if (topP !== undefined && topP !== null) inferenceConfig.topP = topP;
+  return {
+    system: [{ text: system }],
+    messages: messages.map((message) => ({ role: message.role, content: [{ text: message.text }] })),
+    inferenceConfig,
+  };
+}
+
+function converseResponseText(payload) {
+  return (payload?.output?.message?.content || []).map((item) => item.text || "").join("\n");
+}
+
+/**
+ * Bedrock with an API key (the ABSK... long-term or short-term keys issued in
+ * the Bedrock console). These are bearer tokens, not SigV4 credentials, so the
+ * AWS SDK cannot use them without the process-wide AWS_BEARER_TOKEN_BEDROCK
+ * variable - unusable here, because the token is per tenant and this process
+ * serves many. Calling the Converse REST endpoint directly keeps it per request.
+ *
+ * Authentication only. Model entitlement is still granted per AWS account, so a
+ * key cannot reach a model the account has not been approved for.
+ */
+function createBedrockBearerProvider({ modelId, region, apiKey, timeoutMs }) {
+  if (!region) throw providerError("Bedrock with an API key requires a region", { name: "CostAiConfigError", statusCode: 400 });
+  const endpoint = `https://bedrock-runtime.${region}.amazonaws.com/model/${encodeURIComponent(modelId)}/converse`;
+  return {
+    provider: PROVIDER_BEDROCK,
+    modelId,
+    region,
+    authMode: "api-key",
+    async converse(request) {
+      const response = await postJson(endpoint, {
+        headers: { authorization: `Bearer ${apiKey}` },
+        timeoutMs,
+        body: converseRequestBody(request),
+      });
+      if (!response.ok) {
+        // 404 here is Bedrock's shape for "account not entitled to this model",
+        // not a missing endpoint. Pass the message through so the UI can show it.
+        throw providerError(`Bedrock returned ${response.status}: ${await readErrorBody(response)}`, {
+          statusCode: response.status === 429 ? 429 : 502,
+        });
+      }
+      return { text: converseResponseText(await response.json()) };
+    },
+  };
+}
+
+/**
+ * Bedrock with SigV4. The original behaviour: the ambient credential chain (the
+ * ECS task role) unless explicit access keys are supplied, which is how a
+ * customer points the plugin at their own account.
+ */
+function createBedrockProvider({ modelId, region, apiKey, accessKeyId, secretAccessKey, sessionToken, client, timeoutMs }) {
+  // An injected client is a test seam and must win, so check it before the key.
+  if (!client && apiKey) return createBedrockBearerProvider({ modelId, region, apiKey, timeoutMs });
+  const credentials = accessKeyId && secretAccessKey
+    ? { accessKeyId, secretAccessKey, ...(sessionToken ? { sessionToken } : {}) }
+    : undefined;
+  const runtime = client || new BedrockRuntimeClient({ region, ...(credentials ? { credentials } : {}) });
+  return {
+    provider: PROVIDER_BEDROCK,
+    modelId,
+    region,
+    authMode: credentials ? "access-keys" : "ambient",
+    async converse(request) {
+      const response = await runtime.send(new ConverseCommand({ modelId, ...converseRequestBody(request) }));
+      return { text: converseResponseText(response) };
+    },
+  };
+}
+
+function createAnthropicProvider({ modelId, apiKey, baseUrl, timeoutMs }) {
+  if (!apiKey) throw providerError("The Anthropic provider requires an API key", { name: "CostAiConfigError", statusCode: 400 });
+  const endpoint = `${String(baseUrl || "https://api.anthropic.com").replace(/\/+$/, "")}/v1/messages`;
+  return {
+    provider: PROVIDER_ANTHROPIC,
+    modelId,
+    region: null,
+    async converse({ system, messages, maxTokens, temperature, topP }) {
+      const response = await postJson(endpoint, {
+        headers: { "x-api-key": apiKey, "anthropic-version": ANTHROPIC_VERSION },
+        timeoutMs,
+        body: {
+          model: modelId,
+          max_tokens: maxTokens,
+          ...(temperature === undefined || temperature === null ? {} : { temperature }),
+          ...(topP === undefined || topP === null ? {} : { top_p: topP }),
+          system,
+          messages: messages.map((message) => ({ role: message.role, content: message.text })),
+        },
+      });
+      if (!response.ok) {
+        throw providerError(`Anthropic API returned ${response.status}: ${await readErrorBody(response)}`, { statusCode: response.status === 429 ? 429 : 502 });
+      }
+      const payload = await response.json();
+      return { text: (payload.content || []).map((item) => item.text || "").join("\n") };
+    },
+  };
+}
+
+function createOpenAiProvider({ modelId, apiKey, baseUrl, timeoutMs }) {
+  if (!apiKey) throw providerError("The OpenAI provider requires an API key", { name: "CostAiConfigError", statusCode: 400 });
+  const endpoint = `${String(baseUrl || "https://api.openai.com").replace(/\/+$/, "")}/v1/chat/completions`;
+  return {
+    provider: PROVIDER_OPENAI,
+    modelId,
+    region: null,
+    async converse({ system, messages, maxTokens, temperature, topP }) {
+      const response = await postJson(endpoint, {
+        headers: { authorization: `Bearer ${apiKey}` },
+        timeoutMs,
+        body: {
+          model: modelId,
+          max_completion_tokens: maxTokens,
+          ...(temperature === undefined || temperature === null ? {} : { temperature }),
+          ...(topP === undefined || topP === null ? {} : { top_p: topP }),
+          messages: [
+            { role: "system", content: system },
+            ...messages.map((message) => ({ role: message.role, content: message.text })),
+          ],
+        },
+      });
+      if (!response.ok) {
+        throw providerError(`OpenAI API returned ${response.status}: ${await readErrorBody(response)}`, { statusCode: response.status === 429 ? 429 : 502 });
+      }
+      const payload = await response.json();
+      return { text: (payload.choices || []).map((choice) => choice.message?.content || "").join("\n") };
+    },
+  };
+}
+
+/**
+ * @param {object} config
+ * @param {string} config.provider    bedrock | anthropic | openai (loose match)
+ * @param {string} config.modelId
+ * @param {string} [config.apiKey]    required for anthropic and openai
+ * @param {string} [config.region]    bedrock only
+ * @param {string} [config.accessKeyId]      bedrock only; omit for ambient creds
+ * @param {string} [config.secretAccessKey]  bedrock only
+ * @param {string} [config.baseUrl]   overrides the provider endpoint
+ * @param {object} [config.client]    inject a Bedrock client, for tests
+ */
+export function createLlmProvider(config = {}) {
+  const provider = normalizeProviderName(config.provider);
+  const timeoutMs = Math.max(Number(config.timeoutMs || DEFAULT_TIMEOUT_MS), 1_000);
+  if (!config.modelId) throw providerError("A model id is required", { name: "CostAiConfigError", statusCode: 400 });
+  if (provider === PROVIDER_BEDROCK) return createBedrockProvider({ ...config, timeoutMs });
+  if (provider === PROVIDER_ANTHROPIC) return createAnthropicProvider({ ...config, timeoutMs });
+  if (provider === PROVIDER_OPENAI) return createOpenAiProvider({ ...config, timeoutMs });
+  throw providerError(`Unsupported AI provider "${config.provider}"`, { name: "CostAiConfigError", statusCode: 400 });
+}

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,17 @@
+export class CurDataStatus {
+  constructor({ configured, required = true, ready = false, state, action = null, 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.action = action;
+    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,15 @@
+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 = [], meta = {} }) {
+    this.tenant = String(tenant || "default").trim() || "default";
+    this.accounts = Object.freeze(accounts.map(normalizeAccount).filter((account) => account.id));
+    this.meta = Object.freeze({ ...meta });
+    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,82 @@
+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 { CurProviderService } from "./services/cur-provider.service.js";
+import { CostController } from "./controllers/cost.controller.js";
+import { BudgetController } from "./controllers/budget.controller.js";
+import { CostAnalysisController } from "./controllers/cost-analysis.controller.js";
+import { createCostRouter } from "./routes/index.js";
+import { installCostBudgetSchema } from "./schema/cost-budget.schema.js";
+import { installCostAnalysisSchema } from "./schema/cost-analysis.schema.js";
+import { CostAnalysisRepository } from "./repositories/cost-analysis.repository.js";
+import { CostAnalysisDataService } from "./services/cost-analysis-data.service.js";
+import { CostAnalysisService } from "./services/cost-analysis.service.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, providerResolver = null } = {}) {
+  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 costAnalysisRepository = new CostAnalysisRepository({ db, qSchema });
+  const budgetService = new BudgetService({ repository: budgetRepository });
+  const budgetAlertService = new BudgetAlertService({ repository: budgetAlertRepository });
+  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, curProvider, discoveryRepository, logger });
+  const budgetController = new BudgetController({ contextService, budgetService, budgetAlertService });
+  const costAnalysisDataService = new CostAnalysisDataService({ curProvider });
+  // providerResolver lets the host supply per-tenant LLM credentials (the AI
+  // Providers screen). Null keeps the environment-only behaviour.
+  const costAnalysisService = new CostAnalysisService({ contextService, dataService: costAnalysisDataService, repository: costAnalysisRepository, logger, providerResolver });
+  const costAnalysisController = new CostAnalysisController({ service: costAnalysisService });
+  const router = createCostRouter({ costController, budgetController, costAnalysisController }, logger);
+  let mounted = false;
+
+  return {
+    async install() {
+      await installCostBudgetSchema(db, qSchema);
+      await installCostAnalysisSchema(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;