@happyvertical/weather

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5162

Weather data provider abstraction for HAppyVertical SDK

原始使用文档
文档目录17 节
  1. Overview
  2. Supported Providers
  3. Installation
  4. Claude Code Context
  5. Usage
  6. Basic Example
  7. OpenWeatherMap (Free Tier)
  8. OpenWeatherMap One Call (Paid Tier)
  9. Environment Variable Configuration
  10. API Reference
  11. getWeatherAdapter(options?): Promise<IWeatherAdapter>
  12. IWeatherAdapter
  13. WeatherForecast
  14. Environment Variables
  15. Testing
  16. Provider Comparison
  17. License

@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

pnpm add @happyvertical/weather

Claude Code Context

Install Claude Code context files for AI-assisted development:

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

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)

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)

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

# .env
HAVE_WEATHER_PROVIDER=openweathermap
OPENWEATHER_API_KEY=your-api-key-here
HAVE_WEATHER_TIMEOUT=15000
// 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

interface IWeatherAdapter {
  fetchForLocation(
    latitude: number,
    longitude: number,
    options?: FetchOptions
  ): Promise<WeatherForecast[]>

  testConnection(): Promise<boolean>

  supportsLocation(latitude: number, longitude: number): Promise<boolean>
}

WeatherForecast

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

VariableTypeDescription
HAVE_WEATHER_PROVIDERstringProvider name
OPENWEATHER_API_KEYstringOpenWeatherMap API key
HAVE_WEATHER_TIMEOUTnumberRequest timeout (ms)

Testing

The default suite is offline and deterministic, with one key-gated exception. Provider responses come from recorded fixtures in src/__tests__/fixtures/, so on a clean environment no test in test reaches the network:

pnpm turbo run test --filter=@happyvertical/weather

The exception is google-weather.spec.ts. It gates on GOOGLE_API_KEY, per the repository rule that a suite needing a real service gates on a key where one exists — see "Network isolation in the default suites" in .github/CI.md. With the key unset, its live block skips and the offline guarantee holds; that is how CI runs it. With the key exported, it calls the live Google Weather API from test.

Coverage against the other live services lives in *.optional.test.ts and is skipped unless you opt in. OpenWeatherMap gates on its API key; Environment Canada needs no key, so it gates on an explicit flag:

ENVIRONMENT_CANADA_INTEGRATION=1 pnpm --filter @happyvertical/weather test:optional

Run the live suite after re-recording a fixture, to confirm the upstream payload still matches the shape the offline suite asserts. See src/__tests__/fixtures/README.md for how each fixture was recorded.

Provider Comparison

FeatureEnvironment CanadaOpenWeatherMapOWM One Call
CostFreeFree tier availablePaid
CoverageCanada onlyGlobalGlobal
ForecastDay/night3-hour for 5 daysHourly + daily
API KeyNot requiredRequiredRequired
Update Frequency~hourly3 hourshourly

License

MIT

版本与发布记录

@happyvertical/weather 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.02026/11/125 天前
0.112.12026/11/125 天前

关于 @happyvertical/weather 的常见问题

@happyvertical/weather 是什么?

Weather data provider abstraction for HAppyVertical SDK

如何安装 @happyvertical/weather?

在项目目录运行 npm install @happyvertical/weather,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-weather-context,可以用 npx have-weather-context 直接运行。

@happyvertical/weather 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/weather 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/weather 可以商用吗?

@happyvertical/weather 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/weather 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/weather 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,162 次,日均约 172 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/weather 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。