/** * Regional CDN (R2) cache-file URLs. * * Single source of truth for the backend cache writer and both UIs: * - the backend builds the URLs it publishes in `essentialConsts.essentialUrls` * and the object keys it uploads/purges with them; * - the UIs prefer `essentialUrls` from the API and fall back to these same * builders when an older backend or a persisted snapshot does not carry it. * * Path shapes (do not change without migrating the existing buckets): * {assetsDomain}{apiCacheKey}/regions/{regionId}/v-{productsVersion}/{file} * {assetsDomain}regions/{regionId}/av-{availabilityVersion}/availability.json * {assetsDomain}regions/{regionId}/slots/v-{slotsVersion}/slots.json * * Availability and slots intentionally sit OUTSIDE `apiCacheKey`. A builder * returns an empty string when a part it needs is missing, never a malformed * partial URL. */ export const CACHE_FILENAMES = { products: 'products.json', stores: 'stores.json', slots: 'slots.json', availability: 'availability.json', essentialConsts: 'essential-consts.json', banners: 'banners.json', } as const export type CacheFilename = (typeof CACHE_FILENAMES)[keyof typeof CACHE_FILENAMES] export interface CacheVersions { products: number availability: number slots: number } export interface EssentialUrls { productsUrl: string storesUrl: string bannersUrl: string essentialConstsUrl: string availabilityUrl: string slotsUrl: string /** Per-store detail URL with a `{storeId}` placeholder for the caller to replace. */ storeDetailUrlTemplate: string } function clean(value: string | null | undefined): string { return typeof value === 'string' ? value.trim() : '' } /** Assets domain with exactly one trailing slash ('' when unavailable). */ function domainBase(assetsDomain: string | null | undefined): string { const domain = clean(assetsDomain) if (!domain) return '' return domain.endsWith('/') ? domain : `${domain}/` } function cacheKey(apiCacheKey: string | null | undefined): string { return clean(apiCacheKey).replace(/^\/+|\/+$/g, '') } function version(value: number | null | undefined): string | null { return typeof value === 'number' && Number.isFinite(value) ? String(value) : null } function joinUrl(domain: string, path: string): string { return domain && path ? `${domain}${path}` : '' } /* -------------------------------------------------------------------------- */ /* Object keys (bucket-relative, used for uploads) */ /* -------------------------------------------------------------------------- */ export function regionCacheObjectKey( apiCacheKeyValue: string | null | undefined, regionId: number, productsVersion: number, filename: string ): string { const key = cacheKey(apiCacheKeyValue) const fileVersion = version(productsVersion) if (!key || fileVersion == null) return '' return `${key}/regions/${regionId}/v-${fileVersion}/${filename}` } export function availabilityObjectKey( regionId: number, availabilityVersion: number ): string { const fileVersion = version(availabilityVersion) if (fileVersion == null) return '' return `regions/${regionId}/av-${fileVersion}/${CACHE_FILENAMES.availability}` } export function slotsObjectKey(regionId: number, slotsVersion: number): string { const fileVersion = version(slotsVersion) if (fileVersion == null) return '' return `regions/${regionId}/slots/v-${fileVersion}/${CACHE_FILENAMES.slots}` } export function storeDetailObjectKey( apiCacheKeyValue: string | null | undefined, regionId: number, productsVersion: number, storeId: number ): string { if (!Number.isFinite(storeId)) return '' const key = cacheKey(apiCacheKeyValue) const fileVersion = version(productsVersion) if (!key || fileVersion == null) return '' return `${key}/regions/${regionId}/v-${fileVersion}/stores/${storeId}.json` } /* -------------------------------------------------------------------------- */ /* CDN URLs */ /* -------------------------------------------------------------------------- */ export function regionCacheUrl( assetsDomain: string | null | undefined, apiCacheKeyValue: string | null | undefined, regionId: number, productsVersion: number, filename: string ): string { return joinUrl( domainBase(assetsDomain), regionCacheObjectKey(apiCacheKeyValue, regionId, productsVersion, filename) ) } export function availabilityCacheUrl( assetsDomain: string | null | undefined, regionId: number, availabilityVersion: number ): string { return joinUrl(domainBase(assetsDomain), availabilityObjectKey(regionId, availabilityVersion)) } export function slotsCacheUrl( assetsDomain: string | null | undefined, regionId: number, slotsVersion: number ): string { return joinUrl(domainBase(assetsDomain), slotsObjectKey(regionId, slotsVersion)) } export function storeDetailCacheUrl( assetsDomain: string | null | undefined, apiCacheKeyValue: string | null | undefined, regionId: number, productsVersion: number, storeId: number ): string { return joinUrl( domainBase(assetsDomain), storeDetailObjectKey(apiCacheKeyValue, regionId, productsVersion, storeId) ) } export function buildStoreDetailUrlTemplate( assetsDomain: string | null | undefined, apiCacheKeyValue: string | null | undefined, regionId: number, productsVersion: number ): string { return regionCacheUrl( assetsDomain, apiCacheKeyValue, regionId, productsVersion, 'stores/{storeId}.json' ) } export interface EssentialUrlsInput { assetsDomain?: string | null apiCacheKey?: string | null regionId: number versions: CacheVersions } /** Every URL the browsing region can read from the CDN ('' when unavailable). */ export function buildEssentialUrls(input: EssentialUrlsInput): EssentialUrls { const { assetsDomain, apiCacheKey: apiCacheKeyValue, regionId, versions } = input return { productsUrl: regionCacheUrl( assetsDomain, apiCacheKeyValue, regionId, versions.products, CACHE_FILENAMES.products ), storesUrl: regionCacheUrl( assetsDomain, apiCacheKeyValue, regionId, versions.products, CACHE_FILENAMES.stores ), bannersUrl: regionCacheUrl( assetsDomain, apiCacheKeyValue, regionId, versions.products, CACHE_FILENAMES.banners ), essentialConstsUrl: regionCacheUrl( assetsDomain, apiCacheKeyValue, regionId, versions.products, CACHE_FILENAMES.essentialConsts ), availabilityUrl: availabilityCacheUrl(assetsDomain, regionId, versions.availability), slotsUrl: slotsCacheUrl(assetsDomain, regionId, versions.slots), storeDetailUrlTemplate: buildStoreDetailUrlTemplate( assetsDomain, apiCacheKeyValue, regionId, versions.products ), } } /** * Look up the published URL for a cache file. Returns null when the payload has * no usable URL for it (missing field or empty string), so callers can fall back * to the builders above. */ export function cachedFileUrl( urls: Partial | null | undefined, filename: string ): string | null { if (!urls) return null const field = ( { [CACHE_FILENAMES.products]: 'productsUrl', [CACHE_FILENAMES.stores]: 'storesUrl', [CACHE_FILENAMES.banners]: 'bannersUrl', [CACHE_FILENAMES.essentialConsts]: 'essentialConstsUrl', [CACHE_FILENAMES.availability]: 'availabilityUrl', [CACHE_FILENAMES.slots]: 'slotsUrl', } as Record )[filename] const value = field ? urls[field] : null return typeof value === 'string' && value.length > 0 ? value : null }