/** * CACHE-88..98, CACHE-116 — `banners.json` and the versioned `essential-consts.json` * (catalogue §4.6). * * `banners.json` is rebuilt asynchronously with `products_version_num` (the * CacheCreator DO), so every banner mutation polls the versioned file. * `essential-consts.json` is written with the products file (same version) and * carries the flat const payload used by the client apps. * * Rows pinned `(current)`: * - CACHE-88: `getActiveBanners` gates on `serialNum IS NOT NULL`, NOT on * `isActive`; the seeded banners are all `isActive:false` yet present, so the * file is not "active only". * - CACHE-96: the file's `slots_version_num`/`availability_version_num` are a * snapshot taken during the rebuild and may lag the live D1 counters. */ import { uniqueSuffix, type ApiClient } from '../helpers/api' import { staffClient } from '../helpers/sessions' import { getEssentialConsts, scaffoldCache, scaffoldEssentialConsts, type EssentialConsts, } from '../helpers/cache' import { TEST_BOUND_ID, TEST_REGION_ID } from '../helpers/env' jest.setTimeout(600_000) /* -------------------------------------------------------------------------- */ /* Helpers */ /* -------------------------------------------------------------------------- */ async function productsVersion(admin: ApiClient): Promise { const rows: any = await admin.admin.region.getRegionConstants.query() const row = rows.find((entry: any) => entry.key === 'products_version_num') return Number(row?.value ?? 0) } /** The D1 version first, then the KV mirror version if it differs. */ async function candidateVersions(admin: ApiClient): Promise { const d1 = await productsVersion(admin) const kv = Number((await getEssentialConsts()).products_version_num) return d1 === kv ? [d1] : [d1, kv] } /** * Region 1's banners document from the scaffold function (test route). * Same object the cache writer serialises, straight from D1. */ async function pollBanners( _admin: ApiClient, predicate: (doc: any) => boolean, label: string, _options: { minVersion?: number; timeoutMs?: number } = {} ): Promise { const doc = await scaffoldCache('banners', { regionId: TEST_REGION_ID }) if (!predicate(doc)) throw new Error(`[api-tests] banners document did not satisfy: ${label}`) return doc } /** * The essential-consts document from `scaffoldEssentialConsts` (test route). * `version` is the document's own products version. */ async function pollEssentialConsts(_admin: ApiClient): Promise<{ doc: any; version: number }> { const doc: any = await scaffoldEssentialConsts(TEST_BOUND_ID) return { doc, version: Number(doc?.products_version_num ?? 0) } } /* -------------------------------------------------------------------------- */ /* Shared fixture */ /* -------------------------------------------------------------------------- */ interface SharedBanners { consts: EssentialConsts baseline: number inactiveBanner: any updatedBanner: any updatedName: string doc: any essentialConsts: { doc: any; version: number } } let shared: SharedBanners beforeAll(async () => { const admin = await staffClient() const baseline = await productsVersion(admin) const suffix = uniqueSuffix() // Two creates + one update in a single debounce window (one rebuild): one // banner keeps the create default (inactive), the other is activated/renamed. const inactiveBanner: any = await admin.admin.banner.createBanner.mutate({ name: `E2E Cache Banner ${suffix}`, imageUrl: `${(await getEssentialConsts()).assetsDomain}home-banners/e2e-${suffix}.png`, description: 'cache rebuild probe', }) const updatedBanner: any = await admin.admin.banner.createBanner.mutate({ name: `E2E Cache Banner ${suffix} b`, imageUrl: `${(await getEssentialConsts()).assetsDomain}home-banners/e2e-${suffix}-b.png`, }) const updatedName = `${updatedBanner.name} active` await admin.admin.banner.updateBanner.mutate({ id: updatedBanner.id, name: updatedName, isActive: true, serialNum: 7, }) const doc = await pollBanners( admin, (d) => (d.banners ?? []).some((entry: any) => Number(entry.id) === Number(inactiveBanner.id)) && (d.banners ?? []).some( (entry: any) => Number(entry.id) === Number(updatedBanner.id) && entry.name === updatedName && entry.isActive === true ), `banners.json contains the created banners`, { minVersion: baseline } ) const essentialConsts = await pollEssentialConsts(admin) shared = { consts: await getEssentialConsts(), baseline, inactiveBanner, updatedBanner, updatedName, doc, essentialConsts, } }) /* -------------------------------------------------------------------------- */ /* banners.json */ /* -------------------------------------------------------------------------- */ describe('banners.json shape (CACHE-88..91)', () => { it('(current) CACHE-88: banners.json has a banners array; it is serial-num gated, not active-only', () => { // getActiveBanners filters `serialNum IS NOT NULL` only. Every seeded banner // is isActive:false yet present, and a default-created (inactive) banner is // present too, so the reachable contract is "banners array", not "active only". expect(Array.isArray(shared.doc.banners)).toBe(true) expect(shared.doc.banners.length).toBeGreaterThan(0) const mine = shared.doc.banners.find( (entry: any) => Number(entry.id) === Number(shared.inactiveBanner.id) ) expect(mine).toBeTruthy() expect(mine.isActive).toBe(false) expect(shared.doc.banners.some((entry: any) => entry.isActive === false)).toBe(true) }) it('CACHE-89: a banner carries id/name/imageUrl/description/skuIds/redirectUrl/serialNum/isActive', () => { const banner = shared.doc.banners.find( (entry: any) => Number(entry.id) === Number(shared.inactiveBanner.id) ) expect(banner).toBeTruthy() for (const key of [ 'id', 'name', 'imageUrl', 'description', 'skuIds', 'redirectUrl', 'serialNum', 'isActive', ]) { expect(Object.prototype.hasOwnProperty.call(banner, key)).toBe(true) } expect(typeof banner.id).toBe('number') expect(typeof banner.name).toBe('string') expect(banner.imageUrl).toMatch(/^https?:\/\//) expect(banner.imageUrl).toContain('home-banners/') expect(banner.description === null || typeof banner.description === 'string').toBe(true) expect(Array.isArray(banner.skuIds)).toBe(true) expect(banner.redirectUrl === null || typeof banner.redirectUrl === 'string').toBe(true) expect(banner.serialNum === null || typeof banner.serialNum === 'number').toBe(true) expect(typeof banner.isActive).toBe('boolean') }) it('CACHE-90: skuIds is always an array (migration shape)', () => { for (const banner of shared.doc.banners) { expect(Array.isArray(banner.skuIds)).toBe(true) } }) it('CACHE-91: a created banner appears after a rebuild and is initially inactive', () => { const banner = shared.doc.banners.find( (entry: any) => Number(entry.id) === Number(shared.inactiveBanner.id) ) expect(banner).toBeTruthy() expect(banner.isActive).toBe(false) expect(banner.serialNum).toBe(999) expect(banner.skuIds).toEqual([]) }) }) describe('banners.json mutations (CACHE-92..93)', () => { it('CACHE-92: activating/updating a banner makes the new fields appear', () => { const banner = shared.doc.banners.find( (entry: any) => Number(entry.id) === Number(shared.updatedBanner.id) ) expect(banner).toBeTruthy() expect(banner.name).toBe(shared.updatedName) expect(banner.isActive).toBe(true) expect(banner.serialNum).toBe(7) }) it('CACHE-93: deleting a banner removes it after a rebuild', async () => { const admin = await staffClient() const baseline = await productsVersion(admin) await admin.admin.banner.deleteBanner.mutate({ id: shared.updatedBanner.id }) const doc = await pollBanners( admin, (d) => !(d.banners ?? []).some((entry: any) => Number(entry.id) === Number(shared.updatedBanner.id)), `banners.json omits the deleted banner ${shared.updatedBanner.id}`, { minVersion: baseline } ) expect( (doc.banners ?? []).some((entry: any) => Number(entry.id) === Number(shared.updatedBanner.id)) ).toBe(false) }) }) /* -------------------------------------------------------------------------- */ /* essential-consts.json */ /* -------------------------------------------------------------------------- */ describe('essential-consts.json (CACHE-94..98)', () => { it('CACHE-94: the file is a flat payload with numeric version fields', () => { const doc = shared.essentialConsts.doc expect(typeof doc).toBe('object') expect(Array.isArray(doc)).toBe(false) for (const key of ['products_version_num', 'slots_version_num', 'availability_version_num']) { expect(typeof doc[key]).toBe('number') expect(Number.isFinite(doc[key])).toBe(true) } // Flat union: identity/env keys sit at the top level (no nested region/bound). expect(typeof doc.regionId).toBe('number') expect(typeof doc.boundId).toBe('number') expect(typeof doc.assetsDomain).toBe('string') expect(typeof doc.apiCacheKey).toBe('string') expect((doc as any).region).toBeUndefined() expect((doc as any).bound).toBeUndefined() }) it('CACHE-95: the file version matches the path version', () => { expect(shared.essentialConsts.doc.products_version_num).toBe(shared.essentialConsts.version) }) it('(current) CACHE-96: the file’s slots/availability versions are a snapshot that may lag live', async () => { const admin = await staffClient() const rows: any = await admin.admin.region.getRegionConstants.query() const live = (key: string) => Number(rows.find((entry: any) => entry.key === key)?.value ?? 0) const doc = shared.essentialConsts.doc expect(typeof doc.slots_version_num).toBe('number') expect(typeof doc.availability_version_num).toBe('number') // The file is built during a rebuild; later synchronous bumps only move the // live D1 counters forward, so the file never leads them. expect(doc.slots_version_num).toBeLessThanOrEqual(live('slots_version_num')) expect(doc.availability_version_num).toBeLessThanOrEqual(live('availability_version_num')) }) it('CACHE-97: the file carries the effective bound/region identity', async () => { const consts = await getEssentialConsts() expect(shared.essentialConsts.doc.regionId).toBe(TEST_REGION_ID) expect(shared.essentialConsts.doc.boundId).toBe(consts.boundId) expect(consts.boundId).toBe(TEST_BOUND_ID) }) it('CACHE-98: webview fields are null/closable (the file build uses the default host)', () => { const doc = shared.essentialConsts.doc expect(doc.webviewHtml).toBeNull() expect(doc.webViewHtml).toBeNull() expect(doc.isWebviewClosable).toBe(true) }) it('CACHE-116: the file publishes essentialUrls for its own versions', () => { const doc = shared.essentialConsts.doc const urls = doc.essentialUrls expect(urls).toBeTruthy() expect(urls.productsUrl).toBe( `${doc.assetsDomain}${doc.apiCacheKey}/regions/${doc.regionId}/v-${doc.products_version_num}/products.json` ) expect(urls.storesUrl).toBe( `${doc.assetsDomain}${doc.apiCacheKey}/regions/${doc.regionId}/v-${doc.products_version_num}/stores.json` ) expect(urls.bannersUrl).toBe( `${doc.assetsDomain}${doc.apiCacheKey}/regions/${doc.regionId}/v-${doc.products_version_num}/banners.json` ) expect(urls.essentialConstsUrl).toBe( `${doc.assetsDomain}${doc.apiCacheKey}/regions/${doc.regionId}/v-${doc.products_version_num}/essential-consts.json` ) // Availability/slots keep the existing bucket layout (outside the cache key). expect(urls.availabilityUrl).toBe( `${doc.assetsDomain}regions/${doc.regionId}/av-${doc.availability_version_num}/availability.json` ) expect(urls.slotsUrl).toBe( `${doc.assetsDomain}regions/${doc.regionId}/slots/v-${doc.slots_version_num}/slots.json` ) expect(urls.storeDetailUrlTemplate).toBe( `${doc.assetsDomain}${doc.apiCacheKey}/regions/${doc.regionId}/v-${doc.products_version_num}/stores/{storeId}.json` ) }) })