npm package: @soblend/windy
Description: Professional TypeScript library for fetching meteorological data from Windy.com with API and scraping support
Author: soblend
Latest version: 1.0.0

# @soblend/windy

[![npm version](https://img.shields.io/npm/v/@soblend/windy.svg)](https://www.npmjs.com/package/@soblend/windy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Professional TypeScript library for fetching meteorological data from Windy.com**

A robust, well-documented library that provides a programmatic API to obtain weather data (wind, temperature, pressure, layers, forecasts, etc.) from Windy.com. Supports both official API and ethical web scraping with comprehensive rate limiting, caching, retries, and error handling.

---

## ⚠️ Important Legal Notice

**Please read carefully before using this library:**

- **API Mode (Recommended)**: If you have access to Windy's official API, this library will use it as the primary method. This is the recommended and fully legal approach.
- **Scraping Mode**: When no API key is provided, the library can fall back to web scraping. This mode:
  - Respects `robots.txt` by default
  - Implements conservative rate limiting
  - Should only be used for personal, non-commercial projects
  - **You are responsible for compliance with Windy's Terms of Service**
- **Not for Production Abuse**: Do not use scraping mode to bypass API restrictions, overload Windy's servers, or violate their terms
- **Check Windy's Terms**: Always review [Windy's Terms of Service](https://www.windy.com/terms) before use

**By using this library, you agree to use it ethically and responsibly.**

---

## ✨ Features

- 🔑 **Dual Mode**: Official API support (preferred) and ethical web scraping fallback
- 🎯 **TypeScript First**: Full type safety and IntelliSense support
- 🚀 **Production Ready**: Rate limiting, retries, circuit breaker, caching
- 🌐 **Flexible**: Works in Node.js and browser environments
- 📦 **Zero Config**: Works out of the box with sensible defaults
- 🧪 **Well Tested**: Comprehensive unit and E2E test coverage
- 📖 **Documented**: Complete API documentation and examples

---

## 📦 Installation

```bash
npm install @soblend/windy
```

### Peer Dependencies

If using scraping mode, Playwright will be installed automatically:

```bash
npx playwright install chromium
```

---

## 🚀 Quick Start

### With Official API (Recommended)

```typescript
import { WindyClient } from '@soblend/windy';

const client = new WindyClient({
  windyApiKey: 'YOUR_API_KEY', // Get from Windy
  mode: 'api'
});

// Get weather data for a point
const data = await client.getPointData(50.0, 14.5);
console.log(`Wind: ${data.wind.speed} m/s, Temp: ${data.temperature}°C`);

await client.close();
```

### With Scraping (Use Responsibly)

```typescript
import { WindyClient } from '@soblend/windy';

const client = new WindyClient({
  mode: 'scrape',
  checkRobotsTxt: true, // Respect robots.txt
  rateLimit: {
    maxRequests: 5,
    interval: 1000 // 5 requests per second
  }
});

const data = await client.getPointData(40.7128, -74.0060); // NYC
console.log(data);

await client.close();
```

---

## 📚 API Documentation

### `new WindyClient(config?)`

Creates a new Windy client instance.

#### Configuration Options

```typescript
interface WindyClientConfig {
  // API key for official Windy API
  windyApiKey?: string;
  
  // Operation mode: 'api', 'scrape', or 'auto'
  // 'auto' uses API if key provided, otherwise scraping
  mode?: 'api' | 'scrape' | 'auto';
  
  // Rate limiting
  rateLimit?: {
    maxRequests: number;  // Default: 10
    interval: number;     // In ms, default: 1000
  };
  
  // Retry configuration
  retry?: {
    maxRetries: number;        // Default: 3
    initialDelay: number;      // In ms, default: 1000
    maxDelay: number;          // In ms, default: 10000
    backoffMultiplier: number; // Default: 2
  };
  
  // Circuit breaker
  circuitBreaker?: {
    failureThreshold: number;  // Default: 5
    successThreshold: number;  // Default: 2
    timeout: number;           // In ms, default: 60000
  };
  
  // Browser pool (scraping mode)
  browserPool?: {
    maxInstances: number;       // Default: 3
    maxPagesPerInstance: number; // Default: 5
    idleTimeout: number;        // In ms, default: 60000
  };
  
  // Caching
  cache?: CacheAdapter;  // Default: LRU in-memory cache
  cacheTTL?: number;     // In seconds, default: 300
  
  // Other
  timeout?: number;           // Request timeout in ms, default: 30000
  logLevel?: 'none' | 'info' | 'debug'; // Default: 'info'
  checkRobotsTxt?: boolean;   // Check robots.txt, default: true
}
```

### Methods

#### `getPointData(lat, lon, options?)`

Get meteorological data for a specific geographic point.

```typescript
const data = await client.getPointData(50.0, 14.5);

// Returns:
interface WindyPointData {
  lat: number;
  lon: number;
  timestamp: string;
  wind: {
    speed: number;      // m/s
    direction: number;  // degrees 0-360
    gust?: number;      // m/s
  };
  temperature: number;  // °C
  pressure: number;     // hPa
  layerUrls?: Record<string, string>;
  raw?: any;
}
```

**Options:**
- `timeout?: number` - Override default timeout
- `skipCache?: boolean` - Skip cache for this request
- `mode?: ClientMode` - Force specific mode for this request
- `signal?: AbortSignal` - Abort signal for cancellation

#### `getAreaData(bbox, options?)`

Get meteorological data for a geographic area.

```typescript
// BBox format: [minLon, minLat, maxLon, maxLat]
const bbox: BBox = [14.0, 49.0, 15.0, 50.0];
const data = await client.getAreaData(bbox);

// Returns:
interface WindyAreaData {
  bbox: BBox;
  timestamp: string;
  points: WindyPointData[];
  stats?: {
    avgWind: number;
    maxWind: number;
    avgTemp: number;
    avgPressure: number;
  };
  raw?: any;
}
```

#### `getLayer(name, timestamp?, bbox?, options?)`

Get layer data (wind, clouds, precipitation, etc.).

```typescript
const layer = await client.getLayer('wind', undefined, bbox);

// Returns:
interface LayerData {
  name: string;
  timestamp: string;
  bbox?: BBox;
  url?: string;
  data?: any;
  raw?: any;
}
```

#### `screenshotMap(options?)`

Take a screenshot of the Windy map (scraping mode only).

```typescript
const buffer = await client.screenshotMap({
  layer: 'wind',
  bbox: [14.0, 49.0, 15.0, 50.0],
  width: 1920,
  height: 1080,
  format: 'png'
});

// Save to file
import fs from 'fs';
fs.writeFileSync('map.png', buffer);
```

#### `close()`

Close all resources (browser instances, cache, etc.).

```typescript
await client.close();
```

#### `getCircuitBreakerState()`

Get current circuit breaker state (`'CLOSED'`, `'OPEN'`, or `'HALF_OPEN'`).

```typescript
console.log(client.getCircuitBreakerState());
```

#### `resetCircuitBreaker()`

Manually reset the circuit breaker.

```typescript
client.resetCircuitBreaker();
```

---

## 🔧 Advanced Usage

### Custom Cache Adapter

Implement custom caching (e.g., Redis):

```typescript
import { CacheAdapter } from '@soblend/windy';
import Redis from 'ioredis';

class RedisCache implements CacheAdapter {
  private redis: Redis;
  
  constructor() {
    this.redis = new Redis();
  }
  
  async get(key: string) {
    const value = await this.redis.get(key);
    return value ? JSON.parse(value) : null;
  }
  
  async set(key: string, value: any, ttlSeconds = 300) {
    await this.redis.setex(key, ttlSeconds, JSON.stringify(value));
  }
  
  async delete(key: string) {
    await this.redis.del(key);
  }
  
  async clear() {
    await this.redis.flushdb();
  }
}

const client = new WindyClient({
  cache: new RedisCache(),
  cacheTTL: 600 // 10 minutes
});
```

### Error Handling

```typescript
import { WindyError, WindyErrorCode } from '@soblend/windy';

try {
  const data = await client.getPointData(50, 14);
} catch (error) {
  if (error instanceof WindyError) {
    switch (error.code) {
      case WindyErrorCode.RATE_LIMIT_EXCEEDED:
        console.error('Rate limit hit, wait before retrying');
        break;
      case WindyErrorCode.ROBOTS_TXT_DISALLOWED:
        console.error('Scraping not allowed by robots.txt');
        break;
      case WindyErrorCode.CIRCUIT_BREAKER_OPEN:
        console.error('Service temporarily unavailable');
        break;
      default:
        console.error('Error:', error.message);
    }
  }
}
```

### Request Cancellation

```typescript
const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const data = await client.getPointData(50, 14, {
    signal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request cancelled');
  }
}
```

---

## 🧪 Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

---

## 🛠️ Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

# Type check
npm run type-check
```

---

## 📝 Examples

See the `/examples` directory for complete working examples:

- **Basic Usage** (`examples/basic.ts`)
- **Area Data** (`examples/area.ts`)
- **Screenshots** (`examples/screenshot.ts`)
- **Custom Cache** (`examples/redis-cache.ts`)

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT © soblend

See [LICENSE](./LICENSE) for details.

---

## 🙏 Acknowledgments

- Weather data provided by [Windy.com](https://www.windy.com)
- Built with [Playwright](https://playwright.dev/) for browser automation
- Powered by [TypeScript](https://www.typescriptlang.org/)

---

## ⚡ Performance Tips

1. **Use API mode when possible** - Much faster and more reliable
2. **Enable caching** - Reduces redundant requests
3. **Tune rate limits** - Balance between speed and respect for service
4. **Reuse client instances** - Browser pool initialization is expensive
5. **Use AbortSignal** - Cancel slow requests to free resources

---

## 📞 Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/soblend/windy/issues)
- 📖 **Documentation**: This README and inline JSDoc
- 💬 **Discussions**: [GitHub Discussions](https://github.com/soblend/windy/discussions)

---

## 🗺️ Roadmap

- [ ] Support for more Windy layers
- [ ] Batch operations for multiple points
- [ ] Stream API for real-time updates
- [ ] CLI tool
- [ ] Docker container with pre-configured browser

---

**Made with ❤️ by soblend**