@endora-commerce/mod-blog 0.100.0

package/dist/backend/services/blog-settings-resolver.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { ERROR_CODES, BLOG_RESERVED_URL_PREFIXES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { BLOG_DEFAULT_ENABLED, BLOG_DEFAULT_LATEST_COUNT, BLOG_DEFAULT_POSTS_PER_PAGE, BLOG_DEFAULT_URL_PREFIX, BLOG_SETTING_CODES, } from '../../manifest.js';
+/**
+ * BlogSettingsResolver — feature 016 / R7.
+ *
+ * Wraps `settings.service.getValue('blog.*', salesChannelId)` with:
+ *   - default fallbacks (when no row exists yet);
+ *   - type coercion (the Settings module's value-type registry stores
+ *     primitives as `unknown`; the resolver narrows them);
+ *   - range clamps for `latestCount` and `postsPerPage` (any stored value
+ *     ≤ 0 falls back to the documented default with a logged warning —
+ *     the caller is the Settings admin form, which has already validated
+ *     the value, so this branch is a defence-in-depth safeguard);
+ *   - a pure `assertValidPrefix(value)` validator used as the setter
+ *     callback for `blog.url_prefix` (per the spec FR-024 + the
+ *     reference-scan contract § R-5).
+ */
+const URL_PREFIX_REGEX = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+export class BlogSettingsResolver {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async getResolved(salesChannelId) {
+        const enabled = await this.readWithFallback(BLOG_SETTING_CODES.ENABLED, salesChannelId, z.boolean(), BLOG_DEFAULT_ENABLED);
+        const urlPrefixRaw = await this.readWithFallback(BLOG_SETTING_CODES.URL_PREFIX, salesChannelId, z.string(), BLOG_DEFAULT_URL_PREFIX);
+        const latestCount = await this.readWithFallback(BLOG_SETTING_CODES.LATEST_COUNT, salesChannelId, z.number(), BLOG_DEFAULT_LATEST_COUNT);
+        const postsPerPage = await this.readWithFallback(BLOG_SETTING_CODES.POSTS_PER_PAGE, salesChannelId, z.number(), BLOG_DEFAULT_POSTS_PER_PAGE);
+        return {
+            enabled,
+            urlPrefix: URL_PREFIX_REGEX.test(urlPrefixRaw) ? urlPrefixRaw : BLOG_DEFAULT_URL_PREFIX,
+            latestCount: clampPositiveInt(latestCount, BLOG_DEFAULT_LATEST_COUNT),
+            postsPerPage: clampPositiveInt(postsPerPage, BLOG_DEFAULT_POSTS_PER_PAGE),
+        };
+    }
+    async readWithFallback(code, salesChannelId, schema, fallback) {
+        try {
+            return await this.settings.get(code, salesChannelId, schema);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /**
+     * Pure validator wired into the Settings module's setter callback for
+     * the `blog.url_prefix` key. Refuses an invalid shape, a reserved
+     * Next.js segment, or a value already owned by another storefront route
+     * (the cross-module owner check is delegated; v1 only enforces the
+     * shape + reserved-segments rule).
+     */
+    static assertValidPrefix(value) {
+        if (typeof value !== 'string' || !URL_PREFIX_REGEX.test(value)) {
+            throw new HttpError(400, ERROR_CODES.BLOG_URL_PREFIX_INVALID, 'Blog URL prefix must match ^[a-z0-9-]+$ (1–64 characters).');
+        }
+        if (BLOG_RESERVED_URL_PREFIXES.has(value)) {
+            throw new HttpError(409, ERROR_CODES.BLOG_URL_PREFIX_RESERVED, `URL prefix "${value}" is reserved by the storefront and cannot be assigned to the blog.`);
+        }
+    }
+}
+function clampPositiveInt(raw, fallback) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        return fallback;
+    const n = Math.floor(raw);
+    return n >= 1 ? n : fallback;
+}
+//# sourceMappingURL=blog-settings-resolver.js.map

package/dist/backend/services/blog-settings-resolver.js.map

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

package/dist/backend/services/blog-slug-collision.d.ts

@@ -0,0 +1,35 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * Cross-table slug-uniqueness probe — feature 016 / R3.
+ *
+ * Postgres cannot enforce UNIQUE across two tables; the per-table partial
+ * unique indexes are defensive. The cross-table check (Post slug colliding
+ * with a Category slug in the same Sales Channel — they share the
+ * `<prefix>/<slug>` URL space) lives here.
+ *
+ * Each probe runs inside the caller's transaction and acquires a Postgres
+ * advisory lock keyed on (channel, slug) so a concurrent save cannot
+ * sneak between probe and write. The lock is released automatically when
+ * the transaction commits or rolls back.
+ *
+ * Callers MUST be inside an `em.transactional(...)` block.
+ */
+export interface SlugCollisionCheckInput {
+    /** Slug being asserted. */
+    slug: string;
+    /** Sales-channel ids the entity is being attached to. */
+    salesChannelIds: string[];
+    /** Which side is calling — drives the row-id exclusion below. */
+    kind: 'post' | 'category';
+    /** When updating an existing row, exclude it from the probe. */
+    excludeId?: string | undefined;
+}
+/**
+ * Probe `blog_post_sales_channels` ∪ `blog_category_sales_channels` for
+ * any non-soft-deleted row in any of the supplied channels with the same
+ * slug. Throws BLOG_SLUG_TAKEN with `details.colliding[]` populated.
+ *
+ * Returns silently when no collision exists.
+ */
+export declare function assertSlugAvailable(em: EntityManager, input: SlugCollisionCheckInput): Promise<void>;
+//# sourceMappingURL=blog-slug-collision.d.ts.map

package/dist/backend/services/blog-slug-collision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-slug-collision.d.ts","sourceRoot":"","sources":["../../../src/backend/services/blog-slug-collision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAK3D;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAyEf"}

package/dist/backend/services/blog-slug-collision.js

@@ -0,0 +1,84 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { createHash } from 'crypto';
+/**
+ * Probe `blog_post_sales_channels` ∪ `blog_category_sales_channels` for
+ * any non-soft-deleted row in any of the supplied channels with the same
+ * slug. Throws BLOG_SLUG_TAKEN with `details.colliding[]` populated.
+ *
+ * Returns silently when no collision exists.
+ */
+export async function assertSlugAvailable(em, input) {
+    if (input.salesChannelIds.length === 0)
+        return;
+    // 1. Take per-(channel, slug) advisory locks so a concurrent transaction
+    // cannot squeeze a colliding write between this probe and the upcoming
+    // INSERT. The lock is released when the transaction completes.
+    for (const channelId of input.salesChannelIds) {
+        const lockKey = advisoryLockKeyFor(channelId, input.slug);
+        await em.execute('select pg_advisory_xact_lock(?)', [lockKey]);
+    }
+    const placeholders = input.salesChannelIds.map(() => '?').join(', ');
+    const params = [input.slug, ...input.salesChannelIds];
+    // 2. Check the post side. Exclude the calling row if updating.
+    let postSql = `select p.id::text as id, psc.sales_channel_id::text as channel_id
+                   from blog_post_sales_channels psc
+                   join blog_posts p on p.id = psc.blog_post_id
+                  where psc.slug = ?
+                    and psc.sales_channel_id in (${placeholders})
+                    and psc.deleted_at is null`;
+    if (input.kind === 'post' && input.excludeId) {
+        postSql += ' and p.id <> ?';
+        params.push(input.excludeId);
+    }
+    postSql += ' limit 5';
+    const postRows = (await em.execute(postSql, params));
+    // 3. Check the category side.
+    const catParams = [input.slug, ...input.salesChannelIds];
+    let categorySql = `select c.id::text as id, csc.sales_channel_id::text as channel_id
+                       from blog_category_sales_channels csc
+                       join blog_categories c on c.id = csc.blog_category_id
+                      where csc.slug = ?
+                        and csc.sales_channel_id in (${placeholders})
+                        and csc.deleted_at is null`;
+    if (input.kind === 'category' && input.excludeId) {
+        categorySql += ' and c.id <> ?';
+        catParams.push(input.excludeId);
+    }
+    categorySql += ' limit 5';
+    const categoryRows = (await em.execute(categorySql, catParams));
+    if (postRows.length === 0 && categoryRows.length === 0)
+        return;
+    // Surface each colliding owner as a separate detail entry so the admin
+    // UI can render a friendly list. `path: 'slug'` keeps the field
+    // attribution consistent with other slug errors; `issue` carries the
+    // colliding kind + id + channel.
+    const details = [
+        ...postRows.map((r) => ({
+            path: 'slug',
+            issue: `taken by post id=${r.id} in sales-channel id=${r.channel_id}`,
+        })),
+        ...categoryRows.map((r) => ({
+            path: 'slug',
+            issue: `taken by category id=${r.id} in sales-channel id=${r.channel_id}`,
+        })),
+    ];
+    throw new HttpError(409, ERROR_CODES.BLOG_SLUG_TAKEN, `Slug "${input.slug}" is already taken in at least one of the assigned Sales Channels.`, details);
+}
+/**
+ * Hash `(channelId, slug)` into a `bigint` namespace acceptable to
+ * `pg_advisory_xact_lock(bigint)`. We use SHA-256 then take the first
+ * 8 bytes interpreted as a signed bigint (Postgres `bigint` range).
+ */
+function advisoryLockKeyFor(channelId, slug) {
+    const digest = createHash('sha256').update(`blog-slug:${channelId}:${slug}`).digest();
+    // Take the first 8 bytes as a 64-bit big-endian integer; force the
+    // sign bit so the value fits in Postgres's signed bigint range. The
+    // exact mapping doesn't matter — we just need a stable bigint.
+    let hi = digest.readUInt32BE(0);
+    // Clear the top bit so the resulting bigint is positive.
+    hi = hi & 0x7fffffff;
+    const lo = digest.readUInt32BE(4);
+    return ((BigInt(hi) << 32n) | BigInt(lo)).toString();
+}
+//# sourceMappingURL=blog-slug-collision.js.map

package/dist/backend/services/blog-slug-collision.js.map

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

package/dist/backend/services/blog-storefront-resolver.d.ts

@@ -0,0 +1,107 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { BlogBySlugResponse, BlogIndexResponse, BlogProductCard, BlogTagByCodeResponse } from '@endora-commerce/contracts';
+import { BlogCacheService } from './blog-cache.js';
+import type { BlogSettingsResolver } from './blog-settings-resolver.js';
+/**
+ * Cross-module surfaces the storefront resolver delegates to. Each is a
+ * narrow port (Constitution I) — the resolver does not import the
+ * upstream module's internals.
+ */
+export interface BlogStorefrontDeps {
+    /**
+     * Resolves a Library Asset id to a CDN-ready URL. Returns null when
+     * the asset is missing, soft-deleted, or otherwise unavailable.
+     */
+    resolveAssetUrl?: (assetId: string) => Promise<string | null>;
+    /**
+     * Resolves a Catalog Product id to a card payload (or null when the
+     * product is soft-deleted / out-of-channel — handled at the upstream
+     * port, not here). Optional: when omitted, related-products lists
+     * always render as empty (R6 storefront-filter contract).
+     */
+    resolveProductCard?: (productId: string, salesChannelId: string, language: string) => Promise<BlogProductCard | null>;
+}
+/**
+ * The already-resolved sales channel handed down from the route layer
+ * (feature 053). Mirrors the shape of the sales-channel resolver's
+ * `CachedChannel`; the resolver has already refused inactive/unknown
+ * channels upstream, so no re-query or active check is needed here.
+ */
+export type ResolvedChannel = {
+    id: string;
+    code: string;
+    defaultLanguage: string;
+};
+/**
+ * BlogStorefrontResolver — feature 016 / T051.
+ *
+ * Three read endpoints behind `/api/v1/blog/**`:
+ *
+ *   getIndex         → BlogIndexResponse (latest N + first-level categories)
+ *   getBySlug        → BlogBySlugResponse discriminated by `kind`
+ *   getTagByCode     → BlogTagByCodeResponse paginated
+ *
+ * Every method:
+ *   - reads the channel-resolved blog settings via BlogSettingsResolver;
+ *   - returns null (the route maps to 404) when blog.enabled = false;
+ *   - applies the platform-wide language-fallback rule (feature 005)
+ *     via the `pickLanguage` helper;
+ *   - wraps results in BlogCacheService when Redis is wired.
+ */
+export declare class BlogStorefrontResolver {
+    private readonly emFactory;
+    private readonly settingsResolver;
+    private readonly deps;
+    private readonly cache?;
+    constructor(emFactory: () => EntityManager, settingsResolver: BlogSettingsResolver, deps?: BlogStorefrontDeps, cache?: BlogCacheService | undefined);
+    getIndex(input: {
+        resolvedChannel: ResolvedChannel;
+        language?: string | undefined;
+    }): Promise<BlogIndexResponse | null>;
+    getBySlug(slug: string, input: {
+        resolvedChannel: ResolvedChannel;
+        language?: string | undefined;
+        page?: number;
+    }): Promise<BlogBySlugResponse | null>;
+    getTagByCode(code: string, input: {
+        resolvedChannel: ResolvedChannel;
+        language?: string | undefined;
+        page?: number;
+    }): Promise<BlogTagByCodeResponse | null>;
+    /**
+     * Language-fallback rule (FR-019 / R12 / per feature 005): pick the
+     * requested language; fall back to the channel's default language; if
+     * neither exists, return null. The caller decides whether `null`
+     * means "skip this field" or "404 the page" depending on context.
+     */
+    private pickLanguage;
+    /**
+     * Resolve a human-readable name for a published entity. Applies the
+     * standard language fallback (requested → channel default) and, when that
+     * is exhausted, falls back to the first language actually authored on the
+     * entity rather than giving up.
+     *
+     * This keeps a *published* post/category viewable even when its content
+     * was authored only in a language other than the channel's default — the
+     * alternative (returning null) made the post-detail resolver 404 while the
+     * index/category resolvers still listed the post (via their `?? slug`
+     * fallback), an inconsistency that surfaced as "the post is in the list but
+     * its page 404s". A published entity is always reachable; only its display
+     * language degrades.
+     */
+    private pickName;
+    private toPostCard;
+    private toCategoryTile;
+    private toResolvedPost;
+    private maybeAssetUrl;
+    private normaliseDescription;
+    private normaliseContent;
+    /**
+     * Best-effort excerpt extraction — picks the first text-bearing node
+     * in the resolved language's tree. Falls back to the channel default
+     * language. Returns null when nothing usable is found.
+     */
+    private firstParagraph;
+    private toIso;
+}
+//# sourceMappingURL=blog-storefront-resolver.d.ts.map

package/dist/backend/services/blog-storefront-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-storefront-resolver.d.ts","sourceRoot":"","sources":["../../../src/backend/services/blog-storefront-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EACV,kBAAkB,EAElB,iBAAiB,EAGjB,eAAe,EAIf,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CACnB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACtC;AAQD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAoCpF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAHN,SAAS,EAAE,MAAM,aAAa,EAC9B,gBAAgB,EAAE,oBAAoB,EACtC,IAAI,GAAE,kBAAuB,EAC7B,KAAK,CAAC,EAAE,gBAAgB,YAAA;IAGrC,QAAQ,CAAC,KAAK,EAAE;QACpB,eAAe,EAAE,eAAe,CAAC;QACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC/B,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAyD/B,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QAAE,eAAe,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACxF,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAuJ/B,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QAAE,eAAe,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACxF,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAiGxC;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,QAAQ;YAcF,UAAU;YAmCV,cAAc;YAad,cAAc;YA2Gd,aAAa;IAM3B,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,gBAAgB;IAUxB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,KAAK;CAId"}