ropegeo-common 1.12.10 → 1.12.12

package/README.md

@@ -312,9 +312,9 @@ Abstract classes live under `minimap/abstract/`, concrete under `minimap/concret
 
 | Name | Description | Import |
 | --- | --- | --- |
-| `RopeGeoHttpRequest` | Single GET/POST wrapper; parses `Result.fromResponseBody`; optional `timeoutAfterSeconds` (default from helpers) + `timeoutCountdown` children arg. | `import { RopeGeoHttpRequest, Method, Service } from 'ropegeo-common/components'` |
-| `RopeGeoCursorPaginationHttpRequest` | Cursor-paginated fetch with `loadMore`; optional `timeoutAfterSeconds`; `timeoutCountdown` on initial and `loadMore` requests. | `import { RopeGeoCursorPaginationHttpRequest } from 'ropegeo-common/components'` |
-| `RopeGeoPaginationHttpRequest<T>` | Page-based fetch; page 1 emits `timeoutCountdown`; later pages use the same per-fetch deadline; concatenates `results` into `data` (`T[]` when complete, otherwise `null` with `errors`). | `import { RopeGeoPaginationHttpRequest } from 'ropegeo-common/components'` |
+| `RopeGeoHttpRequest` | Single GET/POST wrapper; parses `Result.fromResponseBody`; optional `timeoutAfterSeconds`, `isOnline`, `refreshOnReconnect`, `timeoutCountdown`, and `refreshing` (stale-while-revalidate) children args. | `import { RopeGeoHttpRequest, Method, Service } from 'ropegeo-common/components'` |
+| `RopeGeoCursorPaginationHttpRequest` | Cursor-paginated fetch with `loadMore`; `data` is `T[] \| null` (null until first success); optional `timeoutAfterSeconds`, `isOnline`, `refreshOnReconnect`, `refreshing`, `timeoutCountdown`. | `import { RopeGeoCursorPaginationHttpRequest } from 'ropegeo-common/components'` |
+| `RopeGeoPaginationHttpRequest<T>` | Page-based fetch; concatenates `results` into `data` (`T[]` when complete, otherwise `null` with `errors`); optional `isOnline`, `refreshOnReconnect`, `refreshing`, `timeoutCountdown`. | `import { RopeGeoPaginationHttpRequest } from 'ropegeo-common/components'` |
 
 ---
 

package/dist/components/RopeGeoCursorPaginationHttpRequest.d.ts

@@ -14,23 +14,37 @@ export type RopeGeoCursorPaginationHttpRequestProps<T = unknown> = {
     timeoutAfterSeconds?: number;
     /**
      * When `false`, no HTTP requests run and children receive {@link NO_NETWORK_MESSAGE} as the error.
-     * Previously loaded `data` and cursor `params` are kept until the network returns (same stale
-     * behavior as {@link RopeGeoPaginationHttpRequest} / {@link RopeGeoHttpRequest} when offline).
+     * Previously loaded `data` and cursor `params` are kept until the network returns.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     /**
      * Response body is parsed via CursorPaginationResults.fromResponseBody (must include resultType).
      * Parsed shape is ValidatedCursorPaginationResponse; children receive result.results as data.
+     * `data` is `null` until the first successful response for the current request identity, then an
+     * array (possibly empty) for loaded pages.
      */
     children: (args: {
         loading: boolean;
         loadingMore: boolean;
-        data: T[];
+        /**
+         * `true` while the initial request is in flight after at least one successful response for the
+         * current request identity (stale-while-revalidate). Not used for `loadMore` alone.
+         */
+        refreshing: boolean;
+        data: T[] | null;
         errors: Error | null;
         loadMore: () => void;
         hasMore: boolean;
         timeoutCountdown: number | null;
     }) => ReactNode;
 };
-export declare function RopeGeoCursorPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, children, }: RopeGeoCursorPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoCursorPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoCursorPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoCursorPaginationHttpRequest.d.ts.map

package/dist/components/RopeGeoCursorPaginationHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoCursorPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoCursorPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AASvC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AAsCzE,MAAM,MAAM,uCAAuC,CAAC,CAAC,GAAG,OAAO,IAAI;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,OAAO,CAAC;QACrB,IAAI,EAAE,CAAC,EAAE,CAAC;QACV,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kCAAkC,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9D,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,uCAAuC,CAAC,CAAC,CAAC,2CAsQ5C"}
+{"version":3,"file":"RopeGeoCursorPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoCursorPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AAsCzE,MAAM,MAAM,uCAAuC,CAAC,CAAC,GAAG,OAAO,IAAI;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,OAAO,CAAC;QACrB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kCAAkC,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9D,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,uCAAuC,CAAC,CAAC,CAAC,2CAqV5C"}

package/dist/components/RopeGeoCursorPaginationHttpRequest.js

@@ -30,16 +30,26 @@ function getResponseBody(raw) {
     }
     return raw;
 }
-function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [loadingMore, setLoadingMore] = (0, react_1.useState)(false);
-    const [data, setData] = (0, react_1.useState)([]);
+    const [data, setData] = (0, react_1.useState)(null);
     const [params, setParams] = (0, react_1.useState)(queryParams);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const loadingMoreRef = (0, react_1.useRef)(false);
     const loadMoreAbortRef = (0, react_1.useRef)(null);
     const hasMore = params.cursor != null;
+    const pathParamsKey = JSON.stringify(pathParams ?? null);
+    const queryKey = queryParams.toQueryString();
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryKey}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryKey, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     const buildUrl = (0, react_1.useCallback)((p) => {
         const baseUrl = RopeGeoHttpRequest_1.SERVICE_BASE_URL[service];
         const resolvedPath = resolvePath(path, pathParams);
@@ -48,26 +58,61 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
         return new URL(fullPath, baseUrl).toString();
     }, [service, path, pathParams]);
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setData(null);
+                setHasCommittedOnce(false);
+                setParams(queryParams);
+                setErrors(null);
+            }
             loadMoreAbortRef.current?.abort();
             loadMoreAbortRef.current = null;
             loadingMoreRef.current = false;
             setLoadingMore(false);
+            prevIsOnlineRef.current = false;
             setLoading(false);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setData(null);
+            setParams(queryParams);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const timedOutRef = { current: false };
         const requestStartedAt = Date.now();
         const timeoutMs = (0, network_1.resolveRequestTimeoutMs)(timeoutAfterSeconds);
-        setData([]);
-        setParams(queryParams);
         setLoading(true);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setData(null);
+            setParams(queryParams);
+        }
         const policyDispose = timeoutMs == null
             ? () => { }
             : (0, network_1.installNetworkRequestPolicyTimers)(requestStartedAt, timeoutMs, {
@@ -97,12 +142,16 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 return;
             const text = await res.text();
             if (!res.ok) {
-                setErrors(new Error(`HTTP ${res.status}: ${text || res.statusText}`));
-                setData([]);
+                setErrors(new Error((0, network_1.formatHttpStatusMessage)(res.status, text || res.statusText)));
+                setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if (text.length === 0) {
                 setData([]);
+                setParams(queryParams.withCursor(null));
+                setErrors(null);
+                setHasCommittedOnce(true);
                 return;
             }
             try {
@@ -115,6 +164,7 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 setData(results);
                 setParams(queryParams.withCursor(nextCursor));
                 setErrors(null);
+                setHasCommittedOnce(true);
             }
             catch (parseError) {
                 if (!cancelled) {
@@ -125,7 +175,8 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                         parseError: parseError instanceof Error ? parseError.message : String(parseError),
                     });
                     setErrors(new Error("Invalid JSON response"));
-                    setData([]);
+                    setData(null);
+                    setHasCommittedOnce(false);
                 }
             }
         })
@@ -133,8 +184,9 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
             if (cancelled)
                 return;
             if (timedOutRef.current) {
-                setErrors(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE));
-                setData([]);
+                setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE))));
+                setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if ((0, network_1.isAbortError)(err))
@@ -143,8 +195,9 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 url,
                 error: err instanceof Error ? err.message : String(err),
             });
-            setErrors(err instanceof Error ? err : new Error(String(err)));
-            setData([]);
+            setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(err)));
+            setData(null);
+            setHasCommittedOnce(false);
         })
             .finally(() => {
             policyDispose();
@@ -162,11 +215,13 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
         service,
         method,
         path,
-        pathParams,
-        queryParams,
+        pathParamsKey,
+        queryKey,
         buildUrl,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
     (0, react_1.useEffect)(() => {
         return () => {
@@ -224,7 +279,7 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 const body = getResponseBody(raw);
                 const result = models_1.CursorPaginationResults.fromResponseBody(body);
                 const { results, nextCursor } = result;
-                setData((prev) => [...prev, ...results]);
+                setData((prev) => [...(prev ?? []), ...results]);
                 setParams((p) => p.withCursor(nextCursor));
             }
             catch (parseError) {
@@ -260,9 +315,11 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
             setLoadingMore(false);
         });
     }, [params, method, buildUrl, timeoutAfterSeconds, isOnline]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
             loadingMore,
+            refreshing,
             data,
             errors,
             loadMore,

package/dist/components/RopeGeoHttpRequest.d.ts

@@ -29,12 +29,25 @@ export type RopeGeoHttpRequestProps<T = unknown> = {
      * not fired while offline.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     /**
      * Response body is parsed via Result.fromResponseBody (must include resultType and result).
      * Children receive the validated result.result as data (typed by T).
      */
     children: (args: {
         loading: boolean;
+        /**
+         * `true` while a request is in flight after at least one successful response for the current
+         * request identity (stale-while-revalidate).
+         */
+        refreshing: boolean;
         data: T | null;
         errors: Error | null;
         /**
@@ -45,5 +58,5 @@ export type RopeGeoHttpRequestProps<T = unknown> = {
         timeoutCountdown: number | null;
     }) => ReactNode;
 };
-export declare function RopeGeoHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, children, }: RopeGeoHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoHttpRequest.d.ts.map

package/dist/components/RopeGeoHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAmCF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;;WAIG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9C,OAAO,EACP,MAAM,EACN,IAAI,EACJ,UAAU,EACV,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,uBAAuB,CAAC,CAAC,CAAC,2CAwJ5B"}
+{"version":3,"file":"RopeGeoHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAmCF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;;WAIG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9C,OAAO,EACP,MAAM,EACN,IAAI,EACJ,UAAU,EACV,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,uBAAuB,CAAC,CAAC,CAAC,2CAkO5B"}

package/dist/components/RopeGeoHttpRequest.js

@@ -40,11 +40,16 @@ function buildUrl(baseUrl, path, pathParams, queryParams) {
     }
     return url.toString();
 }
-function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [data, setData] = (0, react_1.useState)(null);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const pathParamsKey = JSON.stringify(pathParams ?? null);
     const queryParamsKey = JSON.stringify(queryParams ?? null);
     const bodyKey = body === undefined || body === null
@@ -52,13 +57,43 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         : typeof body === "object"
             ? JSON.stringify(body)
             : body;
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryParamsKey}|${String(bodyKey)}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryParamsKey, bodyKey, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setData(null);
+                setHasCommittedOnce(false);
+                setErrors(null);
+            }
+            prevIsOnlineRef.current = false;
             setLoading(false);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setData(null);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const timedOutRef = { current: false };
@@ -67,6 +102,13 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         setLoading(true);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setData(null);
+        }
         const policyDispose = timeoutMs == null
             ? () => { }
             : (0, network_1.installNetworkRequestPolicyTimers)(requestStartedAt, timeoutMs, {
@@ -102,12 +144,15 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 return;
             const text = await res.text();
             if (!res.ok) {
-                setErrors(new Error(`HTTP ${res.status}: ${text || res.statusText}`));
+                setErrors(new Error((0, network_1.formatHttpStatusMessage)(res.status, text || res.statusText)));
                 setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if (text.length === 0) {
                 setData(null);
+                setErrors(null);
+                setHasCommittedOnce(true);
                 return;
             }
             try {
@@ -116,6 +161,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 if (!cancelled) {
                     setData(parsed.result);
                     setErrors(null);
+                    setHasCommittedOnce(true);
                 }
             }
             catch (parseError) {
@@ -128,6 +174,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                     });
                     setErrors(parseError instanceof Error ? parseError : new Error("Invalid JSON response"));
                     setData(null);
+                    setHasCommittedOnce(false);
                 }
             }
         })
@@ -135,8 +182,9 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (cancelled)
                 return;
             if (timedOutRef.current) {
-                setErrors(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE));
+                setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE))));
                 setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if ((0, network_1.isAbortError)(err))
@@ -145,8 +193,9 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 url,
                 error: err instanceof Error ? err.message : String(err),
             });
-            setErrors(err instanceof Error ? err : new Error(String(err)));
+            setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(err)));
             setData(null);
+            setHasCommittedOnce(false);
         })
             .finally(() => {
             policyDispose();
@@ -169,9 +218,13 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         bodyKey,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
+            refreshing,
             data,
             errors,
             timeoutCountdown,

package/dist/components/RopeGeoPaginationHttpRequest.d.ts

@@ -25,8 +25,21 @@ export type RopeGeoPaginationHttpRequestProps<T = unknown> = {
      * {@link RopeGeoCursorPaginationHttpRequest}.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     children: (args: {
         loading: boolean;
+        /**
+         * `true` while a full pagination pass is in flight after at least one successful completion for
+         * the current request identity (stale-while-revalidate).
+         */
+        refreshing: boolean;
         received: number;
         total: number | null;
         /**
@@ -46,5 +59,5 @@ export type RopeGeoPaginationHttpRequestProps<T = unknown> = {
  * {@link PaginationResults.fromResponseBody}. Final `data` is pages concatenated in page order.
  * In-flight requests use one {@link AbortController}: unmount or any failure aborts the rest.
  */
-export declare function RopeGeoPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, batchSize, timeoutAfterSeconds, isOnline, children, }: RopeGeoPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, batchSize, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoPaginationHttpRequest.d.ts.map

package/dist/components/RopeGeoPaginationHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AA8DzE,MAAM,MAAM,iCAAiC,CAAC,CAAC,GAAG,OAAO,IAAI;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,+FAA+F;QAC/F,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,qGAAqG;QACrG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EAAE,EACxD,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,SAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,iCAAiC,CAAC,CAAC,CAAC,2CAoPtC"}
+{"version":3,"file":"RopeGeoPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAYvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AA8DzE,MAAM,MAAM,iCAAiC,CAAC,CAAC,GAAG,OAAO,IAAI;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,+FAA+F;QAC/F,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,qGAAqG;QACrG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EAAE,EACxD,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,SAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,iCAAiC,CAAC,CAAC,CAAC,2CAyTtC"}

package/dist/components/RopeGeoPaginationHttpRequest.js

@@ -57,33 +57,79 @@ function concatPaginationResultItemsSorted(pagesByNum) {
  * {@link PaginationResults.fromResponseBody}. Final `data` is pages concatenated in page order.
  * In-flight requests use one {@link AbortController}: unmount or any failure aborts the rest.
  */
-function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, batchSize = 10, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, batchSize = 10, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [received, setReceived] = (0, react_1.useState)(0);
     const [total, setTotal] = (0, react_1.useState)(null);
     const [data, setData] = (0, react_1.useState)(null);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const pathParamsKey = JSON.stringify(pathParams ?? null);
     const queryParamsKey = queryParams.toQueryString();
     const effectiveBatch = Math.max(1, Math.floor(batchSize));
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryParamsKey}|${effectiveBatch}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryParamsKey, effectiveBatch, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setHasCommittedOnce(false);
+                setReceived(0);
+                setTotal(null);
+                setData(null);
+                setErrors(null);
+            }
+            prevIsOnlineRef.current = false;
             setLoading(false);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setReceived(0);
+            setTotal(null);
+            setData(null);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const { signal } = abortController;
         const timeoutMs = (0, network_1.resolveRequestTimeoutMs)(timeoutAfterSeconds);
         setLoading(true);
-        setReceived(0);
-        setTotal(null);
-        setData(null);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setReceived(0);
+            setTotal(null);
+            setData(null);
+            setHasCommittedOnce(false);
+        }
         const baseUrl = RopeGeoHttpRequest_1.SERVICE_BASE_URL[service];
         const resolvedPath = resolvePath(path, pathParams);
         const baseInit = {
@@ -158,7 +204,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                     const text = await res.text();
                     if (!res.ok) {
                         abortController.abort();
-                        throw new Error(`HTTP ${res.status}: ${text || res.statusText}`);
+                        throw new Error((0, network_1.formatHttpStatusMessage)(res.status, text || res.statusText));
                     }
                     if (text.length === 0) {
                         abortController.abort();
@@ -192,7 +238,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                 catch (err) {
                     if (pageNum !== 1 && merged != null && merged.consumeDidTimeout()) {
                         abortController.abort();
-                        throw new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE);
+                        throw new Error((0, network_1.formatNetworkRequestErrorMessage)(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE)));
                     }
                     throw err;
                 }
@@ -216,6 +262,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                         return;
                     setData(concatPaginationResultItemsSorted(pagesByNum));
                     setErrors(null);
+                    setHasCommittedOnce(true);
                     return;
                 }
                 const lastPage = Math.max(1, Math.ceil(totalCount / limit));
@@ -246,6 +293,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                     return;
                 setData(concatPaginationResultItemsSorted(pagesByNum));
                 setErrors(null);
+                setHasCommittedOnce(true);
             }
             catch (err) {
                 if (cancelled || (0, network_1.isAbortError)(err))
@@ -253,8 +301,9 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                 console.error("[RopeGeoPaginationHttpRequest] Request failed", {
                     error: err instanceof Error ? err.message : String(err),
                 });
-                setErrors(err instanceof Error ? err : new Error(String(err)));
+                setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(err)));
                 setData(null);
+                setHasCommittedOnce(false);
             }
             finally {
                 clearActivePolicy();
@@ -272,13 +321,16 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
         path,
         pathParamsKey,
         queryParamsKey,
-        queryParams,
         effectiveBatch,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
+            refreshing,
             received,
             total,
             data,

package/dist/helpers/network/index.d.ts

@@ -3,5 +3,5 @@
  * Published as `ropegeo-common/helpers/network`. Prefer this entry over `ropegeo-common/helpers` in
  * Metro/RN bundles so the full helpers barrel (S3 folder upload, etc.) is not resolved.
  */
-export { NETWORK_REQUEST_TIMED_OUT_MESSAGE, NO_NETWORK_MESSAGE, installNetworkRequestPolicyTimers, isAbortError, isNetworkRequestTimeoutError, mergeParentSignalWithDeadline, resolveRequestTimeoutMs, type MergedDeadlineHandles, type NetworkRequestPolicyTimerCallbacks, } from "./networkRequestPolicy";
+export { formatHttpStatusMessage, formatNetworkRequestErrorMessage, NETWORK_REQUEST_TIMED_OUT_MESSAGE, NO_NETWORK_MESSAGE, installNetworkRequestPolicyTimers, isAbortError, isNetworkRequestTimeoutError, mergeParentSignalWithDeadline, resolveRequestTimeoutMs, type MergedDeadlineHandles, type NetworkRequestPolicyTimerCallbacks, } from "./networkRequestPolicy";
 //# sourceMappingURL=index.d.ts.map

package/dist/helpers/network/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/network/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iCAAiC,EACjC,kBAAkB,EAClB,iCAAiC,EACjC,YAAY,EACZ,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,GACxC,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/network/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,uBAAuB,EACvB,gCAAgC,EAChC,iCAAiC,EACjC,kBAAkB,EAClB,iCAAiC,EACjC,YAAY,EACZ,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,GACxC,MAAM,wBAAwB,CAAC"}

package/dist/helpers/network/index.js

@@ -5,8 +5,10 @@
  * Metro/RN bundles so the full helpers barrel (S3 folder upload, etc.) is not resolved.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveRequestTimeoutMs = exports.mergeParentSignalWithDeadline = exports.isNetworkRequestTimeoutError = exports.isAbortError = exports.installNetworkRequestPolicyTimers = exports.NO_NETWORK_MESSAGE = exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE = void 0;
+exports.resolveRequestTimeoutMs = exports.mergeParentSignalWithDeadline = exports.isNetworkRequestTimeoutError = exports.isAbortError = exports.installNetworkRequestPolicyTimers = exports.NO_NETWORK_MESSAGE = exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE = exports.formatNetworkRequestErrorMessage = exports.formatHttpStatusMessage = void 0;
 var networkRequestPolicy_1 = require("./networkRequestPolicy");
+Object.defineProperty(exports, "formatHttpStatusMessage", { enumerable: true, get: function () { return networkRequestPolicy_1.formatHttpStatusMessage; } });
+Object.defineProperty(exports, "formatNetworkRequestErrorMessage", { enumerable: true, get: function () { return networkRequestPolicy_1.formatNetworkRequestErrorMessage; } });
 Object.defineProperty(exports, "NETWORK_REQUEST_TIMED_OUT_MESSAGE", { enumerable: true, get: function () { return networkRequestPolicy_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE; } });
 Object.defineProperty(exports, "NO_NETWORK_MESSAGE", { enumerable: true, get: function () { return networkRequestPolicy_1.NO_NETWORK_MESSAGE; } });
 Object.defineProperty(exports, "installNetworkRequestPolicyTimers", { enumerable: true, get: function () { return networkRequestPolicy_1.installNetworkRequestPolicyTimers; } });

package/dist/helpers/network/networkRequestPolicy.d.ts

@@ -3,6 +3,16 @@
 export declare const NETWORK_REQUEST_TIMED_OUT_MESSAGE = "Network request timed out";
 /** Use this exact message for client-side offline gating and RN fetch failures treated as offline. */
 export declare const NO_NETWORK_MESSAGE = "No network connection";
+/**
+ * Formats HTTP response failures as user-facing copy (e.g. "500 Internal Server Error").
+ * `detail` can be a response body snippet or `statusText`.
+ */
+export declare function formatHttpStatusMessage(status: number, detail?: string): string;
+/**
+ * Normalizes raw network/request errors into stable user-facing copy.
+ * Keeps NO_NETWORK_MESSAGE unchanged for offline gating checks.
+ */
+export declare function formatNetworkRequestErrorMessage(error: unknown): string;
 export declare function isNetworkRequestTimeoutError(e: unknown): boolean;
 export declare function isAbortError(e: unknown): boolean;
 /** Milliseconds for `timeoutAfterSeconds` on request components; `null` when timeout is disabled. */

package/dist/helpers/network/networkRequestPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"networkRequestPolicy.d.ts","sourceRoot":"","sources":["../../../src/helpers/network/networkRequestPolicy.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC,8BAA8B,CAAC;AAE7E,sGAAsG;AACtG,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAUhD;AAED,qGAAqG;AACrG,wBAAgB,uBAAuB,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASnF;AAED,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,kBAAkB,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,kCAAkC,GAC5C,MAAM,IAAI,CAuCZ;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,iBAAiB,EAAE,MAAM,OAAO,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,WAAW,EACzB,UAAU,EAAE,MAAM,GACjB,qBAAqB,CAqCvB"}
+{"version":3,"file":"networkRequestPolicy.d.ts","sourceRoot":"","sources":["../../../src/helpers/network/networkRequestPolicy.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC,8BAA8B,CAAC;AAE7E,sGAAsG;AACtG,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAoB1D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmBvE;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAUhD;AAED,qGAAqG;AACrG,wBAAgB,uBAAuB,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASnF;AAED,MAAM,MAAM,kCAAkC,GAAG;IAC/C,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,kBAAkB,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,kCAAkC,GAC5C,MAAM,IAAI,CAuCZ;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,iBAAiB,EAAE,MAAM,OAAO,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,WAAW,EACzB,UAAU,EAAE,MAAM,GACjB,qBAAqB,CAqCvB"}

package/dist/helpers/network/networkRequestPolicy.js

@@ -2,6 +2,8 @@
 /** Network helpers for optional request deadlines and timeout countdowns. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NO_NETWORK_MESSAGE = exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE = void 0;
+exports.formatHttpStatusMessage = formatHttpStatusMessage;
+exports.formatNetworkRequestErrorMessage = formatNetworkRequestErrorMessage;
 exports.isNetworkRequestTimeoutError = isNetworkRequestTimeoutError;
 exports.isAbortError = isAbortError;
 exports.resolveRequestTimeoutMs = resolveRequestTimeoutMs;
@@ -11,6 +13,59 @@ exports.mergeParentSignalWithDeadline = mergeParentSignalWithDeadline;
 exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE = "Network request timed out";
 /** Use this exact message for client-side offline gating and RN fetch failures treated as offline. */
 exports.NO_NETWORK_MESSAGE = "No network connection";
+const HTTP_STATUS_TEXT = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+};
+function firstLineOrEmpty(value) {
+    return (value.split("\n")[0] ?? "").trim();
+}
+/**
+ * Formats HTTP response failures as user-facing copy (e.g. "500 Internal Server Error").
+ * `detail` can be a response body snippet or `statusText`.
+ */
+function formatHttpStatusMessage(status, detail) {
+    const trimmed = (detail ?? "").trim();
+    if (trimmed !== "") {
+        const line = firstLineOrEmpty(trimmed);
+        return line === "" ? String(status) : `${status} ${line}`;
+    }
+    return `${status} ${HTTP_STATUS_TEXT[status] ?? "HTTP Error"}`;
+}
+/**
+ * Normalizes raw network/request errors into stable user-facing copy.
+ * Keeps NO_NETWORK_MESSAGE unchanged for offline gating checks.
+ */
+function formatNetworkRequestErrorMessage(error) {
+    const raw = error instanceof Error
+        ? error.message
+        : typeof error === "string"
+            ? error
+            : String(error ?? "");
+    const msg = raw.trim();
+    if (msg === "")
+        return "Request failed";
+    if (msg === exports.NO_NETWORK_MESSAGE)
+        return exports.NO_NETWORK_MESSAGE;
+    if (msg === exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE)
+        return exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE;
+    const http = /^HTTP\s+(\d{3})(?::\s*(.*))?$/i.exec(msg);
+    if (http != null) {
+        const code = Number(http[1]);
+        const detail = (http[2] ?? "").trim();
+        return formatHttpStatusMessage(code, detail);
+    }
+    return msg;
+}
 function isNetworkRequestTimeoutError(e) {
     return e instanceof Error && e.message === exports.NETWORK_REQUEST_TIMED_OUT_MESSAGE;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ropegeo-common",
-    "version": "1.12.10",
+    "version": "1.12.12",
     "description": "Shared domain models and helpers for RopeGeo and WebScraper",
     "license": "ISC",
     "repository": {