Add OpenWeather connector with weather, forecast, air pollution, and geocoding resources

connector-registry/openweather/_meta/README.md

@@ -0,0 +1,6 @@
+# openweather (Registry)
+
+This is the top-level registry entry for `openweather`.
+
+- Versions live under `openweather/v1`
+- See author implementations under `openweather/v1/514-labs`

connector-registry/openweather/_meta/connector.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://schemas.connector-factory.dev/connector-root.schema.json",
+  "identifier": "openweather",
+  "name": "OpenWeather",
+  "category": "api",
+  "tags": ["weather"],
+  "description": "Connector for OpenWeatherMap API providing current weather, forecasts, air pollution data, and geocoding services",
+  "homepage": "https://openweathermap.org"
+}

connector-registry/openweather/v1/514-labs/_meta/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this connector will be documented in this file.
+
+## 0.1.0 - Scaffold created
+
+- Initial scaffold for `openweather` (TypeScript) added.

connector-registry/openweather/v1/514-labs/_meta/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 514-labs
+
+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 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.

connector-registry/openweather/v1/514-labs/_meta/README.md

@@ -0,0 +1,10 @@
+# openweather Connector (by 514-labs)
+
+This directory contains language-agnostic metadata and documentation for the `openweather` connector.
+
+- Name: `openweather`
+- Author: `514-labs`
+- Category: `api`
+- Languages: `typescript`
+
+See `_meta/connector.json` for connector metadata and implementation folders for language-specific code.

connector-registry/openweather/v1/514-labs/_meta/connector.json

@@ -0,0 +1,22 @@
+{
+  "name": "openweather",
+  "author": "514-labs",
+  "version": "v1",
+  "languages": [
+    "typescript"
+  ],
+  "category": "api",
+  "capabilities": {
+    "extract": true,
+    "transform": false,
+    "load": false
+  },
+  "source": {
+    "type": "api",
+    "spec": "https://openweathermap.org/api",
+    "homepage": "https://openweathermap.org"
+  },
+  "tags": ["weather", "forecast", "climate", "air-pollution", "geocoding"],
+  "maintainers": [],
+  "issues": { "typescript": { "default": "" } }
+}

connector-registry/openweather/v1/514-labs/typescript/_meta/connector.json

@@ -0,0 +1,8 @@
+{
+  "identifier": "openweather",
+  "name": "openweather",
+  "author": "514-labs",
+  "version": "v1",
+  "language": "typescript",
+  "implementations": ["default"]
+}

connector-registry/openweather/v1/514-labs/typescript/default/.env.example

@@ -0,0 +1,3 @@
+# OpenWeather API Key
+# Get your API key from: https://openweathermap.org/api
+OPENWEATHER_API_KEY=

connector-registry/openweather/v1/514-labs/typescript/default/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.env

connector-registry/openweather/v1/514-labs/typescript/default/CONNECTOR_GUIDE.md

@@ -0,0 +1,83 @@
+# Connector Implementation Guide
+
+This guide walks you through implementing your `openweather` connector from scaffold to production.
+
+**📖 For detailed step-by-step instructions, see:**
+`connector-registry/_scaffold/CONNECTOR_IMPLEMENTATION_GUIDE.md`
+
+Or view online: [Connector Implementation Guide](../../../../../../_scaffold/CONNECTOR_IMPLEMENTATION_GUIDE.md)
+
+## Quick Checklist
+
+### Phase 1: Understand Your API ✓
+- [ ] Read the `openweather` API documentation
+- [ ] Identify authentication method
+- [ ] Understand pagination pattern
+- [ ] Note rate limits
+- [ ] Identify key endpoints
+
+### Phase 2: Scaffold ✓
+- [x] Connector scaffolded
+
+### Phase 3: Configure Authentication
+- [ ] Update `ConnectorConfig` type in `src/client/connector.ts`
+- [ ] Implement `init()` method to set up auth
+- [ ] Update `.env.example` with required credentials
+
+### Phase 4: Implement Pagination
+- [ ] Choose pagination pattern (offset/cursor/page)
+- [ ] Implement in `src/lib/paginate.ts`
+- [ ] Test with API to verify it works
+
+### Phase 5: Implement Resources
+- [ ] Define resource types in `src/resources/weather.ts`
+- [ ] Implement list/get/create methods as needed
+- [ ] Add resource getters to connector class
+
+### Phase 6: Add Schemas
+- [ ] Create JSON schemas in `schemas/raw/json/`
+- [ ] Add documentation `.md` files
+- [ ] Register in `schemas/index.json`
+
+### Phase 7: Update Documentation
+- [ ] Update `README.md` with examples
+- [ ] Document config in `docs/configuration.md`
+- [ ] Update `.env.example`
+
+### Phase 8: Write Tests
+- [ ] Update `tests/resource.test.ts`
+- [ ] Add observability tests if using logging/metrics
+- [ ] Test pagination edge cases
+
+### Phase 9: Build & Test
+- [ ] Run `pnpm run build` - should complete without errors
+- [ ] Run `pnpm test` - all tests should pass
+- [ ] Try `examples/basic-usage.ts` with real API
+
+### Phase 10: Real-World Testing
+- [ ] Test with real credentials
+- [ ] Verify pagination with large datasets
+- [ ] Test error handling
+- [ ] Test rate limiting (if applicable)
+
+## Common Patterns
+
+See the detailed guide for code examples of:
+- Simple API key authentication
+- Bearer token authentication
+- OAuth2 authentication
+- Offset-based pagination
+- Cursor-based pagination
+- Page number pagination
+
+## Reference Connectors
+
+Look at these for examples:
+- **Socrata** (`connector-registry/socrata/`): Simple API with offset pagination
+- **Meta Ads** (`connector-registry/meta-ads/`): OAuth2 with cursor pagination
+- **Google Analytics** (`connector-registry/google-analytics/`): Service account auth
+
+## Need Help?
+
+Refer to the full implementation guide at:
+`connector-registry/_scaffold/CONNECTOR_IMPLEMENTATION_GUIDE.md`

connector-registry/openweather/v1/514-labs/typescript/default/README.md

@@ -0,0 +1,107 @@
+# OpenWeather Connector (TypeScript)
+
+TypeScript connector for the OpenWeatherMap API by `514-labs`.
+
+## Features
+
+- ✅ Current weather data
+- ✅ 5-day / 3-hour forecast
+- ✅ Air pollution data (current, forecast, historical)
+- ✅ Geocoding (direct, reverse, ZIP code)
+- ✅ Multiple location formats (city name, coordinates, ZIP, city ID)
+- ✅ Multiple units (metric, imperial, standard)
+- ✅ Multi-language support
+- ✅ Built-in logging and metrics
+- ✅ TypeScript type definitions
+
+## Quick Start
+
+```typescript
+import { createConnector } from '@workspace/connector-openweather'
+
+const conn = createConnector()
+conn.init({
+  apiKey: process.env.OPENWEATHER_API_KEY!
+})
+
+// Get current weather
+const weather = await conn.weather.getCurrent({
+  q: 'London,UK',
+  units: 'metric'
+})
+console.log(`Temperature: ${weather.main.temp}°C`)
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - Quick start guide and examples
+- [Configuration](docs/configuration.md) - API key setup and configuration options
+- [Limits](docs/limits.md) - API rate limits and best practices
+- [Observability](docs/observability.md) - Logging and metrics
+- [Schemas](docs/schema.md) - Data schemas and types
+
+## API Resources
+
+### Weather
+```typescript
+// Current weather by city name
+const weather = await conn.weather.getCurrent({ q: 'London,UK', units: 'metric' })
+
+// Current weather by coordinates
+const weather = await conn.weather.getCurrent({ lat: 51.5074, lon: -0.1278, units: 'metric' })
+
+// Multiple cities
+const data = await conn.weather.getMultipleCities([2643743, 5368361], { units: 'metric' })
+```
+
+### Forecast
+```typescript
+// 5-day / 3-hour forecast
+const forecast = await conn.forecast.get5Day3Hour({
+  q: 'London,UK',
+  units: 'metric',
+  cnt: 8  // First 8 timestamps (24 hours)
+})
+```
+
+### Air Pollution
+```typescript
+// Current air quality
+const current = await conn.airPollution.getCurrent({ lat: 51.5074, lon: -0.1278 })
+
+// Air quality forecast
+const forecast = await conn.airPollution.getForecast({ lat: 51.5074, lon: -0.1278 })
+
+// Historical data (requires start and end unix timestamps)
+const historical = await conn.airPollution.getHistorical({
+  lat: 51.5074,
+  lon: -0.1278,
+  start: 1606223802,
+  end: 1606482999
+})
+```
+
+### Geocoding
+```typescript
+// Get coordinates by city name
+const locations = await conn.geocoding.getByLocationName({ q: 'London', limit: 5 })
+
+// Reverse geocoding
+const locations = await conn.geocoding.getByCoordinates({ lat: 51.5074, lon: -0.1278 })
+
+// By ZIP code
+const location = await conn.geocoding.getByZipCode({ zip: '94040,US' })
+```
+
+## Requirements
+
+- Node.js 20+
+- OpenWeather API key (get one at [openweathermap.org](https://openweathermap.org/api))
+
+## License
+
+MIT
+
+> **📖 Implementation Guide**: See `CONNECTOR_GUIDE.md` for step-by-step instructions on implementing this connector.
+
+Schemas: see `schemas/index.json` for machine-readable definitions and accompanying Markdown docs.

connector-registry/openweather/v1/514-labs/typescript/default/docs/configuration.md

@@ -0,0 +1,84 @@
+# Configuration
+
+## Required Configuration
+
+### `apiKey` (required)
+Your OpenWeather API key. Get one from [https://openweathermap.org/api](https://openweathermap.org/api).
+
+```typescript
+conn.init({
+  apiKey: 'your-api-key-here'
+})
+```
+
+## Optional Configuration
+
+### `baseUrl` (optional)
+Override the default API base URL. Default: `https://api.openweathermap.org`
+
+```typescript
+conn.init({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.openweathermap.org'  // custom base URL
+})
+```
+
+### `logging` (optional)
+Configure request/response logging.
+
+```typescript
+conn.init({
+  apiKey: 'your-api-key',
+  logging: {
+    enabled: true,
+    level: 'info',  // 'debug' | 'info' | 'warn' | 'error'
+    includeQueryParams: true,
+    includeHeaders: false,
+    includeBody: false,
+    logger: (level, event) => console.log(level, event)  // custom logger
+  }
+})
+```
+
+### `metrics` (optional)
+Enable metrics collection.
+
+```typescript
+conn.init({
+  apiKey: 'your-api-key',
+  metrics: {
+    enabled: true
+  }
+})
+
+// Access metrics (if enabled)
+const metricsSink = (conn as any)._metricsSink
+console.log(metricsSink.events)
+```
+
+## Environment Variables
+
+Create a `.env` file in your project:
+
+```bash
+OPENWEATHER_API_KEY=your-api-key-here
+```
+
+Then use it:
+
+```typescript
+import 'dotenv/config'
+
+conn.init({
+  apiKey: process.env.OPENWEATHER_API_KEY!
+})
+```
+
+## API Key Setup
+
+1. Sign up at [https://openweathermap.org/home/sign_up](https://openweathermap.org/home/sign_up)
+2. Navigate to API keys section in your account
+3. Generate a new API key
+4. Wait a few hours for the key to be activated
+5. Use the key in your connector configuration
+