Meyi Insight Cost UI

Reusable React UI package for AWS cost overview, monthly/yearly trends, service/account/region breakdowns, standard and comparison reports, scheduled AI report history and downloads plus standard CSV/PDF cost exports.

The package is intended to run inside an authenticated host application. It does not contain AWS credentials, query AWS directly, perform login, or decide whether a plugin is enabled for a tenant. Those responsibilities remain with the host and @meyicloud/meyi-cost-server.

Package contract

• Package name: @meyicloud/meyi-cost-ui
• Runtime: React 19 and React DOM 19, supplied by the consuming application
• Module outputs: ESM, CommonJS, TypeScript declarations, and CSS
• Default UI route: /cost
• Expected server route: ${apiBase}/cost, normally /api/v1/cost

Architecture

flowchart LR
  Host[External React application] --> Route[Authenticated /cost/* route]
  Route --> Page[CostPage]
  Page --> Router[Package router]
  Router --> Features[Overview / AI Analysis / Reports / Sources]
  Features --> Hooks[Feature hooks]
  Hooks --> Service[costService]
  Service --> API[Configured Axios client]
  API --> Backend[/api/v1/cost]

The source follows a feature-oriented structure:

src/
|-- components/              Shared charts and UI primitives
|-- features/
|   |-- overview/            Dashboard, cards, charts, and loading state
|   |-- reports/             Filters, standard/compare reports, tables, export
|-- services/cost.ts         Backend API boundary
|-- api.ts                   Axios configuration and auth interceptor helper
|-- CostPage.tsx             Public embeddable component
|-- router.tsx               Internal routes and navigation metadata
|-- types.ts                 Public and internal cost types
|-- styles/index.css         Package styles
`-- index.tsx                Public exports

Local development and build

Requirements:

• Node.js 20 or newer
• npm

From insight-cost-ui:

npm install
npm run dev
npm run build

npm run dev starts the Vite development server. npm run build creates:

dist/index.mjs       ESM bundle
dist/index.js        CommonJS bundle
dist/index.d.ts      TypeScript declarations
dist/style.css       Styles imported by the consuming application

Do not manually edit dist; rebuild it from src.

Validate the npm package

Run a packaging dry-run before publishing:

npm pack --dry-run

The archive should contain dist, README.md, AGENTS.md, and package.json. It must not contain .env files, tokens, AWS credentials, or host application source.

For a local package installation test:

npm pack
npm install /path/to/meyicloud-meyi-cost-ui-1.4.0.tgz

Publish to npm

Publishing changes the external registry. Run these commands only from the package folder and only after obtaining release authorization:

npm login
npm whoami
npm version patch
npm pack --dry-run
npm publish --access public

Use npm version minor or npm version major instead when the release requires that semantic-version change. The prepublishOnly script automatically runs npm run build; a build failure prevents publishing.

After publishing, verify from a clean consumer project:

npm view @meyicloud/meyi-cost-ui version
npm install @meyicloud/meyi-cost-ui@<published-version>

Integrate with an external React application

Install the published package:

npm install @meyicloud/meyi-cost-ui

For local development before publishing, add a file dependency:

{
  "dependencies": {
    "@meyicloud/meyi-cost-ui": "file:../../meyi-market-places/insight-cost-ui"
  }
}

Build the UI package before building the host when using a file dependency.

1. Add an authenticated wildcard route

The route must accept child paths such as /cost/reports and /cost/analysis. The exact wildcard syntax depends on the host router.

import { CostPage } from "@meyicloud/meyi-cost-ui";
import "@meyicloud/meyi-cost-ui/style.css";

export function CostPluginRoute() {
  const token = getCurrentAccessToken();
  const role = getCurrentUserRole();

  return (
    <CostPage
      apiBase="/api/v1"
      basePath="/cost"
      token={token}
      userRole={role}
    />
  );
}

2. Attach the host's token refresh flow when needed

Passing token is sufficient for a fixed bearer token. If the host refreshes tokens dynamically, attach its normal Axios interceptors to the exported API, or use the included local-storage helper:

import {
  api as costApi,
  attachAuthInterceptors,
} from "@meyicloud/meyi-cost-ui";

attachAuthInterceptors(costApi);

The included helper reads access_token from browser local storage. A host using cookies, another storage key, or token refresh should attach its own request/response interceptors instead.

3. Route backend requests

With apiBase="/api/v1", the package requests /api/v1/cost/*. The host or reverse proxy must route those requests to an installed cost server and must apply authentication and tenant resolution before the cost endpoints.

4. Add navigation and plugin enablement

The package exports costNavItems for Overview, AI Analysis, Reports, Sources, and CUR Discovery. The host may map these entries into its sidebar. Tenant-level installation, role checks, and dynamic menu visibility remain host responsibilities.

CostPage properties

| Property | Required | Default | Purpose | | --- | --- | --- | --- | | apiBase | Yes | None | Base API prefix. /cost is appended automatically. | | basePath | No | /cost | Router base path where the host mounts the UI. | | token | No | None | Bearer token added to cost API requests. | | userRole | No | user | Controls visibility of AI report schedule settings. The server independently requires the admin role when saving. |

Environment variables

The UI package does not read process.env, import.meta.env, or any VITE_* variable directly. This is deliberate: a published browser package cannot safely contain tenant secrets or AWS credentials.

Configure deployment-specific values in the host application and pass the result to CostPage. For example, a Vite host may use:

VITE_API_BASE=/api/v1

<CostPage apiBase={import.meta.env.VITE_API_BASE} basePath="/cost" />

VITE_API_BASE is only an example host variable; it is not consumed by @meyicloud/meyi-cost-ui itself. Never define AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, database credentials, or other secrets in the frontend environment because browser build variables are visible to users.

Server API expected by the UI

The UI consumes these routes below ${apiBase}/cost:

• GET /accounts
• GET /overview
• GET /data-status
• GET /filter-options
• GET /reports
• GET /tags
• GET /analysis/status, GET /analysis/latest, and POST /analysis
• GET /budget-alert-dismissals and POST /budget-alert-dismissals

Use the matching cost server version whenever API response contracts change.

Reference Meyi Connect integration

• Frontend route: meyi-connect/frontend-v2/src/routes/_authenticated/cost/$.tsx
• Sidebar integration: meyi-connect/frontend-v2/src/components/layout/sidebar.tsx
• Backend adapter: meyi-connect/backend/src/plugins/cost/index.mjs

Consumer validation checklist

1. Build @meyicloud/meyi-cost-ui.
2. Install or refresh the package in the host.
3. Build the host frontend.
4. Verify direct navigation and refresh for /cost, /cost/reports, and /cost/analysis.
5. Verify authenticated requests reach /api/v1/cost with the correct tenant.
6. Test loading, empty, error, monthly/yearly, graph/list, report filters, compare mode, pagination, and PDF/CSV export states.