@aguacerowx/react-native 0.0.50 → 0.0.52

package/src/aguaceroCoreDebugHooks.js

@@ -0,0 +1,142 @@
+/**
+ * Per-core hooks for {@link AguaceroCore} when RN debug is enabled.
+ */
+import {
+    aguaceroDebug,
+    aguaceroDebugWarn,
+    getAguaceroAuthDiagnosticSnapshot,
+    isAguaceroRnDebugEnabled,
+    redactApiKeyFromUrl,
+} from './aguaceroRnDebug';
+
+const HOOK_FLAG = '__aguaceroRnDebugHooksInstalled';
+
+/**
+ * @param {import('@aguacerowx/javascript-sdk').AguaceroCore} core
+ * @param {Record<string, unknown>} [extra]
+ */
+export function installAguaceroCoreDebugHooks(core, extra = {}) {
+    if (!core || !isAguaceroRnDebugEnabled() || core[HOOK_FLAG]) {
+        return;
+    }
+    core[HOOK_FLAG] = true;
+
+    aguaceroDebug('core.created', getAguaceroAuthDiagnosticSnapshot(core, extra));
+
+    if (typeof core.initialize === 'function' && !core.__aguaceroOrigInitialize) {
+        core.__aguaceroOrigInitialize = core.initialize.bind(core);
+        core.initialize = async function aguaceroDebugInitialize(options) {
+            aguaceroDebug('core.initialize.start', {
+                stateMode: {
+                    isMRMS: core.state?.isMRMS,
+                    isSatellite: core.state?.isSatellite,
+                    isNexrad: core.state?.isNexrad,
+                    model: core.state?.model,
+                    variable: core.state?.variable,
+                },
+            });
+            try {
+                await core.__aguaceroOrigInitialize(options);
+                aguaceroDebug('core.initialize.done', {
+                    hasModelStatus: Boolean(core.modelStatus),
+                    hasMrmsStatus: Boolean(core.mrmsStatus),
+                    hasSatelliteListing: Boolean(core.satelliteListing),
+                    mrmsVariableCount: core.mrmsStatus ? Object.keys(core.mrmsStatus).length : 0,
+                });
+            } catch (err) {
+                aguaceroDebugWarn('core.initialize.error', { message: err?.message || String(err) });
+                throw err;
+            }
+        };
+    }
+
+    if (typeof core._loadGridData === 'function' && !core.__aguaceroOrigLoadGridData) {
+        core.__aguaceroOrigLoadGridData = core._loadGridData.bind(core);
+        core._loadGridData = async function aguaceroDebugLoadGridData(state) {
+            const tag = 'core._loadGridData';
+            aguaceroDebug(`${tag}.start`, {
+                isMRMS: state?.isMRMS,
+                model: state?.model,
+                variable: state?.variable,
+                mrmsTimestamp: state?.mrmsTimestamp,
+                forecastHour: state?.forecastHour,
+                auth: getAguaceroAuthDiagnosticSnapshot(core),
+            });
+            const result = await core.__aguaceroOrigLoadGridData(state);
+            if (result == null) {
+                aguaceroDebugWarn(`${tag}.null`, {
+                    hint: 'Grid load returned null — often failed fetch (check fetch.httpError above) or missing apiKey',
+                });
+            } else {
+                aguaceroDebug(`${tag}.ok`, {
+                    hasData: Boolean(result?.data),
+                    encodingKeys: result?.encoding ? Object.keys(result.encoding) : [],
+                });
+            }
+            return result;
+        };
+    }
+
+    if (typeof core.refreshNexradTimes === 'function' && !core.__aguaceroOrigRefreshNexradTimes) {
+        core.__aguaceroOrigRefreshNexradTimes = core.refreshNexradTimes.bind(core);
+        core.refreshNexradTimes = async function aguaceroDebugRefreshNexradTimes() {
+            aguaceroDebug('core.refreshNexradTimes.start', {
+                site: core.state?.nexradSite,
+                product: core.state?.nexradProduct,
+                dataSource: core.state?.nexradDataSource,
+            });
+            try {
+                const out = await core.__aguaceroOrigRefreshNexradTimes();
+                aguaceroDebug('core.refreshNexradTimes.done', {
+                    timesCount: out?.unixTimes?.length ?? 0,
+                });
+                return out;
+            } catch (err) {
+                aguaceroDebugWarn('core.refreshNexradTimes.error', { message: err?.message || String(err) });
+                throw err;
+            }
+        };
+    }
+
+    if (typeof core.setState === 'function' && !core.__aguaceroOrigSetState) {
+        core.__aguaceroOrigSetState = core.setState.bind(core);
+        core.setState = async function aguaceroDebugSetState(patch) {
+            const modeChange =
+                patch &&
+                ('isMRMS' in patch || 'isSatellite' in patch || 'isNexrad' in patch || 'variable' in patch);
+            if (modeChange) {
+                aguaceroDebug('core.setState.modePatch', {
+                    keys: Object.keys(patch || {}),
+                    patch: { ...patch, apiKey: undefined },
+                });
+            }
+            return core.__aguaceroOrigSetState(patch);
+        };
+    }
+}
+
+/**
+ * @param {import('@aguacerowx/javascript-sdk').AguaceroCore} core
+ */
+export function logProcessFrameAuthMismatch(core, options, context = {}) {
+    if (!isAguaceroRnDebugEnabled() || !core || !options) return;
+    const mismatches = [];
+    if (options.apiKey && core.apiKey && options.apiKey !== core.apiKey) {
+        mismatches.push('processFrame.apiKey !== core.apiKey');
+    }
+    if (options.bundleId !== undefined && options.bundleId !== core.bundleId) {
+        mismatches.push('processFrame.bundleId !== core.bundleId');
+    }
+    const optOrigin = options.gridRequestSiteOrigin || '';
+    const coreOrigin = core.gridRequestSiteOrigin || '';
+    if (String(optOrigin) !== String(coreOrigin)) {
+        mismatches.push('processFrame.gridRequestSiteOrigin !== core.gridRequestSiteOrigin');
+    }
+    if (mismatches.length > 0) {
+        aguaceroDebugWarn('auth.mismatch', {
+            mismatches,
+            processFrameUrl: redactApiKeyFromUrl(options.url),
+            ...context,
+        });
+    }
+}

package/src/aguaceroRnDebug.js

@@ -0,0 +1,335 @@
+/**
+ * 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';
+import { resolveGridRequestSiteOrigin } from './gridCdnAuth';
+
+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 (RN falls back to https://localhost if omitted)',
+              },
+        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 (!out.gridRequestSiteOrigin && core) {
+        const origin = resolveGridRequestSiteOrigin(undefined, core);
+        if (origin) {
+            out.gridRequestSiteOrigin = origin;
+        }
+    }
+    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/gridCdnAuth.js

@@ -0,0 +1,56 @@
+/**
+ * CloudFront grid CDN auth helpers for React Native.
+ *
+ * The CDN returns HTTP 403 when {@code Origin} is missing (even if {@code x-api-key} and
+ * {@code apiKey} query are valid). Browsers set Origin automatically; RN native HTTP does not.
+ */
+
+/** Fallback when no prop/core/global origin is configured (any origin satisfies the CDN). */
+export const RN_DEFAULT_GRID_REQUEST_SITE_ORIGIN = 'https://localhost';
+
+/**
+ * @returns {string}
+ */
+export function readGlobalGridRequestSiteOrigin() {
+    try {
+        const g = globalThis.__AGUACERO_GRID_REQUEST_SITE_ORIGIN__;
+        if (typeof g === 'string' && g.trim()) {
+            return g.trim().replace(/\/+$/, '');
+        }
+    } catch {
+        /* ignore */
+    }
+    return '';
+}
+
+/**
+ * Resolve the site origin used for {@code Origin} / {@code Referer} on grid CDN requests.
+ *
+ * @param {string | undefined | null} propOrigin - {@link WeatherLayerManager} `gridRequestSiteOrigin` prop
+ * @param {{ gridRequestSiteOrigin?: string | null; isReactNative?: boolean } | null | undefined} core
+ * @returns {string | null} Normalized origin without trailing slash, or null on web when unset
+ */
+export function resolveGridRequestSiteOrigin(propOrigin, core) {
+    const normalize = (s) => {
+        let o = String(s).trim();
+        while (o.endsWith('/')) {
+            o = o.slice(0, -1);
+        }
+        return o;
+    };
+
+    if (typeof propOrigin === 'string' && propOrigin.trim()) {
+        return normalize(propOrigin);
+    }
+    if (typeof core?.gridRequestSiteOrigin === 'string' && core.gridRequestSiteOrigin.trim()) {
+        return normalize(core.gridRequestSiteOrigin);
+    }
+    const fromGlobal = readGlobalGridRequestSiteOrigin();
+    if (fromGlobal) {
+        return fromGlobal;
+    }
+    if (core?.isReactNative) {
+        return RN_DEFAULT_GRID_REQUEST_SITE_ORIGIN;
+    }
+    return null;
+}

package/src/index.js

@@ -1,7 +1,19 @@
-export { MapManager } from './MapManager';
-export { WeatherLayerManager } from './WeatherLayerManager';
-export { default as GridRenderLayer } from './GridRenderLayerNativeComponent';
-export {
-  AGUACERO_NEXRAD_MAP_LAYER_ID,
-  AGUACERO_SATELLITE_MAP_LAYER_ID,
-} from './nws/nwsAndroidConstants';
+export { MapManager } from './MapManager';
+export { WeatherLayerManager } from './WeatherLayerManager';
+export {
+    configureAguaceroRnDebug,
+    setAguaceroRnDebugEnabled,
+    isAguaceroRnDebugEnabled,
+    getAguaceroAuthDiagnosticSnapshot,
+    aguaceroDebug,
+    aguaceroDebugWarn,
+} from './aguaceroRnDebug';
+export {
+    resolveGridRequestSiteOrigin,
+    RN_DEFAULT_GRID_REQUEST_SITE_ORIGIN,
+} from './gridCdnAuth';
+export { default as GridRenderLayer } from './GridRenderLayerNativeComponent';
+export {
+  AGUACERO_NEXRAD_MAP_LAYER_ID,
+  AGUACERO_SATELLITE_MAP_LAYER_ID,
+} from './nws/nwsAndroidConstants';