@ 喜悦的垂直/ 天气
HappyVertical SDK的天气数据提供者抽象.
概览
这个 @happyvertical/weather 软件包为从多个供应商获取天气预报提供了统一的接口。 它遵循的建筑模式与 @happyvertical/ai, (中文(简体) ), @happyvertical/files,以及 @happyvertical/sql。 。 。 .
支持供应商
- 加拿大环境部 - 为加拿大各地提供政府气象服务(免费)
- 打开WeatherMap - 免费和付费的全球气象数据
- 标准API:5天/3小时预报(免费分级)
- 1呼叫API 3.0:48小时+8天每日预报(付费级)
安装
pnpm add @happyvertical/weather
Claude 代码背景
为 AI 辅助开发安装 Claude 代码上下文文件 :
npx have-weather-context
这个复制包 AGENT.md 文献和记录 metadata.json 元数据到您的项目 .claude/ 目录,使克洛德能够在使用该套件时提供更好的帮助.
使用量
基本示例
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}`);
});
打开WeatherMap( 自由地层)
const weather = await getWeatherAdapter({
provider: 'openweathermap',
apiKey: process.env.OPENWEATHER_API_KEY
});
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
OpenWeatherMap 一个呼叫( 援助级别)
const weather = await getWeatherAdapter({
provider: 'openweathermap-onecall',
apiKey: process.env.OPENWEATHER_API_KEY
});
const forecasts = await weather.fetchForLocation(51.0447, -114.0719);
环境可变配置
# .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 参考
getWeatherAdapter(options?): Promise<IWeatherAdapter>
工厂用于创建天气适配器的功能.
选项 :
provider数字 :'environment-canada' | 'openweathermap' | 'openweathermap-onecall'apiKey: API 密钥( OpenWeatherMap 提供者需要此密钥)timeout: 请求超时, 以毫秒计( 默认: 1 000)
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
}
环境变量
| 变量 | 类型 | 说明 |
|---|---|---|
HAVE_WEATHER_PROVIDER | 字符串 | 提供者名称 |
OPENWEATHER_API_KEY | 字符串 | 打开WeatherMap API 密钥 |
HAVE_WEATHER_TIMEOUT | 编号 | 请求超时( 毫秒) |
测试
默认的套房是离线的和决定性的,有一个按键的例外.
提供方的答复来自所记录的固定装置 src/__tests__/fixtures/这样
没有在清洁环境中试验 test 到达网络 :
pnpm turbo run test --filter=@happyvertical/weather
例外的是 google-weather.spec.ts打开门 GOOGLE_API_KEY按
寄存器 :
已存在 —— 见“ 默认套房中的网络隔离 ” .github/CI.md与
键未设置, 它的活块跳过, 离线保证
中情局负责 随密钥导出, 它调用实时 Google Weather API from
test。 。 。 .
其他现场服务的覆盖率 *.optional.test.ts 已经
跳过,除非你选择加入。 在其 API 密钥上打开 WeatherMap 门; 环境
加拿大不需要钥匙,所以它在一面明快的旗帜上登出大门:
ENVIRONMENT_CANADA_INTEGRATION=1 pnpm --filter @happyvertical/weather test:optional
在重新录制固定装置后运行活套房,以确认上游有效载荷
仍然符合离线套房的形状。 见
src/__tests__/fixtures/README.md 记录每个固定.
提供者比较
| 特性 | 加拿大环境部 | 打开WeatherMap | OWM 一通电话 |
|---|---|---|---|
| 费用 | 免费 | 可自由分级 | 已支付 |
| 覆盖范围 | 仅加拿大 | 全球 | 全球 |
| 预测 | 每日/夜间 | 3小时5天 | 小时+每日 |
| API 密钥 | 无需 | 需求 | 需求 |
| 更新频率 | ~小时~ | 3小时 | 小时 |
许可证
麻省理工学院