Merge pull request #22 from TextureHQ/feat/provider-capabilities-fallback

RFC 0001: Provider capability model, health scoring, and fallback policy (Phase 1)

Author: victorquinn

.gitignore

@@ -79,6 +79,9 @@ web_modules/
 .env.production.local
 .env.local
 
+# Crush agent metadata
+.crush
+
 # parcel-bundler cache (https://parceljs.org/)
 .cache
 .parcel-cache

CRUSH.md

@@ -0,0 +1,35 @@
+CRUSH.md — Quick guide for agentic contributors
+
+Build / test / lint
+- Install: npm install
+- Build all: npm run build (runs build:cjs and build:esm)
+- Build CJS only: npm run build:cjs
+- Build ESM only: npm run build:esm
+- Clean before build: handled by prebuild (rimraf ./dist)
+- Run tests: npm test
+- Watch tests: npm run test:watch
+- Coverage: npm run coverage (outputs coverage/lcov.info)
+- Run a single test file: npx jest path/to/file.test.ts
+- Run tests by name/pattern: npx jest -t "pattern"
+
+Project conventions
+- Language: TypeScript (strict true). ESM and CJS builds emitted to dist.
+- Testing: Jest with ts-jest preset; test files use .test.ts/.spec.ts naming.
+- Imports: Use module paths as in source; ES import syntax. Prefer named exports; default exports only when necessary.
+- Formatting: Follow existing style; no formatter config present. Keep two-space indentation, single quotes, semicolons consistent with repo.
+- Types: Prefer explicit return types on public functions; enable strict null checks; use interfaces for shapes and zod for runtime validation when present.
+- Naming: camelCase for variables/functions, PascalCase for types/classes, UPPER_SNAKE_CASE for constants.
+- Error handling: Throw typed errors from src/errors.ts where applicable; wrap external I/O (axios, redis) and surface meaningful messages without leaking secrets.
+- Caching: See src/cache.ts for simple Redis-based cache helpers; ensure keys are namespaced and TTL respected.
+- Providers: Implement IWeatherProvider in src/providers/IWeatherProvider.ts; keep provider-specific logic in their subfolders (nws, openweather). Add tests alongside provider code.
+- Env/config: No .env checked in; do not commit secrets. Use environment variables at runtime; update README if adding new vars.
+
+Tooling details
+- Node 20 in CI; ensure compatibility.
+- Jest config: jest.config.ts (ts-jest preset, node environment, ignores dist/*).
+- TypeScript configs: tsconfig.cjs.json and tsconfig.esm.json drive dual builds; tsconfig.json is repo default for tooling.
+
+Assistant notes
+- No Cursor or Copilot rules files detected.
+- Add any new scripts to package.json and mirror in this CRUSH.md.
+- Prefer small, testable changes and keep providers decoupled via interfaces.

docs/rfcs/0001-provider-capabilities-and-fallback.md

@@ -0,0 +1,126 @@
+# RFC 0001: Provider Capability Model, Health Scoring, and Fallback Policies
+
+Status: Proposed
+Authors: TextureHQ
+Created: 2025-08-15
+Target: Minor release (backward-compatible)
+
+## Motivation
+We currently use a fixed provider precedence and implicit fallback. This RFC formalizes:
+- Provider capability metadata (what each provider supports)
+- Provider health scoring and circuit breakers
+- Pluggable fallback policies (priority, priority-then-health, weighted)
+- Normalized error taxonomy
+All defaults preserve existing behavior.
+
+## Goals & Non-Goals
+Goals
+- Additive types and options; no breaking API changes
+- Deterministic default behavior identical to today
+- Clear extension path for new providers
+Non-Goals
+- Changing existing return shapes by default
+- Mandatory logging/metrics dependencies
+
+## High-level Design
+We introduce a ProviderRegistry that knows provider capabilities and health, and selects providers per request via a policy engine. WeatherService uses the registry; if no config is provided, it registers built-in providers in current order and uses the priority policy (preserves behavior).
+
+### Capability Model
+Each provider publishes static metadata:
+- id: string (e.g., "nws", "openweather")
+- supports: { current: boolean; hourly?: boolean; daily?: boolean; alerts?: boolean }
+- regions?: string[] | GeoJSON region hint (optional)
+- units?: ("standard"|"metric"|"imperial")[] (optional)
+- locales?: string[] (optional)
+
+### Health Model
+We keep a rolling in-memory snapshot per provider:
+- successRate: EMA or sliding window over last N calls
+- p95LatencyMs: recent percentile
+- lastFailureAt?: number (epoch)
+- circuit: "closed" | "open" | "half-open"
+Outcomes are recorded on every provider call: { ok: boolean, latencyMs, errorCode? }.
+
+### Error Taxonomy
+Normalize provider errors to:
+- NetworkError, RateLimitError, NotFoundError, ValidationError, ParseError, UpstreamError, UnavailableError
+Attach: { provider, status?, retryAfterMs?, endpoint? }. Do not log/propagate secrets.
+When all providers fail, return CompositeProviderError with per-provider normalized entries.
+
+### Policies
+- priority (default): try in configured order
+- priority-then-health: priority order, but skip providers that are open-circuit or below health thresholds; probe half-open last
+- weighted: choose initial provider by weights among healthy providers; fallback to next-best healthy
+
+### Configuration (all optional)
+WeatherService options additions:
+- providerPolicy?: "priority" | "priority-then-health" | "weighted"
+- providerWeights?: Record<string, number>
+- healthThresholds?: { minSuccessRate?: number; maxP95Ms?: number }
+- circuit?: { failureCountToOpen?: number; halfOpenAfterMs?: number; successToClose?: number }
+- logger?: { trace/debug/info/warn/error(fielded) }
+- metrics?: hooks for counters/histograms (noop by default)
+
+## Detailed Design
+
+### New/updated modules
+- src/providers/providerRegistry.ts
+  - register(providerId, adapter, capability)
+  - recordOutcome(providerId, outcome)
+  - getHealth(providerId)
+  - listProviders(intent): filters by capabilities
+- src/providers/policy.ts
+  - selectCandidates(intent, registry, config): ProviderId[] with reasons for skips
+- src/errors.ts (additions)
+  - new error classes + CompositeProviderError
+- src/providers/* adapters
+  - export capability metadata
+  - report outcomes via registry hook
+- src/weatherService.ts
+  - wire registry + policy; defaults keep current order and behavior when no options provided
+
+### Data types (sketch)
+- ProviderId = "nws" | "openweather" | string
+- Capability
+- HealthSnapshot
+- Outcome: { ok: true, latencyMs } | { ok: false, latencyMs, code, status?, retryAfterMs? }
+- PolicyConfig (see above)
+
+### Circuit Breaker
+- Open after N consecutive failures
+- Half-open after halfOpenAfterMs, allow limited probes
+- Close after successToClose consecutive successes
+
+## Backward Compatibility
+- Defaults: priority policy, all providers registered in existing precedence, no health filtering, no circuit breaker unless configured with safe defaults (or enabled with conservative thresholds)
+- Existing method signatures unchanged
+
+## Observability
+- Optional logger interface with structured fields
+- Optional metrics hooks (provider_success/failure, latency histograms, circuit_state)
+- CorrelationId is accepted/propagated when provided
+
+## Testing Strategy
+- Unit: capability validation, policy selection logic, circuit transitions (fake timers), error normalization
+- Integration: simulated provider failures and latency distributions; ensure default path equals current behavior
+- Snapshot: CompositeProviderError structure
+
+## Rollout Plan
+1. Land types/interfaces, provider capability exports, no behavior change
+2. Implement registry + outcome recording; keep disabled by default
+3. Implement policy engine; enable via options, default unchanged
+4. Add circuit + thresholds with conservative defaults (opt-in)
+5. Docs + examples; minor release
+
+## Alternatives Considered
+- Single global retry layer only (insufficient insight/control)
+- Hard-coding health logic inside WeatherService (less modular/extendable)
+
+## Security & Privacy
+- Never include tokens or credentials in errors/logs/metrics
+- Ensure PII isn’t logged; redact query params as needed
+
+## Open Questions
+- Default thresholds for health and circuit when enabled?
+- How granular should regions be (country list vs polygons)?
+- Should we persist health across process restarts?

package.json

@@ -1,6 +1,6 @@
 {
   "name": "weather-plus",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Weather Plus is a powerful wrapper around various Weather APIs that simplifies adding weather data to your application",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

src/providers/capabilities.test.ts

@@ -0,0 +1,41 @@
+import { OPENWEATHER_CAPABILITY } from './openweather/client';
+import { NWS_CAPABILITY } from './nws/client';
+import { ProviderCapability } from './capabilities';
+
+describe('provider capabilities', () => {
+  it('NWS_CAPABILITY matches expected shape and values', () => {
+    const cap: ProviderCapability = NWS_CAPABILITY;
+    expect(cap.supports.current).toBe(true);
+    expect(cap.supports.hourly).toBeFalsy();
+    expect(cap.supports.daily).toBeFalsy();
+    expect(cap.supports.alerts).toBeFalsy();
+    expect(cap.regions).toContain('US');
+  });
+
+  it('OPENWEATHER_CAPABILITY matches expected shape and values', () => {
+    const cap: ProviderCapability = OPENWEATHER_CAPABILITY;
+    expect(cap.supports.current).toBe(true);
+    expect(cap.supports.hourly).toBe(true);
+    expect(cap.supports.daily).toBe(true);
+    expect(cap.supports.alerts).toBe(true);
+    expect(cap.units).toEqual(expect.arrayContaining(['standard', 'metric', 'imperial']));
+  });
+
+  it('validates the built-in capabilities map explicitly', () => {
+    const map = {
+      nws: NWS_CAPABILITY,
+      openweather: OPENWEATHER_CAPABILITY,
+    } as const;
+    expect(map).toEqual({
+      nws: {
+        supports: { current: true, hourly: false, daily: false, alerts: false },
+        regions: ['US'],
+      },
+      openweather: {
+        supports: { current: true, hourly: true, daily: true, alerts: true },
+        units: ['standard', 'metric', 'imperial'],
+        locales: [],
+      },
+    });
+  });
+});

src/providers/capabilities.ts

@@ -0,0 +1,42 @@
+export type ProviderId = 'nws' | 'openweather' | (string & {});
+
+export interface ProviderCapability {
+  supports: {
+    current: boolean;
+    hourly?: boolean;
+    daily?: boolean;
+    alerts?: boolean;
+  };
+  regions?: string[];
+  units?: Array<'standard' | 'metric' | 'imperial'>;
+  locales?: string[];
+}
+
+export type ProviderCircuitState = 'closed' | 'open' | 'half-open';
+
+export interface ProviderHealthSnapshot {
+  successRate: number;
+  p95LatencyMs?: number;
+  lastFailureAt?: number;
+  circuit: ProviderCircuitState;
+}
+
+export type ProviderErrorCode =
+  | 'NetworkError'
+  | 'RateLimitError'
+  | 'NotFoundError'
+  | 'ValidationError'
+  | 'ParseError'
+  | 'UpstreamError'
+  | 'UnavailableError';
+
+export type ProviderCallOutcome =
+  | { ok: true; latencyMs: number }
+  | { ok: false; latencyMs: number; code: ProviderErrorCode; status?: number; retryAfterMs?: number };
+
+export interface FallbackPolicyConfig {
+  providerPolicy?: 'priority' | 'priority-then-health' | 'weighted';
+  providerWeights?: Record<string, number>;
+  healthThresholds?: { minSuccessRate?: number; maxP95Ms?: number };
+  circuit?: { failureCountToOpen?: number; halfOpenAfterMs?: number; successToClose?: number };
+}

src/providers/capabilitiesMap.ts

@@ -0,0 +1,10 @@
+import { OPENWEATHER_CAPABILITY } from './openweather/client';
+import { NWS_CAPABILITY } from './nws/client';
+import { ProviderCapability } from './capabilities';
+
+export function getBuiltInCapabilities(): Record<string, ProviderCapability> {
+  return {
+    nws: NWS_CAPABILITY,
+    openweather: OPENWEATHER_CAPABILITY,
+  } as const;
+}

src/providers/index.ts

@@ -1,3 +1,5 @@
 export { IWeatherProvider } from './IWeatherProvider';
 export { NWSProvider } from './nws/client';
 export { OpenWeatherProvider } from './openweather/client';
+export * from './capabilities';
+export { defaultOutcomeReporter, NoopProviderOutcomeReporter, ProviderOutcomeReporter } from './outcomeReporter';

src/providers/nws/client.ts

@@ -12,11 +12,18 @@ import { InvalidProviderLocationError } from '../../errors'; // Import the error
 import { isLocationInUS } from '../../utils/locationUtils';
 import { standardizeCondition } from './condition';
 import { getCloudinessFromCloudLayers } from './cloudiness';
+import { ProviderCapability } from '../capabilities';
+import { defaultOutcomeReporter } from '../outcomeReporter';
 
 const log = debug('weather-plus:nws:client');
 
 export const WEATHER_KEYS = Object.values(IWeatherKey);
 
+export const NWS_CAPABILITY: ProviderCapability = Object.freeze({
+  supports: { current: true, hourly: false, daily: false, alerts: false },
+  regions: ['US'],
+});
+
 export class NWSProvider implements IWeatherProvider {
   name = 'nws';
 
@@ -31,6 +38,7 @@ export class NWSProvider implements IWeatherProvider {
     const data: Partial<IWeatherProviderWeatherData> = {};
     const weatherData: Partial<IWeatherProviderWeatherData>[] = [];
 
+    const start = Date.now();
     try {
       const observationStations = await fetchObservationStationUrl(lat, lng);
       const stations = await fetchNearbyStations(observationStations);
@@ -78,9 +86,17 @@ export class NWSProvider implements IWeatherProvider {
         throw new Error('Invalid observation data');
       }
 
+      defaultOutcomeReporter.record('nws', { ok: true, latencyMs: Date.now() - start });
       return data;
     } catch (error) {
       log('Error in getWeather:', error);
+      try {
+        defaultOutcomeReporter.record('nws', {
+          ok: false,
+          latencyMs: Date.now() - start,
+          code: 'UpstreamError',
+        });
+      } catch {}
       throw error;
     }
   }

src/providers/openweather/client.ts

@@ -4,9 +4,17 @@ import { IWeatherUnits, IWeatherProviderWeatherData } from '../../interfaces';
 import { IOpenWeatherResponse } from './interfaces';
 import { IWeatherProvider } from '../IWeatherProvider';
 import { standardizeCondition} from './condition';
+import { ProviderCapability } from '../capabilities';
+import { defaultOutcomeReporter } from '../outcomeReporter';
 
 const log = debug('weather-plus:openweather:client');
 
+export const OPENWEATHER_CAPABILITY: ProviderCapability = Object.freeze({
+  supports: { current: true, hourly: true, daily: true, alerts: true },
+  units: ['standard', 'metric', 'imperial'] as Array<'standard' | 'metric' | 'imperial'>,
+  locales: [] as string[],
+});
+
 export class OpenWeatherProvider implements IWeatherProvider {
   private apiKey: string;
   name = 'openweather';
@@ -19,6 +27,7 @@ export class OpenWeatherProvider implements IWeatherProvider {
   }
 
   public async getWeather(lat: number, lng: number): Promise<Partial<IWeatherProviderWeatherData>> {
+    const start = Date.now();
     const url = `https://api.openweathermap.org/data/3.0/onecall`;
 
     const params = {
@@ -32,9 +41,22 @@ export class OpenWeatherProvider implements IWeatherProvider {
 
     try {
       const response = await axios.get<IOpenWeatherResponse>(url, { params });
-      return convertToWeatherData(response.data);
-    } catch (error) {
+      const result = convertToWeatherData(response.data);
+      defaultOutcomeReporter.record('openweather', { ok: true, latencyMs: Date.now() - start });
+      return result;
+    } catch (error: any) {
       log('Error in getWeather:', error);
+      try {
+        defaultOutcomeReporter.record('openweather', {
+          ok: false,
+          latencyMs: Date.now() - start,
+          code: 'UpstreamError',
+          status: error?.response?.status,
+          retryAfterMs: error?.response?.headers?.['retry-after']
+            ? Number(error.response.headers['retry-after']) * 1000
+            : undefined,
+        });
+      } catch {}
       throw error;
     }
   }