@endora-commerce/mod-seo 0.100.0

package/dist/migrations/20260425T154404_seo_init.js

@@ -0,0 +1,45 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * SEO module init (T235). Two tables:
+ *   - seo_meta_overrides: per-(entity, locale) editorial overrides.
+ *   - sitemap_cache: singleton cache row for the public XML sitemap.
+ */
+export class Migration20260425T154404SeoInit extends Migration {
+    async up() {
+        this.addSql(`
+      create table "seo_meta_overrides" (
+        "id" uuid not null,
+        "entity_type" varchar(32) not null,
+        "entity_id" uuid not null,
+        "locale" varchar(10) not null,
+        "title" varchar(160) null,
+        "description" varchar(400) null,
+        "og_title" varchar(160) null,
+        "og_description" varchar(400) null,
+        "og_image_url" varchar(2048) null,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "seo_meta_overrides_pkey" primary key ("id"),
+        constraint "uniq_seo_meta_overrides_entity_locale"
+          unique ("entity_type", "entity_id", "locale")
+      );
+    `);
+        this.addSql('create index "seo_meta_overrides_entity_type_index" on "seo_meta_overrides" ("entity_type");');
+        this.addSql('create index "seo_meta_overrides_entity_id_index" on "seo_meta_overrides" ("entity_id");');
+        this.addSql(`
+      create table "sitemap_cache" (
+        "key" varchar(32) not null,
+        "payload" text not null,
+        "url_count" int not null default 0,
+        "byte_size" int not null default 0,
+        "generated_at" timestamptz not null,
+        constraint "sitemap_cache_pkey" primary key ("key")
+      );
+    `);
+    }
+    async down() {
+        this.addSql('drop table if exists "sitemap_cache" cascade;');
+        this.addSql('drop table if exists "seo_meta_overrides" cascade;');
+    }
+}
+//# sourceMappingURL=20260425T154404_seo_init.js.map

package/dist/migrations/20260425T154404_seo_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260425T154404_seo_init.js","sourceRoot":"","sources":["../../src/migrations/20260425T154404_seo_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;GAIG;AACH,MAAM,OAAO,+BAAgC,SAAQ,SAAS;IACnD,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;KAiBX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,8FAA8F,CAAC,CAAC;QAC5G,IAAI,CAAC,MAAM,CAAC,0FAA0F,CAAC,CAAC;QAExG,IAAI,CAAC,MAAM,CAAC;;;;;;;;;KASX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,+CAA+C,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,oDAAoD,CAAC,CAAC;IACpE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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).
+ *
+ * **One class**, 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 { Migration20260425T154404SeoInit } from './20260425T154404_seo_init.js';
+export declare const migrations: (typeof Migration20260425T154404SeoInit)[];
+export { Migration20260425T154404SeoInit };
+//# 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;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAEhF,eAAO,MAAM,UAAU,4CAAoC,CAAC;AAE5D,OAAO,EAAE,+BAA+B,EAAE,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,23 @@
+/**
+ * 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).
+ *
+ * **One class**, 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 { Migration20260425T154404SeoInit } from './20260425T154404_seo_init.js';
+export const migrations = [Migration20260425T154404SeoInit];
+export { Migration20260425T154404SeoInit };
+//# 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;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAEhF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAE5D,OAAO,EAAE,+BAA+B,EAAE,CAAC"}

package/docs/seo.md

@@ -0,0 +1,74 @@
+---
+title: seo
+description: Meta-tag resolver + cached XML sitemap
+---
+
+# `seo`
+
+Per-page meta-tag resolution and the public XML sitemap.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/catalog/sitemap.xml` | crawlers | Cached XML sitemap; falls through to inline regenerate when stale |
+| `POST /api/v1/admin/seo/sitemap/regenerate` | admin (`catalog:write`) | Force a fresh build |
+| `GET /api/v1/admin/seo/sitemap/status` | admin | Last-generated timestamp + size + URL count |
+| `GET /api/v1/admin/seo/meta/:entityType/:entityId` | admin | Resolved meta + override row for a (entity, locale) |
+| `PUT /api/v1/admin/seo/meta/:entityType/:entityId` | admin | Upsert override (per locale) |
+| `DELETE /api/v1/admin/seo/meta/:entityType/:entityId` | admin | Drop the override (resolver returns to rule output) |
+
+## Meta-tag resolution
+
+`MetaTagResolverService.resolve({ entityType, entityId, locale })` returns
+`{ title, description, openGraph, source, locale }`. The resolution order is:
+
+1. Look up the per-(entity, locale) override row.
+2. If a field is set on the override, use it verbatim.
+3. Otherwise fall back to the rule derived from the entity (Product name +
+   description, Category name + auto-summary).
+4. Per-field locale fallback: when a Product has no `pl-PL` text, the rule
+   uses `en-US`, then any available locale.
+
+Title and description are truncated at 60 / 160 characters with an ellipsis.
+The truncation lives in one helper so changes to the SEO budget happen in
+one place.
+
+## Sitemap
+
+`SitemapGeneratorService.regenerate()` walks active, public-visibility,
+non-archived products and non-deleted categories, stamps absolute URLs
+against `STOREFRONT_BASE_URL`, and writes the XML payload to a singleton
+`sitemap_cache` row.
+
+The public route (`GET /catalog/sitemap.xml`) returns the cached payload;
+when the row is older than `staleAfterMs` (default 6 h) it regenerates
+inline. A `Cache-Control: public, max-age=3600` header is set on the
+response so well-behaved CDNs hold the payload for an hour.
+
+## Anonymous-only filtering
+
+The sitemap excludes:
+- products with `status != 'active'`
+- products with `visibility != 'public'`
+- archived (`archivedAt`) and soft-deleted (`deletedAt`) rows
+- soft-deleted categories
+
+The contract is simple: only what an anonymous Customer can see is
+ever exposed to crawlers.
+
+## Entities
+
+`SeoMetaOverride` (entityType, entityId, locale, title?, description?,
+ogTitle?, ogDescription?, ogImageUrl?), `SitemapCache` (singleton key,
+payload, urlCount, byteSize, generatedAt).
+
+## Extension points
+
+- **CMS pages** — when a CMS module ships, hook its slug + body into both
+  `MetaTagResolverService.loadRuleSource()` and
+  `SitemapGeneratorService.regenerate()`.
+- **Sitemap index** — for catalogues > 50 000 URLs, split into per-section
+  sitemaps and emit a `<sitemapindex>` from this module's route.
+- **Scheduled regenerate** — wire a BullMQ repeatable into the production
+  composition root that calls `regenerate()` nightly.

package/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "nav.seo.label": "SEO"
+}

package/i18n/pl.json

@@ -0,0 +1,3 @@
+{
+  "nav.seo.label": "SEO"
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@endora-commerce/mod-seo",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "SEO metadata management for catalog, CMS, and blog surfaces.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "seo"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/seo"
+  },
+  "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",
+    "react": "^19",
+    "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
+    }
+  },
+  "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",
+    "react": "^19.2.5",
+    "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-seo — 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";