Merge pull request #26 from TextureHQ/feat/tomorrow-provider

feat: integrate Tomorrow.io provider

Author: victorquinn

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 - `src/` houses all TypeScript source; entry point is `src/index.ts`, with domain logic in `weatherService.ts` and provider implementations under `src/providers/`.
-- Each provider keeps its own helpers (`openweather/`, `nws/`) and colocated tests (`*.test.ts`). Shared contracts live in `interfaces.ts` and `providers/IWeatherProvider.ts`.
+- Each provider keeps its own helpers (`openweather/`, `nws/`, `tomorrow/`) and colocated tests (`*.test.ts`). Shared contracts live in `interfaces.ts` and `providers/IWeatherProvider.ts`.
 - Utilities (caching, error taxonomy, normalization) sit in `src/utils/` and `src/errors.ts`. Build artifacts publish to `dist/` (CJS and ESM). Architectural notes and RFCs reside in `docs/rfcs/`.
 
 ## Build, Test, and Development Commands

src/providers/capabilities.test.ts

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

src/providers/capabilities.ts

@@ -1,4 +1,4 @@
-export type ProviderId = 'nws' | 'openweather' | (string & {});
+export type ProviderId = 'nws' | 'openweather' | 'tomorrow' | (string & {});
 
 export interface ProviderCapability {
   supports: {

src/providers/capabilitiesMap.ts

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

src/providers/index.ts

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

src/providers/nws/client.test.ts

@@ -214,6 +214,22 @@ describe('NWSProvider', () => {
     await expect(provider.getWeather(latInUS, lngInUS)).rejects.toThrow('Invalid observation data');
   });
 
+  it('reports failure when all stations return unusable data', async () => {
+    mockObservationStationUrl();
+
+    mock
+      .onGet('https://api.weather.gov/gridpoints/XYZ/123,456/stations')
+      .reply(200, {
+        features: [{ id: 'station123' }],
+      });
+
+    mock.onGet('station123/observations/latest').reply(200, {
+      properties: {},
+    });
+
+    await expect(provider.getWeather(latInUS, lngInUS)).rejects.toThrow('Invalid observation data');
+  });
+
   it('should throw when latest observation response omits properties entirely', async () => {
     mockObservationStationUrl();
 

src/providers/nws/client.ts

@@ -82,10 +82,6 @@ export class NWSProvider implements IWeatherProvider {
         }
       }
 
-      if (Object.keys(data).length === 0) {
-        throw new Error('Invalid observation data');
-      }
-
       defaultOutcomeReporter.record('nws', { ok: true, latencyMs: Date.now() - start });
       return data;
     } catch (error) {

src/providers/providerFactory.test.ts

@@ -1,10 +1,17 @@
 import { ProviderFactory } from './providerFactory';
 import { ProviderNotSupportedError } from '../errors';
+import { TomorrowProvider } from './tomorrow/client';
 
 describe('ProviderFactory', () => {
   it('should throw ProviderNotSupportedError for unsupported providers', () => {
     expect(() => {
       ProviderFactory.createProvider('unsupportedProvider');
     }).toThrow(ProviderNotSupportedError);
   });
-});
+
+  it('creates a TomorrowProvider when requested', () => {
+    const provider = ProviderFactory.createProvider('tomorrow', 'api-key');
+    expect(provider).toBeInstanceOf(TomorrowProvider);
+    expect(provider.name).toBe('tomorrow');
+  });
+});

src/providers/providerFactory.ts

@@ -1,6 +1,7 @@
 import { IWeatherProvider } from './IWeatherProvider';
 import { NWSProvider } from './nws/client';
 import { OpenWeatherProvider } from './openweather/client';
+import { TomorrowProvider } from './tomorrow/client';
 import { ProviderNotSupportedError } from '../errors';
 import { ProviderId } from './capabilities';
 
@@ -11,6 +12,8 @@ export const ProviderFactory = {
         return new NWSProvider();
       case 'openweather':
         return new OpenWeatherProvider(apiKey ?? '');
+      case 'tomorrow':
+        return new TomorrowProvider(apiKey ?? '');
       default:
         throw new ProviderNotSupportedError(
           `Provider ${providerName} is not supported yet`

src/providers/tomorrow/client.test.ts

@@ -0,0 +1,142 @@
+import axios from 'axios';
+import MockAdapter from 'axios-mock-adapter';
+import { TomorrowProvider } from './client';
+import { ProviderOutcomeReporter } from '../outcomeReporter';
+import { defaultOutcomeReporter, setDefaultOutcomeReporter } from '../outcomeReporter';
+import { ProviderCallOutcome } from '../capabilities';
+
+describe('TomorrowProvider', () => {
+  const lat = 43.6535;
+  const lng = -79.3839;
+  const apiKey = 'test-api-key';
+  let mock: MockAdapter;
+  let provider: TomorrowProvider;
+
+  beforeEach(() => {
+    mock = new MockAdapter(axios);
+    provider = new TomorrowProvider(apiKey);
+  });
+
+  afterEach(() => {
+    mock.restore();
+  });
+
+  it('throws if API key is missing', () => {
+    expect(() => new TomorrowProvider('')).toThrow('Tomorrow.io provider requires an API key.');
+  });
+
+  it('converts Tomorrow.io realtime response into weather data', async () => {
+    const mockResponse = {
+      data: {
+        time: '2023-01-26T07:48:00Z',
+        values: {
+          cloudCover: 100,
+          dewPoint: 0.88,
+          humidity: 96,
+          temperature: 1.88,
+          weatherCode: 1001,
+        },
+      },
+      location: {
+        lat,
+        lon: lng,
+      },
+    };
+
+    mock
+      .onGet('https://api.tomorrow.io/v4/weather/realtime', {
+        params: {
+          location: `${lat},${lng}`,
+          apikey: apiKey,
+        },
+      })
+      .reply(200, mockResponse);
+
+    const data = await provider.getWeather(lat, lng);
+
+    expect(data).toEqual({
+      temperature: { value: 1.88, unit: 'C' },
+      humidity: { value: 96, unit: 'percent' },
+      dewPoint: { value: 0.88, unit: 'C' },
+      cloudiness: { value: 100, unit: 'percent' },
+      conditions: { value: 'Cloudy', unit: 'string', original: 'Cloudy' },
+    });
+  });
+
+  it('normalizes unknown or missing weather codes into descriptive strings', async () => {
+    mock
+      .onGet('https://api.tomorrow.io/v4/weather/realtime')
+      .reply(200, {
+        data: {
+          values: {
+            humidity: 40,
+          },
+        },
+      });
+
+    const data = await provider.getWeather(lat, lng);
+
+    expect(data).toEqual({
+      humidity: { value: 40, unit: 'percent' },
+      conditions: { value: 'Unknown', unit: 'string', original: 'Code -1' },
+    });
+  });
+
+  it('records failure metadata when Tomorrow.io responds with an error', async () => {
+    class TestReporter implements ProviderOutcomeReporter {
+      public events: Array<{ provider: string; outcome: ProviderCallOutcome }> = [];
+      record(provider: string, outcome: ProviderCallOutcome): void {
+        this.events.push({ provider, outcome });
+      }
+    }
+
+    const reporter = new TestReporter();
+    const original = defaultOutcomeReporter;
+    setDefaultOutcomeReporter(reporter);
+
+    mock
+      .onGet('https://api.tomorrow.io/v4/weather/realtime')
+      .reply(503);
+
+    try {
+      await expect(provider.getWeather(lat, lng)).rejects.toThrow('Request failed with status code 503');
+      expect(reporter.events).toHaveLength(1);
+      expect(reporter.events[0]).toEqual({
+        provider: 'tomorrow',
+        outcome: expect.objectContaining({
+          ok: false,
+          code: 'UpstreamError',
+          status: 503,
+        }),
+      });
+    } finally {
+      setDefaultOutcomeReporter(original);
+    }
+  });
+
+  it('throws when essential weather values are missing', async () => {
+    mock
+      .onGet('https://api.tomorrow.io/v4/weather/realtime')
+      .reply(200, { data: { values: {} } });
+
+    await expect(provider.getWeather(lat, lng)).rejects.toThrow('Invalid weather data');
+  });
+
+  it('throws when values block is missing entirely', async () => {
+    mock
+      .onGet('https://api.tomorrow.io/v4/weather/realtime')
+      .reply(200, { data: {} });
+
+    await expect(provider.getWeather(lat, lng)).rejects.toThrow('Invalid weather data');
+  });
+
+  it('wraps unexpected rejection payloads in a descriptive error', async () => {
+    mock.restore();
+    const spy = jest.spyOn(axios, 'get').mockRejectedValueOnce(undefined);
+
+    await expect(provider.getWeather(lat, lng)).rejects.toThrow('Failed to fetch Tomorrow.io data');
+
+    spy.mockRestore();
+    mock = new MockAdapter(axios);
+  });
+});