@endora-commerce/mod-pwa 0.100.0

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 (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 **named** exports stay 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 each 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.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260625T144228PwaInit } from './20260625T144228_pwa_init.js';
+import { Migration20260830T172022PwaOrganizationAttribution } from './20260830T172022_pwa_organization_attribution.js';
+export declare const migrations: (typeof Migration20260625T144228PwaInit)[];
+export { Migration20260625T144228PwaInit, Migration20260830T172022PwaOrganizationAttribution, };
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,kDAAkD,EAAE,MAAM,mDAAmD,CAAC;AAEvH,eAAO,MAAM,UAAU,4CAGtB,CAAC;AAEF,OAAO,EACL,+BAA+B,EAC/B,kDAAkD,GACnD,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,31 @@
+/**
+ * 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 **named** exports stay 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 each 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.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260625T144228PwaInit } from './20260625T144228_pwa_init.js';
+import { Migration20260830T172022PwaOrganizationAttribution } from './20260830T172022_pwa_organization_attribution.js';
+export const migrations = [
+    Migration20260625T144228PwaInit,
+    Migration20260830T172022PwaOrganizationAttribution,
+];
+export { Migration20260625T144228PwaInit, Migration20260830T172022PwaOrganizationAttribution, };
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,kDAAkD,EAAE,MAAM,mDAAmD,CAAC;AAEvH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,+BAA+B;IAC/B,kDAAkD;CACnD,CAAC;AAEF,OAAO,EACL,+BAA+B,EAC/B,kDAAkD,GACnD,CAAC"}

package/docs/pwa.md

@@ -0,0 +1,93 @@
+---
+title: PWA (Progressive Web App)
+description: Progressive-Web-App capabilities for the storefront and admin — installability, opt-in asset caching, a controlled update path and opt-in push
+---
+
+# PWA (Progressive Web App)
+
+The `pwa` module adds Progressive-Web-App capabilities to the
+storefront and admin: home-screen installability, a Settings-driven per-Sales-
+Channel installable identity, opt-in static-asset caching, a controlled service-
+worker update path, and opt-in push notifications behind a provider-agnostic
+abstraction.
+
+## For the Product Owner
+
+- **Install to home screen** — buyers can add the storefront to their phone's
+  home screen; it launches like a native app with your configured name and icon.
+  Staff can likewise install the admin panel as a separate app.
+- **Configure from Settings** — set the app name, short name, theme/background
+  color, upload an icon, and turn caching and push on/off in **Settings → PWA**.
+  Each value can be global or overridden per Sales Channel. Changes apply within
+  about a minute, no deploy needed.
+- **Faster, offline-resilient storefront** — with caching on, repeat visits load
+  the shell from the device and a clear offline page shows when the network drops.
+  Prices, stock and cart are never cached — they always reflect live data.
+- **Push notifications** — when enabled, buyers can opt in to notifications.
+  You can send a broadcast or targeted message from the admin, and order-status
+  changes / quote-request updates notify subscribed customers automatically.
+  The admin panel does not receive push in this version.
+
+## For developers
+
+### Configuration
+
+All identity + toggles live in the Settings module, group `pwa`, resolved per
+Sales Channel via the standard global + override chain:
+
+| Setting | Type | Notes |
+|---------|------|-------|
+| `pwa.app_name`, `pwa.short_name` | string | manifest identity |
+| `pwa.theme_color`, `pwa.background_color` | string | hex |
+| `pwa.display_mode` | string | `standalone` / `fullscreen` / `minimal-ui` |
+| `pwa.icon_asset_id` | string | assets-library source id |
+| `pwa.caching_enabled`, `pwa.push_enabled` | boolean | default off |
+| `pwa.vapid_public_key` | string | served to the subscribe flow |
+| `pwa.vapid_private_key` | secret | signs Web-Push (AES-256-GCM at rest) |
+| `pwa.fcm_service_account` | secret | reserved for the token-based FCM provider |
+
+### Push abstraction
+
+`PushProvider` (in `@endora-commerce/contracts`) is the swappable delivery seam. The default
+`WebPushProvider` sends standard Web-Push signed with VAPID via the `web-push`
+library (on Chrome the endpoints ride Google's free FCM). A token-based
+`FcmProvider` (`firebase-admin`) and `OneSignalProvider` are drop-in extension
+points — register them in the composition root and set the registry default;
+the storefront subscription flow is unchanged.
+
+Delivery fan-out is a BullMQ consumer (`pwa.push.deliver`) with idempotent
+`(message_id, subscription_id)` deliveries; dead endpoints (`404`/`410`) are
+pruned automatically.
+
+### Service-worker updates
+
+Cache names are keyed by the build id. Set `NEXT_PUBLIC_BUILD_ID` (storefront)
+and `VITE_BUILD_ID` (admin) per deploy. The storefront SW does not `skipWaiting`
+on its own — `PwaRegister` shows a "new version available" prompt and only
+activates on the user's click, so an update never discards in-progress work.
+
+## App-store wrapping checklist
+
+The storefront PWA is built to be wrappable for Google Play (Trusted Web
+Activity) and the App Store (WKWebView wrapper). Producing/submitting the native
+binaries is out of scope; the technical readiness is:
+
+- [x] Complete web manifest: `name`, `short_name`, `start_url`, `scope`,
+  `display: standalone`, `theme_color`, `background_color`, and icons including a
+  512×512 `maskable` icon (served per channel from `/manifest.webmanifest`).
+- [x] Registered service worker with a `fetch` handler and an offline fallback.
+- [x] HTTPS-only (secure context) in production.
+- [x] No install-blocking patterns; graceful degradation on unsupported browsers.
+- [ ] **Android TWA**: host `/.well-known/assetlinks.json` (Digital Asset Links)
+  with the wrapper app's signing-key fingerprint. *(Operator step at packaging.)*
+- [ ] **iOS**: web push only works after the user installs the PWA to the home
+  screen — the opt-in already accounts for this ordering.
+
+## Operator runbook
+
+1. Set `SETTINGS_SECRET_ENCRYPTION_KEY` (for VAPID/FCM secrets) and run
+   `pnpm --filter backend run migration:up` (applies `080_pwa_init`).
+2. In **Settings → PWA**, set identity + upload an icon, toggle caching/push.
+3. Click **Generate VAPID keys** (or `POST /api/v1/admin/pwa/vapid/generate`).
+4. Set `NEXT_PUBLIC_BUILD_ID` / `VITE_BUILD_ID` in the deploy pipeline.
+5. Device-test install + push over HTTPS.

package/i18n/en.json

@@ -0,0 +1,43 @@
+{
+  "adminRoles.permission.pwa:read": "View PWA settings",
+  "adminRoles.permission.pwa:write": "Configure PWA",
+  "adminRoles.permission.pwa:send_push": "Send push notifications",
+  "nav.pwa.label": "PWA",
+  "settings.title": "Progressive Web App",
+  "settings.description": "Configure the installable app identity, asset caching, and push notifications.",
+  "settings.section.identity": "App identity",
+  "settings.field.appName": "App name",
+  "settings.field.shortName": "Short name",
+  "settings.field.themeColor": "Theme color",
+  "settings.field.backgroundColor": "Background color",
+  "settings.field.displayMode": "Display mode",
+  "settings.field.icon": "Home-screen icon",
+  "settings.icon.upload": "Upload icon",
+  "settings.icon.hint": "PNG or WebP, at least 512×512, square.",
+  "settings.icon.invalid": "The image must be a square PNG or WebP of at least 512×512 pixels.",
+  "settings.section.caching": "Asset caching",
+  "settings.field.cachingEnabled": "Enable static-asset caching",
+  "settings.section.push": "Push notifications",
+  "settings.field.pushEnabled": "Enable push notifications",
+  "settings.vapid.generate": "Generate VAPID keys",
+  "settings.vapid.generated": "VAPID keys generated.",
+  "settings.vapid.unset": "No VAPID keys configured.",
+  "settings.channel.global": "Global (all channels)",
+  "settings.channel.override": "Channel override",
+  "settings.save": "Save",
+  "settings.saved": "Settings saved.",
+  "push.title": "Send push notification",
+  "push.field.title": "Title",
+  "push.field.body": "Message",
+  "push.field.url": "Link (opened on tap)",
+  "push.field.audience": "Audience",
+  "push.audience.all": "All subscribers",
+  "push.audience.customers": "Specific customers",
+  "push.send": "Send",
+  "push.test": "Send test to me",
+  "push.queued": "Queued {count} notification(s).",
+  "push.unconfigured": "Push is not configured. Generate VAPID keys and enable push first.",
+  "push.subscribers": "Subscribers",
+  "push.subscribers.active": "Active",
+  "push.subscribers.invalid": "Invalid"
+}

package/i18n/pl.json

@@ -0,0 +1,43 @@
+{
+  "adminRoles.permission.pwa:read": "Podgląd ustawień PWA",
+  "adminRoles.permission.pwa:write": "Konfiguracja PWA",
+  "adminRoles.permission.pwa:send_push": "Wysyłanie powiadomień push",
+  "nav.pwa.label": "PWA",
+  "settings.title": "Aplikacja PWA",
+  "settings.description": "Skonfiguruj tożsamość instalowanej aplikacji, cache zasobów i powiadomienia push.",
+  "settings.section.identity": "Tożsamość aplikacji",
+  "settings.field.appName": "Nazwa aplikacji",
+  "settings.field.shortName": "Nazwa skrócona",
+  "settings.field.themeColor": "Kolor motywu",
+  "settings.field.backgroundColor": "Kolor tła",
+  "settings.field.displayMode": "Tryb wyświetlania",
+  "settings.field.icon": "Ikona na ekranie głównym",
+  "settings.icon.upload": "Wgraj ikonę",
+  "settings.icon.hint": "PNG lub WebP, co najmniej 512×512, kwadrat.",
+  "settings.icon.invalid": "Obraz musi być kwadratowym plikiem PNG lub WebP o rozmiarze co najmniej 512×512 pikseli.",
+  "settings.section.caching": "Cache zasobów",
+  "settings.field.cachingEnabled": "Włącz cache zasobów statycznych",
+  "settings.section.push": "Powiadomienia push",
+  "settings.field.pushEnabled": "Włącz powiadomienia push",
+  "settings.vapid.generate": "Wygeneruj klucze VAPID",
+  "settings.vapid.generated": "Wygenerowano klucze VAPID.",
+  "settings.vapid.unset": "Brak skonfigurowanych kluczy VAPID.",
+  "settings.channel.global": "Globalnie (wszystkie kanały)",
+  "settings.channel.override": "Nadpisanie dla kanału",
+  "settings.save": "Zapisz",
+  "settings.saved": "Zapisano ustawienia.",
+  "push.title": "Wyślij powiadomienie push",
+  "push.field.title": "Tytuł",
+  "push.field.body": "Treść",
+  "push.field.url": "Odnośnik (otwierany po kliknięciu)",
+  "push.field.audience": "Odbiorcy",
+  "push.audience.all": "Wszyscy subskrybenci",
+  "push.audience.customers": "Wybrani klienci",
+  "push.send": "Wyślij",
+  "push.test": "Wyślij test do mnie",
+  "push.queued": "Zakolejkowano {count} powiadomień.",
+  "push.unconfigured": "Push nie jest skonfigurowany. Najpierw wygeneruj klucze VAPID i włącz push.",
+  "push.subscribers": "Subskrybenci",
+  "push.subscribers.active": "Aktywni",
+  "push.subscribers.invalid": "Nieaktywni"
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@endora-commerce/mod-pwa",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Installability, static-asset caching, controlled service-worker updates, and provider-agnostic push notifications for the storefront and admin.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "pwa"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/pwa"
+  },
+  "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": {
+    "@fastify/multipart": "^10",
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "bullmq": "^5",
+    "fastify": "^5",
+    "ioredis": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "sharp": "^0",
+    "web-push": "^3",
+    "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
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fastify/multipart": "^10.0.0",
+    "@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",
+    "@types/web-push": "^3.6.4",
+    "bullmq": "^5.76.1",
+    "fastify": "^5.12.5",
+    "ioredis": "^5.10.1",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "sharp": "^0.35.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "web-push": "^3.6.7",
+    "zod": "^4.2.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0",
+    "@endora-commerce/admin-kit": "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-pwa — 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";