@namiml/sdk-core 3.4.12-dev.202609252349 → 3.4.12-dev.202609281806

package/dist/index.cjs

@@ -106,7 +106,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.4.12", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.12-dev.202609252349", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.12-dev.202609281806", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -119,7 +119,13 @@ API_VERSION: exports.API_VERSION = "v3", BASE_URL_PATH: exports.BASE_URL_PATH =
 EXTENDED_CLIENT_INFO_PREFIX: exports.EXTENDED_CLIENT_INFO_PREFIX = "extendedClientInfo", EXTENDED_CLIENT_INFO_DELIMITER: exports.EXTENDED_CLIENT_INFO_DELIMITER = ":", VALIDATE_PRODUCT_GROUPS: exports.VALIDATE_PRODUCT_GROUPS = "validateProductGroups", LOG_HTTP_REQUESTS: exports.LOG_HTTP_REQUESTS = "logHTTPRequests", LOG_HTTP_TRAFFIC: exports.LOG_HTTP_TRAFFIC = "logHTTPTraffic", API_TRAFFIC_OBSERVER: exports.API_TRAFFIC_OBSERVER = "apiTrafficObserver", STARTUP_TELEMETRY: exports.STARTUP_TELEMETRY = "startupTelemetry", 
 // Test hook: every platform-config fetch attempt fails before the request leaves.
 // Same namiCommand as Apple's and Android's, so the shared first-run flows drive it.
-SIMULATE_CONFIG_FETCH_FAILURE: exports.SIMULATE_CONFIG_FETCH_FAILURE = "simulateConfigFetchFailure", EXTENDED_PLATFORM: exports.EXTENDED_PLATFORM = "extended-platform", EXTENDED_PLATFORM_VERSION: exports.EXTENDED_PLATFORM_VERSION = "extended-platform-version", API_MAX_CALLS_LIMIT: exports.API_MAX_CALLS_LIMIT = 2, API_RETRY_DELAY_SEC: exports.API_RETRY_DELAY_SEC = 2, API_TIMEOUT_LIMIT: exports.API_TIMEOUT_LIMIT = 20000, DEVICE_API_TIMEOUT_LIMIT: exports.DEVICE_API_TIMEOUT_LIMIT = 2000, 
+SIMULATE_CONFIG_FETCH_FAILURE: exports.SIMULATE_CONFIG_FETCH_FAILURE = "simulateConfigFetchFailure", 
+// Test hook: every per-paywall body fetch fails before the request leaves, so the body cache's
+// failure rows can be exercised without a proxy. Same namiCommand as Apple's and Android's (NAM-4357).
+SIMULATE_PAYWALL_FETCH_FAILURE: exports.SIMULATE_PAYWALL_FETCH_FAILURE = "simulatePaywallFetchFailure", 
+// `campaignCacheTTL=<seconds>` overrides the config's campaign_cache_ttl — Apple's command name.
+// It lets the paywall-cache e2e suite pin TTL 3600 / 1 / 0 per load (NAM-4357).
+CAMPAIGN_CACHE_TTL_PREFIX: exports.CAMPAIGN_CACHE_TTL_PREFIX = "campaignCacheTTL=", EXTENDED_PLATFORM: exports.EXTENDED_PLATFORM = "extended-platform", EXTENDED_PLATFORM_VERSION: exports.EXTENDED_PLATFORM_VERSION = "extended-platform-version", API_MAX_CALLS_LIMIT: exports.API_MAX_CALLS_LIMIT = 2, API_RETRY_DELAY_SEC: exports.API_RETRY_DELAY_SEC = 2, API_TIMEOUT_LIMIT: exports.API_TIMEOUT_LIMIT = 20000, DEVICE_API_TIMEOUT_LIMIT: exports.DEVICE_API_TIMEOUT_LIMIT = 2000, 
 // Platform-config attempts when no initial config was supplied (Android's
 // CONFIG_MAX_ATTEMPTS; Apple's retry(maxAttempts: 3)).
 CONFIG_MAX_ATTEMPTS: exports.CONFIG_MAX_ATTEMPTS = 3, 
@@ -3059,6 +3065,206 @@ function uniqBy(array, iteratee) {
   return (array && array.length) ? baseUniq(array, baseIteratee(iteratee)) : [];
 }
 
+/** Storage key of an entry's raw body; the exact URL follows the prefix. */
+const PAYWALL_BODY_KEY_PREFIX = "api_paywall_body:";
+/**
+ * Storage key of an entry's metadata. Written AFTER the body, so it is the commit point: an entry
+ * is visible only once both are durable, and a body with no metadata is an interrupted write.
+ */
+const PAYWALL_BODY_META_KEY_PREFIX = "api_paywall_body_meta:";
+const DEFAULT_MAX_BODY_ENTRIES = 500;
+class PaywallBodyCache {
+    constructor(storage = () => getPlatformAdapters().storage, maxEntries = DEFAULT_MAX_BODY_ENTRIES) {
+        this.storage = storage;
+        this.maxEntries = maxEntries;
+        /** Set under `campaign_cache_ttl == 0`: entries live here, in this process only. */
+        this.memory = null;
+        /** Metadata of every persisted entry, loaded once from the storage adapter. */
+        this.index = null;
+    }
+    get count() {
+        return this.memory ? this.memory.size : this.loadIndex().size;
+    }
+    /**
+     * Applies `campaign_cache_ttl` at the start of a resolution. `null` keeps everything, `n > 0`
+     * purges entries whose own age is `>= n` seconds, and `0` purges the persistent store and keeps
+     * this process's entries in memory only.
+     */
+    evaluateTtl(ttl, now = Date.now()) {
+        if (ttl === 0) {
+            if (this.memory)
+                return;
+            this.dropPersisted([...this.loadIndex().keys()]);
+            this.memory = new Map();
+            return;
+        }
+        // Leaving TTL 0 goes back to the persistent store; the process-local entries are dropped.
+        this.memory = null;
+        if (ttl === null)
+            return;
+        const expired = [...this.loadIndex().values()].filter((meta) => isExpired(meta, ttl, now));
+        this.dropPersisted(expired.map((meta) => meta.url));
+    }
+    /**
+     * The entry stored under this exact URL, or null when there is none, it is past `ttl`, or its
+     * body is missing (a half-written entry, which is deleted here).
+     */
+    validEntry(url, ttl, now = Date.now()) {
+        if (this.memory)
+            return this.memory.get(url) ?? null;
+        const meta = this.loadIndex().get(url);
+        if (!meta)
+            return null;
+        if (ttl !== null && ttl > 0 && isExpired(meta, ttl, now)) {
+            this.dropPersisted([url]);
+            return null;
+        }
+        const body = this.read(PAYWALL_BODY_KEY_PREFIX + url);
+        if (body === null) {
+            this.dropPersisted([url]);
+            return null;
+        }
+        return { meta, body };
+    }
+    /**
+     * The stored body for this exact URL, read straight from storage rather than through the index,
+     * with no TTL check. This is what rebuilds the aggregate `api_paywalls`, so it also sees an entry
+     * a host wrote after the index was loaded (the web test apps inject local test paywalls that way).
+     */
+    bodyFor(url) {
+        if (this.memory)
+            return this.memory.get(url)?.body ?? null;
+        return this.read(PAYWALL_BODY_KEY_PREFIX + url);
+    }
+    /** Stores a body under its exact URL. Returns false when the write did not land (quota, I/O). */
+    store(url, contentHash, body, now = Date.now()) {
+        const meta = { url, savedAt: now, ...(contentHash ? { contentHash } : {}) };
+        if (this.memory) {
+            this.memory.set(url, { meta, body });
+            return true;
+        }
+        const index = this.loadIndex();
+        const metaJson = JSON.stringify(meta);
+        // Body first, metadata last. Each write is verified by reading it back: the web adapter
+        // swallows a quota error rather than throwing, so a silent no-op is the common failure.
+        if (this.write(PAYWALL_BODY_KEY_PREFIX + url, body) &&
+            this.write(PAYWALL_BODY_META_KEY_PREFIX + url, metaJson)) {
+            index.set(url, meta);
+            return true;
+        }
+        logger.warn(`Paywall body cache: could not store ${url}; it will be fetched next time`);
+        this.dropPersisted([url]);
+        return false;
+    }
+    /** Stores a bundled body unless an entry already exists — a body the SDK fetched always wins. */
+    seedIfAbsent(url, contentHash, body, now = Date.now()) {
+        const exists = this.memory ? this.memory.has(url) : this.loadIndex().has(url);
+        return exists ? false : this.store(url, contentHash, body, now);
+    }
+    /** Deletes one entry — used for an undecodable body. Not eviction. */
+    remove(url) {
+        if (this.memory)
+            this.memory.delete(url);
+        else
+            this.dropPersisted([url]);
+    }
+    /**
+     * Eviction, run once per resolution after a complete `campaign_rules` fetch: delete every entry
+     * whose URL this resolution did not name, then cap the store at `maxEntries`, oldest first.
+     */
+    reconcile(currentUrls) {
+        const metas = this.memory
+            ? [...this.memory.values()].map((entry) => entry.meta)
+            : [...this.loadIndex().values()];
+        const unnamed = metas.filter((meta) => !currentUrls.has(meta.url)).map((meta) => meta.url);
+        const kept = metas.filter((meta) => currentUrls.has(meta.url)).sort((a, b) => a.savedAt - b.savedAt);
+        const overCap = kept.slice(0, Math.max(0, kept.length - this.maxEntries)).map((meta) => meta.url);
+        [...unnamed, ...overCap].forEach((url) => this.remove(url));
+    }
+    /** Empties the store — persisted and in-memory entries alike. Called by `Nami.reset()`. */
+    purgeAll() {
+        this.dropPersisted([...this.loadIndex().keys()]);
+        this.memory?.clear();
+    }
+    /** Builds the index from the metadata keys, clearing away half-written and unreadable entries. */
+    loadIndex() {
+        if (this.index)
+            return this.index;
+        this.index = new Map();
+        let keys;
+        try {
+            keys = this.storage().getAllKeys();
+        }
+        catch (error) {
+            logger.warn(`Paywall body cache: storage unavailable, caching nothing (${error})`);
+            return this.index;
+        }
+        const bodies = new Set(keys.filter((key) => key.startsWith(PAYWALL_BODY_KEY_PREFIX)).map((key) => key.slice(PAYWALL_BODY_KEY_PREFIX.length)));
+        const stale = [];
+        for (const key of keys) {
+            if (!key.startsWith(PAYWALL_BODY_META_KEY_PREFIX))
+                continue;
+            const url = key.slice(PAYWALL_BODY_META_KEY_PREFIX.length);
+            const meta = parseMeta(this.read(key));
+            if (meta?.url === url && bodies.has(url))
+                this.index.set(url, meta);
+            else
+                stale.push(url);
+            bodies.delete(url);
+        }
+        // Bodies whose metadata never landed: interrupted writes.
+        this.dropPersisted([...stale, ...bodies]);
+        return this.index;
+    }
+    dropPersisted(urls) {
+        for (const url of urls) {
+            this.index?.delete(url);
+            this.removeKey(PAYWALL_BODY_META_KEY_PREFIX + url);
+            this.removeKey(PAYWALL_BODY_KEY_PREFIX + url);
+        }
+    }
+    read(key) {
+        try {
+            return this.storage().getItem(key);
+        }
+        catch {
+            return null;
+        }
+    }
+    write(key, value) {
+        try {
+            this.storage().setItem(key, value);
+        }
+        catch {
+            return false;
+        }
+        return this.read(key) === value;
+    }
+    removeKey(key) {
+        try {
+            this.storage().removeItem(key);
+        }
+        catch {
+            // Nothing more to do: an entry that cannot be deleted is re-validated on the next read.
+        }
+    }
+}
+function isExpired(meta, ttlSeconds, now) {
+    return (now - meta.savedAt) / 1000 >= ttlSeconds;
+}
+function parseMeta(raw) {
+    if (raw === null)
+        return null;
+    try {
+        const meta = JSON.parse(raw);
+        return typeof meta?.url === "string" && typeof meta?.savedAt === "number" ? meta : null;
+    }
+    catch {
+        return null;
+    }
+}
+const paywallBodyCache = new PaywallBodyCache();
+
 class StorageService {
     constructor() {
         this.memoryStore = {};
@@ -3141,6 +3347,20 @@ class StorageService {
         }
         this.setItem(key, paywalls);
     }
+    /**
+     * Writes the aggregate `api_paywalls` as the list of URLs a per-URL resolution produced, rather
+     * than a second copy of their bodies (NAM-4357): the bodies already live in the per-URL body
+     * cache, and `getPaywalls(API_PAYWALLS)` rebuilds the paywall objects from it. The legacy bulk
+     * path still writes whole objects through `setPaywalls`.
+     */
+    setApiPaywallsFromBodyCache(urls) {
+        const index = { bodyCacheUrls: urls };
+        if (this.getCampaignCacheTtl() === 0) {
+            this.memoryStore[exports.API_PAYWALLS] = JSON.stringify(index);
+            return;
+        }
+        this.setItem(exports.API_PAYWALLS, index);
+    }
     getPaywalls(key) {
         if (key === exports.INITIAL_PAYWALLS) {
             return this.memoryStore[exports.INITIAL_PAYWALLS]
@@ -3149,8 +3369,10 @@ class StorageService {
         }
         if (key === exports.API_PAYWALLS) {
             const memoryValue = this.memoryStore[exports.API_PAYWALLS];
-            if (memoryValue != null)
-                return JSON.parse(memoryValue);
+            if (memoryValue != null) {
+                const parsed = JSON.parse(memoryValue);
+                return isBodyCacheAggregate(parsed) ? paywallsFromBodyCache(parsed.bodyCacheUrls) : parsed;
+            }
             let stored = this.getItem(exports.API_PAYWALLS);
             if (stored === null)
                 return null;
@@ -3162,6 +3384,8 @@ class StorageService {
                     return stored;
                 }
             }
+            if (isBodyCacheAggregate(stored))
+                return paywallsFromBodyCache(stored.bodyCacheUrls);
             return this.isLegacyTimestampedCache(stored) ? stored.data : stored;
         }
         return this.getItem(key);
@@ -3330,7 +3554,18 @@ class StorageService {
         this.resetItem(exports.API_CAMPAIGN_RULES);
         this.resetItem(exports.API_CAMPAIGN_SESSION_TIMESTAMP);
     }
+    /**
+     * The effective `campaign_cache_ttl`: a `campaignCacheTTL=<n>` namiCommand first, then the API
+     * config, then the initial config. Lives here rather than in `utils/config` because this service
+     * needs it to decide where the aggregate caches go, and `utils/config` already imports this one.
+     */
     getCampaignCacheTtl() {
+        const override = this.getNamiConfig()?.namiCommands
+            ?.filter((cmd) => cmd.startsWith(exports.CAMPAIGN_CACHE_TTL_PREFIX))
+            .map((cmd) => cmd.slice(exports.CAMPAIGN_CACHE_TTL_PREFIX.length))
+            .find((value) => /^\d+$/.test(value));
+        if (override !== undefined)
+            return parseInt(override, 10);
         const config = this.getAppConfig(exports.API_CONFIG)
             || this.getAppConfig(exports.INITIAL_APP_CONFIG);
         return config?.campaign_cache_ttl ?? null;
@@ -3422,6 +3657,28 @@ class StorageService {
         this.memoryStore = {};
     }
 }
+function isBodyCacheAggregate(value) {
+    return typeof value === "object" && value !== null && Array.isArray(value.bodyCacheUrls);
+}
+/**
+ * The paywalls a per-URL resolution produced, decoded from the body cache. A URL whose entry has
+ * since gone (evicted, purged, or a write that never landed) is simply absent.
+ */
+function paywallsFromBodyCache(urls) {
+    const paywalls = [];
+    for (const url of urls) {
+        const body = paywallBodyCache.bodyFor(url);
+        if (body === null)
+            continue;
+        try {
+            paywalls.push(JSON.parse(body));
+        }
+        catch {
+            paywallBodyCache.remove(url);
+        }
+    }
+    return paywalls;
+}
 const storageService = new StorageService();
 
 class RetryLimitExceededError extends Error {
@@ -6799,11 +7056,8 @@ const hasCapability = (capability) => {
         || storageService.getAppConfig(exports.INITIAL_APP_CONFIG);
     return appConfig?.capabilities?.includes(capability) ?? false;
 };
-const getCampaignCacheTtl = () => {
-    const config = storageService.getAppConfig(exports.API_CONFIG)
-        || storageService.getAppConfig(exports.INITIAL_APP_CONFIG);
-    return config?.campaign_cache_ttl ?? null;
-};
+/** The effective `campaign_cache_ttl`, `campaignCacheTTL=<n>` namiCommand first. */
+const getCampaignCacheTtl = () => storageService.getCampaignCacheTtl();
 /**
  * The effective global journey settings from the current config, coalescing a missing
  * `journey_settings` object — or any missing field — to {@link DEFAULT_JOURNEY_SETTINGS}.
@@ -57510,22 +57764,23 @@ class CampaignRuleRepository {
     static hasPaywallUrls(campaigns) {
         return campaigns.some((c) => c.paywall_url || c.page_urls || c.flow?.page_urls);
     }
+    /**
+     * The campaign rules for this form factor, unvalidated, plus whether they came from the network.
+     * `fromNetwork` is false when the stored rules stood in for a failed fetch (or updates are
+     * disabled): the per-URL body cache must then neither resolve nor evict (NAM-4357).
+     */
     async fetchCampaignRulesRaw() {
-        const authDevice = storageService.getDevice();
         if (this.disableCampaignUpdates) {
             logger.info("Campaign updates disabled by configuration. Skipping fetch.");
-            return [];
-        }
-        let campaignRules;
-        if (!authDevice?.id) {
-            campaignRules = await this.getAnonymousCampaigns();
-        }
-        else {
-            campaignRules = await this.getCampaigns(authDevice.id);
+            return { campaigns: [], fromNetwork: false };
         }
-        campaignRules = campaignRules?.filter((cRule) => (cRule.paywall && cRule.form_factors.some((f) => f.form_factor === this.currentFormFactor)) ||
+        const authDevice = storageService.getDevice();
+        const fetched = authDevice?.id
+            ? await this.fetchCampaigns(authDevice.id)
+            : await this.fetchAnonymousCampaigns();
+        const campaigns = fetched.campaigns?.filter((cRule) => (cRule.paywall && cRule.form_factors.some((f) => f.form_factor === this.currentFormFactor)) ||
             (cRule.flow && cRule.form_factors?.some((f) => f.form_factor === this.currentFormFactor)));
-        return campaignRules;
+        return { campaigns, fromNetwork: fetched.fromNetwork };
     }
     finalizeCampaignRules(campaignRules, paywalls) {
         // NAM-2457: a server flow rule is kept only when BOTH assets are satisfied —
@@ -57561,10 +57816,19 @@ class CampaignRuleRepository {
         listeners.forEach((handler) => handler(campaigns));
     }
     async getAnonymousCampaigns(sdkVersion = exports.NAMI_SDK_VERSION) {
+        return (await this.fetchAnonymousCampaigns(sdkVersion)).campaigns;
+    }
+    async getCampaigns(deviceId) {
+        return (await this.fetchCampaigns(deviceId)).campaigns;
+    }
+    async fetchAnonymousCampaigns(sdkVersion = exports.NAMI_SDK_VERSION) {
         const path = `campaign_rules/?sdk_version=${sdkVersion}`;
         try {
             const resp = await NamiAPI.instance.fetchAPI(path);
-            return mapAnonymousCampaigns(resp.results ?? [], this.splitPosition, this.currentFormFactor);
+            return {
+                campaigns: mapAnonymousCampaigns(resp.results ?? [], this.splitPosition, this.currentFormFactor),
+                fromNetwork: true,
+            };
         }
         catch (error) {
             const data = this.fallbackData();
@@ -57572,23 +57836,23 @@ class CampaignRuleRepository {
                 logger.error(handleErrors(error.status, path));
                 throw error;
             }
-            return data.results;
+            return { campaigns: data.results, fromNetwork: false };
         }
     }
-    async getCampaigns(deviceId) {
+    async fetchCampaigns(deviceId) {
         const path = `device/${deviceId}/campaign_rules/`;
-        let data;
         try {
-            data = await NamiAPI.instance.fetchAPI(path);
+            const data = await NamiAPI.instance.fetchAPI(path);
+            return { campaigns: data?.results || [], fromNetwork: true };
         }
         catch (error) {
-            data = this.fallbackData();
+            const data = this.fallbackData();
             if (!data) {
                 logger.error(handleErrors(error.status, path));
                 throw error;
             }
+            return { campaigns: data.results || [], fromNetwork: false };
         }
-        return data?.results || [];
     }
     fallbackData() {
         const storedData = storageService.getCampaignRules(exports.API_CAMPAIGN_RULES)
@@ -57871,6 +58135,15 @@ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * RetryExhaustedError when all attempts and/or the budget are spent.
  */
 async function fetchWithCdnRetry(url, opts = {}) {
+    const { data, retryCount } = await fetchTextWithCdnRetry(url, opts);
+    return { data: JSON.parse(data), retryCount };
+}
+/**
+ * {@link fetchWithCdnRetry}'s retry loop, returning the raw 2xx body text instead of parsed JSON.
+ * The per-URL paywall body cache stores those exact bytes, so a cached body is decoded by the
+ * same `JSON.parse` a fetched one is (NAM-4357).
+ */
+async function fetchTextWithCdnRetry(url, opts = {}) {
     const maxAttempts = opts.maxAttempts ?? DEFAULTS.maxAttempts;
     const baseDelayMs = opts.baseDelayMs ?? DEFAULTS.baseDelayMs;
     const maxDelayMs = opts.maxDelayMs ?? DEFAULTS.maxDelayMs;
@@ -57920,8 +58193,7 @@ async function fetchWithCdnRetry(url, opts = {}) {
                 const responseBody = await response.clone().text();
                 logger.debug(`[HTTP] Response ${response.status}: ${responseBody}`);
             }
-            const data = (await response.json());
-            return { data, retryCount: attempt };
+            return { data: await response.text(), retryCount: attempt };
         }
         catch (err) {
             if (err instanceof NonRetryableHttpError)
@@ -57942,7 +58214,43 @@ async function fetchWithCdnRetry(url, opts = {}) {
     throw new RetryExhaustedError(url, attempt, lastStatus);
 }
 
+/**
+ * Reads the parts of a `campaign_rules` paywall URL the per-URL body cache needs (NAM-4357).
+ *
+ * Both helpers scan the string rather than build a `URL`: the cache is keyed on the exact bytes
+ * the server sent, so nothing here may normalise, re-encode or reject a URL — a malformed one is
+ * simply un-hashed.
+ */
+/**
+ * The `content_hash` query value, or undefined when it is missing or empty. When the item appears
+ * more than once the first value wins. The value is never parsed or validated: it is a
+ * cache-validity token, not a content selector.
+ */
+function contentHashOf(url) {
+    const query = url.split("#")[0].split("?")[1];
+    if (!query)
+        return undefined;
+    for (const item of query.split("&")) {
+        const eq = item.indexOf("=");
+        const name = eq === -1 ? item : item.slice(0, eq);
+        if (name !== "content_hash")
+            continue;
+        const value = eq === -1 ? "" : item.slice(eq + 1);
+        return value || undefined;
+    }
+    return undefined;
+}
+/** The path segment after `/paywall/` — the paywall id the URL names — or undefined. */
+function paywallIdOf(url) {
+    const path = url.split(/[?#]/)[0];
+    const match = /\/paywall\/([^/]+)/.exec(path);
+    return match ? match[1] : undefined;
+}
+
 class PaywallRepository {
+    constructor(bodyCache = paywallBodyCache) {
+        this.bodyCache = bodyCache;
+    }
     async fetchPaywalls() {
         const authDevice = storageService.getDevice();
         let paywalls;
@@ -57991,34 +58299,131 @@ class PaywallRepository {
         }
         return data?.results || [];
     }
-    async fetchPaywallByUrl(url) {
-        return fetchWithCdnRetry(url);
-    }
-    async fetchPaywallsByUrls(urls) {
+    /**
+     * Resolves the URL set named by `campaign_rules` into paywall objects — the decision table of
+     * `api-resilience-and-caching.md` § 2.2, run identically at startup and on `refresh()`:
+     *
+     * | URL       | entry for the exact URL within TTL | action                        | provenance               |
+     * |-----------|------------------------------------|-------------------------------|--------------------------|
+     * | hashed    | yes                                | serve it, no request          | `cacheHit`               |
+     * | hashed    | no                                 | fetch; store the 2xx body     | `fetched`                |
+     * | un-hashed | not consulted                      | fetch; store the 2xx body     | `fetched`                |
+     * | either    | fetch failed, entry within TTL     | serve it, keep it             | `cacheAfterFetchFailure` |
+     * | either    | fetch failed, no entry             | no body                       | counts `failed`          |
+     *
+     * Writes the aggregate `api_paywalls` — as the URLs of every body this resolution produced, since
+     * the bodies themselves are already in the body cache — unless it produced none, so an outage
+     * cannot overwrite a good aggregate with an empty one. Eviction is the caller's: it runs only
+     * after a complete `campaign_rules` fetch.
+     */
+    async resolvePaywallsByUrls(urls) {
         const uniqueUrls = [...new Set(urls)];
-        const results = await Promise.allSettled(uniqueUrls.map((url) => this.fetchPaywallByUrl(url)));
-        const paywalls = [];
-        let retryCount = 0;
-        for (const result of results) {
-            if (result.status === "fulfilled") {
-                paywalls.push(result.value.data);
-                retryCount += result.value.retryCount;
-            }
-            else {
-                // Note: an exhausted-failure path contributed retries we can't see
-                // from the rejected promise, so retryCount under-reports failures.
-                // Acceptable for the telemetry signal; revisit if full accounting matters.
-                logger.error(`Failed to fetch individual paywall: ${result.reason}`);
+        const ttl = getCampaignCacheTtl();
+        this.bodyCache.evaluateTtl(ttl);
+        const resolutions = await Promise.all(uniqueUrls.map((url) => this.resolvePaywall(url, ttl)));
+        const outcome = {
+            paywalls: [],
+            urls: uniqueUrls.length,
+            hashed: uniqueUrls.filter((url) => contentHashOf(url) !== undefined).length,
+            cacheHits: 0,
+            fetched: 0,
+            cacheAfterFetchFailure: 0,
+            failed: 0,
+            retryCount: 0,
+        };
+        const resolvedUrls = new Map();
+        resolutions.forEach((resolution, i) => {
+            outcome.retryCount += resolution.retryCount;
+            if (!resolution.paywall) {
+                outcome.failed += 1;
+                return;
             }
+            resolvedUrls.set(resolution.paywall, uniqueUrls[i]);
+            if (resolution.paywall.fetchSource === "cacheHit")
+                outcome.cacheHits += 1;
+            else if (resolution.paywall.fetchSource === "cacheAfterFetchFailure")
+                outcome.cacheAfterFetchFailure += 1;
+            else
+                outcome.fetched += 1;
+        });
+        outcome.paywalls = this.validatePaywalls([...resolvedUrls.keys()]);
+        if (outcome.paywalls.length > 0) {
+            storageService.setApiPaywallsFromBodyCache(outcome.paywalls.map((paywall) => resolvedUrls.get(paywall)));
         }
-        if (paywalls.length > 0) {
-            const valid = this.validatePaywalls(paywalls);
-            if (valid.length > 0) {
-                storageService.setPaywalls(exports.API_PAYWALLS, valid);
+        return outcome;
+    }
+    /**
+     * Seeds the body cache from the initial-config bundle (§ 2.2 "Seeding"): every **hashed** bundled
+     * URL whose paywall id matches a bundled body is stored under that exact URL unless an entry
+     * already exists. A hash in a bundled URL was minted against the bundled body, so the pair is
+     * exact. Runs at configure, before the first resolution.
+     */
+    seedFromInitialConfig(campaignRules, paywalls) {
+        const bundled = new Map(paywalls.map((paywall) => [paywall.id, paywall]));
+        this.bodyCache.evaluateTtl(getCampaignCacheTtl());
+        let candidates = 0;
+        let seeded = 0;
+        for (const url of new Set(bundledPaywallUrls(campaignRules))) {
+            const contentHash = contentHashOf(url);
+            const id = paywallIdOf(url);
+            const paywall = id ? bundled.get(id) : undefined;
+            if (!contentHash || !paywall)
+                continue;
+            candidates += 1;
+            if (this.bodyCache.seedIfAbsent(url, contentHash, JSON.stringify(paywall)))
+                seeded += 1;
+        }
+        logger.info(`Paywall body cache seeded from initial config: seeded=${seeded}, candidates=${candidates}`);
+    }
+    /** One row of the decision table. Never throws. */
+    async resolvePaywall(url, ttl) {
+        const contentHash = contentHashOf(url);
+        if (contentHash) {
+            const hit = this.decodeCached(url, ttl);
+            if (hit)
+                return { paywall: withProvenance(hit, "cacheHit", contentHash), retryCount: 0 };
+        }
+        let retryCount = 0;
+        try {
+            const response = await this.fetchPaywallText(url);
+            retryCount = response.retryCount;
+            const paywall = decodePaywall(response.data);
+            if (paywall) {
+                this.bodyCache.store(url, contentHash, response.data);
+                return { paywall: withProvenance(paywall, "fetched", contentHash), retryCount };
             }
-            return { paywalls: valid, retryCount };
+            logger.error(`Paywall body from ${url} is not a decodable paywall`);
         }
-        return { paywalls, retryCount };
+        catch (error) {
+            // Note: an exhausted-failure path contributed retries we can't see from the thrown error,
+            // so retry_count under-reports failures. Acceptable for the telemetry signal.
+            logger.error(`Failed to fetch individual paywall: ${error}`);
+        }
+        const fallback = this.decodeCached(url, ttl);
+        if (fallback) {
+            logger.warn(`Serving the cached body for ${url} after fetch failure (within campaign_cache_ttl)`);
+            return { paywall: withProvenance(fallback, "cacheAfterFetchFailure", contentHash), retryCount };
+        }
+        return { retryCount };
+    }
+    /** The stored body for this exact URL, decoded; an undecodable one is deleted (not eviction). */
+    decodeCached(url, ttl) {
+        const entry = this.bodyCache.validEntry(url, ttl);
+        if (!entry)
+            return undefined;
+        const paywall = decodePaywall(entry.body);
+        if (!paywall) {
+            logger.warn(`Deleting an undecodable cached paywall body for ${url}`);
+            this.bodyCache.remove(url);
+        }
+        return paywall;
+    }
+    fetchPaywallText(url) {
+        if (storageService.getNamiConfig()?.namiCommands?.includes(exports.SIMULATE_PAYWALL_FETCH_FAILURE)) {
+            logger.warn(`${exports.SIMULATE_PAYWALL_FETCH_FAILURE}: failing the fetch for ${url} before the network`);
+            return Promise.reject(new RetryExhaustedError(url, 0));
+        }
+        return fetchTextWithCdnRetry(url);
     }
     validatePaywalls(paywalls) {
         return paywalls.filter((paywall) => {
@@ -58043,6 +58448,33 @@ class PaywallRepository {
     }
 }
 PaywallRepository.instance = new PaywallRepository();
+function decodePaywall(text) {
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function withProvenance(paywall, fetchSource, contentHash) {
+    return { ...paywall, fetchSource, ...(contentHash ? { contentHash } : {}) };
+}
+/** Every paywall URL a bundled (anonymous-format) rule names, across all of its segments. */
+function bundledPaywallUrls(campaignRules) {
+    const urls = [];
+    for (const rule of campaignRules) {
+        for (const segment of rule.segments ?? []) {
+            if (segment.paywall_url)
+                urls.push(segment.paywall_url);
+            if (segment.page_urls)
+                urls.push(...Object.values(segment.page_urls));
+            if (segment.flow?.page_urls)
+                urls.push(...Object.values(segment.flow.page_urls));
+        }
+    }
+    return urls;
+}
 
 class ConfigRepository {
     /**
@@ -61843,7 +62275,10 @@ class NamiRefs {
             }
         }
         if (initconfig?.paywalls) {
-            storageService.setPaywalls(exports.INITIAL_PAYWALLS, initconfig.paywalls);
+            storageService.setPaywalls(exports.INITIAL_PAYWALLS, initconfig.paywalls.map((paywall) => ({ ...paywall, fetchSource: "initialConfig" })));
+            if (initconfig.campaign_rules?.length) {
+                PaywallRepository.instance.seedFromInitialConfig(initconfig.campaign_rules, initconfig.paywalls);
+            }
         }
         if (initconfig?.products) {
             storageService.setProducts(exports.INITIAL_PRODUCTS, initconfig.products);
@@ -61910,7 +62345,7 @@ class NamiRefs {
         const paywallRepo = PaywallRepository.instance;
         const startTime = Date.now();
         const campaignRulesStartTime = Date.now();
-        const rawCampaigns = await campaignRepo.fetchCampaignRulesRaw();
+        const { campaigns: rawCampaigns, fromNetwork } = await campaignRepo.fetchCampaignRulesRaw();
         const campaignRulesDuration = Date.now() - campaignRulesStartTime;
         // Hydrate flow objects: fetch flow JSON from flow.url for campaigns that
         // use the URL-based format (4.0.0+ since NAM-3493) instead of inline flow.object
@@ -61931,24 +62366,35 @@ class NamiRefs {
         const useIndividual = !campaignRepo.useLegacyPaywallFetch &&
             CampaignRuleRepository.hasPaywallUrls(rawCampaigns);
         let paywalls;
-        let retryCount = 0;
+        let outcome = null;
         const paywallsStartTime = Date.now();
-        if (useIndividual) {
+        if (useIndividual && !fromNetwork) {
+            // campaign_rules came from the stored copy, so this is not a complete page set: no
+            // resolution and no eviction (api-resilience-and-caching.md § 2.2). The aggregate serves.
+            logger.info("Paywall resolution skipped: campaign_rules were served from the stored copy");
+            paywalls = getApiPaywalls();
+        }
+        else if (useIndividual) {
             const urls = CampaignRuleRepository.extractPaywallUrls(rawCampaigns);
-            const result = await paywallRepo.fetchPaywallsByUrls(urls);
-            paywalls = result.paywalls;
-            retryCount = result.retryCount;
+            outcome = await paywallRepo.resolvePaywallsByUrls(urls);
+            paywalls = outcome.paywalls;
+            paywallBodyCache.reconcile(new Set(urls));
         }
         else {
             paywalls = await paywallRepo.fetchPaywalls();
         }
         const paywallsDuration = Date.now() - paywallsStartTime;
         const totalDuration = Date.now() - startTime;
-        if (Nami.instance.maxLogging) {
-            logger.info(`Paywall fetch telemetry: strategy=${useIndividual ? "individual" : "bulk"}, ` +
-                `count=${paywalls.length}, total=${totalDuration}ms, ` +
+        if (!useIndividual || outcome) {
+            // The line every SDK emits once per resolution; the paywall-cache e2e suites parse it.
+            const cacheFields = outcome
+                ? `, urls=${outcome.urls}, hashed=${outcome.hashed}, cache_hits=${outcome.cacheHits}, ` +
+                    `fetched=${outcome.fetched}, cache_after_fetch_failure=${outcome.cacheAfterFetchFailure}, failed=${outcome.failed}`
+                : "";
+            logger.debug(`Paywall fetch telemetry: strategy=${useIndividual ? "individual" : "bulk"}, ` +
+                `count=${paywalls.length}${cacheFields}, total=${totalDuration}ms, ` +
                 `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms` +
-                `${useIndividual ? `, retry_count=${retryCount}` : ""}`);
+                `${outcome ? `, retry_count=${outcome.retryCount}` : ""}`);
         }
         return campaignRepo.finalizeCampaignRules(rawCampaigns, paywalls);
     }
@@ -62122,6 +62568,8 @@ class Nami {
     static async reset() {
         var _a;
         storageService.clearAll();
+        // The per-URL paywall body cache keeps its own prefixed keys and an in-memory index (NAM-4357).
+        paywallBodyCache.purgeAll();
         clearInMemoryAnonymousMode();
         __classPrivateFieldSet(Nami.instance, _Nami_isInitialized, false, "f");
         __classPrivateFieldGet((_a = Nami.instance), _Nami_removeForegroundListener, "f")?.call(_a);