@namiml/sdk-core 3.4.0-dev.202605190129 → 3.4.0-dev.202605190929

package/dist/index.cjs

@@ -98,7 +98,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION: exports.NAMI_SDK_VERSION = "3.4.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.0-dev.202605190129", 
+NAMI_SDK_PACKAGE_VERSION: exports.NAMI_SDK_PACKAGE_VERSION = "3.4.0-dev.202605190929", 
 // environments
 PRODUCTION: exports.PRODUCTION = "production", DEVELOPMENT: exports.DEVELOPMENT = "development", 
 // error messages
@@ -6849,7 +6849,7 @@ async function withRetry(url, options, timeout = exports.API_TIMEOUT_LIMIT, retr
         if (logTraffic && options?.body) {
             logger.debug(`[HTTP] Request body: ${options.body}`);
         }
-        const response = await timeoutRequest(url, options, timeout);
+        const response = await timeoutRequest$1(url, options, timeout);
         if (!response.ok) {
             if (logTraffic) {
                 const errorBody = await response.clone().text();
@@ -6879,7 +6879,7 @@ async function withRetry(url, options, timeout = exports.API_TIMEOUT_LIMIT, retr
     const response = await fetchWithRetry();
     return response.json();
 }
-async function timeoutRequest(url, options = {}, timeout) {
+async function timeoutRequest$1(url, options = {}, timeout) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     options["signal"] = controller.signal;
@@ -8309,6 +8309,161 @@ class ProductRepository {
 }
 ProductRepository.instance = new ProductRepository();
 
+const DEFAULTS = {
+    maxAttempts: 3,
+    baseDelayMs: 200,
+    maxDelayMs: 2000,
+    budgetMs: 5000,
+};
+const TRANSIENT_STATUSES = new Set([408, 425, 429]);
+const TRANSIENT_ERROR_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT"]);
+class NonRetryableHttpError extends Error {
+    constructor(status, url) {
+        super(`CDN fetch failed with non-retryable status ${status} for ${url}`);
+        this.name = "NonRetryableHttpError";
+        this.status = status;
+        this.url = url;
+    }
+}
+class RetryExhaustedError extends Error {
+    constructor(url, attempts, lastStatus) {
+        super(`CDN fetch exhausted ${attempts} attempts for ${url}${lastStatus !== undefined ? ` (last status ${lastStatus})` : ""}`);
+        this.name = "RetryExhaustedError";
+        this.url = url;
+        this.attempts = attempts;
+        this.lastStatus = lastStatus;
+    }
+}
+/**
+ * Classify a failure as transient (worth retrying) or not.
+ *
+ * Transient:
+ * - HTTP 408 / 425 / 429 / any 5xx (504 Gateway Timeout from the CDN edge
+ *   is the motivating production case)
+ * - AbortError from the request timeout
+ * - Any TypeError thrown by fetch — covers Safari's "Load failed",
+ *   Chrome's "Failed to fetch", Firefox's "NetworkError ...", and
+ *   CORS-blocked responses from the CDN edge (a 504 without
+ *   Access-Control-Allow-Origin surfaces as a TypeError, not a Response)
+ * - ECONNRESET/ECONNREFUSED/ENOTFOUND/ETIMEDOUT in Node test envs
+ *
+ * Non-transient: every other status (including 404 — a missing paywall is
+ * genuinely gone; retrying just delays the inevitable failure).
+ */
+function isTransientFailure(err, status) {
+    if (typeof status === "number") {
+        return TRANSIENT_STATUSES.has(status) || status >= 500;
+    }
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.name === "AbortError")
+            return true;
+        if (e.code && TRANSIENT_ERROR_CODES.has(e.code))
+            return true;
+        // fetch() throws TypeError for network-layer failures (DNS/TCP/TLS,
+        // CORS-blocked, edge dropped). HTTP status failures arrive as fulfilled
+        // responses with !response.ok — never as a thrown TypeError. So any
+        // TypeError reaching this catch is by definition transient. Don't filter
+        // on message text: Safari ("Load failed"), Chrome ("Failed to fetch"),
+        // and Firefox ("NetworkError ...") all differ, and any future variation
+        // would silently be classified non-transient.
+        if (err instanceof TypeError)
+            return true;
+    }
+    return false;
+}
+async function timeoutRequest(url, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Fetch a single CDN-hosted paywall with bounded retries on transient
+ * failures. Exponential backoff (baseDelayMs * 2^n, capped at maxDelayMs)
+ * with ±50% jitter; the whole loop is clamped to budgetMs wall-clock so
+ * the parallel-fetch window can't balloon when one edge is degraded.
+ *
+ * Throws NonRetryableHttpError for hard 4xx (including 404), or
+ * RetryExhaustedError when all attempts and/or the budget are spent.
+ */
+async function fetchWithCdnRetry(url, opts = {}) {
+    const maxAttempts = opts.maxAttempts ?? DEFAULTS.maxAttempts;
+    const baseDelayMs = opts.baseDelayMs ?? DEFAULTS.baseDelayMs;
+    const maxDelayMs = opts.maxDelayMs ?? DEFAULTS.maxDelayMs;
+    const budgetMs = opts.budgetMs ?? DEFAULTS.budgetMs;
+    const timeoutMs = opts.timeoutMs ?? exports.API_TIMEOUT_LIMIT;
+    const randomFn = opts.randomFn ?? Math.random;
+    const sleepFn = opts.sleepFn ?? defaultSleep;
+    const logRequests = shouldLogHTTPRequests();
+    const logTraffic = shouldLogHTTPTraffic();
+    const start = Date.now();
+    let attempt = 0;
+    let lastStatus;
+    let lastError;
+    while (attempt < maxAttempts) {
+        if (attempt > 0) {
+            const elapsed = Date.now() - start;
+            if (elapsed >= budgetMs)
+                break;
+            const baseDelay = Math.min(baseDelayMs * Math.pow(2, attempt - 1), maxDelayMs);
+            // ±50% jitter: random in [0,1) → factor in [-0.5, 0.5)
+            const jitter = baseDelay * (randomFn() - 0.5);
+            const remaining = Math.max(0, budgetMs - elapsed);
+            const sleepFor = Math.min(Math.max(0, baseDelay + jitter), remaining);
+            await sleepFn(sleepFor);
+            // If the sleep consumed the rest of the budget, don't fire another fetch.
+            if (Date.now() - start >= budgetMs)
+                break;
+        }
+        try {
+            if (logRequests || logTraffic) {
+                logger.debug(`[HTTP] GET ${url} (cdn attempt ${attempt + 1}/${maxAttempts})`);
+            }
+            const response = await timeoutRequest(url, timeoutMs);
+            if (!response.ok) {
+                if (logTraffic) {
+                    const errorBody = await response.clone().text();
+                    logger.debug(`[HTTP] Response ${response.status}: ${errorBody}`);
+                }
+                lastStatus = response.status;
+                if (isTransientFailure(undefined, response.status)) {
+                    attempt++;
+                    continue;
+                }
+                throw new NonRetryableHttpError(response.status, url);
+            }
+            if (logTraffic) {
+                const responseBody = await response.clone().text();
+                logger.debug(`[HTTP] Response ${response.status}: ${responseBody}`);
+            }
+            const data = (await response.json());
+            return { data, retryCount: attempt };
+        }
+        catch (err) {
+            if (err instanceof NonRetryableHttpError)
+                throw err;
+            if (isTransientFailure(err)) {
+                lastError = err;
+                attempt++;
+                continue;
+            }
+            throw err;
+        }
+    }
+    // If we exited the loop without success but never saw a transient response,
+    // fall back to surfacing the last raw error. Otherwise raise the canonical
+    // exhausted-attempts signal with the last seen status for telemetry.
+    if (lastStatus === undefined && lastError !== undefined)
+        throw lastError;
+    throw new RetryExhaustedError(url, attempt, lastStatus);
+}
+
 class PaywallRepository {
     async fetchPaywalls() {
         const authDevice = storageService.getDevice();
@@ -8359,17 +8514,22 @@ class PaywallRepository {
         return data?.results || [];
     }
     async fetchPaywallByUrl(url) {
-        return withRetry(url);
+        return fetchWithCdnRetry(url);
     }
     async fetchPaywallsByUrls(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);
+                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}`);
             }
         }
@@ -8378,9 +8538,9 @@ class PaywallRepository {
             if (valid.length > 0) {
                 storageService.setPaywalls(exports.API_PAYWALLS, valid);
             }
-            return valid;
+            return { paywalls: valid, retryCount };
         }
-        return paywalls;
+        return { paywalls, retryCount };
     }
     validatePaywalls(paywalls) {
         return paywalls.filter((paywall) => {
@@ -11856,10 +12016,13 @@ class NamiRefs {
         const useIndividual = !campaignRepo.useLegacyPaywallFetch &&
             CampaignRuleRepository.hasPaywallUrls(rawCampaigns);
         let paywalls;
+        let retryCount = 0;
         const paywallsStartTime = Date.now();
         if (useIndividual) {
             const urls = CampaignRuleRepository.extractPaywallUrls(rawCampaigns);
-            paywalls = await paywallRepo.fetchPaywallsByUrls(urls);
+            const result = await paywallRepo.fetchPaywallsByUrls(urls);
+            paywalls = result.paywalls;
+            retryCount = result.retryCount;
         }
         else {
             paywalls = await paywallRepo.fetchPaywalls();
@@ -11868,7 +12031,8 @@ class NamiRefs {
         const totalDuration = Date.now() - startTime;
         logger.info(`Paywall fetch telemetry: strategy=${useIndividual ? "individual" : "bulk"}, ` +
             `count=${paywalls.length}, total=${totalDuration}ms, ` +
-            `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms`);
+            `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms` +
+            `${useIndividual ? `, retry_count=${retryCount}` : ""}`);
         return campaignRepo.finalizeCampaignRules(rawCampaigns, paywalls);
     }
     reRenderPaywall() {

package/dist/index.d.ts

@@ -2974,13 +2974,26 @@ declare class EntitlementRepository {
     private invokeActiveEntitlementsHandler;
 }
 
+/**
+ * Result of a single per-paywall CDN fetch — carries the parsed body
+ * alongside the number of retries it took to land. Aggregated upstream
+ * by PaywallRepository.fetchPaywallsByUrls and surfaced in telemetry.
+ */
+type CdnFetchResult<T> = {
+    data: T;
+    retryCount: number;
+};
+
 declare class PaywallRepository {
     static instance: PaywallRepository;
     fetchPaywalls(): Promise<IPaywall[]>;
     private getAnonymousPaywalls;
     private getPaywalls;
-    fetchPaywallByUrl(url: string): Promise<IPaywall>;
-    fetchPaywallsByUrls(urls: string[]): Promise<IPaywall[]>;
+    fetchPaywallByUrl(url: string): Promise<CdnFetchResult<IPaywall>>;
+    fetchPaywallsByUrls(urls: string[]): Promise<{
+        paywalls: IPaywall[];
+        retryCount: number;
+    }>;
     private validatePaywalls;
     private fallbackData;
 }

package/dist/index.mjs

@@ -96,7 +96,7 @@ const {
 // version — stamped by scripts/version.sh
 NAMI_SDK_VERSION = "3.4.0", 
 // full package version including dev suffix — stamped by scripts/version.sh
-NAMI_SDK_PACKAGE_VERSION = "3.4.0-dev.202605190129", 
+NAMI_SDK_PACKAGE_VERSION = "3.4.0-dev.202605190929", 
 // environments
 PRODUCTION = "production", DEVELOPMENT = "development", 
 // error messages
@@ -6847,7 +6847,7 @@ async function withRetry(url, options, timeout = API_TIMEOUT_LIMIT, retries = AP
         if (logTraffic && options?.body) {
             logger.debug(`[HTTP] Request body: ${options.body}`);
         }
-        const response = await timeoutRequest(url, options, timeout);
+        const response = await timeoutRequest$1(url, options, timeout);
         if (!response.ok) {
             if (logTraffic) {
                 const errorBody = await response.clone().text();
@@ -6877,7 +6877,7 @@ async function withRetry(url, options, timeout = API_TIMEOUT_LIMIT, retries = AP
     const response = await fetchWithRetry();
     return response.json();
 }
-async function timeoutRequest(url, options = {}, timeout) {
+async function timeoutRequest$1(url, options = {}, timeout) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     options["signal"] = controller.signal;
@@ -8307,6 +8307,161 @@ class ProductRepository {
 }
 ProductRepository.instance = new ProductRepository();
 
+const DEFAULTS = {
+    maxAttempts: 3,
+    baseDelayMs: 200,
+    maxDelayMs: 2000,
+    budgetMs: 5000,
+};
+const TRANSIENT_STATUSES = new Set([408, 425, 429]);
+const TRANSIENT_ERROR_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT"]);
+class NonRetryableHttpError extends Error {
+    constructor(status, url) {
+        super(`CDN fetch failed with non-retryable status ${status} for ${url}`);
+        this.name = "NonRetryableHttpError";
+        this.status = status;
+        this.url = url;
+    }
+}
+class RetryExhaustedError extends Error {
+    constructor(url, attempts, lastStatus) {
+        super(`CDN fetch exhausted ${attempts} attempts for ${url}${lastStatus !== undefined ? ` (last status ${lastStatus})` : ""}`);
+        this.name = "RetryExhaustedError";
+        this.url = url;
+        this.attempts = attempts;
+        this.lastStatus = lastStatus;
+    }
+}
+/**
+ * Classify a failure as transient (worth retrying) or not.
+ *
+ * Transient:
+ * - HTTP 408 / 425 / 429 / any 5xx (504 Gateway Timeout from the CDN edge
+ *   is the motivating production case)
+ * - AbortError from the request timeout
+ * - Any TypeError thrown by fetch — covers Safari's "Load failed",
+ *   Chrome's "Failed to fetch", Firefox's "NetworkError ...", and
+ *   CORS-blocked responses from the CDN edge (a 504 without
+ *   Access-Control-Allow-Origin surfaces as a TypeError, not a Response)
+ * - ECONNRESET/ECONNREFUSED/ENOTFOUND/ETIMEDOUT in Node test envs
+ *
+ * Non-transient: every other status (including 404 — a missing paywall is
+ * genuinely gone; retrying just delays the inevitable failure).
+ */
+function isTransientFailure(err, status) {
+    if (typeof status === "number") {
+        return TRANSIENT_STATUSES.has(status) || status >= 500;
+    }
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.name === "AbortError")
+            return true;
+        if (e.code && TRANSIENT_ERROR_CODES.has(e.code))
+            return true;
+        // fetch() throws TypeError for network-layer failures (DNS/TCP/TLS,
+        // CORS-blocked, edge dropped). HTTP status failures arrive as fulfilled
+        // responses with !response.ok — never as a thrown TypeError. So any
+        // TypeError reaching this catch is by definition transient. Don't filter
+        // on message text: Safari ("Load failed"), Chrome ("Failed to fetch"),
+        // and Firefox ("NetworkError ...") all differ, and any future variation
+        // would silently be classified non-transient.
+        if (err instanceof TypeError)
+            return true;
+    }
+    return false;
+}
+async function timeoutRequest(url, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Fetch a single CDN-hosted paywall with bounded retries on transient
+ * failures. Exponential backoff (baseDelayMs * 2^n, capped at maxDelayMs)
+ * with ±50% jitter; the whole loop is clamped to budgetMs wall-clock so
+ * the parallel-fetch window can't balloon when one edge is degraded.
+ *
+ * Throws NonRetryableHttpError for hard 4xx (including 404), or
+ * RetryExhaustedError when all attempts and/or the budget are spent.
+ */
+async function fetchWithCdnRetry(url, opts = {}) {
+    const maxAttempts = opts.maxAttempts ?? DEFAULTS.maxAttempts;
+    const baseDelayMs = opts.baseDelayMs ?? DEFAULTS.baseDelayMs;
+    const maxDelayMs = opts.maxDelayMs ?? DEFAULTS.maxDelayMs;
+    const budgetMs = opts.budgetMs ?? DEFAULTS.budgetMs;
+    const timeoutMs = opts.timeoutMs ?? API_TIMEOUT_LIMIT;
+    const randomFn = opts.randomFn ?? Math.random;
+    const sleepFn = opts.sleepFn ?? defaultSleep;
+    const logRequests = shouldLogHTTPRequests();
+    const logTraffic = shouldLogHTTPTraffic();
+    const start = Date.now();
+    let attempt = 0;
+    let lastStatus;
+    let lastError;
+    while (attempt < maxAttempts) {
+        if (attempt > 0) {
+            const elapsed = Date.now() - start;
+            if (elapsed >= budgetMs)
+                break;
+            const baseDelay = Math.min(baseDelayMs * Math.pow(2, attempt - 1), maxDelayMs);
+            // ±50% jitter: random in [0,1) → factor in [-0.5, 0.5)
+            const jitter = baseDelay * (randomFn() - 0.5);
+            const remaining = Math.max(0, budgetMs - elapsed);
+            const sleepFor = Math.min(Math.max(0, baseDelay + jitter), remaining);
+            await sleepFn(sleepFor);
+            // If the sleep consumed the rest of the budget, don't fire another fetch.
+            if (Date.now() - start >= budgetMs)
+                break;
+        }
+        try {
+            if (logRequests || logTraffic) {
+                logger.debug(`[HTTP] GET ${url} (cdn attempt ${attempt + 1}/${maxAttempts})`);
+            }
+            const response = await timeoutRequest(url, timeoutMs);
+            if (!response.ok) {
+                if (logTraffic) {
+                    const errorBody = await response.clone().text();
+                    logger.debug(`[HTTP] Response ${response.status}: ${errorBody}`);
+                }
+                lastStatus = response.status;
+                if (isTransientFailure(undefined, response.status)) {
+                    attempt++;
+                    continue;
+                }
+                throw new NonRetryableHttpError(response.status, url);
+            }
+            if (logTraffic) {
+                const responseBody = await response.clone().text();
+                logger.debug(`[HTTP] Response ${response.status}: ${responseBody}`);
+            }
+            const data = (await response.json());
+            return { data, retryCount: attempt };
+        }
+        catch (err) {
+            if (err instanceof NonRetryableHttpError)
+                throw err;
+            if (isTransientFailure(err)) {
+                lastError = err;
+                attempt++;
+                continue;
+            }
+            throw err;
+        }
+    }
+    // If we exited the loop without success but never saw a transient response,
+    // fall back to surfacing the last raw error. Otherwise raise the canonical
+    // exhausted-attempts signal with the last seen status for telemetry.
+    if (lastStatus === undefined && lastError !== undefined)
+        throw lastError;
+    throw new RetryExhaustedError(url, attempt, lastStatus);
+}
+
 class PaywallRepository {
     async fetchPaywalls() {
         const authDevice = storageService.getDevice();
@@ -8357,17 +8512,22 @@ class PaywallRepository {
         return data?.results || [];
     }
     async fetchPaywallByUrl(url) {
-        return withRetry(url);
+        return fetchWithCdnRetry(url);
     }
     async fetchPaywallsByUrls(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);
+                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}`);
             }
         }
@@ -8376,9 +8536,9 @@ class PaywallRepository {
             if (valid.length > 0) {
                 storageService.setPaywalls(API_PAYWALLS, valid);
             }
-            return valid;
+            return { paywalls: valid, retryCount };
         }
-        return paywalls;
+        return { paywalls, retryCount };
     }
     validatePaywalls(paywalls) {
         return paywalls.filter((paywall) => {
@@ -11854,10 +12014,13 @@ class NamiRefs {
         const useIndividual = !campaignRepo.useLegacyPaywallFetch &&
             CampaignRuleRepository.hasPaywallUrls(rawCampaigns);
         let paywalls;
+        let retryCount = 0;
         const paywallsStartTime = Date.now();
         if (useIndividual) {
             const urls = CampaignRuleRepository.extractPaywallUrls(rawCampaigns);
-            paywalls = await paywallRepo.fetchPaywallsByUrls(urls);
+            const result = await paywallRepo.fetchPaywallsByUrls(urls);
+            paywalls = result.paywalls;
+            retryCount = result.retryCount;
         }
         else {
             paywalls = await paywallRepo.fetchPaywalls();
@@ -11866,7 +12029,8 @@ class NamiRefs {
         const totalDuration = Date.now() - startTime;
         logger.info(`Paywall fetch telemetry: strategy=${useIndividual ? "individual" : "bulk"}, ` +
             `count=${paywalls.length}, total=${totalDuration}ms, ` +
-            `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms`);
+            `campaigns=${campaignRulesDuration}ms, paywalls=${paywallsDuration}ms` +
+            `${useIndividual ? `, retry_count=${retryCount}` : ""}`);
         return campaignRepo.finalizeCampaignRules(rawCampaigns, paywalls);
     }
     reRenderPaywall() {

package/package.json

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