@openora/core 0.4.1-canary.18 → 0.4.1-canary.181

package/dist/cms/service/cms.service.js

@@ -1,13 +1,65 @@
-import { makeNotFoundError, findOneOrThrow, cached, invalidate, } from '@openora/core/server';
-import { eq, and, asc, desc, isNotNull } from 'drizzle-orm';
-import { page as pageTable, banner as bannerTable } from '../schema/index.js';
+import { randomUUID } from 'node:crypto';
+import { makeNotFoundError, makeConflictError, createDomainError, findOneOrThrow, cached, invalidate, withAdvisoryXactLock, } from '@openora/core/server';
+import { eq, ne, and, or, asc, desc, isNotNull, inArray, sql, gt, lt, gte, lte } from 'drizzle-orm';
+import { page as pageTable, bannerConfiguration as bannerConfigurationTable, bannerImage as bannerImageTable, bannerSchedule as bannerScheduleTable, } from '../schema/index.js';
+import { BANNER_IMAGE_COUNT_BOUNDS, DEFAULT_LOCALE } from '../contract/index.js';
+import { validateBannerImageUrl } from '../moderation/validate-banner-image-url.js';
 export const PageNotFoundError = makeNotFoundError('Page');
-export const BannerNotFoundError = makeNotFoundError('Banner');
+export const BannerConfigurationNotFoundError = makeNotFoundError('BannerConfiguration');
+export const BannerImageNotFoundError = makeNotFoundError('BannerImage');
+export const BannerConfigurationIsDefaultError = makeConflictError('BannerConfigurationIsDefaultError', 'This configuration is currently the placement default - set a different default or unset it before deleting');
+export const BannerConfigurationImageCountError = createDomainError('BannerConfigurationImageCountError', (layout, min, max, actual) => min === max
+    ? `A ${layout} banner configuration needs exactly ${min} image(s) to be set as default (has ${actual})`
+    : `A ${layout} banner configuration needs ${min}-${max} images to be set as default (has ${actual})`);
+export const BannerImageHostNotAllowedError = createDomainError('BannerImageHostNotAllowedError', (reason) => `Banner image URL rejected: ${reason}`);
+export const BannerScheduleNotFoundError = makeNotFoundError('BannerSchedule');
+export const BannerConfigurationHasScheduleError = makeConflictError('BannerConfigurationHasScheduleError', 'This configuration has a banner schedule attached - it cannot be deleted or re-scheduled while one exists');
+export const BannerPlacementHasScheduleError = makeConflictError('BannerPlacementHasScheduleError', 'This placement has an active or future banner schedule - its default configuration cannot be unset');
+export const BannerScheduleInvalidRangeError = createDomainError('BannerScheduleInvalidRangeError', (reason) => `Invalid banner schedule range: ${reason}`);
+export const BannerScheduleExpiredError = makeConflictError('BannerScheduleExpiredError', 'An expired banner schedule cannot be resumed');
+export class BannerScheduleOverlapError extends Error {
+    data;
+    constructor(startsAt, endsAt) {
+        const startsAtIso = startsAt instanceof Date ? startsAt.toISOString() : startsAt;
+        const endsAtIso = endsAt instanceof Date ? endsAt.toISOString() : endsAt;
+        super(`This placement already has a schedule for ${startsAtIso} - ${endsAtIso}`);
+        this.name = 'BannerScheduleOverlapError';
+        this.data = { startsAt: startsAtIso, endsAt: endsAtIso };
+    }
+}
 // Public content is read far more than written; a short TTL bounds staleness
 // after a publish/edit to the invalidation below, not to this window alone.
 const CMS_CACHE_TTL_MS = 60_000;
 const pageCacheKey = (slug) => `cms:page:${slug}`;
-const bannersCacheKey = (placement) => `cms:banners:${placement}`;
+const publicBannerCacheEpochKey = (placement) => `cms:banner-placement:${placement}:epoch`;
+const publicBannerCacheKey = (placement, epoch, locale) => `cms:banner-placement:${placement}:${epoch}:${locale}`;
+const bannerScheduleLockKey = (placement) => `cms:banner-schedule:${placement}`;
+const bannerConfigurationMutationLockKey = (bannerConfigurationId) => `cms:banner-configuration:${bannerConfigurationId}`;
+const bannerImageUrlLockKey = (url) => `cms:banner-image-url:${url}`;
+async function currentPublicBannerCacheKey(cache, placement, locale) {
+    const epoch = await cached(cache, publicBannerCacheEpochKey(placement), CMS_CACHE_TTL_MS, async () => randomUUID());
+    return publicBannerCacheKey(placement, epoch, locale);
+}
+async function withBannerImageUrlLocks(tx, urls, fn) {
+    const lockKeys = [...new Set(urls)].sort().map(bannerImageUrlLockKey);
+    const locked = lockKeys.reduceRight((next, key) => () => withAdvisoryXactLock(tx, key, next), fn);
+    return locked();
+}
+async function unreferencedBannerImageUrls(tx, candidates) {
+    const uniqueCandidates = [...new Set(candidates)];
+    if (uniqueCandidates.length === 0) {
+        return [];
+    }
+    const references = await tx
+        .select({
+        desktopImageUrl: bannerImageTable.desktopImageUrl,
+        mobileImageUrl: bannerImageTable.mobileImageUrl,
+    })
+        .from(bannerImageTable)
+        .where(or(inArray(bannerImageTable.desktopImageUrl, uniqueCandidates), inArray(bannerImageTable.mobileImageUrl, uniqueCandidates)));
+    const referencedUrls = new Set(references.flatMap((reference) => [reference.desktopImageUrl, reference.mobileImageUrl]));
+    return uniqueCandidates.filter((url) => !referencedUrls.has(url));
+}
 function toPage(record) {
     return {
         id: record.id,
@@ -18,15 +70,47 @@ function toPage(record) {
         createdAt: record.createdAt.toISOString(),
     };
 }
-function toBanner(record) {
+function toBannerImage(record) {
     return {
         id: record.id,
-        placement: record.placement,
-        title: record.title,
-        imageUrl: record.imageUrl,
-        linkUrl: record.linkUrl,
-        isActive: record.isActive,
+        bannerConfigurationId: record.bannerConfigurationId,
         sortOrder: record.sortOrder,
+        locale: record.locale,
+        desktopImageUrl: record.desktopImageUrl,
+        mobileImageUrl: record.mobileImageUrl,
+        linkUrl: record.linkUrl,
+        createdAt: record.createdAt.toISOString(),
+    };
+}
+function toBannerConfiguration(record, images) {
+    return {
+        id: record.id,
+        placement: record.placement,
+        layout: record.layout,
+        isDefault: record.isDefault,
+        createdBy: record.createdBy,
+        createdAt: record.createdAt.toISOString(),
+        images,
+    };
+}
+function toBannerConfigurationSummary(record, imageCount) {
+    return {
+        id: record.id,
+        placement: record.placement,
+        layout: record.layout,
+        isDefault: record.isDefault,
+        createdBy: record.createdBy,
+        createdAt: record.createdAt.toISOString(),
+        imageCount,
+    };
+}
+function toBannerSchedule(record) {
+    return {
+        id: record.id,
+        bannerConfigurationId: record.bannerConfigurationId,
+        startsAt: record.startsAt.toISOString(),
+        endsAt: record.endsAt.toISOString(),
+        createdBy: record.createdBy,
         createdAt: record.createdAt.toISOString(),
     };
 }
@@ -34,10 +118,12 @@ export class CmsService {
     drizzle;
     events;
     cache;
-    constructor(drizzle, events, cache) {
+    allowedBannerImageHosts;
+    constructor(drizzle, events, cache, allowedBannerImageHosts = []) {
         this.drizzle = drizzle;
         this.events = events;
         this.cache = cache;
+        this.allowedBannerImageHosts = allowedBannerImageHosts;
     }
     // Public routes (no adminGuard, HTTP-cacheable) - published-only. There is no
     // admin equivalent yet, so a draft page is visible only via direct DB access.
@@ -72,7 +158,7 @@ export class CmsService {
             return toPage(record);
         });
     }
-    async createPage(input, actorId) {
+    async createPage(input, actorId, meta) {
         const record = findOneOrThrow(await this.drizzle.db
             .insert(pageTable)
             .values({
@@ -83,13 +169,23 @@ export class CmsService {
         })
             .returning(), new PageNotFoundError(input.slug));
         await invalidate(this.cache, pageCacheKey(input.slug));
-        this.events.emit('cms.page.created', { pageId: record.id, actorId });
+        this.events.emit('cms.page.created', {
+            pageId: record.id,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
         if (record.publishedAt) {
-            this.events.emit('cms.page.published', { pageId: record.id, slug: record.slug });
+            this.events.emit('cms.page.published', {
+                pageId: record.id,
+                slug: record.slug,
+                ip: meta?.ip ?? null,
+                userAgent: meta?.userAgent ?? null,
+            });
         }
         return toPage(record);
     }
-    async updatePage(input, actorId) {
+    async updatePage(input, actorId, meta) {
         const existing = findOneOrThrow(await this.drizzle.db.select().from(pageTable).where(eq(pageTable.id, input.id)), new PageNotFoundError(input.id));
         const wasPublished = existing.publishedAt !== null;
         const patch = {};
@@ -111,79 +207,638 @@ export class CmsService {
             .where(eq(pageTable.id, input.id))
             .returning(), new PageNotFoundError(input.id));
         await invalidate(this.cache, [existing.slug, input.slug ?? existing.slug].map(pageCacheKey));
-        this.events.emit('cms.page.updated', { pageId: record.id, actorId });
+        this.events.emit('cms.page.updated', {
+            pageId: record.id,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
         const nowPublished = record.publishedAt !== null;
         if (!wasPublished && nowPublished) {
-            this.events.emit('cms.page.published', { pageId: record.id, slug: record.slug });
+            this.events.emit('cms.page.published', {
+                pageId: record.id,
+                slug: record.slug,
+                ip: meta?.ip ?? null,
+                userAgent: meta?.userAgent ?? null,
+            });
         }
         return toPage(record);
     }
-    async deletePage(id, actorId) {
+    async deletePage(id, actorId, meta) {
         const existing = findOneOrThrow(await this.drizzle.db.select().from(pageTable).where(eq(pageTable.id, id)), new PageNotFoundError(id));
         await this.drizzle.db.delete(pageTable).where(eq(pageTable.id, id));
         await invalidate(this.cache, pageCacheKey(existing.slug));
-        this.events.emit('cms.page.deleted', { pageId: id, actorId });
+        this.events.emit('cms.page.deleted', {
+            pageId: id,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
         return { success: true };
     }
-    async listBanners() {
-        const banners = await this.drizzle.db
+    // Every existing placement (default or not), batched (no N+1) across two extra
+    // queries regardless of how many placements exist.
+    async listPlacements() {
+        const [placementRows, defaultRows] = await Promise.all([
+            this.drizzle.db
+                .selectDistinct({ placement: bannerConfigurationTable.placement })
+                .from(bannerConfigurationTable),
+            this.drizzle.db
+                .select()
+                .from(bannerConfigurationTable)
+                .where(eq(bannerConfigurationTable.isDefault, true)),
+        ]);
+        const defaultByPlacement = new Map(defaultRows.map((r) => [r.placement, r]));
+        const defaultIds = defaultRows.map((r) => r.id);
+        const defaultImages = defaultIds.length
+            ? await this.drizzle.db
+                .select()
+                .from(bannerImageTable)
+                .where(inArray(bannerImageTable.bannerConfigurationId, defaultIds))
+                .orderBy(asc(bannerImageTable.sortOrder))
+            : [];
+        const imagesByConfig = new Map();
+        for (const image of defaultImages) {
+            const list = imagesByConfig.get(image.bannerConfigurationId) ?? [];
+            list.push(image);
+            imagesByConfig.set(image.bannerConfigurationId, list);
+        }
+        // Placements with no default use the most recent updatedAt across their
+        // (non-default) configurations for the summary timestamp.
+        const nonDefaultPlacements = placementRows
+            .map((r) => r.placement)
+            .filter((p) => !defaultByPlacement.has(p));
+        // A raw sql aggregate has no column metadata for Drizzle to decode, so this comes
+        // back as Postgres's text representation, not a Date - parse it explicitly.
+        const latestUpdatedByPlacement = new Map();
+        if (nonDefaultPlacements.length > 0) {
+            const rows = await this.drizzle.db
+                .select({
+                placement: bannerConfigurationTable.placement,
+                updatedAt: sql `max(${bannerConfigurationTable.updatedAt})`,
+            })
+                .from(bannerConfigurationTable)
+                .where(inArray(bannerConfigurationTable.placement, nonDefaultPlacements))
+                .groupBy(bannerConfigurationTable.placement);
+            for (const row of rows) {
+                latestUpdatedByPlacement.set(row.placement, new Date(row.updatedAt));
+            }
+        }
+        return placementRows.map(({ placement }) => {
+            const defaultRow = defaultByPlacement.get(placement);
+            if (defaultRow) {
+                return {
+                    placement,
+                    defaultConfigurationId: defaultRow.id,
+                    defaultConfiguration: toBannerConfiguration(defaultRow, (imagesByConfig.get(defaultRow.id) ?? []).map(toBannerImage)),
+                    updatedAt: defaultRow.updatedAt.toISOString(),
+                };
+            }
+            const updatedAt = latestUpdatedByPlacement.get(placement) ?? new Date(0);
+            return {
+                placement,
+                defaultConfigurationId: null,
+                defaultConfiguration: null,
+                updatedAt: updatedAt.toISOString(),
+            };
+        });
+    }
+    async listConfigurationsByPlacement(placement) {
+        const configs = await this.drizzle.db
+            .select()
+            .from(bannerConfigurationTable)
+            .where(eq(bannerConfigurationTable.placement, placement))
+            .orderBy(desc(bannerConfigurationTable.createdAt));
+        const ids = configs.map((c) => c.id);
+        const counts = ids.length
+            ? await this.drizzle.db
+                .select({
+                bannerConfigurationId: bannerImageTable.bannerConfigurationId,
+                count: sql `count(*)::int`,
+            })
+                .from(bannerImageTable)
+                .where(inArray(bannerImageTable.bannerConfigurationId, ids))
+                .groupBy(bannerImageTable.bannerConfigurationId)
+            : [];
+        const countByConfig = new Map(counts.map((c) => [c.bannerConfigurationId, c.count]));
+        return configs.map((record) => toBannerConfigurationSummary(record, countByConfig.get(record.id) ?? 0));
+    }
+    async getConfiguration(id) {
+        const record = findOneOrThrow(await this.drizzle.db
+            .select()
+            .from(bannerConfigurationTable)
+            .where(eq(bannerConfigurationTable.id, id)), new BannerConfigurationNotFoundError(id));
+        const images = await this.drizzle.db
             .select()
-            .from(bannerTable)
-            .orderBy(asc(bannerTable.placement), asc(bannerTable.sortOrder));
-        return banners.map(toBanner);
+            .from(bannerImageTable)
+            .where(eq(bannerImageTable.bannerConfigurationId, id))
+            .orderBy(asc(bannerImageTable.sortOrder));
+        return toBannerConfiguration(record, images.map(toBannerImage));
+    }
+    async createConfiguration(input, actorId, meta) {
+        const record = findOneOrThrow(await this.drizzle.db
+            .insert(bannerConfigurationTable)
+            .values({
+            placement: input.placement,
+            layout: input.layout,
+            isDefault: false,
+            createdBy: actorId,
+        })
+            .returning(), new BannerConfigurationNotFoundError(input.placement));
+        this.events.emit('cms.banner.configuration.created', {
+            bannerConfigurationId: record.id,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return toBannerConfiguration(record, []);
     }
-    async listBannersByPlacement(placement) {
-        return cached(this.cache, bannersCacheKey(placement), CMS_CACHE_TTL_MS, async () => {
-            const banners = await this.drizzle.db
+    async deleteConfiguration(id, actorId, meta) {
+        const droppedImageUrls = await this.drizzle.db.transaction((tx) => withAdvisoryXactLock(tx, bannerConfigurationMutationLockKey(id), async () => {
+            const existing = findOneOrThrow(await tx
                 .select()
-                .from(bannerTable)
-                .where(and(eq(bannerTable.placement, placement), eq(bannerTable.isActive, true)))
-                .orderBy(asc(bannerTable.sortOrder));
-            return banners.map(toBanner);
+                .from(bannerConfigurationTable)
+                .where(eq(bannerConfigurationTable.id, id)), new BannerConfigurationNotFoundError(id));
+            if (existing.isDefault) {
+                throw new BannerConfigurationIsDefaultError();
+            }
+            // Blocked unconditionally (queued, active, or expired) - no live-time
+            // computation in this guard, see D4 in the scheduling design.
+            const [schedule] = await tx
+                .select({ id: bannerScheduleTable.id })
+                .from(bannerScheduleTable)
+                .where(eq(bannerScheduleTable.bannerConfigurationId, id));
+            if (schedule) {
+                throw new BannerConfigurationHasScheduleError();
+            }
+            const images = await tx
+                .select({
+                desktopImageUrl: bannerImageTable.desktopImageUrl,
+                mobileImageUrl: bannerImageTable.mobileImageUrl,
+            })
+                .from(bannerImageTable)
+                .where(eq(bannerImageTable.bannerConfigurationId, id));
+            const imageUrls = images.flatMap((image) => [image.desktopImageUrl, image.mobileImageUrl]);
+            return withBannerImageUrlLocks(tx, imageUrls, async () => {
+                // Cascades to banner_image rows via the FK's onDelete: 'cascade'.
+                await tx.delete(bannerConfigurationTable).where(eq(bannerConfigurationTable.id, id));
+                return unreferencedBannerImageUrls(tx, imageUrls);
+            });
+        }));
+        this.events.emit('cms.banner.configuration.deleted', {
+            bannerConfigurationId: id,
+            droppedImageUrls,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
         });
+        return { success: true };
     }
-    async createBanner(input, actorId) {
-        const record = findOneOrThrow(await this.drizzle.db.insert(bannerTable).values(input).returning(), new BannerNotFoundError(input.placement));
-        await invalidate(this.cache, bannersCacheKey(input.placement));
-        this.events.emit('cms.banner.created', { bannerId: record.id, actorId });
-        return toBanner(record);
+    async setDefaultConfiguration(id, actorId, meta) {
+        const placement = await this.drizzle.db.transaction(async (tx) => {
+            const initialConfig = findOneOrThrow(await tx.select().from(bannerConfigurationTable).where(eq(bannerConfigurationTable.id, id)), new BannerConfigurationNotFoundError(id));
+            return withAdvisoryXactLock(tx, bannerScheduleLockKey(initialConfig.placement), async () => {
+                const config = findOneOrThrow(await tx
+                    .select()
+                    .from(bannerConfigurationTable)
+                    .where(eq(bannerConfigurationTable.id, id)), new BannerConfigurationNotFoundError(id));
+                const [schedule] = await tx
+                    .select({ id: bannerScheduleTable.id })
+                    .from(bannerScheduleTable)
+                    .where(eq(bannerScheduleTable.bannerConfigurationId, id));
+                if (schedule) {
+                    throw new BannerConfigurationHasScheduleError();
+                }
+                await this.assertBannerConfigurationImageCount(tx, config);
+                await tx
+                    .update(bannerConfigurationTable)
+                    .set({ isDefault: false })
+                    .where(and(eq(bannerConfigurationTable.placement, config.placement), eq(bannerConfigurationTable.isDefault, true)));
+                await tx
+                    .update(bannerConfigurationTable)
+                    .set({ isDefault: true })
+                    .where(eq(bannerConfigurationTable.id, id));
+                return config.placement;
+            });
+        });
+        await invalidate(this.cache, publicBannerCacheEpochKey(placement));
+        this.events.emit('cms.banner.configuration.set_default', {
+            bannerConfigurationId: id,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return this.getPlacementSummary(placement);
     }
-    async updateBanner(input, actorId) {
-        const existing = findOneOrThrow(await this.drizzle.db.select().from(bannerTable).where(eq(bannerTable.id, input.id)), new BannerNotFoundError(input.id));
-        const patch = {};
-        if (input.placement !== undefined) {
-            patch.placement = input.placement;
+    async unsetDefaultConfiguration(placement, actorId, meta) {
+        const previousBannerConfigurationId = await this.drizzle.db.transaction((tx) => withAdvisoryXactLock(tx, bannerScheduleLockKey(placement), async () => {
+            const [schedule] = await tx
+                .select({ id: bannerScheduleTable.id })
+                .from(bannerScheduleTable)
+                .innerJoin(bannerConfigurationTable, eq(bannerScheduleTable.bannerConfigurationId, bannerConfigurationTable.id))
+                .where(and(eq(bannerConfigurationTable.placement, placement), gt(bannerScheduleTable.endsAt, new Date())))
+                .limit(1);
+            if (schedule) {
+                throw new BannerPlacementHasScheduleError();
+            }
+            const [current] = await tx
+                .select()
+                .from(bannerConfigurationTable)
+                .where(and(eq(bannerConfigurationTable.placement, placement), eq(bannerConfigurationTable.isDefault, true)));
+            if (!current) {
+                return null;
+            }
+            await tx
+                .update(bannerConfigurationTable)
+                .set({ isDefault: false })
+                .where(eq(bannerConfigurationTable.id, current.id));
+            return current.id;
+        }));
+        await invalidate(this.cache, publicBannerCacheEpochKey(placement));
+        this.events.emit('cms.banner.configuration.unset_default', {
+            placement,
+            previousBannerConfigurationId,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return this.getPlacementSummary(placement);
+    }
+    async setBannerImage(input, actorId, meta) {
+        for (const url of [input.desktopImageUrl, input.mobileImageUrl]) {
+            const result = validateBannerImageUrl(url, this.allowedBannerImageHosts);
+            if (!result.ok) {
+                throw new BannerImageHostNotAllowedError(result.reason);
+            }
         }
-        if (input.title !== undefined) {
-            patch.title = input.title;
+        const locale = input.locale ?? DEFAULT_LOCALE;
+        const { configuration, record, droppedImageUrls } = await this.drizzle.db.transaction((tx) => withAdvisoryXactLock(tx, bannerConfigurationMutationLockKey(input.bannerConfigurationId), async () => {
+            const configuration = findOneOrThrow(await tx
+                .select()
+                .from(bannerConfigurationTable)
+                .where(eq(bannerConfigurationTable.id, input.bannerConfigurationId)), new BannerConfigurationNotFoundError(input.bannerConfigurationId));
+            const [replaced] = await tx
+                .select({
+                desktopImageUrl: bannerImageTable.desktopImageUrl,
+                mobileImageUrl: bannerImageTable.mobileImageUrl,
+            })
+                .from(bannerImageTable)
+                .where(and(eq(bannerImageTable.bannerConfigurationId, input.bannerConfigurationId), eq(bannerImageTable.sortOrder, input.sortOrder), eq(bannerImageTable.locale, locale)));
+            const retained = new Set([input.desktopImageUrl, input.mobileImageUrl]);
+            const droppedImageUrlCandidates = replaced
+                ? [replaced.desktopImageUrl, replaced.mobileImageUrl].filter((url) => !retained.has(url))
+                : [];
+            return withBannerImageUrlLocks(tx, [
+                input.desktopImageUrl,
+                input.mobileImageUrl,
+                ...(replaced ? [replaced.desktopImageUrl, replaced.mobileImageUrl] : []),
+            ], async () => {
+                const record = findOneOrThrow(await tx
+                    .insert(bannerImageTable)
+                    .values({
+                    bannerConfigurationId: input.bannerConfigurationId,
+                    sortOrder: input.sortOrder,
+                    locale,
+                    desktopImageUrl: input.desktopImageUrl,
+                    mobileImageUrl: input.mobileImageUrl,
+                    linkUrl: input.linkUrl ?? null,
+                })
+                    .onConflictDoUpdate({
+                    target: [
+                        bannerImageTable.bannerConfigurationId,
+                        bannerImageTable.sortOrder,
+                        bannerImageTable.locale,
+                    ],
+                    set: {
+                        desktopImageUrl: input.desktopImageUrl,
+                        mobileImageUrl: input.mobileImageUrl,
+                        linkUrl: input.linkUrl ?? null,
+                    },
+                })
+                    .returning(), new BannerConfigurationNotFoundError(input.bannerConfigurationId));
+                const droppedImageUrls = await unreferencedBannerImageUrls(tx, droppedImageUrlCandidates);
+                return { configuration, record, droppedImageUrls };
+            });
+        }));
+        if (configuration.isDefault) {
+            await invalidate(this.cache, publicBannerCacheEpochKey(configuration.placement));
         }
-        if (input.imageUrl !== undefined) {
-            patch.imageUrl = input.imageUrl;
+        this.events.emit('cms.banner.image.set', {
+            bannerImageId: record.id,
+            bannerConfigurationId: input.bannerConfigurationId,
+            droppedImageUrls,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return toBannerImage(record);
+    }
+    async deleteBannerImage(id, actorId, meta) {
+        const { existing, configuration, droppedImageUrls } = await this.drizzle.db.transaction(async (tx) => {
+            const initial = findOneOrThrow(await tx
+                .select({ bannerConfigurationId: bannerImageTable.bannerConfigurationId })
+                .from(bannerImageTable)
+                .where(eq(bannerImageTable.id, id)), new BannerImageNotFoundError(id));
+            return withAdvisoryXactLock(tx, bannerConfigurationMutationLockKey(initial.bannerConfigurationId), async () => {
+                const existing = findOneOrThrow(await tx
+                    .select({
+                    id: bannerImageTable.id,
+                    bannerConfigurationId: bannerImageTable.bannerConfigurationId,
+                    locale: bannerImageTable.locale,
+                    desktopImageUrl: bannerImageTable.desktopImageUrl,
+                    mobileImageUrl: bannerImageTable.mobileImageUrl,
+                })
+                    .from(bannerImageTable)
+                    .where(eq(bannerImageTable.id, id)), new BannerImageNotFoundError(id));
+                return withBannerImageUrlLocks(tx, [existing.desktopImageUrl, existing.mobileImageUrl], async () => {
+                    const [deleted] = await tx
+                        .delete(bannerImageTable)
+                        .where(eq(bannerImageTable.id, id))
+                        .returning({
+                        id: bannerImageTable.id,
+                        bannerConfigurationId: bannerImageTable.bannerConfigurationId,
+                        locale: bannerImageTable.locale,
+                        desktopImageUrl: bannerImageTable.desktopImageUrl,
+                        mobileImageUrl: bannerImageTable.mobileImageUrl,
+                    });
+                    if (!deleted) {
+                        throw new BannerImageNotFoundError(id);
+                    }
+                    const [configuration] = await tx
+                        .select({
+                        placement: bannerConfigurationTable.placement,
+                        isDefault: bannerConfigurationTable.isDefault,
+                    })
+                        .from(bannerConfigurationTable)
+                        .where(eq(bannerConfigurationTable.id, deleted.bannerConfigurationId));
+                    const droppedImageUrls = await unreferencedBannerImageUrls(tx, [
+                        deleted.desktopImageUrl,
+                        deleted.mobileImageUrl,
+                    ]);
+                    return { existing: deleted, configuration, droppedImageUrls };
+                });
+            });
+        });
+        if (configuration?.isDefault) {
+            await invalidate(this.cache, publicBannerCacheEpochKey(configuration.placement));
         }
-        if (input.linkUrl !== undefined) {
-            patch.linkUrl = input.linkUrl;
+        this.events.emit('cms.banner.image.deleted', {
+            bannerImageId: id,
+            bannerConfigurationId: existing.bannerConfigurationId,
+            droppedImageUrls,
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return { success: true };
+    }
+    async getPublicBanner(placement, locale) {
+        const resolvedLocale = locale ?? DEFAULT_LOCALE;
+        return cached(this.cache, await currentPublicBannerCacheKey(this.cache, placement, resolvedLocale), CMS_CACHE_TTL_MS, async () => {
+            // "What's live" is resolved here, at read time, not by a background job - a
+            // scheduled banner wins over the default while now() falls inside its
+            // [startsAt, endsAt] window (same auto-expiry approach as rgExclusion, see
+            // compliance/schema/index.ts). No invalidation is needed at the schedule's
+            // own start/end boundary; the pre-existing CMS_CACHE_TTL_MS bounds the lag.
+            const now = new Date();
+            const [scheduled] = await this.drizzle.db
+                .select({
+                id: bannerConfigurationTable.id,
+                layout: bannerConfigurationTable.layout,
+            })
+                .from(bannerScheduleTable)
+                .innerJoin(bannerConfigurationTable, eq(bannerConfigurationTable.id, bannerScheduleTable.bannerConfigurationId))
+                .where(and(eq(bannerConfigurationTable.placement, placement), lte(bannerScheduleTable.startsAt, now), gte(bannerScheduleTable.endsAt, now)))
+                .limit(1);
+            const activeConfig = scheduled ??
+                (await this.drizzle.db
+                    .select({
+                    id: bannerConfigurationTable.id,
+                    layout: bannerConfigurationTable.layout,
+                })
+                    .from(bannerConfigurationTable)
+                    .where(and(eq(bannerConfigurationTable.placement, placement), eq(bannerConfigurationTable.isDefault, true))))[0];
+            if (!activeConfig) {
+                return null;
+            }
+            const images = await this.drizzle.db
+                .select()
+                .from(bannerImageTable)
+                .where(eq(bannerImageTable.bannerConfigurationId, activeConfig.id))
+                .orderBy(asc(bannerImageTable.sortOrder));
+            const localeRowBySlot = new Map(images.filter((i) => i.locale === resolvedLocale).map((i) => [i.sortOrder, i]));
+            const baseRows = images.filter((i) => i.locale === DEFAULT_LOCALE);
+            const slots = baseRows
+                .map((base) => {
+                const resolved = localeRowBySlot.get(base.sortOrder) ?? base;
+                return {
+                    sortOrder: base.sortOrder,
+                    desktopImageUrl: resolved.desktopImageUrl,
+                    mobileImageUrl: resolved.mobileImageUrl,
+                    linkUrl: resolved.linkUrl,
+                };
+            })
+                .sort((a, b) => a.sortOrder - b.sortOrder);
+            return { placement, layout: activeConfig.layout, slots };
+        });
+    }
+    async createBannerSchedule(bannerConfigurationId, input, actorId, meta) {
+        const startsAt = new Date(input.startsAt);
+        const endsAt = new Date(input.endsAt);
+        const { record, placement } = await this.drizzle.db.transaction(async (tx) => {
+            const initialConfig = findOneOrThrow(await tx
+                .select()
+                .from(bannerConfigurationTable)
+                .where(eq(bannerConfigurationTable.id, bannerConfigurationId)), new BannerConfigurationNotFoundError(bannerConfigurationId));
+            return withAdvisoryXactLock(tx, bannerScheduleLockKey(initialConfig.placement), async () => {
+                const config = findOneOrThrow(await tx
+                    .select()
+                    .from(bannerConfigurationTable)
+                    .where(eq(bannerConfigurationTable.id, bannerConfigurationId)), new BannerConfigurationNotFoundError(bannerConfigurationId));
+                // A schedule requires a default to layer onto, and can never target the
+                // default configuration itself (it is already live).
+                if (config.isDefault) {
+                    throw new BannerConfigurationIsDefaultError();
+                }
+                const [defaultConfig] = await tx
+                    .select({ id: bannerConfigurationTable.id })
+                    .from(bannerConfigurationTable)
+                    .where(and(eq(bannerConfigurationTable.placement, config.placement), eq(bannerConfigurationTable.isDefault, true)));
+                if (!defaultConfig) {
+                    throw new BannerConfigurationNotFoundError(config.placement);
+                }
+                const [existingSchedule] = await tx
+                    .select({ id: bannerScheduleTable.id })
+                    .from(bannerScheduleTable)
+                    .where(eq(bannerScheduleTable.bannerConfigurationId, bannerConfigurationId));
+                if (existingSchedule) {
+                    throw new BannerConfigurationHasScheduleError();
+                }
+                if (endsAt <= startsAt) {
+                    throw new BannerScheduleInvalidRangeError('endsAt must be after startsAt');
+                }
+                if (startsAt <= new Date()) {
+                    throw new BannerScheduleInvalidRangeError('startsAt must be in the future');
+                }
+                await this.assertBannerConfigurationImageCount(tx, config);
+                await this.assertNoScheduleOverlap(tx, config.placement, bannerConfigurationId, {
+                    startsAt,
+                    endsAt,
+                });
+                const inserted = findOneOrThrow(await tx
+                    .insert(bannerScheduleTable)
+                    .values({ bannerConfigurationId, startsAt, endsAt, createdBy: actorId })
+                    .returning(), new BannerConfigurationNotFoundError(bannerConfigurationId));
+                return { record: inserted, placement: config.placement };
+            });
+        });
+        await invalidate(this.cache, publicBannerCacheEpochKey(placement));
+        this.events.emit('cms.banner.schedule.created', {
+            bannerScheduleId: record.id,
+            bannerConfigurationId,
+            placement,
+            startsAt: record.startsAt.toISOString(),
+            endsAt: record.endsAt.toISOString(),
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return toBannerSchedule(record);
+    }
+    async updateBannerScheduleEnd(bannerConfigurationId, input, actorId, meta) {
+        const newEndsAt = new Date(input.endsAt);
+        const { record, placement, previousEndsAt } = await this.drizzle.db.transaction(async (tx) => {
+            const initialConfig = findOneOrThrow(await tx
+                .select()
+                .from(bannerConfigurationTable)
+                .where(eq(bannerConfigurationTable.id, bannerConfigurationId)), new BannerConfigurationNotFoundError(bannerConfigurationId));
+            return withAdvisoryXactLock(tx, bannerScheduleLockKey(initialConfig.placement), async () => {
+                const config = findOneOrThrow(await tx
+                    .select()
+                    .from(bannerConfigurationTable)
+                    .where(eq(bannerConfigurationTable.id, bannerConfigurationId)), new BannerConfigurationNotFoundError(bannerConfigurationId));
+                const schedule = findOneOrThrow(await tx
+                    .select()
+                    .from(bannerScheduleTable)
+                    .where(eq(bannerScheduleTable.bannerConfigurationId, bannerConfigurationId)), new BannerScheduleNotFoundError(bannerConfigurationId));
+                if (newEndsAt <= schedule.startsAt) {
+                    throw new BannerScheduleInvalidRangeError('endsAt must be after startsAt');
+                }
+                const now = new Date();
+                if (schedule.endsAt <= now && newEndsAt > now) {
+                    throw new BannerScheduleExpiredError();
+                }
+                // startsAt is not editable and not re-validated against now() here - ending a
+                // schedule early legitimately moves endsAt to now or the past.
+                await this.assertNoScheduleOverlap(tx, config.placement, bannerConfigurationId, {
+                    startsAt: schedule.startsAt,
+                    endsAt: newEndsAt,
+                });
+                const updated = findOneOrThrow(await tx
+                    .update(bannerScheduleTable)
+                    .set({ endsAt: newEndsAt })
+                    .where(eq(bannerScheduleTable.id, schedule.id))
+                    .returning(), new BannerScheduleNotFoundError(bannerConfigurationId));
+                return { record: updated, placement: config.placement, previousEndsAt: schedule.endsAt };
+            });
+        });
+        await invalidate(this.cache, publicBannerCacheEpochKey(placement));
+        this.events.emit('cms.banner.schedule.updated', {
+            bannerScheduleId: record.id,
+            bannerConfigurationId,
+            placement,
+            startsAt: record.startsAt.toISOString(),
+            endsAt: record.endsAt.toISOString(),
+            before: { endsAt: previousEndsAt.toISOString() },
+            actorId,
+            ip: meta?.ip ?? null,
+            userAgent: meta?.userAgent ?? null,
+        });
+        return toBannerSchedule(record);
+    }
+    async listBannerSchedulesByPlacement(placement) {
+        const rows = await this.drizzle.db
+            .select({ schedule: bannerScheduleTable, configuration: bannerConfigurationTable })
+            .from(bannerScheduleTable)
+            .innerJoin(bannerConfigurationTable, eq(bannerConfigurationTable.id, bannerScheduleTable.bannerConfigurationId))
+            .where(eq(bannerConfigurationTable.placement, placement))
+            .orderBy(asc(bannerScheduleTable.startsAt));
+        const configIds = rows.map((r) => r.configuration.id);
+        const counts = configIds.length
+            ? await this.drizzle.db
+                .select({
+                bannerConfigurationId: bannerImageTable.bannerConfigurationId,
+                count: sql `count(*)::int`,
+            })
+                .from(bannerImageTable)
+                .where(inArray(bannerImageTable.bannerConfigurationId, configIds))
+                .groupBy(bannerImageTable.bannerConfigurationId)
+            : [];
+        const countByConfig = new Map(counts.map((c) => [c.bannerConfigurationId, c.count]));
+        return rows.map((r) => ({
+            ...toBannerSchedule(r.schedule),
+            configuration: toBannerConfigurationSummary(r.configuration, countByConfig.get(r.configuration.id) ?? 0),
+        }));
+    }
+    // Half-open interval overlap: an existing schedule on the same placement (excluding
+    // the target configuration itself) conflicts unless it ends at-or-before the new
+    // start or starts at-or-after the new end - so touching boundaries are allowed.
+    async assertNoScheduleOverlap(tx, placement, excludeBannerConfigurationId, range) {
+        const [conflict] = await tx
+            .select({ startsAt: bannerScheduleTable.startsAt, endsAt: bannerScheduleTable.endsAt })
+            .from(bannerScheduleTable)
+            .innerJoin(bannerConfigurationTable, eq(bannerConfigurationTable.id, bannerScheduleTable.bannerConfigurationId))
+            .where(and(eq(bannerConfigurationTable.placement, placement), ne(bannerScheduleTable.bannerConfigurationId, excludeBannerConfigurationId), gt(bannerScheduleTable.endsAt, range.startsAt), lt(bannerScheduleTable.startsAt, range.endsAt)))
+            .limit(1);
+        if (conflict) {
+            throw new BannerScheduleOverlapError(conflict.startsAt, conflict.endsAt);
         }
-        if (input.isActive !== undefined) {
-            patch.isActive = input.isActive;
+    }
+    async assertBannerConfigurationImageCount(tx, configuration) {
+        // Slot count is measured against base-locale rows only: locale overrides replace
+        // a slot rather than adding a publishable slot.
+        const slotRows = await tx
+            .select({ sortOrder: bannerImageTable.sortOrder })
+            .from(bannerImageTable)
+            .where(and(eq(bannerImageTable.bannerConfigurationId, configuration.id), eq(bannerImageTable.locale, DEFAULT_LOCALE)));
+        const slotCount = new Set(slotRows.map((row) => row.sortOrder)).size;
+        const bounds = BANNER_IMAGE_COUNT_BOUNDS[configuration.layout];
+        if (slotCount < bounds.min || slotCount > bounds.max) {
+            throw new BannerConfigurationImageCountError(configuration.layout, bounds.min, bounds.max, slotCount);
         }
-        if (input.sortOrder !== undefined) {
-            patch.sortOrder = input.sortOrder;
+    }
+    // Shared by setDefaultConfiguration/unsetDefaultConfiguration - single-placement,
+    // so the extra queries here are not the N+1 pattern listPlacements avoids.
+    async getPlacementSummary(placement) {
+        const [defaultRow] = await this.drizzle.db
+            .select()
+            .from(bannerConfigurationTable)
+            .where(and(eq(bannerConfigurationTable.placement, placement), eq(bannerConfigurationTable.isDefault, true)));
+        if (defaultRow) {
+            const images = await this.drizzle.db
+                .select()
+                .from(bannerImageTable)
+                .where(eq(bannerImageTable.bannerConfigurationId, defaultRow.id))
+                .orderBy(asc(bannerImageTable.sortOrder));
+            return {
+                placement,
+                defaultConfigurationId: defaultRow.id,
+                defaultConfiguration: toBannerConfiguration(defaultRow, images.map(toBannerImage)),
+                updatedAt: defaultRow.updatedAt.toISOString(),
+            };
         }
-        const record = findOneOrThrow(await this.drizzle.db
-            .update(bannerTable)
-            .set(patch)
-            .where(eq(bannerTable.id, input.id))
-            .returning(), new BannerNotFoundError(input.id));
-        await invalidate(this.cache, [existing.placement, input.placement ?? existing.placement].map(bannersCacheKey));
-        this.events.emit('cms.banner.updated', { bannerId: record.id, actorId });
-        return toBanner(record);
-    }
-    async deleteBanner(id, actorId) {
-        const existing = findOneOrThrow(await this.drizzle.db.select().from(bannerTable).where(eq(bannerTable.id, id)), new BannerNotFoundError(id));
-        await this.drizzle.db.delete(bannerTable).where(eq(bannerTable.id, id));
-        await invalidate(this.cache, bannersCacheKey(existing.placement));
-        this.events.emit('cms.banner.deleted', { bannerId: id, actorId });
-        return { success: true };
+        // A raw sql aggregate has no column metadata for Drizzle to decode, so this comes
+        // back as Postgres's text representation, not a Date - parse it explicitly.
+        const [latest] = await this.drizzle.db
+            .select({ updatedAt: sql `max(${bannerConfigurationTable.updatedAt})` })
+            .from(bannerConfigurationTable)
+            .where(eq(bannerConfigurationTable.placement, placement));
+        return {
+            placement,
+            defaultConfigurationId: null,
+            defaultConfiguration: null,
+            updatedAt: (latest?.updatedAt ? new Date(latest.updatedAt) : new Date()).toISOString(),
+        };
     }
 }
 //# sourceMappingURL=cms.service.js.map