@endora-commerce/mod-google-analytics 0.100.0

package/dist/manifest.js

@@ -0,0 +1,134 @@
+import { defineModuleManifest, defineModuleSettingsManifest } from '@endora-commerce/contracts';
+import { GOOGLE_ANALYTICS_SETTING_CODES } from '@endora-commerce/contracts';
+/**
+ * Google Analytics module (feature 049). Integrates the storefront with
+ * Google Analytics 4: per-sales-channel activation + Measurement ID, Enhanced
+ * Ecommerce, an optional server-side tagging delivery path (durable BullMQ
+ * worker — Principle X), and an admin custom-events builder. Per-channel
+ * configuration is stored through the Settings module; the Measurement Protocol
+ * API secret uses the `secret` value type (feature 043, AES-256-GCM at rest).
+ *
+ * Distinct from the legacy `analytics` module (internal first-party event log +
+ * env-gated forwarder), which this module supersedes for GA forwarding.
+ */
+export const googleAnalyticsSettingsManifest = defineModuleSettingsManifest({
+    moduleCode: 'google_analytics',
+    groups: [{ code: 'google_analytics', name: 'Google Analytics' }],
+    settings: [
+        {
+            // Feature 073 — the operator's activation control. Platform-wide, and
+            // deliberately not `google_analytics.enabled`: that code already exists
+            // and is per-sales-channel, answering "does GA4 load on this storefront".
+            // This one answers "does this client have Google Analytics at all".
+            code: 'google_analytics.module_enabled',
+            name: 'Google Analytics module enabled',
+            description: 'Switches GA4 injection, the custom-event mappings, the server-side delivery queue and the admin screen on or off for the whole platform. Separate from the per-channel switch, which decides where the tag actually loads. Nothing is dropped: mappings stay in the database and every setting keeps its value.',
+            groupCode: 'google_analytics',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.ENABLED,
+            name: 'Enable Google Analytics',
+            description: 'Master switch for the module. Per-channel overridable.',
+            groupCode: 'google_analytics',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.MEASUREMENT_ID,
+            name: 'Measurement ID',
+            description: 'GA4 Measurement ID (G-XXXXXXXXXX). Blank means the channel is untracked.',
+            groupCode: 'google_analytics',
+            valueType: 'string',
+            defaultValue: '',
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.ENHANCED_ECOMMERCE_ENABLED,
+            name: 'Enhanced Ecommerce',
+            description: 'Emit GA4 recommended ecommerce events (view_item, add_to_cart, begin_checkout, purchase).',
+            groupCode: 'google_analytics',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.SERVER_SIDE_ENABLED,
+            name: 'Server-side tagging',
+            description: 'Route the channel\'s events through the server-side delivery worker instead of the browser.',
+            groupCode: 'google_analytics',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.SERVER_SIDE_ENDPOINT,
+            name: 'Server-side endpoint',
+            description: 'Server-side GTM container URL. Blank uses the GA4 Measurement Protocol default endpoint.',
+            groupCode: 'google_analytics',
+            valueType: 'string',
+            defaultValue: '',
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.SERVER_SIDE_API_SECRET,
+            name: 'Measurement Protocol API secret',
+            description: 'GA4 Measurement Protocol API secret (GA4 Admin → Data Streams → Measurement Protocol API secrets). Stored encrypted at rest; write-only.',
+            groupCode: 'google_analytics',
+            valueType: 'secret',
+            defaultValue: '',
+        },
+        {
+            code: GOOGLE_ANALYTICS_SETTING_CODES.REQUIRE_CONSENT,
+            name: 'Require analytics consent',
+            description: 'When enabled, GA loads in Consent Mode v2 denied-by-default until consent is granted.',
+            groupCode: 'google_analytics',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+    ],
+});
+export const manifest = defineModuleManifest({
+    id: 'google_analytics',
+    name: 'Google Analytics',
+    description: 'Google Analytics 4 integration: per-sales-channel activation and Measurement ID, Enhanced Ecommerce, configurable custom events, and optional server-side tagging.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes are gated by; feature
+    // 072 made it a container resolution rather than a constructor argument.
+    //
+    // `cms` owns `cmsBlockSeedPort`, the seam the cookie-consent banner message
+    // is kept in place through (feature 075 / D-87). Declared rather than withheld
+    // as non-binding because the edge is binding in the direction that matters to
+    // an operator: the banner text *is* that block, and a consent banner with no
+    // message is not a reduced banner — it is a consent this deployment cannot
+    // show it asked for.
+    dependencies: ['audit_logs', 'cms', 'sales_channels', 'settings', 'auth'],
+    settings: googleAnalyticsSettingsManifest,
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    permissions: [
+        { code: 'google_analytics:read', label: 'View Google Analytics configuration' },
+        { code: 'google_analytics:write', label: 'Manage Google Analytics configuration and custom events' },
+    ],
+    actions: [
+        {
+            id: 'open-google-analytics',
+            labelKey: 'actions.openGoogleAnalytics.label',
+            descriptionKey: 'actions.openGoogleAnalytics.description',
+            icon: 'Sparkles',
+            targetRoute: '/google-analytics',
+            requiredPermission: 'google_analytics:read',
+            keywords: ['google', 'analytics', 'ga4', 'tracking', 'events', 'ecommerce'],
+            weight: 240,
+        },
+        {
+            id: 'new-google-analytics-event',
+            labelKey: 'actions.newCustomEvent.label',
+            descriptionKey: 'actions.newCustomEvent.description',
+            icon: 'Plus',
+            targetRoute: '/google-analytics/new',
+            requiredPermission: 'google_analytics:write',
+            keywords: ['google', 'analytics', 'ga4', 'event', 'zdarzenie', 'custom'],
+            weight: 241,
+        },
+    ],
+    activation: { settingCode: 'google_analytics.module_enabled', default: true },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/migrations/20260715T171116_google_analytics_init.d.ts

@@ -0,0 +1,14 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 049 — Google Analytics.
+ *
+ * Creates `ga_custom_events`: admin-defined mappings from a storefront trigger
+ * action to a named GA4 event, with the selected payload fields stored inline
+ * as JSONB (research §R9 / data-model simplification). Per-channel config lives
+ * in the Settings module (no table). `sales_channel_id` null ⇒ all channels.
+ */
+export declare class Migration20260715T171116GoogleAnalyticsInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260715T171116_google_analytics_init.d.ts.map

package/dist/migrations/20260715T171116_google_analytics_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260715T171116_google_analytics_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260715T171116_google_analytics_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;GAOG;AACH,qBAAa,2CAA4C,SAAQ,SAAS;IACzD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260715T171116_google_analytics_init.js

@@ -0,0 +1,35 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 049 — Google Analytics.
+ *
+ * Creates `ga_custom_events`: admin-defined mappings from a storefront trigger
+ * action to a named GA4 event, with the selected payload fields stored inline
+ * as JSONB (research §R9 / data-model simplification). Per-channel config lives
+ * in the Settings module (no table). `sales_channel_id` null ⇒ all channels.
+ */
+export class Migration20260715T171116GoogleAnalyticsInit extends Migration {
+    async up() {
+        this.addSql(`
+      create table "ga_custom_events" (
+        "id" uuid not null,
+        "sales_channel_id" uuid null,
+        "event_name" varchar(40) not null,
+        "trigger_action" varchar(32) not null,
+        "button_id" varchar(128) null,
+        "enabled" boolean not null default true,
+        "fields" jsonb not null default '[]',
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "ga_custom_events_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "ga_custom_events_channel_action_idx" on "ga_custom_events" ("sales_channel_id", "trigger_action");`);
+        this.addSql(`alter table "ga_custom_events" add constraint "ga_custom_events_sales_channel_id_foreign" ` +
+            `foreign key ("sales_channel_id") references "sales_channels" ("id") on update cascade on delete cascade;`);
+    }
+    async down() {
+        this.addSql(`drop table if exists "ga_custom_events" cascade;`);
+    }
+}
+//# sourceMappingURL=20260715T171116_google_analytics_init.js.map

package/dist/migrations/20260715T171116_google_analytics_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260715T171116_google_analytics_init.js","sourceRoot":"","sources":["../../src/migrations/20260715T171116_google_analytics_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,OAAO,2CAA4C,SAAQ,SAAS;IAC/D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;KAcX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,kHAAkH,CACnH,CAAC;QACF,IAAI,CAAC,MAAM,CACT,4FAA4F;YAC1F,0GAA0G,CAC7G,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,kDAAkD,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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. There is exactly one class here, which
+ * is the case most likely to tempt an author into publishing the class alone and
+ * calling it done — `blog` shipped `export *` on that reasoning until D-168, and
+ * an installed `blog` stopped the platform from booting.
+ *
+ * One class means the intra-module order this array carries is trivial, and it
+ * still is not the order the migration runs in: where this module's block sits
+ * relative to every other module's is decided by the manifest `dependencies`
+ * graph (feature 081), and this one names `sales_channels`, whose table the
+ * `ga_custom_events` foreign key references.
+ *
+ * The **named** export stays, 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 { Migration20260715T171116GoogleAnalyticsInit } from './20260715T171116_google_analytics_init.js';
+export declare const migrations: (typeof Migration20260715T171116GoogleAnalyticsInit)[];
+export { Migration20260715T171116GoogleAnalyticsInit };
+//# 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,2CAA2C,EAAE,MAAM,4CAA4C,CAAC;AAEzG,eAAO,MAAM,UAAU,wDAAgD,CAAC;AAExE,OAAO,EAAE,2CAA2C,EAAE,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,28 @@
+/**
+ * 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. There is exactly one class here, which
+ * is the case most likely to tempt an author into publishing the class alone and
+ * calling it done — `blog` shipped `export *` on that reasoning until D-168, and
+ * an installed `blog` stopped the platform from booting.
+ *
+ * One class means the intra-module order this array carries is trivial, and it
+ * still is not the order the migration runs in: where this module's block sits
+ * relative to every other module's is decided by the manifest `dependencies`
+ * graph (feature 081), and this one names `sales_channels`, whose table the
+ * `ga_custom_events` foreign key references.
+ *
+ * The **named** export stays, 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 { Migration20260715T171116GoogleAnalyticsInit } from './20260715T171116_google_analytics_init.js';
+export const migrations = [Migration20260715T171116GoogleAnalyticsInit];
+export { Migration20260715T171116GoogleAnalyticsInit };
+//# 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,2CAA2C,EAAE,MAAM,4CAA4C,CAAC;AAEzG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,2CAA2C,CAAC,CAAC;AAExE,OAAO,EAAE,2CAA2C,EAAE,CAAC"}

package/docs/google-analytics.md

@@ -0,0 +1,106 @@
+---
+title: Google Analytics
+description: Google Analytics 4 for the storefront — per-channel Measurement ID, Enhanced Ecommerce, a custom-events builder and optional server-side tagging
+---
+
+# Google Analytics
+
+The `google_analytics` module integrates the storefront with
+**Google Analytics 4**: per-Sales-Channel activation and Measurement ID,
+Enhanced Ecommerce, an admin-configurable custom-events builder, and an optional
+**server-side tagging** delivery path. It is a separate module from the legacy
+internal `analytics` event log and supersedes that module's env-gated GA4
+forwarder.
+
+## Configuration (Settings module)
+
+All per-channel configuration lives in the Settings module under the
+`google_analytics.*` group (global value + per-channel override):
+
+| Setting | Type | Meaning |
+| --- | --- | --- |
+| `google_analytics.enabled` | boolean | Master switch (per-channel overridable). |
+| `google_analytics.measurement_id` | string | GA4 `G-XXXXXXXXXX`. Blank ⇒ channel untracked. |
+| `google_analytics.enhanced_ecommerce_enabled` | boolean | Emit GA4 ecommerce events. |
+| `google_analytics.server_side_enabled` | boolean | Route events through the server-side worker. |
+| `google_analytics.server_side_endpoint` | string | Server-side GTM container URL (blank ⇒ GA4 Measurement Protocol). |
+| `google_analytics.server_side_api_secret` | secret | Measurement Protocol API secret (needs `SETTINGS_SECRET_ENCRYPTION_KEY`). |
+| `google_analytics.require_consent` | boolean | Load GA in Consent Mode v2 denied-by-default until consent is granted. |
+
+A channel with a blank Measurement ID emits nothing, regardless of the master
+switch.
+
+## Storefront behaviour
+
+- `gtag.js` is injected with `next/script` (`afterInteractive`, Core-Web-Vitals
+  safe) and initialized with `send_page_view: false`.
+- A `page_view` is emitted on every App-Router navigation (initial load plus
+  each client-side route change) — exactly one per destination.
+- **Consent Mode v2**: when `require_consent` is on, GA starts in the denied
+  default. A cookie banner drives `updateAnalyticsConsent(granted)` to flip to
+  granted. (This module provides the consent plumbing, not a full cookie
+  banner.)
+- **Enhanced Ecommerce** (when enabled): `view_item` (product page),
+  `add_to_cart`, `begin_checkout` (checkout), and `purchase` (order-confirmation
+  page).
+
+## Custom events
+
+Admins define custom events on the `/google-analytics` admin screen. Each event
+has a name (GA4 event-name shape), a trigger action, and a selected subset of
+the fields available for that action:
+
+| Trigger action | Available fields |
+| --- | --- |
+| `contact_form_submitted` | all contact-form fields **except file uploads** |
+| `place_order_clicked` | the checkout submission fields |
+| `add_to_cart` / `add_to_quote_request` / `add_to_shopping_list` | `sku`, `name`, `price`, `quantity` |
+| `button_click_by_id` | the originating page + the button's `data-*` attributes (requires a button ID) |
+
+Only the selected fields are sent; absent fields are omitted (never blocking the
+event). File uploads are never included. Custom events may be scoped to one
+channel or all channels, and multiple events may bind to the same action.
+
+> The storefront has no contact form yet; the `contact_form_submitted` trigger
+> ships as a client hook (`trackContactFormSubmit`) that becomes active once a
+> contact form is added.
+
+## Server-side tagging (pure Measurement Protocol)
+
+When `server_side_enabled` is on for a channel the module runs **pure
+server-side tagging through the platform's own server** — no external container
+and no browser-side Google library:
+
+- **gtag.js is not loaded.** Every event (page_view, Enhanced Ecommerce, custom)
+  is posted to `POST /api/v1/storefront/google-analytics/collect`, so **no hit
+  reaches Google directly from the browser** (best ad-blocker resilience, no
+  client/server double count).
+- The route is a **pure producer** — it validates and enqueues one job per event
+  onto the durable BullMQ queue `google_analytics.ss.deliver`. A separable worker
+  (co-located in the API process unless `BACKEND_ROLE=api`, then only in the
+  `worker` process) forwards each event to GA4 via the **Measurement Protocol**,
+  retrying on failure. Each event carries a stable `eventId` idempotency key.
+- **GA4 default metrics come for free.** The browser owns a first-party
+  `client_id` and a rolling 30-minute `session_id` (cookies only once consent is
+  granted; ephemeral in-memory before that) and sends `engagement_time_msec` with
+  every event, so GA4 auto-derives `first_visit`, `session_start`, sessions, and
+  active users from the MP stream.
+- **Optional destination override.** By default the worker sends to GA4's
+  Measurement Protocol endpoint. Set `server_side_endpoint` to route events to a
+  different collection URL instead (e.g. a self-hosted proxy or a server-side GTM
+  container). The `server_side_api_secret` (a GA4 Measurement Protocol API
+  secret, created under GA4 Admin → Data Streams → Measurement Protocol API
+  secrets) authenticates delivery.
+- **Consent** is carried in the MP payload (`analyticsStorage`) reflecting the
+  visitor's actual banner decision.
+- **Enhanced Measurement** is replicated in the browser (since gtag.js is not
+  loaded) and routed through the server: `scroll` (90%), outbound `click`,
+  `file_download`, `form_start` / `form_submit`, and `view_search_results` (site
+  search). Video engagement is not covered — it would require a client-side
+  YouTube-player integration. In client mode gtag.js emits all of these itself.
+
+## Permissions
+
+`google_analytics:read` and `google_analytics:write` gate the admin surface
+(custom-events CRUD). Per-channel Settings are managed through the generic
+Settings admin screen.

package/i18n/en.json

@@ -0,0 +1,33 @@
+{
+  "actions.openGoogleAnalytics.label": "Google Analytics",
+  "actions.openGoogleAnalytics.description": "Configure Google Analytics custom events",
+  "actions.newCustomEvent.label": "New Google Analytics event",
+  "actions.newCustomEvent.description": "Create a custom Google Analytics event",
+  "nav.googleAnalytics.label": "Google Analytics",
+  "customEvents.title": "Custom events",
+  "customEvents.subtitle": "Map storefront actions to Google Analytics events",
+  "customEvents.empty": "No custom events yet",
+  "customEvents.new": "New event",
+  "customEvents.edit": "Edit event",
+  "customEvents.eventName": "Event name",
+  "customEvents.triggerAction": "Trigger action",
+  "customEvents.buttonId": "Button ID",
+  "customEvents.salesChannel": "Sales channel",
+  "customEvents.allChannels": "All channels",
+  "customEvents.enabled": "Enabled",
+  "customEvents.fields": "Payload fields",
+  "customEvents.fieldsHint": "Pick which fields to send — values are filled automatically at the trigger.",
+  "customEvents.addField": "Add field",
+  "customEvents.fieldKey": "Field",
+  "customEvents.payloadKey": "Sent as",
+  "customEvents.sentAs": "sent as",
+  "customEvents.payloadKeyHint": "(same as field)",
+  "customEvents.save": "Save",
+  "customEvents.delete": "Delete",
+  "customEvents.actions.contact_form_submitted": "Contact form submitted",
+  "customEvents.actions.place_order_clicked": "Place Order clicked",
+  "customEvents.actions.add_to_cart": "Add to cart",
+  "customEvents.actions.add_to_quote_request": "Add to quote request",
+  "customEvents.actions.add_to_shopping_list": "Add to shopping list",
+  "customEvents.actions.button_click_by_id": "Button click (by ID)"
+}

package/i18n/pl.json

@@ -0,0 +1,33 @@
+{
+  "actions.openGoogleAnalytics.label": "Google Analytics",
+  "actions.openGoogleAnalytics.description": "Konfiguruj własne zdarzenia Google Analytics",
+  "actions.newCustomEvent.label": "Nowe zdarzenie Google Analytics",
+  "actions.newCustomEvent.description": "Utwórz własne zdarzenie Google Analytics",
+  "nav.googleAnalytics.label": "Google Analytics",
+  "customEvents.title": "Zdarzenia własne",
+  "customEvents.subtitle": "Przypisz akcje w Storefront do zdarzeń Google Analytics",
+  "customEvents.empty": "Brak zdarzeń własnych",
+  "customEvents.new": "Nowe zdarzenie",
+  "customEvents.edit": "Edytuj zdarzenie",
+  "customEvents.eventName": "Nazwa zdarzenia",
+  "customEvents.triggerAction": "Akcja wyzwalająca",
+  "customEvents.buttonId": "ID przycisku",
+  "customEvents.salesChannel": "Kanał sprzedaży",
+  "customEvents.allChannels": "Wszystkie kanały",
+  "customEvents.enabled": "Aktywne",
+  "customEvents.fields": "Pola payloadu",
+  "customEvents.fieldsHint": "Wybierz, które pola wysłać — wartości uzupełniają się automatycznie w miejscu zdarzenia.",
+  "customEvents.addField": "Dodaj pole",
+  "customEvents.fieldKey": "Pole",
+  "customEvents.payloadKey": "Wysyłane jako",
+  "customEvents.sentAs": "wysyłane jako",
+  "customEvents.payloadKeyHint": "(jak nazwa pola)",
+  "customEvents.save": "Zapisz",
+  "customEvents.delete": "Usuń",
+  "customEvents.actions.contact_form_submitted": "Zapis formularza kontaktowego",
+  "customEvents.actions.place_order_clicked": "Kliknięcie „Złóż zamówienie”",
+  "customEvents.actions.add_to_cart": "Dodaj do koszyka",
+  "customEvents.actions.add_to_quote_request": "Dodaj do zapytania ofertowego",
+  "customEvents.actions.add_to_shopping_list": "Dodaj do listy zakupowej",
+  "customEvents.actions.button_click_by_id": "Kliknięcie przycisku (wg ID)"
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@endora-commerce/mod-google-analytics",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Google Analytics 4 integration: per-sales-channel activation and Measurement ID, Enhanced Ecommerce, configurable custom events, and optional server-side tagging.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "google_analytics"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/google_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",
+    "bullmq": "^5",
+    "fastify": "^5",
+    "ioredis": "^5",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "zod": "^4",
+    "@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
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "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",
+    "bullmq": "^5.76.1",
+    "fastify": "^5.12.5",
+    "ioredis": "^5.10.1",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "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-google-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";