@happyvertical/weather 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/weather
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Weather data provider abstraction for HAppyVertical SDK
+
+## Package Map
+- Package: `@happyvertical/weather`
+- Hierarchy path: `@happyvertical/sdk > packages > weather`
+- Workspace position: `30 of 30` local packages
+- Internal dependencies: `@happyvertical/utils`
+- Internal dependents: none
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/weather build
+pnpm --filter @happyvertical/weather test
+pnpm --filter @happyvertical/weather clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/weather build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/weather clean` followed by `pnpm --filter @happyvertical/weather build` and `pnpm --filter @happyvertical/weather test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Weather data provider abstraction for HAppyVertical SDK
+- Implements: none
+- Requires: @happyvertical/utils
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @happyvertical/weather
+
+Weather data provider abstraction for the HAppyVertical SDK.
+
+## Overview
+
+The `@happyvertical/weather` package provides a unified interface for fetching weather forecasts from multiple providers. It follows the same architectural pattern as `@happyvertical/ai`, `@happyvertical/files`, and `@happyvertical/sql`.
+
+## Supported Providers
+
+- **Environment Canada** - Government weather service for Canadian locations (free)
+- **OpenWeatherMap** - Global weather data with free and paid tiers
+  - Standard API: 5-day/3-hour forecasts (free tier)
+  - One Call API 3.0: 48hr hourly + 8-day daily forecasts (paid tier)
+
+## Installation
+
+```bash
+pnpm add @happyvertical/weather
+```
+
+## Claude Code Context
+
+Install Claude Code context files for AI-assisted development:
+
+```bash
+npx have-weather-context
+```
+
+This copies the package's `AGENT.md` documentation and `metadata.json` metadata to your project's `.claude/` directory, enabling Claude to provide better assistance when working with this package.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { getWeatherAdapter } from '@happyvertical/weather';
+
+// Create adapter for Environment Canada
+const weather = await getWeatherAdapter({
+  provider: 'environment-canada'
+});
+
+// Fetch forecast for a location (latitude, longitude)
+const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
+
+forecasts.forEach(forecast => {
+  console.log(`${forecast.timestamp}: ${forecast.temperature}°C - ${forecast.conditions}`);
+});
+```
+
+### OpenWeatherMap (Free Tier)
+
+```typescript
+const weather = await getWeatherAdapter({
+  provider: 'openweathermap',
+  apiKey: process.env.OPENWEATHER_API_KEY
+});
+
+const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
+```
+
+### OpenWeatherMap One Call (Paid Tier)
+
+```typescript
+const weather = await getWeatherAdapter({
+  provider: 'openweathermap-onecall',
+  apiKey: process.env.OPENWEATHER_API_KEY
+});
+
+const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
+```
+
+### Environment Variable Configuration
+
+```bash
+# .env
+HAVE_WEATHER_PROVIDER=openweathermap
+OPENWEATHER_API_KEY=your-api-key-here
+HAVE_WEATHER_TIMEOUT=15000
+```
+
+```typescript
+// Automatically uses environment variables
+const weather = await getWeatherAdapter();
+const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
+```
+
+## API Reference
+
+### `getWeatherAdapter(options?): Promise<IWeatherAdapter>`
+
+Factory function for creating weather adapters.
+
+**Options:**
+- `provider`: `'environment-canada' | 'openweathermap' | 'openweathermap-onecall'`
+- `apiKey`: API key (required for OpenWeatherMap providers)
+- `timeout`: Request timeout in milliseconds (default: 10000)
+
+### `IWeatherAdapter`
+
+```typescript
+interface IWeatherAdapter {
+  fetchForLocation(
+    latitude: number,
+    longitude: number,
+    options?: FetchOptions
+  ): Promise<WeatherForecast[]>
+
+  testConnection(): Promise<boolean>
+
+  supportsLocation(latitude: number, longitude: number): Promise<boolean>
+}
+```
+
+### `WeatherForecast`
+
+```typescript
+interface WeatherForecast {
+  timestamp: Date
+  temperature: number      // °C
+  feelsLike?: number       // °C
+  temperatureMin?: number  // °C
+  temperatureMax?: number  // °C
+  conditions: string       // Human-readable description
+  humidity: number         // Percentage 0-100
+  windSpeed: number        // km/h
+  windDirection?: number   // Degrees 0-360
+  windGust?: number        // km/h
+  pressure?: number        // hPa
+  cloudCover?: number      // Percentage 0-100
+  visibility?: number      // km
+  precipProbability?: number  // Percentage 0-100
+  precipAmount?: number    // mm
+  confidence?: number      // Provider's confidence 0-100
+  raw: any                 // Provider-specific raw data
+}
+```
+
+## Environment Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `HAVE_WEATHER_PROVIDER` | string | Provider name |
+| `OPENWEATHER_API_KEY` | string | OpenWeatherMap API key |
+| `HAVE_WEATHER_TIMEOUT` | number | Request timeout (ms) |
+
+## Provider Comparison
+
+| Feature | Environment Canada | OpenWeatherMap | OWM One Call |
+|---------|-------------------|----------------|--------------|
+| **Cost** | Free | Free tier available | Paid |
+| **Coverage** | Canada only | Global | Global |
+| **Forecast** | Day/night | 3-hour for 5 days | Hourly + daily |
+| **API Key** | Not required | Required | Required |
+| **Update Frequency** | ~hourly | 3 hours | hourly |
+
+## License
+
+MIT

package/dist/claude-context.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/cli/claude-context.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=claude-context.d.ts.map

package/dist/cli/claude-context.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { existsSync as o, mkdirSync as i, copyFileSync as m } from "node:fs";
+import { dirname as s, join as e } from "node:path";
+import { fileURLToPath as d } from "node:url";
+const l = s(d(import.meta.url)), t = e(l, "../.."), a = e(process.cwd(), ".claude");
+o(a) || i(a, { recursive: !0 });
+const n = "weather", r = o(e(t, "AGENT.md")) ? e(t, "AGENT.md") : e(t, "CLAUDE.md"), c = o(e(t, "metadata.json")) ? e(t, "metadata.json") : e(t, ".claude-meta.json");
+o(r) && m(r, e(a, `have-${n}.md`));
+o(c) && m(c, e(a, `have-${n}.meta.json`));
+console.log(`✓ Installed @happyvertical/${n} context to .claude/`);

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Authentication error - thrown when API key is invalid or missing
+ */
+export declare class AuthenticationError extends WeatherError {
+    constructor(provider: string, message?: string);
+}
+
+/**
+ * Calculate distance between two coordinates using Haversine formula
+ *
+ * @param lat1 - First latitude
+ * @param lon1 - First longitude
+ * @param lat2 - Second latitude
+ * @param lon2 - Second longitude
+ * @returns Distance in kilometers
+ */
+export declare function calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+
+/**
+ * Ensure coordinates are valid, throw error if not
+ *
+ * @param provider - Provider name for error messages
+ * @param latitude - Latitude to validate
+ * @param longitude - Longitude to validate
+ * @throws InvalidLocationError if coordinates are invalid
+ */
+export declare function ensureValidCoordinates(provider: string, latitude: number, longitude: number): void;
+
+/**
+ * Environment Canada provider options
+ */
+export declare interface EnvironmentCanadaOptions {
+    provider: 'environment-canada';
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+
+/**
+ * Convert temperature from Fahrenheit to Celsius
+ *
+ * @param fahrenheit - Temperature in Fahrenheit
+ * @returns Temperature in Celsius
+ */
+export declare function fahrenheitToCelsius(fahrenheit: number): number;
+
+/**
+ * Fetch options for weather data
+ */
+export declare interface FetchOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Maximum number of forecast periods to return */
+    limit?: number;
+    /** Force refresh even if cached data exists */
+    forceRefresh?: boolean;
+}
+
+/**
+ * Create a weather adapter instance
+ *
+ * @param options - Weather adapter options or undefined to use environment variables
+ * @returns Weather adapter instance
+ *
+ * @example
+ * ```typescript
+ * // Use environment variables (HAVE_WEATHER_PROVIDER, OPENWEATHER_API_KEY)
+ * const weather = await getWeatherAdapter();
+ *
+ * // Explicit configuration
+ * const weather = await getWeatherAdapter({
+ *   provider: 'openweathermap',
+ *   apiKey: 'your-api-key'
+ * });
+ * ```
+ */
+declare function getWeatherAdapter(options?: PartialWeatherAdapterOptions): Promise<IWeatherAdapter>;
+export default getWeatherAdapter;
+export { getWeatherAdapter }
+
+/**
+ * Google Weather API provider options
+ */
+export declare interface GoogleWeatherOptions {
+    provider: 'google-weather';
+    /** Google API key (required) */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+
+/**
+ * Fetch options for historical weather data.
+ */
+export declare interface HistoricalFetchOptions extends FetchOptions {
+    /** Start of the requested historical window */
+    start: Date | string;
+    /** End of the requested historical window. Defaults to start. */
+    end?: Date | string;
+    /** Requested granularity. Providers may support only hourly data. */
+    interval?: 'hourly';
+}
+
+/**
+ * Invalid location error - thrown when location is invalid or unsupported
+ */
+export declare class InvalidLocationError extends WeatherError {
+    constructor(provider: string, latitude: number, longitude: number, message?: string);
+}
+
+/**
+ * Check if location is in Canada (very rough approximation)
+ * Based on latitude/longitude bounding box
+ *
+ * @param latitude - Location latitude
+ * @param longitude - Location longitude
+ * @returns true if location appears to be in Canada
+ */
+export declare function isInCanada(latitude: number, longitude: number): boolean;
+
+/**
+ * Public weather adapter interface (identical to IWeatherProvider)
+ * This is the interface returned by getWeatherAdapter()
+ */
+export declare type IWeatherAdapter = IWeatherProvider;
+
+/**
+ * Core weather provider interface
+ * All weather providers must implement this interface
+ */
+export declare interface IWeatherProvider {
+    /** Provider name for logging and identification */
+    readonly name: string;
+    /** Provider type */
+    readonly providerType: 'government' | 'community' | 'commercial';
+    /**
+     * Fetch weather forecasts for a location
+     *
+     * @param latitude - Location latitude (-90 to 90)
+     * @param longitude - Location longitude (-180 to 180)
+     * @param options - Fetch options
+     * @returns Array of weather forecasts
+     */
+    fetchForLocation(latitude: number, longitude: number, options?: FetchOptions): Promise<WeatherForecast[]>;
+    /**
+     * Fetch historical weather observations for a location.
+     *
+     * Providers that cannot serve historical data must reject with
+     * UnsupportedWeatherCapabilityError instead of silently falling back.
+     *
+     * @param latitude - Location latitude (-90 to 90)
+     * @param longitude - Location longitude (-180 to 180)
+     * @param options - Historical fetch options
+     * @returns Array of historical weather observations
+     */
+    fetchHistoricalForLocation(latitude: number, longitude: number, options: HistoricalFetchOptions): Promise<WeatherForecast[]>;
+    /**
+     * Test connection to the weather API
+     *
+     * @returns true if connection successful, false otherwise
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Check if provider supports a specific location
+     *
+     * @param latitude - Location latitude
+     * @param longitude - Location longitude
+     * @returns true if location is supported
+     */
+    supportsLocation(latitude: number, longitude: number): Promise<boolean>;
+}
+
+/**
+ * Convert temperature from Kelvin to Celsius
+ *
+ * @param kelvin - Temperature in Kelvin
+ * @returns Temperature in Celsius
+ */
+export declare function kelvinToCelsius(kelvin: number): number;
+
+/**
+ * Convert wind speed from m/s to km/h
+ *
+ * @param metersPerSecond - Wind speed in m/s
+ * @returns Wind speed in km/h
+ */
+export declare function metersPerSecondToKmPerHour(metersPerSecond: number): number;
+
+/**
+ * Convert visibility from meters to kilometers
+ *
+ * @param meters - Visibility in meters
+ * @returns Visibility in kilometers
+ */
+export declare function metersToKilometers(meters: number): number;
+
+/**
+ * Convert wind speed from mph to km/h
+ *
+ * @param milesPerHour - Wind speed in mph
+ * @returns Wind speed in km/h
+ */
+export declare function milesPerHourToKmPerHour(milesPerHour: number): number;
+
+/**
+ * Convert visibility from miles to kilometers
+ *
+ * @param miles - Visibility in miles
+ * @returns Visibility in kilometers
+ */
+export declare function milesToKilometers(miles: number): number;
+
+/**
+ * No results error - thrown when provider returns no forecast data
+ */
+export declare class NoResultsError extends WeatherError {
+    constructor(provider: string, latitude: number, longitude: number);
+}
+
+/**
+ * Open-Meteo provider options
+ */
+export declare interface OpenMeteoOptions {
+    provider: 'open-meteo';
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+
+/**
+ * OpenWeatherMap One Call API provider options (paid tier)
+ */
+export declare interface OpenWeatherMapOneCallOptions {
+    provider: 'openweathermap-onecall';
+    /** OpenWeatherMap API key (required) */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+
+/**
+ * OpenWeatherMap provider options (free tier)
+ */
+export declare interface OpenWeatherMapOptions {
+    provider: 'openweathermap';
+    /** OpenWeatherMap API key (required) */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+
+/* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */
+
+/**
+ * Partial provider options for environment variable configuration
+ */
+export declare type PartialWeatherAdapterOptions = Partial<Omit<EnvironmentCanadaOptions, 'provider'>> & Partial<Omit<OpenWeatherMapOptions, 'provider'>> & Partial<Omit<OpenWeatherMapOneCallOptions, 'provider'>> & Partial<Omit<GoogleWeatherOptions, 'provider'>> & Partial<Omit<OpenMeteoOptions, 'provider'>> & {
+    provider?: 'environment-canada' | 'openweathermap' | 'openweathermap-onecall' | 'google-weather' | 'open-meteo';
+};
+
+/**
+ * Rate limit error - thrown when API rate limit is exceeded
+ */
+export declare class RateLimitError extends WeatherError {
+    constructor(provider: string, retryAfter?: number);
+}
+
+/**
+ * Unsupported capability error - thrown when a provider cannot serve an optional capability.
+ */
+export declare class UnsupportedWeatherCapabilityError extends WeatherError {
+    constructor(provider: string, capability: string, message?: string);
+}
+
+/**
+ * Shared utilities for weather providers
+ */
+/**
+ * Validate coordinates
+ *
+ * @param latitude - Latitude to validate (-90 to 90)
+ * @param longitude - Longitude to validate (-180 to 180)
+ * @returns Validation result with optional error message
+ */
+export declare function validateCoordinates(latitude: number, longitude: number): {
+    valid: boolean;
+    error?: string;
+};
+
+/**
+ * Discriminated union of all provider options
+ */
+export declare type WeatherAdapterOptions = EnvironmentCanadaOptions | OpenWeatherMapOptions | OpenWeatherMapOneCallOptions | GoogleWeatherOptions | OpenMeteoOptions;
+
+/**
+ * Weather alert from Google Weather API
+ */
+export declare interface WeatherAlert {
+    /** Alert identifier */
+    id: string;
+    /** Alert headline */
+    headline: string;
+    /** Detailed description */
+    description: string;
+    /** Severity level */
+    severity: string;
+    /** Alert start time */
+    startTime: Date;
+    /** Alert end time */
+    endTime: Date;
+    /** Raw API response */
+    raw: any;
+}
+
+/**
+ * Weather error - base class for weather-related errors
+ */
+export declare class WeatherError extends Error {
+    readonly provider: string;
+    readonly code?: string | undefined;
+    readonly details?: any | undefined;
+    constructor(message: string, provider: string, code?: string | undefined, details?: any | undefined);
+}
+
+/**
+ * Weather package type definitions
+ *
+ * Provides standardized interfaces for weather data providers
+ */
+/**
+ * Standard weather forecast data structure
+ * All providers must return this format
+ */
+export declare interface WeatherForecast {
+    /** Forecast timestamp */
+    timestamp: Date;
+    /** Temperature in Celsius */
+    temperature: number;
+    /** Feels-like temperature in Celsius (optional) */
+    feelsLike?: number;
+    /** Minimum temperature in Celsius (optional) */
+    temperatureMin?: number;
+    /** Maximum temperature in Celsius (optional) */
+    temperatureMax?: number;
+    /** Human-readable conditions description */
+    conditions: string;
+    /** Humidity percentage (0-100) */
+    humidity: number;
+    /** Wind speed in km/h */
+    windSpeed: number;
+    /** Wind direction in degrees (0-360, optional) */
+    windDirection?: number;
+    /** Wind gust speed in km/h (optional) */
+    windGust?: number;
+    /** Atmospheric pressure in hPa (optional) */
+    pressure?: number;
+    /** Cloud cover percentage (0-100, optional) */
+    cloudCover?: number;
+    /** Visibility in kilometers (optional) */
+    visibility?: number;
+    /** Precipitation probability percentage (0-100, optional) */
+    precipProbability?: number;
+    /** Precipitation amount in mm (optional) */
+    precipAmount?: number;
+    /** Provider's confidence in forecast (0-100, optional) */
+    confidence?: number;
+    /** Raw provider-specific data */
+    raw: any;
+}
+
+export { }