@endora-commerce/mod-analytics 0.100.0

package/dist/migrations/20260912T125655_analytics_events_tenant_scope_indexes.js

@@ -0,0 +1,37 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The two tenant-key indexes on `analytics_events` (feature 050, research
+ * §R5 — the guard filters on `organization_id` and `customer_account_id`,
+ * and neither column was indexed).
+ *
+ * They were created by the platform's frozen
+ * `Migration20260717T134752CoreTenantScopeIndexes` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3. Under D-226 a
+ * migration may name a table only if its own module, its transitive
+ * `dependencies` closure or the platform creates it; the platform declares
+ * no dependencies, so it could never name `analytics_events`. An instance
+ * that omits `analytics` had a frozen corpus indexing a table nothing
+ * builds. The table is this module's own, so here the closure is trivial.
+ *
+ * The statements are the frozen ones verbatim, `if not exists` and all, so
+ * the two paths reach one schema. A database that has already applied the
+ * frozen migration is offered nothing from it — the storage keys on the
+ * class name and holds no checksum — and these two are the no-ops they
+ * already read as.
+ *
+ * The frozen migration's note is worth carrying: `analytics_events` can grow
+ * large, and a plain in-transaction `CREATE INDEX` locks writes while it
+ * builds. Ops may pre-create both CONCURRENTLY out of band, which
+ * `if not exists` makes free.
+ */
+export class Migration20260912T125655AnalyticsEventsTenantScopeIndexes extends Migration {
+    async up() {
+        this.addSql('create index if not exists "analytics_events_organization_id_index" on "analytics_events" ("organization_id");');
+        this.addSql('create index if not exists "analytics_events_customer_account_id_index" on "analytics_events" ("customer_account_id");');
+    }
+    async down() {
+        this.addSql('drop index if exists "analytics_events_organization_id_index";');
+        this.addSql('drop index if exists "analytics_events_customer_account_id_index";');
+    }
+}
+//# sourceMappingURL=20260912T125655_analytics_events_tenant_scope_indexes.js.map

package/dist/migrations/20260912T125655_analytics_events_tenant_scope_indexes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125655_analytics_events_tenant_scope_indexes.js","sourceRoot":"","sources":["../../src/migrations/20260912T125655_analytics_events_tenant_scope_indexes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,yDAA0D,SAAQ,SAAS;IAC7E,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CACT,gHAAgH,CACjH,CAAC;QACF,IAAI,CAAC,MAAM,CACT,wHAAwH,CACzH,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,gEAAgE,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,CAAC,oEAAoE,CAAC,CAAC;IACpF,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's. The first is
+ * stamped inside the frozen historical prefix (`BASELINE_THROUGH`,
+ * `db/migration-order.ts`), so its position is history and the manifest graph
+ * does not move it.
+ *
+ * The **named** export stays beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports the class by name
+ * from this specifier, and a migration class name is contract in a way an
+ * entity class name is not: `mikro_orm_migrations` persists it, so it is a
+ * string every already-migrated database holds.
+ */
+import { Migration20260425T143139AnalyticsInit } from './20260425T143139_analytics_init.js';
+import { Migration20260912T125655AnalyticsEventsTenantScopeIndexes } from './20260912T125655_analytics_events_tenant_scope_indexes.js';
+export declare const migrations: (typeof Migration20260425T143139AnalyticsInit)[];
+export { Migration20260425T143139AnalyticsInit, Migration20260912T125655AnalyticsEventsTenantScopeIndexes, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,qCAAqC,EAAE,MAAM,qCAAqC,CAAC;AAC5F,OAAO,EAAE,yDAAyD,EAAE,MAAM,4DAA4D,CAAC;AAEvI,eAAO,MAAM,UAAU,kDAGtB,CAAC;AAEF,OAAO,EACL,qCAAqC,EACrC,yDAAyD,GAC1D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,30 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's. The first is
+ * stamped inside the frozen historical prefix (`BASELINE_THROUGH`,
+ * `db/migration-order.ts`), so its position is history and the manifest graph
+ * does not move it.
+ *
+ * The **named** export stays beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports the class by name
+ * from this specifier, and a migration class name is contract in a way an
+ * entity class name is not: `mikro_orm_migrations` persists it, so it is a
+ * string every already-migrated database holds.
+ */
+import { Migration20260425T143139AnalyticsInit } from './20260425T143139_analytics_init.js';
+import { Migration20260912T125655AnalyticsEventsTenantScopeIndexes } from './20260912T125655_analytics_events_tenant_scope_indexes.js';
+export const migrations = [
+    Migration20260425T143139AnalyticsInit,
+    Migration20260912T125655AnalyticsEventsTenantScopeIndexes,
+];
+export { Migration20260425T143139AnalyticsInit, Migration20260912T125655AnalyticsEventsTenantScopeIndexes, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,qCAAqC,EAAE,MAAM,qCAAqC,CAAC;AAC5F,OAAO,EAAE,yDAAyD,EAAE,MAAM,4DAA4D,CAAC;AAEvI,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,qCAAqC;IACrC,yDAAyD;CAC1D,CAAC;AAEF,OAAO,EACL,qCAAqC,EACrC,yDAAyD,GAC1D,CAAC"}

package/docs/analytics.md

@@ -0,0 +1,74 @@
+---
+title: analytics
+description: Storefront event ingest + admin aggregation + optional GA4 forwarder
+---
+
+# `analytics`
+
+Append-only event log fed by the storefront and admin, plus a small
+aggregation read path for the admin dashboard. An optional GA4 forwarder
+mirrors each ingested event into Google Analytics when configured.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `POST /api/v1/analytics/events` | storefront / admin (no auth) | Ingest a batch of events (≤ 100) |
+| `GET /api/v1/admin/analytics/summary` | admin (`analytics:read`) | Totals by type + per-day breakdown for a window |
+
+## Event types
+
+The Zod boundary accepts a fixed set:
+
+- `product.viewed`, `category.viewed`
+- `product.added_to_cart`, `cart.abandoned`
+- `order.placed`
+- `search.performed`, `filter.clicked`
+
+Adding a new type is a single edit in
+`packages/contracts/src/analytics.ts`.
+
+## Ingest semantics
+
+Storefront sends batches; the boundary Zod schema rejects an entire batch
+if any event is malformed (storefront should not be allowed to drift the
+type union). Per-event validation inside the service still runs in case a
+property field is unexpected — those individual events are reported in the
+response's `rejected` array and the rest of the batch lands.
+
+The endpoint returns `202 Accepted` with `{ accepted, rejected[] }`. Each
+stored row mirrors the request's `X-Request-Id` for cross-log correlation.
+
+## Aggregation
+
+`AnalyticsQueryService.summary({ from, to, salesChannelId? })` runs two
+window-bounded queries (totals by type, daily totals by type) against the
+`(occurred_at)` and `(type, occurred_at)` indexes. The dashboard never
+queries an unbounded range.
+
+## GA4 forwarder
+
+`buildForwarderFromEnv(env)` returns:
+
+- `Ga4Forwarder` — when both `ANALYTICS_GA4_MEASUREMENT_ID` and
+  `ANALYTICS_GA4_API_SECRET` are set. Each ingest is fire-and-forget POSTed
+  to GA4's Measurement Protocol; client_id is bucketed by sessionId →
+  customerAccountId → organizationId → `'anonymous'` so GA4 sees coherent
+  user journeys.
+- `NoopForwarder` — otherwise. Ingest never blocks on a forwarder failure
+  and the source events are durable in `analytics_events` regardless.
+
+## Entities
+
+`AnalyticsEvent` — `type`, `occurredAt`, `recordedAt`, optional
+`salesChannelId`, `customerAccountId`, `organizationId`, `sessionId`,
+`properties` (JSONB), `requestId`.
+
+## Extension points
+
+- **New consumers** — implement the `AnalyticsForwarder` interface and
+  register in the composition root (e.g. PostHog, Mixpanel, internal data
+  warehouse).
+- **Pre-aggregated rollups** — the dashboard query is fine at hundreds of
+  thousands of events; for sustained million-event volumes, materialise a
+  daily rollup table here and have the indexer fold inserts into it.

package/i18n/en.json

@@ -0,0 +1,19 @@
+{
+  "actions.openAnalytics.label": "Analytics",
+  "actions.openAnalytics.description": "Aggregated counts of storefront events",
+  "nav.analytics.label": "Analytics",
+  "page.title": "Analytics",
+  "page.descriptionPrefix": "Aggregated counts of storefront events. Window:",
+  "range.7days": "Last 7 days",
+  "range.30days": "Last 30 days",
+  "range.90days": "Last 90 days",
+  "refresh": "Refresh",
+  "loading": "Loading…",
+  "empty": "No events recorded in this window.",
+  "error.load": "Failed to load summary.",
+  "totals.title": "Totals by event type",
+  "daily.title": "Daily breakdown",
+  "column.eventType": "Event type",
+  "column.count": "Count",
+  "column.day": "Day"
+}

package/i18n/pl.json

@@ -0,0 +1,19 @@
+{
+  "actions.openAnalytics.label": "Analityka",
+  "actions.openAnalytics.description": "Zagregowane liczniki zdarzeń sklepu",
+  "nav.analytics.label": "Analityka",
+  "page.title": "Analityka",
+  "page.descriptionPrefix": "Zagregowane liczniki zdarzeń sklepu. Okno:",
+  "range.7days": "Ostatnie 7 dni",
+  "range.30days": "Ostatnie 30 dni",
+  "range.90days": "Ostatnie 90 dni",
+  "refresh": "Odśwież",
+  "loading": "Ładowanie…",
+  "empty": "Brak zdarzeń zarejestrowanych w tym oknie.",
+  "error.load": "Nie udało się załadować podsumowania.",
+  "totals.title": "Sumy wg typu zdarzenia",
+  "daily.title": "Rozbicie dzienne",
+  "column.eventType": "Typ zdarzenia",
+  "column.count": "Liczba",
+  "column.day": "Dzień"
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@endora-commerce/mod-analytics",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Server-side analytics aggregation and dashboard data feeds.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "analytics"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/analytics"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/platform": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-analytics — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";