@meyicloud/meyi-cost-server 1.4.1 → 1.5.0

package/AGENTS.md

@@ -76,6 +76,7 @@ flowchart LR
 The plugin currently owns these route groups under `${apiBaseUri}/cost`:
 
 - `GET /accounts`, `/data-status`, `/overview`, `/filter-options`, `/reports`, `/tags`
+- `GET`/`PUT /analysis/schedule`, `GET /analysis/reports`, and tenant-scoped PDF downloads
 - `GET /budgets` and `POST /budgets`
 - `DELETE /budgets/:id`
 - `GET /budget-alert-dismissals` and `POST /budget-alert-dismissals`

package/README.md

@@ -30,6 +30,9 @@ and AWS onboarding. The plugin owns cost routes and its budget-related tables.
 - Explicit CUR setup, pending-data, and unavailable states
 - Tenant-scoped budget rules
 - User-, tenant-, month-, and status-scoped budget-alert dismissals
+- Tenant-configurable daily, weekly, and monthly AI report schedules
+- PostgreSQL-backed background report jobs with failure history
+- Server-generated PDF reports available through tenant-scoped downloads
 
 Budgets are application rules stored in PostgreSQL; they are not AWS Budgets
 resources. The consuming application evaluates them against current cost and
@@ -94,7 +97,7 @@ For a local package installation test:
 
 ```bash
 npm pack
-npm install /path/to/meyicloud-meyi-cost-server-1.4.1.tgz
+npm install /path/to/meyicloud-meyi-cost-server-1.5.0.tgz
 ```
 
 ## Publish to npm
@@ -257,17 +260,37 @@ SaaS Athena resources.
 
 AI analysis is optional and invokes Amazon Bedrock from the backend runtime.
 Only aggregated cost facts are sent to the model; tenant IDs, AWS credentials,
-resource IDs, and raw CUR rows are excluded.
+resource IDs, and raw CUR rows are excluded. AI reports are generated by a
+background worker, not by a browser request. Daily reports cover the previous
+complete day, weekly reports cover the previous seven complete days, and
+monthly reports cover the previous calendar month in the configured timezone.
+
+The authenticated report API is:
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/analysis/schedule` | Read this tenant's schedule. |
+| `PUT` | `/analysis/schedule` | Update the schedule; requires `req.user.role=admin`. |
+| `GET` | `/analysis/reports` | List tenant report history without PDF bytes. |
+| `GET` | `/analysis/reports/:id` | Read one tenant report. |
+| `GET` | `/analysis/reports/:id/pdf` | Download a completed report PDF. |
+
+Schedule and report rows live in `cost_ai_report_schedules` and
+`cost_ai_reports`. The worker atomically claims due schedules with a lease, so
+a restarted task can resume future work without relying on in-memory timers.
 
 | Variable | Default | Required | Purpose |
 | --- | --- | --- | --- |
 | `COST_AI_ENABLED` | `false` | No | Enables the AI analysis endpoints and Bedrock client. |
 | `COST_AI_REGION` | `AWS_REGION` or `us-east-1` | When enabled | Region used by the Bedrock Runtime client. |
 | `COST_AI_MODEL_ID` | Global Claude Sonnet inference profile | When enabled | Bedrock model or inference-profile ID. |
-| `COST_AI_MAX_TOKENS` | `1600` | No | Maximum response tokens, clamped from 600 to 3000. |
+| `COST_AI_MAX_TOKENS` | `4000` | No | Maximum response tokens, clamped from 600 to 8000. |
 | `COST_AI_CACHE_TTL_MS` | `21600000` | No | Tenant analysis cache duration; defaults to six hours. |
 | `COST_AI_HOURLY_LIMIT` | `6` | No | Maximum non-cached generations per tenant per hour. |
 | `COST_AI_TIMEOUT_MS` | `120000` | No | Per-request timeout for key-based providers; Bedrock uses the SDK default. |
+| `COST_AI_REPORT_POLL_INTERVAL_MS` | `60000` | No | How often the background worker claims due schedules; minimum 10 seconds. |
+| `COST_AI_REPORT_LEASE_MS` | `1800000` | No | Claim lease used to recover from an interrupted worker. |
+| `COST_AI_REPORT_BATCH_SIZE` | `5` | No | Maximum schedules claimed by one worker tick; clamped from 1 to 25. |
 
 ### Choosing a provider
 
@@ -305,8 +328,9 @@ tenant, including a `source` of `tenant-configuration` or `environment`.
 
 The runtime role needs `bedrock:InvokeModel` for the selected model or
 inference profile. Analysis results are stored in the tenant-scoped
-`cost_ai_analyses` table. Model or permission failures affect only the analysis
-request and do not change CUR, reports, or budgets.
+`cost_ai_analyses` table and scheduled PDF jobs are stored in
+`cost_ai_reports`. Model or permission failures mark only that scheduled report
+as failed and do not change CUR, standard reports, onboarding, or budgets.
 
 ### CUR/Athena variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meyicloud/meyi-cost-server",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Tenant-aware AWS CUR and Athena cost plugin server for MeyiConnect",
   "type": "module",
   "main": "./index.js",
@@ -25,7 +25,9 @@
     "@aws-sdk/client-sts": "^3.850.0",
     "@aws-sdk/credential-providers": "^3.850.0",
     "drizzle-orm": "^0.44.7",
-    "express": "^4.21.1"
+    "express": "^4.21.1",
+    "luxon": "^3.7.2",
+    "pdfkit": "^0.17.2"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/controllers/cost-analysis.controller.js

@@ -1,8 +1,7 @@
-import { dateRange } from "../lib/cost-utils.js";
-
 export class CostAnalysisController {
-  constructor({ service }) {
+  constructor({ service, reportService }) {
     this.service = service;
+    this.reportService = reportService;
   }
 
   async status(req, res, next) {
@@ -17,12 +16,33 @@ export class CostAnalysisController {
     } catch (error) { return next(error); }
   }
 
-  async generate(req, res, next) {
+  async schedule(req, res, next) {
+    try { return res.json(await this.reportService.getSchedule(req)); }
+    catch (error) { return next(error); }
+  }
+
+  async updateSchedule(req, res, next) {
+    try { return res.json(await this.reportService.saveSchedule(req, req.body || {})); }
+    catch (error) { return next(error); }
+  }
+
+  async reports(req, res, next) {
+    try { return res.json({ reports: await this.reportService.list(req, req.query.limit) }); }
+    catch (error) { return next(error); }
+  }
+
+  async report(req, res, next) {
+    try { return res.json(await this.reportService.get(req, req.params.id)); }
+    catch (error) { return next(error); }
+  }
+
+  async downloadPdf(req, res, next) {
     try {
-      const range = dateRange(req.body || {});
-      const durationDays = (new Date(`${range.End}T00:00:00Z`) - new Date(`${range.Start}T00:00:00Z`)) / 86_400_000;
-      if (durationDays > 366) return res.status(400).json({ error: "AI analysis supports a maximum range of 366 days" });
-      return res.json(await this.service.analyze(req, range));
+      const report = await this.reportService.pdf(req, req.params.id);
+      res.setHeader("Content-Type", "application/pdf");
+      res.setHeader("Content-Disposition", `attachment; filename="${report.filename}"`);
+      res.setHeader("Content-Length", report.data.length);
+      return res.send(report.data);
     } catch (error) { return next(error); }
   }
 }

package/src/lib/cost-analysis-schedule.js

@@ -0,0 +1,45 @@
+import { DateTime, IANAZone } from "luxon";
+
+const FREQUENCIES = new Set(["daily", "weekly", "monthly"]);
+
+export function validateSchedule(input = {}) {
+  const frequency = String(input.frequency || "weekly").toLowerCase();
+  const timezone = String(input.timezone || "UTC").trim();
+  const time = String(input.time || "09:00").trim();
+  if (!FREQUENCIES.has(frequency)) throw Object.assign(new Error("Frequency must be daily, weekly, or monthly"), { statusCode: 400 });
+  if (!IANAZone.isValidZone(timezone)) throw Object.assign(new Error("A valid IANA timezone is required"), { statusCode: 400 });
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)) throw Object.assign(new Error("Time must use 24-hour HH:mm format"), { statusCode: 400 });
+  const dayOfWeek = frequency === "weekly" ? Number(input.dayOfWeek ?? 1) : null;
+  const dayOfMonth = frequency === "monthly" ? Number(input.dayOfMonth ?? 1) : null;
+  if (dayOfWeek !== null && (!Number.isInteger(dayOfWeek) || dayOfWeek < 0 || dayOfWeek > 6)) throw Object.assign(new Error("Weekly day must be between 0 and 6"), { statusCode: 400 });
+  if (dayOfMonth !== null && (!Number.isInteger(dayOfMonth) || dayOfMonth < 1 || dayOfMonth > 28)) throw Object.assign(new Error("Monthly day must be between 1 and 28"), { statusCode: 400 });
+  return { enabled: Boolean(input.enabled), frequency, timezone, time, dayOfWeek, dayOfMonth };
+}
+
+function atTime(date, time) {
+  const [hour, minute] = time.split(":").map(Number);
+  return date.set({ hour, minute, second: 0, millisecond: 0 });
+}
+
+export function nextScheduleRun(schedule, after = new Date()) {
+  const local = DateTime.fromJSDate(after, { zone: schedule.timezone });
+  let candidate = atTime(local.startOf("day"), schedule.time);
+  if (schedule.frequency === "daily") {
+    if (candidate <= local) candidate = candidate.plus({ days: 1 });
+  } else if (schedule.frequency === "weekly") {
+    const targetWeekday = schedule.dayOfWeek === 0 ? 7 : schedule.dayOfWeek;
+    candidate = atTime(local.startOf("week").plus({ days: targetWeekday - 1 }), schedule.time);
+    if (candidate <= local) candidate = candidate.plus({ weeks: 1 });
+  } else {
+    candidate = atTime(local.startOf("month").set({ day: schedule.dayOfMonth }), schedule.time);
+    if (candidate <= local) candidate = atTime(candidate.plus({ months: 1 }).startOf("month").set({ day: schedule.dayOfMonth }), schedule.time);
+  }
+  return candidate.toUTC().toJSDate();
+}
+
+export function reportRange(schedule, scheduledFor) {
+  const scheduledDay = DateTime.fromJSDate(new Date(scheduledFor), { zone: schedule.timezone }).startOf("day");
+  const end = schedule.frequency === "monthly" ? scheduledDay.startOf("month") : scheduledDay;
+  const start = schedule.frequency === "monthly" ? end.minus({ months: 1 }) : end.minus({ days: schedule.frequency === "weekly" ? 7 : 1 });
+  return { Start: start.toISODate(), End: end.toISODate() };
+}

package/src/plugin.js

@@ -12,9 +12,13 @@ import { CostAnalysisController } from "./controllers/cost-analysis.controller.j
 import { createCostRouter } from "./routes/index.js";
 import { installCostBudgetSchema } from "./schema/cost-budget.schema.js";
 import { installCostAnalysisSchema } from "./schema/cost-analysis.schema.js";
+import { installCostAnalysisReportSchema } from "./schema/cost-analysis-report.schema.js";
 import { CostAnalysisRepository } from "./repositories/cost-analysis.repository.js";
+import { CostAnalysisReportRepository } from "./repositories/cost-analysis-report.repository.js";
 import { CostAnalysisDataService } from "./services/cost-analysis-data.service.js";
 import { CostAnalysisService } from "./services/cost-analysis.service.js";
+import { CostAnalysisReportService } from "./services/cost-analysis-report.service.js";
+import { CostAnalysisReportWorker } from "./workers/cost-analysis-report.worker.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";
@@ -32,6 +36,7 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
   const budgetRepository = new BudgetRepository({ db, qSchema });
   const budgetAlertRepository = new BudgetAlertRepository({ db, qSchema });
   const costAnalysisRepository = new CostAnalysisRepository({ db, qSchema });
+  const costAnalysisReportRepository = new CostAnalysisReportRepository({ db, qSchema });
   const budgetService = new BudgetService({ repository: budgetRepository });
   const budgetAlertService = new BudgetAlertService({ repository: budgetAlertRepository });
   const athenaContextService = new SaasAthenaContextService();
@@ -53,7 +58,9 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
   // 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 costAnalysisReportService = new CostAnalysisReportService({ contextService, repository: costAnalysisReportRepository, analysisService: costAnalysisService });
+  const costAnalysisReportWorker = new CostAnalysisReportWorker({ repository: costAnalysisReportRepository, analysisService: costAnalysisService, logger });
+  const costAnalysisController = new CostAnalysisController({ service: costAnalysisService, reportService: costAnalysisReportService });
   const router = createCostRouter({ costController, budgetController, costAnalysisController }, logger);
   let mounted = false;
 
@@ -61,6 +68,7 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
     async install() {
       await installCostBudgetSchema(db, qSchema);
       await installCostAnalysisSchema(db, qSchema);
+      await installCostAnalysisReportSchema(db, qSchema);
       await installCurDiscoverySchema(db, qSchema);
       logger.log?.("[Cost] Database migration verified");
     },
@@ -70,10 +78,12 @@ export function createInsightCost({ app, db, apiBaseUri = "/api/v1", logger = co
         mounted = true;
       }
       discoveryWorker.start();
+      costAnalysisReportWorker.start();
       logger.log?.(`[Cost] Routes active at ${apiBaseUri}/cost/*`);
     },
     async stop() {
       discoveryWorker.stop();
+      costAnalysisReportWorker.stop();
     },
     router,
   };

package/src/repositories/cost-analysis-report.repository.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "drizzle-orm";
+import { rows } from "../lib/cost-utils.js";
+
+export class CostAnalysisReportRepository {
+  constructor({ db, qSchema }) {
+    this.db = db;
+    this.schedules = `${qSchema}.cost_ai_report_schedules`;
+    this.reports = `${qSchema}.cost_ai_reports`;
+  }
+
+  async getSchedule(tenantId) {
+    return rows(await this.db.execute(sql`SELECT * FROM ${sql.raw(this.schedules)} WHERE tenant_id = ${tenantId}`))[0] || null;
+  }
+
+  async saveSchedule(tenantId, schedule, nextRunAt) {
+    return rows(await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.schedules)}
+        (tenant_id, enabled, frequency, time_of_day, timezone, day_of_week, day_of_month, next_run_at)
+      VALUES (${tenantId}, ${schedule.enabled}, ${schedule.frequency}, ${schedule.time}, ${schedule.timezone}, ${schedule.dayOfWeek}, ${schedule.dayOfMonth}, ${nextRunAt})
+      ON CONFLICT (tenant_id) DO UPDATE SET
+        enabled = EXCLUDED.enabled, frequency = EXCLUDED.frequency,
+        time_of_day = EXCLUDED.time_of_day, timezone = EXCLUDED.timezone,
+        day_of_week = EXCLUDED.day_of_week, day_of_month = EXCLUDED.day_of_month,
+        next_run_at = EXCLUDED.next_run_at, updated_at = now()
+      RETURNING *
+    `))[0];
+  }
+
+  async claimDue(limit, leaseMs) {
+    const leaseUntil = new Date(Date.now() + leaseMs);
+    const batchSize = Math.min(Math.max(Number(limit) || 10, 1), 50);
+    return rows(await this.db.execute(sql`
+      WITH due AS (
+        SELECT tenant_id, next_run_at AS scheduled_for
+        FROM ${sql.raw(this.schedules)}
+        WHERE enabled = true AND next_run_at IS NOT NULL AND next_run_at <= now()
+        ORDER BY next_run_at
+        FOR UPDATE SKIP LOCKED
+        LIMIT ${batchSize}
+      )
+      UPDATE ${sql.raw(this.schedules)} s
+      SET next_run_at = ${leaseUntil}, updated_at = now()
+      FROM due
+      WHERE s.tenant_id = due.tenant_id
+      RETURNING s.*, due.scheduled_for
+    `));
+  }
+
+  async setNextRun(tenantId, nextRunAt, completed = false, leaseUntil = null) {
+    await this.db.execute(sql`
+      UPDATE ${sql.raw(this.schedules)}
+      SET next_run_at = ${nextRunAt}, last_run_at = CASE WHEN ${completed} THEN now() ELSE last_run_at END, updated_at = now()
+      WHERE tenant_id = ${tenantId}
+        AND (${leaseUntil}::timestamptz IS NULL OR next_run_at = ${leaseUntil})
+    `);
+  }
+
+  async createReport(schedule, range) {
+    const inserted = rows(await this.db.execute(sql`
+      INSERT INTO ${sql.raw(this.reports)}
+        (id, tenant_id, schedule_frequency, scheduled_for, period_start, period_end)
+      VALUES (${randomUUID()}, ${schedule.tenant_id}, ${schedule.frequency}, ${schedule.scheduled_for}, ${range.Start}, ${range.End})
+      ON CONFLICT (tenant_id, scheduled_for) DO NOTHING
+      RETURNING *
+    `));
+    return inserted[0] || null;
+  }
+
+  async markRunning(id) {
+    return rows(await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET status = 'RUNNING', attempt_count = attempt_count + 1, started_at = now(), error = NULL, updated_at = now() WHERE id = ${id} AND status = 'PENDING' RETURNING *`))[0] || null;
+  }
+
+  async complete(id, analysis, pdf) {
+    await this.db.execute(sql`
+      UPDATE ${sql.raw(this.reports)} SET status = 'COMPLETED', model_id = ${analysis.modelId}, data_source = ${analysis.dataSource || null},
+        facts = ${JSON.stringify(analysis.facts)}::jsonb,
+        result = ${JSON.stringify({ summary: analysis.summary, findings: analysis.findings, recommendations: analysis.recommendations, limitations: analysis.limitations })}::jsonb,
+        pdf_data = ${pdf}, pdf_size = ${pdf.length}, completed_at = now(), updated_at = now()
+      WHERE id = ${id}
+    `);
+  }
+
+  async fail(id, error) {
+    await this.db.execute(sql`UPDATE ${sql.raw(this.reports)} SET status = 'FAILED', error = ${String(error?.message || error).slice(0, 2000)}, completed_at = now(), updated_at = now() WHERE id = ${id}`);
+  }
+
+  async list(tenantId, limit = 100) {
+    return rows(await this.db.execute(sql`
+      SELECT id, schedule_frequency, scheduled_for, period_start, period_end, status,
+             attempt_count, model_id, data_source, facts, result, pdf_size, error,
+             started_at, completed_at, created_at
+      FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId}
+      ORDER BY scheduled_for DESC LIMIT ${Math.min(Math.max(Number(limit) || 100, 1), 250)}
+    `));
+  }
+
+  async find(tenantId, id, includePdf = false) {
+    if (includePdf) {
+      return rows(await this.db.execute(sql`SELECT * FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId} AND id = ${id} LIMIT 1`))[0] || null;
+    }
+    return rows(await this.db.execute(sql`
+      SELECT id, schedule_frequency, scheduled_for, period_start, period_end, status,
+             attempt_count, model_id, data_source, facts, result, pdf_size, error,
+             started_at, completed_at, created_at
+      FROM ${sql.raw(this.reports)} WHERE tenant_id = ${tenantId} AND id = ${id} LIMIT 1
+    `))[0] || null;
+  }
+}

package/src/routes/index.js

@@ -11,7 +11,11 @@ export function createCostRouter({ costController, budgetController, costAnalysi
   router.get("/cur-discovery", costController.curDiscovery.bind(costController));
   router.get("/analysis/status", costAnalysisController.status.bind(costAnalysisController));
   router.get("/analysis/latest", costAnalysisController.latest.bind(costAnalysisController));
-  router.post("/analysis", costAnalysisController.generate.bind(costAnalysisController));
+  router.get("/analysis/schedule", costAnalysisController.schedule.bind(costAnalysisController));
+  router.put("/analysis/schedule", costAnalysisController.updateSchedule.bind(costAnalysisController));
+  router.get("/analysis/reports", costAnalysisController.reports.bind(costAnalysisController));
+  router.get("/analysis/reports/:id", costAnalysisController.report.bind(costAnalysisController));
+  router.get("/analysis/reports/:id/pdf", costAnalysisController.downloadPdf.bind(costAnalysisController));
   router.get("/budgets", budgetController.list.bind(budgetController));
   router.post("/budgets", budgetController.create.bind(budgetController));
   router.delete("/budgets/:id", budgetController.delete.bind(budgetController));

package/src/schema/cost-analysis-report.schema.js

@@ -0,0 +1,43 @@
+import { sql } from "drizzle-orm";
+
+export async function installCostAnalysisReportSchema(db, qSchema) {
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_ai_report_schedules (
+    tenant_id text PRIMARY KEY,
+    enabled boolean NOT NULL DEFAULT false,
+    frequency text NOT NULL DEFAULT 'weekly' CHECK (frequency IN ('daily', 'weekly', 'monthly')),
+    time_of_day time NOT NULL DEFAULT '09:00:00',
+    timezone text NOT NULL DEFAULT 'UTC',
+    day_of_week smallint CHECK (day_of_week BETWEEN 0 AND 6),
+    day_of_month smallint CHECK (day_of_month BETWEEN 1 AND 28),
+    next_run_at timestamptz,
+    last_run_at timestamptz,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now()
+  )`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_report_schedules_due_idx ON ${qSchema}.cost_ai_report_schedules (enabled, next_run_at)`));
+
+  await db.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${qSchema}.cost_ai_reports (
+    id text PRIMARY KEY,
+    tenant_id text NOT NULL,
+    schedule_frequency text NOT NULL CHECK (schedule_frequency IN ('daily', 'weekly', 'monthly')),
+    scheduled_for timestamptz NOT NULL,
+    period_start date NOT NULL,
+    period_end date NOT NULL,
+    status text NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')),
+    attempt_count integer NOT NULL DEFAULT 0,
+    model_id text,
+    data_source text,
+    facts jsonb,
+    result jsonb,
+    pdf_data bytea,
+    pdf_size integer,
+    error text,
+    started_at timestamptz,
+    completed_at timestamptz,
+    created_at timestamptz NOT NULL DEFAULT now(),
+    updated_at timestamptz NOT NULL DEFAULT now(),
+    UNIQUE (tenant_id, scheduled_for)
+  )`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_reports_tenant_created_idx ON ${qSchema}.cost_ai_reports (tenant_id, created_at DESC)`));
+  await db.execute(sql.raw(`CREATE INDEX IF NOT EXISTS cost_ai_reports_status_idx ON ${qSchema}.cost_ai_reports (status, created_at)`));
+}

package/src/services/cost-analysis-pdf.service.js

@@ -0,0 +1,42 @@
+import PDFDocument from "pdfkit";
+
+const money = (value, currency = "USD") => new Intl.NumberFormat("en-US", { style: "currency", currency }).format(Number(value || 0));
+
+export function createCostAnalysisPdf(analysis) {
+  return new Promise((resolve, reject) => {
+    const doc = new PDFDocument({ size: "A4", margin: 48, info: { Title: "Meyi Connect AI Cost Analysis", Author: "Meyi Connect" } });
+    const chunks = [];
+    doc.on("data", (chunk) => chunks.push(chunk));
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+    const ensure = (height = 80) => { if (doc.y + height > doc.page.height - 48) doc.addPage(); };
+    const inclusiveEnd = new Date(`${analysis.period.End}T00:00:00Z`);
+    inclusiveEnd.setUTCDate(inclusiveEnd.getUTCDate() - 1);
+    doc.font("Helvetica-Bold").fontSize(20).fillColor("#122235").text("AI Cost Analysis");
+    doc.moveDown(0.35).font("Helvetica").fontSize(9).fillColor("#53657a").text(`Generated ${new Date(analysis.generatedAt).toUTCString()} | AWS CUR | ${analysis.period.Start} to ${inclusiveEnd.toISOString().slice(0, 10)}`);
+    doc.moveDown(1).font("Helvetica-Bold").fontSize(12).fillColor("#122235").text("Executive summary");
+    doc.moveDown(0.35).font("Helvetica").fontSize(10).fillColor("#27384a").text(analysis.summary, { lineGap: 3 });
+    doc.moveDown(1).font("Helvetica-Bold").fontSize(12).fillColor("#122235").text("Cost facts");
+    doc.moveDown(0.35).font("Helvetica").fontSize(10).fillColor("#27384a");
+    doc.text(`Period spend: ${money(analysis.facts.currentTotal, analysis.facts.currency)}`);
+    doc.text(`Previous period: ${money(analysis.facts.previousTotal, analysis.facts.currency)}`);
+    doc.text(`Change: ${money(analysis.facts.change, analysis.facts.currency)} (${analysis.facts.changePercentage == null ? "no baseline" : `${analysis.facts.changePercentage}%`})`);
+    doc.moveDown(1).font("Helvetica-Bold").fontSize(12).fillColor("#122235").text("Key findings");
+    for (const finding of analysis.findings || []) {
+      ensure();
+      doc.moveDown(0.5).font("Helvetica-Bold").fontSize(10).fillColor("#122235").text(`${String(finding.severity).toUpperCase()}: ${finding.title}`);
+      doc.font("Helvetica").fillColor("#27384a").text(finding.explanation, { lineGap: 2 });
+      doc.fontSize(9).fillColor("#53657a").text(`Evidence: ${finding.evidence}`);
+    }
+    ensure();
+    doc.moveDown(1).font("Helvetica-Bold").fontSize(12).fillColor("#122235").text("Recommended actions");
+    for (const item of [...(analysis.recommendations || [])].sort((a, b) => a.priority - b.priority)) {
+      ensure();
+      doc.moveDown(0.5).font("Helvetica-Bold").fontSize(10).fillColor("#122235").text(`${item.priority}. ${item.title}`);
+      doc.font("Helvetica").fillColor("#27384a").text(item.action, { lineGap: 2 });
+      doc.fontSize(9).fillColor("#53657a").text(item.rationale);
+    }
+    doc.moveDown(1).font("Helvetica-Oblique").fontSize(8).fillColor("#6b7785").text("AI recommendations are advisory. Review them before changing AWS resources.");
+    doc.end();
+  });
+}

package/src/services/cost-analysis-report.service.js

@@ -0,0 +1,52 @@
+import { nextScheduleRun, reportRange, validateSchedule } from "../lib/cost-analysis-schedule.js";
+
+function scheduleDto(row) {
+  if (!row) return { enabled: false, frequency: "weekly", time: "09:00", timezone: "UTC", dayOfWeek: 1, dayOfMonth: 1, nextRunAt: null, lastRunAt: null };
+  return { enabled: row.enabled, frequency: row.frequency, time: String(row.time_of_day).slice(0, 5), timezone: row.timezone, dayOfWeek: row.day_of_week, dayOfMonth: row.day_of_month, nextRunAt: row.next_run_at, lastRunAt: row.last_run_at };
+}
+
+function reportDto(row) {
+  return {
+    id: row.id, frequency: row.schedule_frequency, scheduledFor: row.scheduled_for,
+    period: { Start: String(row.period_start).slice(0, 10), End: String(row.period_end).slice(0, 10) },
+    status: row.status, attempts: Number(row.attempt_count || 0), modelId: row.model_id,
+    dataSource: row.data_source, facts: row.facts || null, ...(row.result || {}),
+    pdfReady: row.status === "COMPLETED" && Number(row.pdf_size || 0) > 0,
+    pdfSize: Number(row.pdf_size || 0), error: row.error, startedAt: row.started_at,
+    completedAt: row.completed_at, createdAt: row.created_at,
+  };
+}
+
+export class CostAnalysisReportService {
+  constructor({ contextService, repository, analysisService }) {
+    this.contextService = contextService;
+    this.repository = repository;
+    this.analysisService = analysisService;
+  }
+
+  tenant(req) { return this.contextService.tenantId(req); }
+
+  async getSchedule(req) { return scheduleDto(await this.repository.getSchedule(this.tenant(req))); }
+
+  async saveSchedule(req, input) {
+    if (String(req.user?.role || "").toLowerCase() !== "admin") throw Object.assign(new Error("Administrator access is required to change the AI report schedule"), { statusCode: 403 });
+    const schedule = validateSchedule(input);
+    const nextRunAt = schedule.enabled ? nextScheduleRun(schedule) : null;
+    return scheduleDto(await this.repository.saveSchedule(this.tenant(req), schedule, nextRunAt));
+  }
+
+  async list(req, limit) { return (await this.repository.list(this.tenant(req), limit)).map(reportDto); }
+
+  async get(req, id) {
+    const row = await this.repository.find(this.tenant(req), id);
+    if (!row) throw Object.assign(new Error("AI cost report was not found"), { statusCode: 404 });
+    return reportDto(row);
+  }
+
+  async pdf(req, id) {
+    const row = await this.repository.find(this.tenant(req), id, true);
+    if (!row) throw Object.assign(new Error("AI cost report was not found"), { statusCode: 404 });
+    if (row.status !== "COMPLETED" || !row.pdf_data) throw Object.assign(new Error("The PDF is not ready"), { statusCode: 409 });
+    return { data: Buffer.from(row.pdf_data), filename: `meyi-cost-analysis-${String(row.period_start).slice(0, 10)}-${id.slice(0, 8)}.pdf` };
+  }
+}

package/src/workers/cost-analysis-report.worker.js

@@ -0,0 +1,66 @@
+import { nextScheduleRun, reportRange } from "../lib/cost-analysis-schedule.js";
+import { createCostAnalysisPdf } from "../services/cost-analysis-pdf.service.js";
+
+export class CostAnalysisReportWorker {
+  constructor({ repository, analysisService, logger = console, env = process.env, pdfGenerator = createCostAnalysisPdf }) {
+    this.repository = repository;
+    this.analysisService = analysisService;
+    this.logger = logger;
+    this.pdfGenerator = pdfGenerator;
+    this.enabled = String(env.COST_AI_ENABLED || "").toLowerCase() === "true";
+    this.pollMs = Math.max(Number(env.COST_AI_REPORT_POLL_INTERVAL_MS || 60_000), 10_000);
+    this.leaseMs = Math.max(Number(env.COST_AI_REPORT_LEASE_MS || 30 * 60_000), 60_000);
+    this.batchSize = Math.min(Math.max(Number(env.COST_AI_REPORT_BATCH_SIZE || 5), 1), 25);
+    this.running = false;
+    this.timer = null;
+    this.initialTimer = null;
+  }
+
+  async run(schedule) {
+    const normalized = { ...schedule, time: String(schedule.time_of_day).slice(0, 5), dayOfWeek: schedule.day_of_week, dayOfMonth: schedule.day_of_month };
+    const range = reportRange(normalized, schedule.scheduled_for);
+    const report = await this.repository.createReport(schedule, range);
+    const nextRunAt = nextScheduleRun(normalized, new Date());
+    if (!report) return this.repository.setNextRun(schedule.tenant_id, nextRunAt, false, schedule.next_run_at);
+    const claimed = await this.repository.markRunning(report.id);
+    if (!claimed) return this.repository.setNextRun(schedule.tenant_id, nextRunAt, false, schedule.next_run_at);
+    try {
+      const req = { body: { force: true }, headers: {}, user: { tenant_id: schedule.tenant_id, tenantId: schedule.tenant_id } };
+      const analysis = await this.analysisService.analyze(req, range);
+      const pdf = await this.pdfGenerator(analysis);
+      await this.repository.complete(report.id, analysis, pdf);
+      await this.repository.setNextRun(schedule.tenant_id, nextRunAt, true, schedule.next_run_at);
+    } catch (error) {
+      await this.repository.fail(report.id, error);
+      await this.repository.setNextRun(schedule.tenant_id, nextRunAt, true, schedule.next_run_at);
+      this.logger.error?.("[Cost AI Reports] Scheduled analysis failed", { tenantId: schedule.tenant_id, reportId: report.id, message: error.message });
+    }
+  }
+
+  async tick() {
+    if (!this.enabled || this.running) return;
+    this.running = true;
+    try {
+      const schedules = await this.repository.claimDue(this.batchSize, this.leaseMs);
+      for (const schedule of schedules) await this.run(schedule);
+    } catch (error) {
+      this.logger.error?.("[Cost AI Reports] Scheduler tick failed", error);
+    } finally { this.running = false; }
+  }
+
+  start() {
+    if (!this.enabled || this.timer) return;
+    this.initialTimer = setTimeout(() => void this.tick(), 2_000);
+    this.initialTimer.unref?.();
+    this.timer = setInterval(() => void this.tick(), this.pollMs);
+    this.timer.unref?.();
+    this.logger.log?.(`[Cost AI Reports] Scheduler started; poll=${Math.round(this.pollMs / 1000)}s`);
+  }
+
+  stop() {
+    if (this.initialTimer) clearTimeout(this.initialTimer);
+    if (this.timer) clearInterval(this.timer);
+    this.initialTimer = null;
+    this.timer = null;
+  }
+}