@meyicloud/meyi-cost-server 1.4.1

package/AGENTS.md

@@ -0,0 +1,197 @@
+# Insight Cost Server Agent Guide
+
+## Scope
+
+This package is a tenant-aware Express plugin for AWS cost overview, reports,
+budgets, alert dismissals, Cost Explorer, and optional CUR/Athena data. It is
+designed to be mounted inside a host backend; it does not own login, tenant
+onboarding, or the host plugin registry.
+
+Never weaken tenant scoping or expose AWS credentials. A management/payer role
+may return organization and member-account costs. A member role normally only
+returns the costs visible to that member account.
+
+## Folder structure
+
+```text
+insight-cost-server/
+|-- src/
+|   |-- controllers/          # Maps validated HTTP input to service calls
+|   |-- routes/               # Express paths and common error handling
+|   |-- models/               # Immutable customer, SaaS CUR, and status models
+|   |-- repositories/         # Tenant-scoped onboarding persistence reads
+|   |-- services/             # Cost Explorer, SaaS Athena, context, budgets
+|   |-- schema/               # Plugin-owned database tables and installation
+|   |-- lib/                  # Stateless date, cost, and filter helpers
+|   `-- plugin.js             # Dependency composition and lifecycle
+|-- index.js                  # Public createInsightCost export
+|-- cur.js                    # CUR compatibility export
+|-- README.md                 # Runtime and AWS configuration
+|-- package.json
+`-- AGENTS.md
+```
+
+Keep HTTP concerns in routes/controllers, AWS and database behavior in services,
+schema creation in `schema`, and pure calculations in `lib`. `index.js` and
+`cur.js` must remain thin compatibility entry points.
+
+## AI provider abstraction
+
+`src/lib/llm-provider.js` is the only place that knows which vendor answers.
+`createLlmProvider({ provider, modelId, apiKey, region, ... })` returns an
+object with a single `converse({ system, messages, maxTokens, temperature,
+topP })` method resolving to `{ text }`. Bedrock, Anthropic and OpenAI are
+supported; `normalizeProviderName` matches loosely so UI labels like
+"AWS Bedrock" resolve correctly.
+
+`CostAnalysisService.resolveProvider(tenantId)` picks between a host-supplied
+`providerResolver` and the `COST_AI_*` environment defaults. Two rules matter:
+the analysis fingerprint is computed from the **effective** model so switching
+provider cannot serve a cached answer from the previous one, and a resolver
+failure degrades to the environment rather than failing the request.
+
+When adding a provider, add it here and to `test/llm-provider.test.js`; no
+other file should need to change.
+
+## Request and data flow
+
+```mermaid
+flowchart LR
+  Host[Host Express app] --> Auth[Host authentication middleware]
+  Auth --> Enabled[Tenant plugin-enabled check]
+  Enabled --> Router[/api/v1/cost router]
+  Router --> Controller[Cost controller]
+  Controller --> Customer[Customer AWS context service]
+  Customer -->|Customer role| CE[AWS Cost Explorer]
+  Controller --> Source{Configured source}
+  Source -->|CUR| SaaS[SaaS Athena context service]
+  SaaS --> Athena[Central tenant CUR partition]
+  Source -->|auto fallback| CE
+  Controller --> Budget[Budget and dismissal services]
+  Budget --> DB[(Tenant-scoped PostgreSQL)]
+  Athena --> Controller
+  CE --> Controller
+```
+
+The plugin currently owns these route groups under `${apiBaseUri}/cost`:
+
+- `GET /accounts`, `/data-status`, `/overview`, `/filter-options`, `/reports`, `/tags`
+- `GET /budgets` and `POST /budgets`
+- `DELETE /budgets/:id`
+- `GET /budget-alert-dismissals` and `POST /budget-alert-dismissals`
+
+## Integrating with another Express application
+
+Install from the registry after publishing, or use a local file dependency:
+
+```bash
+npm install @meyicloud/meyi-cost-server
+```
+
+```js
+import express from "express";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { createInsightCost } from "@meyicloud/meyi-cost-server";
+
+const app = express();
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle(pool);
+
+// Register host authentication before starting the cost plugin.
+app.use("/api/v1/cost", authenticateRequest);
+
+const costPlugin = createInsightCost({
+  app,
+  db,
+  apiBaseUri: "/api/v1",
+  logger: console,
+});
+
+await costPlugin.install();
+await costPlugin.start();
+```
+
+Call `install()` during plugin installation/migration so plugin-owned tables
+exist, then call `start()` once per process to mount routes. Call `stop()` from
+the host lifecycle when supported.
+
+The host authentication layer must populate the authenticated user and tenant
+context expected by the adapter (`req.user.id`, `req.user.tenant_id`, or the
+approved tenant header). The host must verify that this plugin is enabled for
+that tenant before requests reach its router. Do not trust an arbitrary tenant
+ID without authenticated host validation.
+
+The current Meyi Connect adapter is
+`meyi-connect/backend/src/plugins/cost/index.mjs`. It supplies the Drizzle
+database, authentication, tenant plugin checks, and host lifecycle wiring.
+
+## AWS and database configuration
+
+Use onboarding role metadata in production. Environment credentials are an
+explicit local-testing fallback and must stay backend-only. See `README.md` for
+the supported Cost Explorer, assume-role, CUR/Athena, and local-test variables.
+
+Important invariants:
+
+- Resolve the customer AWS role per tenant for Cost Explorer/account metadata.
+- Use only the SaaS runtime identity or `COST_CUR_ROLE_ARN` for Athena. Never
+  pass `CustomerAwsContext.credentials` into an Athena client.
+- Keep central catalog configuration in SaaS environment settings. A customer
+  onboarding record may supply source-bucket and tenant-partition metadata, but
+  cannot override the central catalog unless the explicit legacy compatibility
+  switch is enabled.
+- Scope account records, budgets, and alert dismissals by tenant.
+- Preserve payer/organization access when showing linked member accounts.
+- Keep CUR/Athena optional; `auto` may fall back to Cost Explorer, while `cur`
+  must surface CUR configuration/access errors.
+- Do not send access keys, secret keys, or session tokens in API responses or
+  logs.
+- Keep SQL parameterized and schema-qualified through the existing helpers.
+
+## Development and validation
+
+This package is native Node.js ESM and has no transpilation build step:
+
+```bash
+npm install
+node --check index.js
+node --check src/plugin.js
+npm test
+npm pack --dry-run
+```
+
+For any change, syntax-check every changed JavaScript file and exercise route
+creation with an Express app and a stub database. Changes to AWS queries should
+also test empty results, missing permissions, assumed-role failures, and both
+Cost Explorer and CUR source selection. Never use real customer credentials in
+automated tests.
+
+When packaging in Docker, copy `index.js`, `cur.js`, and the complete `src`
+directory. Copying only the entry point will produce runtime module-not-found
+errors after the package was split into layers.
+
+## Version and npm publishing
+
+Publishing changes external state. Only publish when explicitly authorized:
+
+```bash
+npm version patch
+npm pack --dry-run
+npm publish --access public
+```
+
+Confirm that the dry-run archive contains both entry points, all `src` layers,
+`README.md`, and `AGENTS.md`. Do not publish `.env` files, AWS credentials,
+database dumps, logs, screenshots, or host application source.
+
+## Change checklist
+
+1. Preserve `createInsightCost({ app, db, apiBaseUri, logger })` and its
+   `install`, `start`, and `stop` lifecycle.
+2. Add or change routes in the router, controller, service, and shared types as
+   appropriate; do not place the whole feature in one file.
+3. Validate tenant isolation for every query and mutation.
+4. Keep response shapes compatible with `@meyicloud/meyi-cost-ui`, or update both packages
+   and the host adapter in the same release.
+5. Run syntax checks and package dry-run, then build the consuming host backend.

package/README.md

@@ -0,0 +1,454 @@
+# Meyi Insight Cost Server
+
+Tenant-aware Express plugin that provides AWS cost overview, reports, dynamic
+filters, budgets, and budget-alert dismissals from centralized Cost and Usage
+Report (CUR) data queried through Athena. CUR is mandatory; the package does not
+call or fall back to AWS Cost Explorer.
+
+The package is designed to be mounted by a host backend. The host owns login,
+token verification, tenant/plugin enablement, PostgreSQL connection creation,
+and AWS onboarding. The plugin owns cost routes and its budget-related tables.
+
+## Package contract
+
+- Package name: `@meyicloud/meyi-cost-server`
+- Runtime: Node.js 20 or newer, ESM
+- Framework: Express 4
+- Database API: injected Drizzle PostgreSQL instance
+- Peer dependency: `pg >= 8`
+- Default route: `/api/v1/cost`
+- Public factory: `createInsightCost({ app, db, apiBaseUri, logger })`
+
+## Features
+
+- Tenant-isolated payer/organization and member-account cost views
+- Monthly and yearly overview data
+- Service, account, region, resource, and cost-allocation-tag reports
+- Dynamic service, region, linked-account, and tag filter options
+- Standard and comparison report data used by `@meyicloud/meyi-cost-ui`
+- CUR/Athena active-resource counts and detailed cost data
+- Explicit CUR setup, pending-data, and unavailable states
+- Tenant-scoped budget rules
+- User-, tenant-, month-, and status-scoped budget-alert dismissals
+
+Budgets are application rules stored in PostgreSQL; they are not AWS Budgets
+resources. The consuming application evaluates them against current cost and
+shows the notification UI.
+
+## Architecture and request flow
+
+```mermaid
+flowchart LR
+  Host[External Express application] --> Auth[Authentication]
+  Auth --> Enabled[Tenant plugin check]
+  Enabled --> Router[/api/v1/cost]
+  Router --> Controller[Cost controller]
+  Controller --> Customer[Tenant CUR metadata]
+  Controller --> SaaS[SaaS Athena context]
+  SaaS --> Athena[Central tenant-partitioned CUR]
+  Controller --> Budget[Budget services]
+  Budget --> DB[(PostgreSQL)]
+```
+
+```text
+src/
+|-- controllers/             HTTP-to-service orchestration
+|-- routes/                  Express routes and error handling
+|-- models/                  Normalized immutable domain models
+|-- repositories/            Tenant onboarding persistence access
+|-- services/                AWS CUR/Athena contexts and budgets
+|-- schema/                  Budget and dismissal table installation
+|-- lib/                     Cost, date, filter, and SQL helpers
+`-- plugin.js                Dependency composition and lifecycle
+```
+
+## Local development and validation
+
+Requirements:
+
+- Node.js 20 or newer
+- npm
+- PostgreSQL available to the host used for integration testing
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+This package is native JavaScript ESM and has no transpilation build step.
+Validate syntax and package contents with:
+
+```bash
+node --check index.js
+node --check cur.js
+node --check src/plugin.js
+npm pack --dry-run
+```
+
+When files below `src` change, syntax-check every changed `.js` file. The npm
+archive must include `index.js`, `cur.js`, the complete `src` directory,
+`README.md`, and `AGENTS.md`.
+
+For a local package installation test:
+
+```bash
+npm pack
+npm install /path/to/meyicloud-meyi-cost-server-1.4.1.tgz
+```
+
+## Publish to npm
+
+Publishing changes the external registry. Run these commands only after release
+authorization:
+
+```bash
+npm login
+npm whoami
+npm version patch
+npm pack --dry-run
+npm publish --access public
+```
+
+Use `npm version minor` or `npm version major` when appropriate. This server
+package currently has no compile step or `prepublishOnly` script, so syntax and
+integration validation must be completed before publishing.
+
+After publishing:
+
+```bash
+npm view @meyicloud/meyi-cost-server version
+npm install @meyicloud/meyi-cost-server@<published-version>
+```
+
+## Integrate with an external Express application
+
+Install the package and its PostgreSQL peer dependency:
+
+```bash
+npm install @meyicloud/meyi-cost-server pg
+```
+
+For local development, use a file dependency:
+
+```json
+{
+  "dependencies": {
+    "@meyicloud/meyi-cost-server": "file:../../meyi-market-places/insight-cost-server"
+  }
+}
+```
+
+Create the plugin using the host's Express app and Drizzle database:
+
+```js
+import express from "express";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { createInsightCost } from "@meyicloud/meyi-cost-server";
+
+const app = express();
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle(pool);
+
+app.use(express.json());
+
+// These host middlewares must be registered before plugin.start().
+app.use("/api/v1/cost", authenticateRequest);
+app.use("/api/v1/cost", requireCostPluginForTenant);
+
+const costPlugin = createInsightCost({
+  app,
+  db,
+  apiBaseUri: "/api/v1",
+  logger: console,
+});
+
+await costPlugin.install();
+await costPlugin.start();
+```
+
+Lifecycle behavior:
+
+- `install()` creates or verifies plugin-owned budget and dismissal tables.
+- `start()` mounts the router once at `${apiBaseUri}/cost`.
+- `stop()` is currently a no-op but is available for host lifecycle symmetry.
+- `router` is also returned for hosts that need custom mounting.
+
+`app` is optional only when the host mounts the returned `router` itself. `db`
+is required.
+
+## Host authentication and tenant contract
+
+Before a request reaches the plugin, the host should authenticate it and set:
+
+```js
+req.user = {
+  id: "authenticated-user-id",
+  tenant_id: "authenticated-tenant-id",
+};
+```
+
+The tenant resolver checks `req.user.tenant_id`, then `req.user.tenantId`, then
+`x-tenant-id`, then `DEFAULT_TENANT_ID`. In production, prefer an authenticated
+`req.user` tenant and do not accept an untrusted tenant header.
+
+The Marketplace onboarding integration loads tenant access from:
+
+- `<DB_SCHEMA>.aws_connections`
+- `<DB_SCHEMA>.aws_accounts`
+- `<DB_SCHEMA>.cost_cur_config`
+- `<DB_SCHEMA>.cost_cur_discovery_jobs`
+- `<DB_SCHEMA>.cost_cur_discovery_job_logs`
+
+Only a connected row containing `Cost` with verified Cost access is accepted.
+Connection metadata supplies account display names and CUR source metadata; the
+dedicated Cost CUR table supplies the tenant partition and delivery/readiness
+state. Customer credentials are never passed to the central Athena client.
+
+CUR discovery runs as one shared scheduler with independent tenant job rows.
+Each job checks only its configured S3 prefix, finds a tenant-safe Glue table,
+and verifies the tenant partition through Athena. A successful job becomes
+`READY` and is no longer scheduled. Job events are retained separately in
+`cost_cur_discovery_job_logs` and also include tenant and job IDs in application
+logs.
+
+## Data-source behavior
+
+### Central CUR through SaaS Athena
+
+CUR applies `line_item_unblended_cost > 0` for displayed gross cost and can also
+calculate net cost, credits/adjustments, active resources, detailed resource
+rows, account/region relationships, and allocation-tag data.
+
+The SaaS runtime identity, or the dedicated role configured by
+`COST_CUR_ROLE_ARN`, queries the SaaS-owned Athena/Glue/S3 resources. Customer
+onboarding creates a CUR 2.0 Data Export directly into a tenant prefix in the
+Meyi-owned bucket; customer AWS credentials are not reused for Athena.
+
+CUR is mandatory. `/data-status` reports whether configuration, discovery, and
+tenant rows are ready. Data endpoints return HTTP 503 with a structured state
+and action when CUR is not configured, still waiting for rows, or unavailable.
+
+## Environment variables
+
+All variables below belong to the **backend runtime**. Never place AWS or
+database secrets in `@meyicloud/meyi-cost-ui`, a browser environment, source control, or a
+Docker image layer. Supply them at container/process runtime.
+
+### Database and tenant variables
+
+| Variable | Default | Required | Purpose |
+| --- | --- | --- | --- |
+| `DB_SCHEMA` | `meyiconnect` | No | PostgreSQL schema containing onboarding and plugin-owned tables. |
+| `DEFAULT_TENANT_ID` | `default` | No | Final tenant fallback when authenticated request context is absent. Prefer authenticated tenant context in production. |
+| `DATABASE_URL` | None | Host-specific | Not read by the package directly. The host commonly uses it to create the injected `db` connection. |
+
+Production tenants should use per-tenant onboarding role metadata. Environment
+credentials are process-wide and therefore unsuitable as the normal credential
+source for a multi-tenant service.
+
+When customer environment credentials are enabled, central Athena is disabled
+unless `COST_CUR_ROLE_ARN` is also configured. This prevents the AWS SDK default
+credential chain from accidentally using a customer's local test key against
+SaaS Athena resources.
+
+### AI analysis variables
+
+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.
+
+| 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_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. |
+
+### Choosing a provider
+
+The `COST_AI_*` variables above configure the deployment default, which is
+Bedrock. A host application can additionally supply `providerResolver` to
+`createInsightCost` to select a provider per tenant:
+
+```js
+createInsightCost({
+  app, db,
+  providerResolver: async (tenantId) => ({
+    provider: "anthropic",        // bedrock | anthropic | openai
+    modelId: "claude-sonnet-4-5",
+    apiKey: "...",                // required for anthropic and openai
+    region: "ap-south-2",         // bedrock only
+    accessKeyId: "...",           // bedrock only; omit to use ambient credentials
+    secretAccessKey: "...",
+  }),
+})
+```
+
+Returning `null` falls back to the environment configuration, so a host that
+does not pass a resolver behaves exactly as before. A resolver that throws is
+logged and also falls back, so a credential-store outage degrades the feature
+rather than failing the request.
+
+Why this exists: Bedrock authenticates with SigV4 and is subject to
+account-level Anthropic model access. The key-based providers are not, so a
+deployment blocked on Bedrock model access can still run analysis. It also
+lets a customer bring their own model account.
+
+`GET /analysis/status` reports the provider that would serve the caller's
+tenant, including a `source` of `tenant-configuration` or `environment`.
+**Host applications are responsible for encrypting stored credentials.**
+
+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.
+
+### CUR/Athena variables
+
+| Variable | Default | Required | Purpose |
+| --- | --- | --- | --- |
+| `COST_DATA_SOURCE` | `cur` | No | Compatibility setting. Cost data is always CUR/Athena only. |
+| `COST_CUR_DATABASE` | Empty | CUR | Athena/Glue database containing the CUR table. |
+| `COST_CUR_TABLE` | Empty | No | Optional manual Glue table override. When empty, the tenant discovery job supplies the verified table. |
+| `COST_CUR_OUTPUT_LOCATION` | Empty | CUR | S3 URI where Athena writes query results. |
+| `COST_CUR_REGION` | `AWS_REGION` or `us-east-1` | No | Region for the Athena client. |
+| `COST_CUR_WORKGROUP` | `meyi-cost` | No | Meyi-owned Athena workgroup used for every query. |
+| `AWS_REGION` | `us-east-1` | No | Used as the CUR region fallback. |
+| `COST_CUR_TENANT_COLUMN` | `tenant_id` | No | CUR column used to isolate the Hive-style tenant partition. |
+| `COST_CUR_TENANT_PARTITION` | Request tenant ID | No | Overrides the partition value. Avoid a global override in multi-tenant production unless every request is intentionally mapped to that partition. |
+| `COST_CUR_MAX_ROWS` | `1000` | No | Resource-report row cap, clamped between 1 and 5000. |
+| `COST_CUR_ROLE_ARN` | Empty | No | Dedicated SaaS-side role assumed only for central Athena/Glue/S3 queries. |
+| `COST_CUR_EXTERNAL_ID` | Empty | No | External ID for the dedicated SaaS CUR role. |
+| `COST_CUR_ALLOW_TENANT_CATALOG` | `false` | No | Compatibility switch allowing tenant metadata to override the central catalog. Keep `false` for centralized SaaS CUR. |
+| `COST_CUR_INGESTION_MODE` | `central` | No | Describes the CUR ingestion contract returned by readiness status. |
+| `COST_CUR_STATUS_CACHE_MS` | `300000` | No | Cache duration for the live tenant CUR readiness query. |
+| `COST_CUR_DISCOVERY_ENABLED` | `true` | No | Enables tenant-specific background CUR discovery. |
+| `COST_CUR_DISCOVERY_INTERVAL_MS` | `3600000` | No | Retry interval for non-ready tenant jobs; minimum 60000 ms. |
+| `COST_CUR_DISCOVERY_BATCH_SIZE` | `25` | No | Maximum due tenant jobs selected per scheduler tick. |
+
+Central catalog settings come from the SaaS backend environment. Only the
+tenant partition and customer source metadata come from onboarding by default.
+Legacy per-tenant catalog overrides are accepted only when
+`COST_CUR_ALLOW_TENANT_CATALOG=true`.
+
+### Example: centralized CUR/Athena
+
+```env
+COST_DATA_SOURCE=cur
+COST_CUR_DATABASE=meyi_central_cur
+COST_CUR_TABLE=
+COST_CUR_OUTPUT_LOCATION=s3://meyi-saas-athena-results/
+COST_CUR_REGION=us-east-1
+COST_CUR_WORKGROUP=meyi-cost
+COST_CUR_TENANT_COLUMN=tenant_id
+COST_CUR_MAX_ROWS=1000
+COST_CUR_ROLE_ARN=arn:aws:iam::SAAS_ACCOUNT_ID:role/meyi-cur-query
+COST_CUR_ALLOW_TENANT_CATALOG=false
+COST_CUR_INGESTION_MODE=central
+COST_CUR_DISCOVERY_ENABLED=true
+COST_CUR_DISCOVERY_INTERVAL_MS=3600000
+```
+
+## Required AWS read-only access
+
+The **SaaS identity** must be able to query Athena, read the Glue
+catalog and central CUR bucket, and write to the Athena results bucket. The
+customer onboarding role needs only the customer-side permissions required by
+the chosen CUR export/DataSync design. These policies must remain separate.
+
+A payer/management-account role can expose organization-wide linked-account
+costs. A member-account role normally exposes only the costs AWS makes visible
+to that member. Separate member-account roles are not required merely to group
+organization cost by linked account when the payer role already has that data.
+
+## HTTP API
+
+Routes are mounted below `${apiBaseUri}/cost`:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/accounts` | Selected or discovered AWS accounts. |
+| `GET` | `/data-status` | Central CUR configuration, ingestion, readiness, row count, and freshness without exposing secrets. |
+| `GET` | `/overview` | Totals, trends, accounts, services, regions, and active resources when CUR is available. |
+| `GET` | `/filter-options` | Dynamic report filter values. |
+| `GET` | `/reports` | Standard/comparison source data grouped by service, account, region, resource, or tag. |
+| `GET` | `/tags` | Available cost-allocation tags. |
+| `GET` | `/analysis/status` | Whether Cost AI is enabled and its non-secret runtime metadata. |
+| `GET` | `/analysis/latest` | Latest stored analysis for the authenticated tenant. |
+| `POST` | `/analysis` | Generate or reuse a cached tenant analysis for a validated date range. |
+| `GET` | `/budgets` | Tenant budget rules. |
+| `POST` | `/budgets` | Create a tenant budget rule. |
+| `DELETE` | `/budgets/:id` | Delete a tenant budget rule. |
+| `GET` | `/budget-alert-dismissals` | Current user's persisted dismissals. |
+| `POST` | `/budget-alert-dismissals` | Dismiss one budget/month/status alert. |
+
+## Docker packaging
+
+When embedding the local package in a Docker build, copy all published package
+files, not only `index.js`:
+
+```text
+index.js
+cur.js
+src/
+package.json
+README.md
+AGENTS.md
+```
+
+Environment files should not be copied into the image. Pass required variables
+with the deployment platform, Docker Compose `env_file`, or secret manager at
+runtime.
+
+## Reference Meyi Connect integration
+
+The current host adapter is:
+
+`meyi-connect/backend/src/plugins/cost/index.mjs`
+
+It supplies the shared Drizzle database, authenticated token middleware,
+tenant-level plugin enablement, and plugin lifecycle wiring.
+
+## Consumer validation checklist
+
+1. Run server syntax checks and `npm pack --dry-run`.
+2. Install or refresh the package in the host backend.
+3. Run `install()` against a disposable/test database.
+4. Verify unauthenticated and disabled-tenant requests are rejected by the host.
+5. Verify two tenants cannot access each other's accounts, budgets, or alert
+   dismissals.
+6. Test CUR ready, not-configured, pending-data, and unavailable modes.
+7. Verify payer and member-account visibility matches the AWS role used.
+8. Build and start the consuming host backend before creating a Docker image.
+
+## Central CUR ingestion contract
+
+The package implements the application side of the FinOps-style design: strict
+credential separation, tenant-partitioned Athena queries, fail-closed data
+access, and live readiness/freshness reporting. The AWS data-transfer plane
+must deliver each customer's CUR objects into the central CUR layout consumed
+by Glue. That is deployment infrastructure, not an HTTP request made with a
+customer access key.
+
+Onboarding may persist these non-secret fields in session `meta`:
+
+```json
+{
+  "curSourceBucket": "customer-cur-bucket",
+  "curSourcePrefix": "reports/meyi/",
+  "curSourceRegion": "us-east-1",
+  "curTenantPartition": "authenticated-tenant-id",
+  "curIngestionMode": "central"
+}
+```
+
+The transfer pipeline must copy or replicate only that source prefix into the
+SaaS central location for the matching tenant partition. `GET /data-status`
+then verifies that Athena can see rows for that partition. Until rows arrive,
+cost endpoints remain unavailable and the UI directs the user to Cost sources
+or CUR discovery with the applicable readiness message.

package/cur.js

@@ -0,0 +1,2 @@
+// Backwards-compatible export for existing consumers. New code uses the layered service.
+export * from "./src/services/cur.service.js";

package/index.js

@@ -0,0 +1,2 @@
+export { createInsightCost, createInsightCost as default } from "./src/plugin.js";
+export { createLlmProvider, normalizeProviderName, PROVIDER_BEDROCK, PROVIDER_ANTHROPIC, PROVIDER_OPENAI } from "./src/lib/llm-provider.js";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@meyicloud/meyi-cost-server",
+  "version": "1.4.1",
+  "description": "Tenant-aware AWS CUR and Athena cost plugin server for MeyiConnect",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "index.js",
+    "cur.js",
+    "src",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-athena": "^3.850.0",
+    "@aws-sdk/client-bedrock-runtime": "^3.850.0",
+    "@aws-sdk/client-glue": "^3.850.0",
+    "@aws-sdk/client-s3": "^3.850.0",
+    "@aws-sdk/client-sts": "^3.850.0",
+    "@aws-sdk/credential-providers": "^3.850.0",
+    "drizzle-orm": "^0.44.7",
+    "express": "^4.21.1"
+  },
+  "peerDependencies": {
+    "pg": ">=8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}