@namiml/sdk-core 3.5.0-dev.202610272352 → 3.5.0-dev.202610311618

package/dist/index.cjs

@@ -106,7 +106,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.5.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202610272352", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202610311618", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -3110,7 +3110,11 @@ class PaywallBodyCache {
         if (ttl === null)
             return;
         const expired = [...this.loadIndex().values()].filter((meta) => isExpired(meta, ttl, now));
+        if (expired.length === 0)
+            return;
         this.dropPersisted(expired.map((meta) => meta.url));
+        const oldestAge = ageSeconds(Math.min(...expired.map((meta) => meta.savedAt)), now);
+        logger.debug(`Paywall body cache: evicted ${expired.length} expired entries (campaign_cache_ttl=${ttl}s, oldest_age=${oldestAge}s)`);
     }
     /**
      * The entry stored under this exact URL, or null when there is none, it is past `ttl`, or its
@@ -3124,6 +3128,7 @@ class PaywallBodyCache {
             return null;
         if (ttl !== null && ttl > 0 && isExpired(meta, ttl, now)) {
             this.dropPersisted([url]);
+            logger.debug(`Paywall body cache: evicted expired entry on read (campaign_cache_ttl=${ttl}s, age=${ageSeconds(meta.savedAt, now)}s): ${url}`);
             return null;
         }
         const body = this.read(PAYWALL_BODY_KEY_PREFIX + url);
@@ -3168,6 +3173,30 @@ class PaywallBodyCache {
         const exists = this.memory ? this.memory.has(url) : this.loadIndex().has(url);
         return exists ? false : this.store(url, contentHash, body, now);
     }
+    /**
+     * Restarts the TTL window of a resolution's `content_hash` hits: the latest `campaign_rules` still
+     * names each exact URL, and a `content_hash` is a pure function of the body, so the stored body is
+     * still the current one. Rewrites only the metadata key (the body is untouched) and skips absent
+     * entries. A renew that does not land keeps the old `savedAt`, which is harmless. Nothing is
+     * renewed under `null` (never ages) or `0` (memory only). Returns the number of entries renewed.
+     */
+    renew(urls, ttl, now = Date.now()) {
+        if (ttl === null || ttl <= 0 || this.memory)
+            return 0;
+        const index = this.loadIndex();
+        let renewed = 0;
+        for (const url of urls) {
+            const meta = index.get(url);
+            if (!meta)
+                continue;
+            const fresh = { ...meta, savedAt: now };
+            if (this.write(PAYWALL_BODY_META_KEY_PREFIX + url, JSON.stringify(fresh))) {
+                index.set(url, fresh);
+                renewed += 1;
+            }
+        }
+        return renewed;
+    }
     /** Deletes one entry — used for an undecodable body. Not eviction. */
     remove(url) {
         if (this.memory)
@@ -3186,7 +3215,11 @@ class PaywallBodyCache {
         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);
+        if (unnamed.length === 0 && overCap.length === 0)
+            return;
         [...unnamed, ...overCap].forEach((url) => this.remove(url));
+        logger.debug(`Paywall body cache: evicted ${unnamed.length} entries no longer named by campaign_rules, ` +
+            `${overCap.length} over the ${this.maxEntries}-entry cap`);
     }
     /** Empties the store — persisted and in-memory entries alike. Called by `Nami.reset()`. */
     purgeAll() {
@@ -3259,6 +3292,10 @@ class PaywallBodyCache {
 function isExpired(meta, ttlSeconds, now) {
     return (now - meta.savedAt) / 1000 >= ttlSeconds;
 }
+/** Whole seconds since `savedAt` (epoch ms), as the cross-SDK eviction logs print it. */
+function ageSeconds(savedAt, now) {
+    return Math.floor((now - savedAt) / 1000);
+}
 function parseMeta(raw) {
     if (raw === null)
         return null;
@@ -58362,6 +58399,7 @@ class PaywallRepository {
             cacheAfterFetchFailure: 0,
             failed: 0,
             retryCount: 0,
+            renewableUrls: [],
         };
         const resolvedUrls = new Map();
         resolutions.forEach((resolution, i) => {
@@ -58371,8 +58409,11 @@ class PaywallRepository {
                 return;
             }
             resolvedUrls.set(resolution.paywall, uniqueUrls[i]);
-            if (resolution.paywall.fetchSource === "cacheHit")
+            if (resolution.paywall.fetchSource === "cacheHit") {
                 outcome.cacheHits += 1;
+                if (contentHashOf(uniqueUrls[i]))
+                    outcome.renewableUrls.push(uniqueUrls[i]);
+            }
             else if (resolution.paywall.fetchSource === "cacheAfterFetchFailure")
                 outcome.cacheAfterFetchFailure += 1;
             else
@@ -58384,6 +58425,16 @@ class PaywallRepository {
         }
         return outcome;
     }
+    /**
+     * Sliding expiry (§ 2.2 → TTL): under `campaign_cache_ttl > 0`, renews the `savedAt` of every
+     * `content_hash` hit in one batch, so an entry expires only once no resolution has named it for a
+     * full TTL. Un-hashed URLs never renew — nothing vouches that their stored body is current. The
+     * caller runs this after reconcile, and only after a resolution that ran on `campaign_rules` from
+     * the network, so a stale stored copy of the rules can never keep entries alive.
+     */
+    renewCacheHits(outcome) {
+        this.bodyCache.renew(outcome.renewableUrls, getCampaignCacheTtl());
+    }
     /**
      * 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
@@ -62675,6 +62726,10 @@ class NamiRefs {
                 `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms` +
                 `${outcome ? `, retry_count=${outcome.retryCount}` : ""}`);
         }
+        // After reconcile and the telemetry line, in one batch. `outcome` is set only when the rules
+        // came from the network, so a stored copy of them never renews an entry.
+        if (outcome)
+            paywallRepo.renewCacheHits(outcome);
         return campaignRepo.finalizeCampaignRules(rawCampaigns, paywalls);
     }
     reRenderPaywall() {

package/dist/index.d.ts

@@ -3862,12 +3862,15 @@ declare class EntitlementRepository {
  * 2026-09-28, NFL Web Prod's largest set is 66 bodies / 2.1 MB, well inside localStorage's ~5 MB;
  * a second copy beside an aggregate would have doubled that. Under `campaign_cache_ttl == 0`
  * entries are held in memory instead. Every storage failure degrades to "not cached".
+ *
+ * Cache hits on `content_hash` URLs renew their entries (`renew`), so an entry expires only once
+ * no resolution has named it for a full TTL (sliding expiry, NAM-5368). Every eviction is logged.
  */
 type PaywallBodyMeta = {
     url: string;
     /** The URL's `content_hash`, absent for an un-hashed URL. */
     contentHash?: string;
-    /** Epoch milliseconds at which this entry was stored. */
+    /** Epoch milliseconds at which this entry was stored, or last renewed by a cache hit. */
     savedAt: number;
 };
 type PaywallBodyEntry = {
@@ -3904,6 +3907,14 @@ declare class PaywallBodyCache {
     store(url: string, contentHash: string | undefined, body: string, now?: number): boolean;
     /** Stores a bundled body unless an entry already exists — a body the SDK fetched always wins. */
     seedIfAbsent(url: string, contentHash: string | undefined, body: string, now?: number): boolean;
+    /**
+     * Restarts the TTL window of a resolution's `content_hash` hits: the latest `campaign_rules` still
+     * names each exact URL, and a `content_hash` is a pure function of the body, so the stored body is
+     * still the current one. Rewrites only the metadata key (the body is untouched) and skips absent
+     * entries. A renew that does not land keeps the old `savedAt`, which is harmless. Nothing is
+     * renewed under `null` (never ages) or `0` (memory only). Returns the number of entries renewed.
+     */
+    renew(urls: string[], ttl: number | null, now?: number): number;
     /** Deletes one entry — used for an undecodable body. Not eviction. */
     remove(url: string): void;
     /**
@@ -3933,6 +3944,8 @@ type PaywallResolutionOutcome = {
     cacheAfterFetchFailure: number;
     failed: number;
     retryCount: number;
+    /** Hit-row URLs that carry a `content_hash`: the entries `renewCacheHits` renews. */
+    renewableUrls: string[];
 };
 declare class PaywallRepository {
     private readonly bodyCache;
@@ -3959,6 +3972,14 @@ declare class PaywallRepository {
      * after a complete `campaign_rules` fetch.
      */
     resolvePaywallsByUrls(urls: string[]): Promise<PaywallResolutionOutcome>;
+    /**
+     * Sliding expiry (§ 2.2 → TTL): under `campaign_cache_ttl > 0`, renews the `savedAt` of every
+     * `content_hash` hit in one batch, so an entry expires only once no resolution has named it for a
+     * full TTL. Un-hashed URLs never renew — nothing vouches that their stored body is current. The
+     * caller runs this after reconcile, and only after a resolution that ran on `campaign_rules` from
+     * the network, so a stale stored copy of the rules can never keep entries alive.
+     */
+    renewCacheHits(outcome: PaywallResolutionOutcome): void;
     /**
      * 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

package/dist/index.mjs

@@ -104,7 +104,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION = "3.5.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202610272352", 
+NAMI_SDK_PACKAGE_VERSION = "3.5.0-dev.202610311618", 
 // environments
 PRODUCTION = "production", DEVELOPMENT = "development", 
 // error messages
@@ -3108,7 +3108,11 @@ class PaywallBodyCache {
         if (ttl === null)
             return;
         const expired = [...this.loadIndex().values()].filter((meta) => isExpired(meta, ttl, now));
+        if (expired.length === 0)
+            return;
         this.dropPersisted(expired.map((meta) => meta.url));
+        const oldestAge = ageSeconds(Math.min(...expired.map((meta) => meta.savedAt)), now);
+        logger.debug(`Paywall body cache: evicted ${expired.length} expired entries (campaign_cache_ttl=${ttl}s, oldest_age=${oldestAge}s)`);
     }
     /**
      * The entry stored under this exact URL, or null when there is none, it is past `ttl`, or its
@@ -3122,6 +3126,7 @@ class PaywallBodyCache {
             return null;
         if (ttl !== null && ttl > 0 && isExpired(meta, ttl, now)) {
             this.dropPersisted([url]);
+            logger.debug(`Paywall body cache: evicted expired entry on read (campaign_cache_ttl=${ttl}s, age=${ageSeconds(meta.savedAt, now)}s): ${url}`);
             return null;
         }
         const body = this.read(PAYWALL_BODY_KEY_PREFIX + url);
@@ -3166,6 +3171,30 @@ class PaywallBodyCache {
         const exists = this.memory ? this.memory.has(url) : this.loadIndex().has(url);
         return exists ? false : this.store(url, contentHash, body, now);
     }
+    /**
+     * Restarts the TTL window of a resolution's `content_hash` hits: the latest `campaign_rules` still
+     * names each exact URL, and a `content_hash` is a pure function of the body, so the stored body is
+     * still the current one. Rewrites only the metadata key (the body is untouched) and skips absent
+     * entries. A renew that does not land keeps the old `savedAt`, which is harmless. Nothing is
+     * renewed under `null` (never ages) or `0` (memory only). Returns the number of entries renewed.
+     */
+    renew(urls, ttl, now = Date.now()) {
+        if (ttl === null || ttl <= 0 || this.memory)
+            return 0;
+        const index = this.loadIndex();
+        let renewed = 0;
+        for (const url of urls) {
+            const meta = index.get(url);
+            if (!meta)
+                continue;
+            const fresh = { ...meta, savedAt: now };
+            if (this.write(PAYWALL_BODY_META_KEY_PREFIX + url, JSON.stringify(fresh))) {
+                index.set(url, fresh);
+                renewed += 1;
+            }
+        }
+        return renewed;
+    }
     /** Deletes one entry — used for an undecodable body. Not eviction. */
     remove(url) {
         if (this.memory)
@@ -3184,7 +3213,11 @@ class PaywallBodyCache {
         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);
+        if (unnamed.length === 0 && overCap.length === 0)
+            return;
         [...unnamed, ...overCap].forEach((url) => this.remove(url));
+        logger.debug(`Paywall body cache: evicted ${unnamed.length} entries no longer named by campaign_rules, ` +
+            `${overCap.length} over the ${this.maxEntries}-entry cap`);
     }
     /** Empties the store — persisted and in-memory entries alike. Called by `Nami.reset()`. */
     purgeAll() {
@@ -3257,6 +3290,10 @@ class PaywallBodyCache {
 function isExpired(meta, ttlSeconds, now) {
     return (now - meta.savedAt) / 1000 >= ttlSeconds;
 }
+/** Whole seconds since `savedAt` (epoch ms), as the cross-SDK eviction logs print it. */
+function ageSeconds(savedAt, now) {
+    return Math.floor((now - savedAt) / 1000);
+}
 function parseMeta(raw) {
     if (raw === null)
         return null;
@@ -58360,6 +58397,7 @@ class PaywallRepository {
             cacheAfterFetchFailure: 0,
             failed: 0,
             retryCount: 0,
+            renewableUrls: [],
         };
         const resolvedUrls = new Map();
         resolutions.forEach((resolution, i) => {
@@ -58369,8 +58407,11 @@ class PaywallRepository {
                 return;
             }
             resolvedUrls.set(resolution.paywall, uniqueUrls[i]);
-            if (resolution.paywall.fetchSource === "cacheHit")
+            if (resolution.paywall.fetchSource === "cacheHit") {
                 outcome.cacheHits += 1;
+                if (contentHashOf(uniqueUrls[i]))
+                    outcome.renewableUrls.push(uniqueUrls[i]);
+            }
             else if (resolution.paywall.fetchSource === "cacheAfterFetchFailure")
                 outcome.cacheAfterFetchFailure += 1;
             else
@@ -58382,6 +58423,16 @@ class PaywallRepository {
         }
         return outcome;
     }
+    /**
+     * Sliding expiry (§ 2.2 → TTL): under `campaign_cache_ttl > 0`, renews the `savedAt` of every
+     * `content_hash` hit in one batch, so an entry expires only once no resolution has named it for a
+     * full TTL. Un-hashed URLs never renew — nothing vouches that their stored body is current. The
+     * caller runs this after reconcile, and only after a resolution that ran on `campaign_rules` from
+     * the network, so a stale stored copy of the rules can never keep entries alive.
+     */
+    renewCacheHits(outcome) {
+        this.bodyCache.renew(outcome.renewableUrls, getCampaignCacheTtl());
+    }
     /**
      * 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
@@ -62673,6 +62724,10 @@ class NamiRefs {
                 `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms` +
                 `${outcome ? `, retry_count=${outcome.retryCount}` : ""}`);
         }
+        // After reconcile and the telemetry line, in one batch. `outcome` is set only when the rules
+        // came from the network, so a stored copy of them never renews an entry.
+        if (outcome)
+            paywallRepo.renewCacheHits(outcome);
         return campaignRepo.finalizeCampaignRules(rawCampaigns, paywalls);
     }
     reRenderPaywall() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namiml/sdk-core",
-  "version": "3.5.0-dev.202610272352",
+  "version": "3.5.0-dev.202610311618",
   "description": "Platform-agnostic core for the Nami SDK — business logic, API, types, and state management",
   "type": "module",
   "main": "./dist/index.cjs",