@aguacerowx/react-native 0.0.50 → 0.0.51

package/src/aguaceroRnDebug.js

@@ -0,0 +1,328 @@
+/**
+ * React Native SDK auth / HTTP diagnostics.
+ *
+ * Enable in your app (pick one):
+ *
+ * 1. **Recommended** — pass `debug={true}` on {@link WeatherLayerManager}:
+ *    ```jsx
+ *    <WeatherLayerManager apiKey={key} debug gridRequestSiteOrigin="https://your-allowed-origin.com" />
+ *    ```
+ *
+ * 2. **Global** — before rendering weather (works in release builds):
+ *    ```js
+ *    import { configureAguaceroRnDebug } from '@aguacerowx/react-native';
+ *    configureAguaceroRnDebug({ enabled: true });
+ *    ```
+ *    or: `globalThis.__AGUACERO_DEBUG__ = true` in your entry file.
+ *
+ * Logs use the prefix `[AguaceroRN][debug]` (Metro, Xcode, Logcat).
+ * API keys are never printed in full — only length, fingerprint, and whitespace hints.
+ */
+
+import { Platform } from 'react-native';
+
+const LOG_PREFIX = '[AguaceroRN][debug]';
+
+/** @type {boolean | null} */
+let _explicitEnabled = null;
+
+let _fetchLoggerInstalled = false;
+let _fetchSeq = 0;
+
+const AGUACERO_URL_MARKERS = [
+    'cloudfront.net',
+    'lambda-url.us-east-2.on.aws',
+    'amazonaws.com',
+    'noaa.gov',
+];
+
+/**
+ * @param {boolean} enabled
+ */
+export function setAguaceroRnDebugEnabled(enabled) {
+    configureAguaceroRnDebug({ enabled: Boolean(enabled) });
+}
+
+/**
+ * @param {{ enabled?: boolean }} opts
+ */
+export function configureAguaceroRnDebug(opts = {}) {
+    if (opts && typeof opts.enabled === 'boolean') {
+        _explicitEnabled = opts.enabled;
+    }
+    const on = isAguaceroRnDebugEnabled();
+    try {
+        if (typeof globalThis !== 'undefined') {
+            globalThis.__AGUACERO_DEBUG__ = on;
+            globalThis.__AGUACERO_WX_GRID_DEBUG__ = on;
+            globalThis.__AGUACERO_NEXRAD_DEBUG__ = on;
+        }
+    } catch {
+        /* ignore */
+    }
+    if (on) {
+        installGlobalFetchLogger();
+        aguaceroDebug('debug.enabled', {
+            platform: Platform.OS,
+            explicitFlag: _explicitEnabled,
+            globalFlag: safeGlobalDebugFlag(),
+        });
+    }
+}
+
+/**
+ * True when `debug={true}`, {@link configureAguaceroRnDebug}, or `globalThis.__AGUACERO_DEBUG__ === true`.
+ * @returns {boolean}
+ */
+export function isAguaceroRnDebugEnabled() {
+    if (_explicitEnabled === true) return true;
+    if (_explicitEnabled === false) {
+        try {
+            return typeof globalThis !== 'undefined' && globalThis.__AGUACERO_DEBUG__ === true;
+        } catch {
+            return false;
+        }
+    }
+    try {
+        if (typeof __DEV__ !== 'undefined' && __DEV__) return false;
+    } catch {
+        /* ignore */
+    }
+    try {
+        return typeof globalThis !== 'undefined' && globalThis.__AGUACERO_DEBUG__ === true;
+    } catch {
+        return false;
+    }
+}
+
+function safeGlobalDebugFlag() {
+    try {
+        return typeof globalThis !== 'undefined' ? globalThis.__AGUACERO_DEBUG__ === true : false;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * @param {string | null | undefined} secret
+ * @returns {Record<string, unknown>}
+ */
+export function describeSecret(secret) {
+    if (secret == null || secret === '') {
+        return { present: false, length: 0 };
+    }
+    const s = String(secret);
+    const trimmed = s.trim();
+    return {
+        present: true,
+        length: s.length,
+        trimmedLength: trimmed.length,
+        hasLeadingWhitespace: s.length > 0 && s !== trimmed && /^\s/.test(s),
+        hasTrailingWhitespace: s.length > 0 && s !== trimmed && /\s$/.test(s),
+        hasInternalWhitespace: /\s/.test(trimmed) && trimmed.indexOf(' ') >= 0,
+        fingerprint: fingerprintSecret(trimmed || s),
+        looksLikePlaceholder: /^(your[-_]?)?api[-_]?key|xxx+|test+$/i.test(trimmed),
+    };
+}
+
+/**
+ * @param {string} s
+ * @returns {string}
+ */
+export function fingerprintSecret(s) {
+    if (!s) return '(empty)';
+    if (s.length <= 8) return `len${s.length}`;
+    return `${s.slice(0, 4)}…${s.slice(-4)} (len=${s.length})`;
+}
+
+/**
+ * @param {string} u
+ * @returns {string}
+ */
+export function redactApiKeyFromUrl(u) {
+    if (!u || typeof u !== 'string') return String(u);
+    return u.replace(/([?&])apiKey=[^&]*/gi, '$1apiKey=(redacted)');
+}
+
+/**
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function shouldLogAguaceroUrl(url) {
+    if (!url || typeof url !== 'string') return false;
+    const lower = url.toLowerCase();
+    return AGUACERO_URL_MARKERS.some((m) => lower.includes(m));
+}
+
+/**
+ * @param {string} tag
+ * @param {Record<string, unknown> | undefined} detail
+ */
+export function aguaceroDebug(tag, detail) {
+    if (!isAguaceroRnDebugEnabled()) return;
+    if (detail !== undefined) {
+        console.warn(`${LOG_PREFIX}[${tag}]`, detail);
+    } else {
+        console.warn(`${LOG_PREFIX}[${tag}]`);
+    }
+}
+
+/**
+ * Auth / HTTP failures: logged when debug is on (same prefix).
+ * @param {string} tag
+ * @param {Record<string, unknown> | undefined} detail
+ */
+export function aguaceroDebugWarn(tag, detail) {
+    if (!isAguaceroRnDebugEnabled()) return;
+    if (detail !== undefined) {
+        console.warn(`${LOG_PREFIX}[WARN][${tag}]`, detail);
+    } else {
+        console.warn(`${LOG_PREFIX}[WARN][${tag}]`);
+    }
+}
+
+/**
+ * @param {import('@aguacerowx/javascript-sdk').AguaceroCore | { apiKey?: string; bundleId?: string | null; gridRequestSiteOrigin?: string | null; baseGridUrl?: string; isReactNative?: boolean }} core
+ * @param {Record<string, unknown>} [extra]
+ */
+export function getAguaceroAuthDiagnosticSnapshot(core, extra = {}) {
+    const apiKey = core?.apiKey;
+    const bundleId = core?.bundleId;
+    const origin = core?.gridRequestSiteOrigin;
+    return {
+        platform: Platform.OS,
+        isReactNative: Boolean(core?.isReactNative),
+        baseGridUrl: core?.baseGridUrl ?? null,
+        apiKey: describeSecret(apiKey),
+        bundleId: bundleId
+            ? { present: true, value: String(bundleId), length: String(bundleId).length }
+            : { present: false, hint: 'Install react-native-device-info for x-app-identifier on CDN requests' },
+        gridRequestSiteOrigin: origin
+            ? { present: true, value: String(origin), length: String(origin).length }
+            : {
+                  present: false,
+                  hint: 'Pass gridRequestSiteOrigin on WeatherLayerManager — many CloudFront rules require Origin + Referer',
+              },
+        willSendAppIdentifier: Boolean(bundleId && core?.isReactNative),
+        willSendOriginHeaders: Boolean(origin && String(origin).trim()),
+        ...extra,
+    };
+}
+
+/**
+ * @param {Record<string, unknown>} options - {@link buildGridFrameProcessOptions} output
+ * @param {import('@aguacerowx/javascript-sdk').AguaceroCore} [core]
+ * @returns {Record<string, unknown>}
+ */
+export function augmentProcessFrameOptionsForDebug(options, core) {
+    const out = { ...options };
+    if (!isAguaceroRnDebugEnabled()) {
+        return out;
+    }
+    out.debug = true;
+    aguaceroDebug('processFrame.options', {
+        url: redactApiKeyFromUrl(out.url),
+        hasApiKeyInQuery: typeof out.url === 'string' && /[?&]apiKey=/i.test(out.url),
+        apiKey: describeSecret(out.apiKey),
+        bundleId: out.bundleId ? { present: true, value: String(out.bundleId) } : { present: false },
+        gridRequestSiteOrigin: out.gridRequestSiteOrigin ?? null,
+        coreSnapshot: core ? getAguaceroAuthDiagnosticSnapshot(core) : undefined,
+    });
+    return out;
+}
+
+/**
+ * @param {string | Request} input
+ * @param {RequestInit | undefined} init
+ */
+function summarizeFetchRequest(input, init) {
+    const url = typeof input === 'string' ? input : input?.url;
+    const headers = new Headers(
+        (typeof input !== 'string' && input?.headers) || init?.headers || undefined,
+    );
+    const headerRecord = {};
+    headers.forEach((v, k) => {
+        const lk = k.toLowerCase();
+        if (lk === 'x-api-key' || lk === 'authorization') {
+            headerRecord[k] = describeSecret(v);
+        } else {
+            headerRecord[k] = v;
+        }
+    });
+    return {
+        url: redactApiKeyFromUrl(url || ''),
+        method: init?.method || (typeof input !== 'string' ? input?.method : undefined) || 'GET',
+        headers: headerRecord,
+        hasApiKeyQuery: typeof url === 'string' && /[?&]apiKey=/i.test(url),
+    };
+}
+
+/**
+ * Patches `global.fetch` once to log Aguacero CDN / API traffic when debug is enabled.
+ */
+export function installGlobalFetchLogger() {
+    if (_fetchLoggerInstalled || !isAguaceroRnDebugEnabled()) return;
+    if (typeof globalThis === 'undefined' || typeof globalThis.fetch !== 'function') return;
+
+    const originalFetch = globalThis.fetch.bind(globalThis);
+    _fetchLoggerInstalled = true;
+
+    globalThis.fetch = async function aguaceroInstrumentedFetch(input, init) {
+        const url = typeof input === 'string' ? input : input?.url;
+        const shouldLog = shouldLogAguaceroUrl(url || '');
+        const reqId = shouldLog ? `f${++_fetchSeq}` : null;
+        const started = Date.now();
+
+        if (shouldLog) {
+            aguaceroDebug('fetch.start', { reqId, ...summarizeFetchRequest(input, init) });
+        }
+
+        try {
+            const response = await originalFetch(input, init);
+            if (shouldLog) {
+                const elapsedMs = Date.now() - started;
+                const base = {
+                    reqId,
+                    status: response.status,
+                    statusText: response.statusText,
+                    ok: response.ok,
+                    elapsedMs,
+                    url: redactApiKeyFromUrl(url || ''),
+                };
+                if (!response.ok) {
+                    let bodySnippet = null;
+                    try {
+                        const clone = response.clone();
+                        const text = await clone.text();
+                        bodySnippet = text.length > 600 ? `${text.slice(0, 600)}…` : text;
+                    } catch {
+                        bodySnippet = '(could not read body)';
+                    }
+                    aguaceroDebugWarn('fetch.httpError', {
+                        ...base,
+                        bodySnippet,
+                        hint403:
+                            response.status === 403
+                                ? '403 usually means: invalid/disabled API key, bundleId not allowlisted (x-app-identifier), or missing/wrong gridRequestSiteOrigin (Origin/Referer). Compare snapshot at core.created / processFrame.options.'
+                                : undefined,
+                    });
+                } else {
+                    aguaceroDebug('fetch.ok', base);
+                }
+            }
+            return response;
+        } catch (err) {
+            if (shouldLog) {
+                aguaceroDebugWarn('fetch.throw', {
+                    reqId,
+                    message: err?.message || String(err),
+                    elapsedMs: Date.now() - started,
+                    url: redactApiKeyFromUrl(url || ''),
+                });
+            }
+            throw err;
+        }
+    };
+
+    aguaceroDebug('fetch.hookInstalled', { platform: Platform.OS });
+}

package/src/index.js

@@ -1,5 +1,13 @@
 export { MapManager } from './MapManager';
 export { WeatherLayerManager } from './WeatherLayerManager';
+export {
+    configureAguaceroRnDebug,
+    setAguaceroRnDebugEnabled,
+    isAguaceroRnDebugEnabled,
+    getAguaceroAuthDiagnosticSnapshot,
+    aguaceroDebug,
+    aguaceroDebugWarn,
+} from './aguaceroRnDebug';
 export { default as GridRenderLayer } from './GridRenderLayerNativeComponent';
 export {
   AGUACERO_NEXRAD_MAP_LAYER_ID,

package/src/nexrad/nexradAndroidController.js

@@ -18,6 +18,7 @@ import { sampleNexradFrameAtLatLon } from './nexradCrossSectionSampleAtLatLon.bu
 import { buildNexradLutRgba } from './nexradLutBuild.js';
 import { Platform } from 'react-native';
 import { nexradDiagBootSnapshot, nexradDiagGateTextureSummary, nexradPerfSpan } from './nexradDiag.js';
+import { aguaceroDebug, getAguaceroAuthDiagnosticSnapshot, isAguaceroRnDebugEnabled } from '../aguaceroRnDebug';
 
 nexradDiagBootSnapshot({
     archiveExports: {
@@ -258,6 +259,9 @@ export class NexradAndroidController {
             setNexradSitesFetchAuth(core.apiKey || '', core.bundleId || '');
         }
         setNexradArchiveSiteOrigin(core.gridRequestSiteOrigin || '');
+        if (isAguaceroRnDebugEnabled()) {
+            aguaceroDebug('nexrad.authConfigured', getAguaceroAuthDiagnosticSnapshot(core, { phase: 'NexradAndroidController.constructor' }));
+        }
     }
 
     _trimNativeGpuReadyKeys(max) {
@@ -739,7 +743,13 @@ export class NexradAndroidController {
         setNexradArchiveBundleId(this.core.bundleId || '');
         setNexradArchiveSiteOrigin(this.core.gridRequestSiteOrigin || '');
         setNexradSitesFetchAuth(this.core.apiKey || '', this.core.bundleId || '');
-
+        if (isAguaceroRnDebugEnabled()) {
+            aguaceroDebug('nexrad.authConfigured', getAguaceroAuthDiagnosticSnapshot(this.core, {
+                phase: 'NexradAndroidController.preload',
+                site: state.nexradSite,
+                product: state.nexradProduct,
+            }));
+        }
 
         const snapshot = { ...state };
         const preloadBatch = nexradPerfSpan(`preload.batch site=${state.nexradSite} times=${times.length}`);

package/src/nexrad/nexradDiag.js

@@ -8,7 +8,13 @@
  */
 
 export function nexradDiagEnabled() {
-    return typeof globalThis !== 'undefined' && globalThis.__AGUACERO_NEXRAD_DEBUG === true;
+    if (typeof globalThis !== 'undefined' && globalThis.__AGUACERO_NEXRAD_DEBUG === true) {
+        return true;
+    }
+    if (typeof globalThis !== 'undefined' && globalThis.__AGUACERO_DEBUG__ === true) {
+        return true;
+    }
+    return false;
 }
 
 /**

package/src/satellite/satelliteAndroidController.js

@@ -4,6 +4,7 @@
  */
 import { resolveSatelliteS3FileName } from '@aguacerowx/javascript-sdk';
 import { satBridgeWarn } from '../satelliteBridgeDiag';
+import { aguaceroDebug, getAguaceroAuthDiagnosticSnapshot, isAguaceroRnDebugEnabled, redactApiKeyFromUrl } from '../aguaceroRnDebug';
 
 /**
  * Target frame first, then remaining frames by increasing temporal distance to {@code targetUnix}.
@@ -181,6 +182,14 @@ export class SatelliteAndroidController {
         const timelineChanged = timelineSig !== this._cachedTimelineSig;
 
         if (runKeyChanged || timelineChanged) {
+            if (isAguaceroRnDebugEnabled()) {
+                aguaceroDebug('satellite.sync.payload', {
+                    auth: getAguaceroAuthDiagnosticSnapshot(this.core),
+                    frameCount: frames.length,
+                    sampleFrameUrl: frames[0] ? redactApiKeyFromUrl(frames[0].url) : null,
+                    gridRequestSiteOrigin: mergedState.gridRequestSiteOrigin ?? this.core.gridRequestSiteOrigin ?? null,
+                });
+            }
             const sortedFrames = sortFramesByTargetProximity(frames, targetUnix);
             const payload = {
                 runKey: satRunKey,