use-weather-forecast 0.1.128 → 0.1.129

package/README.md

@@ -2,14 +2,16 @@
 
 [![Coverage](https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent/graph/badge.svg?component=package-react-weather-forecast)](https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent)
 
-React weather forecast component using Open-Meteo for current, hourly, and daily forecasts and Cloudflare/ipapi.co for IP geolocation.
+React weather forecast component using Open-Meteo for current, hourly, and daily forecasts and Cloudflare/ipapi.co for IP geolocation, with a fallback chain behind both.
 
 ## Features
 
 - Current weather.
 - Next hours forecast.
 - Next days forecast.
-- IP geolocation fallback.
+- Four weather upstreams tried in order, four IP geolocation upstreams behind that.
+- Every request validated before it is sent, retried with backoff when it can recover.
+- Stale-cache fallback so a total outage still renders a widget.
 - Latitude/longitude override.
 - Split SVG weather icon components.
 - TypeScript + tsup library scaffold.
@@ -37,6 +39,66 @@ export default function App() {
 }
 ```
 
+## Reliability
+
+Nothing here needs configuring -- these are the defaults -- but this is what
+the package does when an upstream misbehaves.
+
+### `Weather request failed: 400 Bad Request`
+
+Open-Meteo answers `400` for a query it cannot parse, and the usual way to
+build one is not a typo in your props: an IP geolocation upstream answers
+`200` with no coordinates in the body, `Number(undefined)` becomes `NaN`,
+`latitude=NaN` goes out on the wire. Everything that goes into a request is
+validated first now:
+
+| Input | What happens to it |
+| --- | --- |
+| `latitude` / `longitude` | Must be finite and on the globe, and are rounded to 4 decimals. A geolocation response without them counts as a failed lookup, so the next provider gets a turn. Unusable props fall back to IP geolocation. |
+| `location.timezone` | Canonicalized (`US/Pacific` becomes `America/Los_Angeles`); a zone the runtime cannot resolve is dropped rather than sent, and Open-Meteo resolves the zone from the coordinates instead. |
+| `forecastDays` / `forecastHours` | Clamped to the 1-16 days and 1-384 hours the API accepts. |
+| Variable list | A `400` from an endpoint that refused one of the optional variables is retried once with the minimal set the widget needs. |
+
+### Retries
+
+Requests go through [`grab-url`](https://www.npmjs.com/package/grab-url) rather
+than `fetch`. Each one is tried up to `retryAttempts` times (3 by default for a
+forecast, 2 per geolocation provider since that chain is longer) with
+exponential backoff from `retryDelay` (400ms, then 800ms, ...). A `429`, a
+`5xx`, a timeout or a dropped connection is repeated; a request the server
+called invalid (`400`, `404`) is not, since replaying it only burns the
+upstream's rate limit.
+
+### Fallback APIs
+
+| Order | Weather | IP geolocation |
+| --- | --- | --- |
+| 1 | `open-meteo` -- `api.open-meteo.com/v1/forecast` | `geoEndpoint` (the bundled worker), when given |
+| 2 | `open-meteo-gfs` -- the GFS model endpoint | `ipapi` -- ipapi.co |
+| 3 | `met-no` -- met.no, a different operator and model | `ipwho` -- ipwho.is |
+| 4 | `wttr` -- wttr.in, no key required | `geojs` -- get.geojs.io |
+| 5 | | `freeipapi` -- freeipapi.com |
+
+The fallbacks normalize their own condition codes, units and timestamps into
+the same shape Open-Meteo returns, so a failover is invisible in the rendered
+widget (wttr.in is 3-hourly rather than hourly). If every provider fails, a
+cached forecast up to a day old is served instead of throwing; only if there is
+no cache either does an error reach the widget, listing what each provider
+said.
+
+```tsx
+<WeatherForecast
+  weatherProviders={['open-meteo', 'met-no']}
+  geoProviders={['ipwho', 'geojs']}
+  retryAttempts={3}
+  retryDelay={400}
+  timeout={15}
+  fallbackLocation={{ city: 'Austin', latitude: 30.27, longitude: -97.74 }}
+  allowStaleCache
+  onProviderError={({ provider, stage, error }) => console.warn(stage, provider, error.message)}
+/>
+```
+
 ## Direct API usage
 
 ```ts
@@ -72,10 +134,17 @@ This package no longer uses ipinfo.io. Instead:
   no mixed-content issues, though ipapi.co's free tier is rate-limited (1,000
   requests/day) — deploy the worker and pass `geoEndpoint` for higher-volume or
   production use.
-- A failed lookup is **repeated** before it throws: `getClientLocation` tries three
-  times by default, waiting 500ms, then 1s, so a single rate-limited or cold-start
-  response doesn't take the whole forecast down. Tune it with the third argument:
-  `getClientLocation(geoEndpoint, ip, { attempts: 5, retryDelay: 250 })`.
+- A failed lookup is **repeated** before the chain moves on: `getClientLocation`
+  tries each provider twice by default, waiting 500ms, then walks the rest of the
+  chain (ipapi.co, ipwho.is, get.geojs.io, freeipapi.com) so a single rate-limited
+  or cold-start response doesn't take the whole forecast down. Tune it with the
+  third argument: `getClientLocation(geoEndpoint, ip, { attempts: 5, retryDelay: 250, providers: ['ipwho'] })`.
+- A response **without usable coordinates counts as a failure** rather than being
+  passed on as `NaN`, and `fallbackLocation` covers the case where every provider
+  is down.
+- The bundled worker does the same on its side: it falls back to the IP lookups
+  when Cloudflare's own geolocation carries no coordinates, and answers `502` with
+  a reason instead of a body the caller cannot use.
 
 ### Deploying the geo worker
 
@@ -90,16 +159,20 @@ This deploys `worker/geo-worker.ts` via Wrangler. Use the resulting `*.workers.d
 ## Caching
 
 `getWeatherForecast` caches each response in `localStorage` for 30 minutes, keyed by
-the exact request URL (location + units + forecast range). Repeated calls for the same
+the request itself (location + units + forecast range + timezone), so a fallback
+provider's answer is reused exactly like the primary one's. Repeated calls for the same
 location/options within that window are served from the cache instead of hitting
-Open-Meteo again, which keeps the widget well under Open-Meteo's rate limits. Call
-`clearWeatherForecastCache()` to evict everything (e.g. in tests). The cache is a no-op
-in non-browser environments (SSR) or when `localStorage` is unavailable/full.
+Open-Meteo again, which keeps the widget well under Open-Meteo's rate limits. Past
+the 30 minutes an entry is kept for a day as the last-resort fallback described
+above, and evicted after that. Call `clearWeatherForecastCache()` to evict
+everything (e.g. in tests). The cache is a no-op in non-browser environments (SSR)
+or when `localStorage` is unavailable/full.
 
 ## Notes
 
-- Open-Meteo powers the forecast data.
-- Cloudflare's `request.cf` and ipapi.co power IP geolocation (see above).
+- Open-Meteo powers the forecast data, with met.no and wttr.in behind it.
+- Cloudflare's `request.cf`, ipapi.co, ipwho.is, get.geojs.io and freeipapi.com
+  power IP geolocation (see above).
 - HTTP requests go through [`grab-url`](https://www.npmjs.com/package/grab-url), the
   repo-wide client, rather than raw `fetch`. It is the package's only runtime
   dependency.

package/dist/api/forecast.d.ts

@@ -1,2 +1,26 @@
 import type { WeatherForecastData, WeatherForecastOptions } from '../types';
+import { type ForecastRequest } from './providers';
+/**
+ * Everything that goes on the wire is validated first, then the providers are
+ * tried in order until one answers.
+ *
+ * The `400 Bad Request` this used to render came from an unvalidated request:
+ * a geolocation upstream answering 200 with no coordinates put `latitude=NaN`
+ * in the URL, and an unknown timezone string or an out-of-range `forecastDays`
+ * did the same. Those are caught in {@link buildForecastRequest} now, before a
+ * request is sent, and anything that still fails falls through to the next
+ * provider and finally to a stale cache entry.
+ */
+/** Cache key for a request, so a fallback provider's answer is reused like the primary one's. */
+export declare function forecastCacheKey(request: ForecastRequest): string;
+/** Validate and clamp every option into a request that no upstream can reject as malformed. */
+export declare function buildForecastRequest(options?: WeatherForecastOptions): Promise<ForecastRequest>;
+/**
+ * Current, hourly and daily forecast for a location.
+ *
+ * @param options Location, units, range, provider chain and retry settings.
+ * @returns The first provider's answer, a cached one, or -- if every provider
+ *   failed and `allowStaleCache` is on -- the last good answer for this exact
+ *   request.
+ */
 export declare function getWeatherForecast(options?: WeatherForecastOptions): Promise<WeatherForecastData>;

package/dist/api/geolocation.d.ts

@@ -1,20 +1,50 @@
 import type { WeatherLocation } from '../types';
+/** One IP geolocation upstream. */
+export type GeoProvider = {
+    id: string;
+    /** Used in the thrown message, e.g. `ipapi.co lookup`. */
+    label: string;
+    /** Full URL for the lookup; `ip` is the address to look up, if any. */
+    url: (ip?: string) => string;
+    /** Map the body onto a location, or return `null` if it carries none. */
+    parse: (body: Record<string, any>) => Partial<WeatherLocation> | null;
+};
 export type GeolocationOptions = {
-    /** default=3 How many times the lookup is tried before the error is thrown. */
+    /** default=2 How many times each provider is tried before the next one is used. */
     attempts?: number;
-    /** default=500 Milliseconds to wait before the second try; each further wait grows by that much. */
+    /** default=500 Milliseconds before a retry; each further wait doubles. */
     retryDelay?: number;
+    /** default=8 Seconds before a single lookup is aborted. */
+    timeout?: number;
+    /** Providers to try, by id or as objects. Omit for {@link DEFAULT_GEO_PROVIDERS}. */
+    providers?: (string | GeoProvider)[];
+    /** Used when every provider failed, instead of throwing. */
+    fallbackLocation?: Partial<WeatherLocation> | null;
+    /** Called for each provider that failed, before the next one is tried. */
+    onProviderError?: (info: {
+        provider: string;
+        error: Error;
+    }) => void;
 };
+export declare const ipapiProvider: GeoProvider;
+export declare const ipwhoProvider: GeoProvider;
+export declare const geojsProvider: GeoProvider;
+export declare const freeipapiProvider: GeoProvider;
+/** Tried in order; each is a different operator, so a rate limit on one is not a rate limit on all. */
+export declare const DEFAULT_GEO_PROVIDERS: GeoProvider[];
+/** The bundled Cloudflare worker, wrapped as a provider so it joins the same chain. */
+export declare function createWorkerGeoProvider(geoEndpoint: string): GeoProvider;
+export declare function resolveGeoProviders(providers?: (string | GeoProvider)[], geoEndpoint?: string): GeoProvider[];
 /**
- * Resolve the caller's location, either from a deployed geo worker or from
- * ipapi.co directly.
+ * Resolve the caller's location from a deployed geo worker or from one of the
+ * public IP lookups.
  *
- * A failed lookup is repeated with a growing delay and only the last error is
- * thrown, so a single rate-limited or cold-started response no longer takes
- * the whole forecast down with it.
+ * Each provider is retried with a growing delay, then the chain moves on; only
+ * if all of them fail (and no `fallbackLocation` was given) does an error
+ * reach the caller, listing what every provider said.
  *
- * @param geoEndpoint URL of a deployed geo worker; omit to use ipapi.co.
+ * @param geoEndpoint URL of a deployed geo worker; it is tried before the public providers.
  * @param ip Look up this IP instead of the caller's own.
- * @param options How often to repeat the lookup, and how long to wait between tries.
+ * @param options Retry, timeout, provider chain and fallback settings.
  */
 export declare function getClientLocation(geoEndpoint?: string, ip?: string, options?: GeolocationOptions): Promise<WeatherLocation>;

package/dist/api/http.d.ts

@@ -1,25 +1,55 @@
 /**
- * Shared JSON transport for the package's upstreams (the geo worker, ipapi.co
- * and Open-Meteo).
+ * Shared JSON transport for every upstream this package talks to (the geo
+ * worker, the IP geolocation providers and the weather providers).
  *
- * `grab-url` is the HTTP client used across this repo: it parses the JSON,
- * applies a timeout and can repeat a failed request itself. Unlike `fetch` it
- * resolves rather than rejects when a request fails, handing back the message
- * on `.error`, so every call site has to inspect the payload -- that check
- * lives here so the callers can just `await` a typed body.
+ * `grab-url` is the HTTP client used across this repo rather than `fetch`: it
+ * parses the JSON, applies a timeout and can repeat a failed request itself.
+ * Unlike `fetch` it resolves rather than rejects when a request fails, handing
+ * back the message on `.error`, so every call site has to inspect the payload
+ * -- that check lives here so the callers can just `await` a typed body.
+ *
+ * On top of that this module adds what the upstreams actually need to stay up:
+ * a classified retry loop (repeat what can recover, give up immediately on a
+ * request the server called invalid) with exponential backoff.
  */
 export type GrabJsonOptions = {
     headers?: Record<string, string>;
-    /** default=0 Times grab-url repeats a request that failed at the transport level. */
-    retryAttempts?: number;
-    /** default=15 Seconds before the request is aborted. */
+    /** default=3 Total tries for this request, including the first one. */
+    attempts?: number;
+    /** default=400 Milliseconds before the second try; each further wait doubles. */
+    retryDelay?: number;
+    /** default=15 Seconds before a single try is aborted. */
     timeout?: number;
+    /**
+     * default=0 Times grab-url itself repeats a try that failed at the transport
+     * level, inside each of our `attempts`. Left at 0 so the backoff and the
+     * status classification below stay in charge of every repeat.
+     */
+    retryAttempts?: number;
+    /**
+     * default=false Repeat even when the server rejected the request as invalid
+     * (a 4xx other than 408/429). Off by default: replaying a request that is
+     * malformed only wastes the upstream's rate limit.
+     */
+    retryClientErrors?: boolean;
 };
+/** A failed upstream call, carrying the HTTP status when the failure had one. */
+export declare class HttpRequestError extends Error {
+    readonly status?: number;
+    readonly retryable: boolean;
+    constructor(message: string, options?: {
+        status?: number;
+        retryable?: boolean;
+    });
+}
+/** No status at all means the request never reached the server -- worth a repeat. */
+export declare function isRetryableStatus(status?: number): boolean;
 /**
- * Request a JSON body, throwing a labelled error for any failure.
+ * Request a JSON body, repeating what can recover and throwing a labelled
+ * {@link HttpRequestError} once it cannot.
  *
  * @param url Full URL to request.
  * @param label Prefix for the thrown message, e.g. `ipapi.co lookup`.
- * @param options Transport options passed through to grab-url.
+ * @param options Transport and retry options.
  */
 export declare function grabJson<T>(url: string, label: string, options?: GrabJsonOptions): Promise<T>;

package/dist/api/providers/index.d.ts

@@ -0,0 +1,21 @@
+import type { WeatherProvider } from './types';
+export * from './types';
+export { createOpenMeteoProvider, openMeteoProvider, openMeteoGfsProvider } from './open-meteo';
+export { metNoProvider, symbolToWmoCode } from './met-no';
+export { wttrProvider, wwoToWmoCode } from './wttr';
+/**
+ * Tried in order until one answers.
+ *
+ * Open-Meteo stays the primary source; its GFS endpoint covers a query the
+ * default model refused or rate-limited, and met.no and wttr.in are run by
+ * different operators entirely, so they still answer when Open-Meteo itself is
+ * unreachable.
+ */
+export declare const DEFAULT_WEATHER_PROVIDERS: WeatherProvider[];
+/**
+ * Turn the `weatherProviders` option into the list to try.
+ *
+ * @param providers Ids (`'open-meteo'`, `'met-no'`, `'wttr'`, `'open-meteo-gfs'`)
+ *   or provider objects of your own. Omit for {@link DEFAULT_WEATHER_PROVIDERS}.
+ */
+export declare function resolveWeatherProviders(providers?: (string | WeatherProvider)[]): WeatherProvider[];

package/dist/api/providers/met-no.d.ts

@@ -0,0 +1,11 @@
+import type { WeatherProvider } from './types';
+export declare function symbolToWmoCode(symbol: string | undefined): number;
+/**
+ * met.no is an independent upstream (a different operator, a different model),
+ * so it stays useful exactly when Open-Meteo is the thing that is down.
+ *
+ * It reports instants in UTC with Celsius and m/s; everything is converted to
+ * the request's units and rewritten into the naive local timestamps the widget
+ * renders, so a failover is invisible.
+ */
+export declare const metNoProvider: WeatherProvider;

package/dist/api/providers/open-meteo.d.ts

@@ -0,0 +1,26 @@
+import type { ForecastRequest, WeatherProvider } from './types';
+/** Every variable the widget can render. */
+declare const FULL_VARIABLES: {
+    current: string[];
+    hourly: string[];
+    daily: string[];
+};
+type Variables = typeof FULL_VARIABLES;
+export declare function buildOpenMeteoUrl(endpoint: string, request: ForecastRequest, variables?: Variables): string;
+/**
+ * Open-Meteo, the package's primary source.
+ *
+ * @param id Provider id, e.g. `open-meteo`.
+ * @param label Name used in the aggregated error message.
+ * @param endpoint Full endpoint URL; the model endpoints (`/v1/gfs` and
+ *   friends) take the same query as `/v1/forecast`.
+ */
+export declare function createOpenMeteoProvider(id: string, label: string, endpoint: string): WeatherProvider;
+/** `https://api.open-meteo.com/v1/forecast` -- the default, best-model source. */
+export declare const openMeteoProvider: WeatherProvider;
+/**
+ * The GFS model endpoint on the same host. It answers when `/v1/forecast` is
+ * rate-limited or refuses the query, and speaks exactly the same dialect.
+ */
+export declare const openMeteoGfsProvider: WeatherProvider;
+export {};

package/dist/api/providers/types.d.ts

@@ -0,0 +1,30 @@
+import type { GrabJsonOptions } from '../http';
+import type { TemperatureUnit, WeatherForecastData, WeatherLocation, WindSpeedUnit } from '../../types';
+/** A forecast request after validation: every field is safe to put in a URL. */
+export type ForecastRequest = {
+    location: WeatherLocation;
+    temperatureUnit: TemperatureUnit;
+    windSpeedUnit: WindSpeedUnit;
+    /** 1-16. */
+    forecastDays: number;
+    /** 1-384. */
+    forecastHours: number;
+    /** A validated IANA zone, or `undefined` to let the provider resolve it. */
+    timezone?: string;
+    /** Transport and retry settings passed through to grab-url. */
+    transport: GrabJsonOptions;
+};
+/**
+ * One upstream that can answer a {@link ForecastRequest}.
+ *
+ * Providers are tried in order and the first one to answer wins, so each has
+ * to return the same normalized shape whatever units or codes it speaks
+ * natively.
+ */
+export type WeatherProvider = {
+    /** Stable id, e.g. `open-meteo`. Used in options and in the error message. */
+    id: string;
+    /** Human-readable name for the aggregated error message. */
+    label: string;
+    fetchForecast: (request: ForecastRequest) => Promise<WeatherForecastData>;
+};

package/dist/api/providers/wttr.d.ts

@@ -0,0 +1,11 @@
+import type { WeatherProvider } from './types';
+export declare function wwoToWmoCode(code: unknown): number;
+/**
+ * wttr.in, the second independent fallback.
+ *
+ * Its free endpoint needs no key and answers with the location's own local
+ * times, in both Celsius and Fahrenheit, so only the wind speed has to be
+ * converted. It is 3-hourly rather than hourly -- a coarser forecast, but a
+ * rendered widget rather than an error message.
+ */
+export declare const wttrProvider: WeatherProvider;

package/dist/hooks/useWeatherForecast.d.ts

@@ -1,4 +1,11 @@
 import type { WeatherForecastData, WeatherForecastOptions } from '../types';
+/**
+ * Fetch a forecast for `options`, refetching whenever they change.
+ *
+ * The last good forecast is kept while a refetch is in flight *and* if that
+ * refetch fails, so a rate-limited upstream leaves the widget showing the
+ * previous data rather than replacing it with an error.
+ */
 export declare function useWeatherForecast(options?: WeatherForecastOptions): {
     data: WeatherForecastData | null;
     error: Error | null;