RiverSat Developers

I want to integrate the RiverSat API into this codebase using the TypeScript client library provided below. RiverSat provides river water level data, forecasts, and discharge information via a REST API.


## API Overview

**Base URL:** https://api.insights.earthdaily.com
**Authentication:** Bearer API key in Authorization header
**Response Format:** CSV (default) or JSON. Add `?format=json` to any data endpoint for JSON array responses.

## Available Endpoints

| Endpoint | Description |
|----------|-------------|
| GET /v1/rivers | List available rivers |
| GET /v1/rivers/{river}/discharge | Get discharge data |
| GET /v1/rivers/{river}/daily-levels | Get daily water levels |
| GET /v1/rivers/{river}/daily-levels/{station} | Get levels for specific station |
| GET /v1/rivers/{river}/forecast | Get forecast data |
| GET /v1/rivers/{river}/historical-forecast | Get historical forecasts |
| GET /v1/rivers/{river}/historical-forecast/{station}/{year} | Get forecast by station and year |

## Supported Rivers and Stations

**Rhine River (rhine):**
- maxau, kaub, cologne, duisburg, emmerich

**Mississippi River (mississippi):**
- st_paul_mn, winona_mn, camanche_ia, grafton_il

## TypeScript Client Library

Add this client library to your project as `riversat-client.ts`:

```typescript
const API_BASE_URL = 'https://api.insights.earthdaily.com'

type River = 'rhine' | 'mississippi'
type Format = 'csv' | 'json'

interface RiverInfo {
  id: string
  display_name: string
  is_mock: boolean
  data_sources: string[]
}

// Configuration
let authToken: string | null = null

export function setToken(token: string) {
  authToken = token
}

// Helper for authenticated requests
async function fetchWithAuth(url: string): Promise<Response> {
  if (!authToken) {
    throw new Error('No auth token set. Call setToken() first.')
  }
  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${authToken}` }
  })
  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`)
  }
  return response
}

// Helper to append format parameter to URL
function withFormat(url: string, format: Format): string {
  if (format === 'csv') return url
  const sep = url.includes('?') ? '&' : '?'
  return url + sep + 'format=' + format
}

// Helper to parse response based on format
async function parseResponse(response: Response, format: Format): Promise<string | object[]> {
  if (format === 'json') return response.json()
  return response.text()
}

// List all available rivers
async function listRivers(): Promise<RiverInfo[]> {
  const response = await fetchWithAuth(`${API_BASE_URL}/v1/rivers`)
  return response.json()
}

// Get river discharge data (CSV or JSON)
async function getDischarge(
  river: River,
  stationName: string,
  startDate: string,
  endDate?: string,
  format: Format = 'csv'
): Promise<string | object[]> {
  const params = new URLSearchParams({ station_name: stationName, start_date: startDate })
  if (endDate) params.set('end_date', endDate)
  if (format !== 'csv') params.set('format', format)
  const response = await fetchWithAuth(`${API_BASE_URL}/v1/rivers/${river}/discharge?${params}`)
  return parseResponse(response, format)
}

// Get daily river levels (CSV or JSON)
async function getDailyLevels(
  river: River,
  options?: { includeHistorical?: boolean; format?: Format }
): Promise<string | object[]> {
  const fmt = options?.format ?? 'csv'
  let url = `${API_BASE_URL}/v1/rivers/${river}/levels/daily`
  if (options?.includeHistorical) url += '?include_historical=true'
  url = withFormat(url, fmt)
  const response = await fetchWithAuth(url)
  return parseResponse(response, fmt)
}

// Get daily levels for a specific station and date range (CSV or JSON)
async function getDailyLevelsByStation(
  river: River,
  station: string,
  startDate: string,
  endDate: string,
  format: Format = 'csv'
): Promise<string | object[]> {
  const params = new URLSearchParams({ start_date: startDate, end_date: endDate })
  const url = withFormat(
    `${API_BASE_URL}/v1/rivers/${river}/levels/daily/${station}?${params}`,
    format
  )
  const response = await fetchWithAuth(url)
  return parseResponse(response, format)
}

// Get recent forecast data (CSV or JSON)
async function getForecast(river: River, format: Format = 'csv'): Promise<string | object[]> {
  const url = withFormat(`${API_BASE_URL}/v1/rivers/${river}/forecast`, format)
  const response = await fetchWithAuth(url)
  return parseResponse(response, format)
}

// Get historical forecast for a specific station and year (CSV or JSON)
async function getForecastByStationYear(
  river: River,
  station: string,
  year: number,
  format: Format = 'csv'
): Promise<string | object[]> {
  const url = withFormat(
    `${API_BASE_URL}/v1/rivers/${river}/forecast/historical/${station}/${year}`,
    format
  )
  const response = await fetchWithAuth(url)
  return parseResponse(response, format)
}

export const riversat = {
  setToken,
  listRivers,
  getDischarge,
  getDailyLevels,
  getDailyLevelsByStation,
  getForecast,
  getForecastByStationYear
}

```

## OpenAPI Specification

For complete API details, schemas, and additional endpoints, refer to the OpenAPI spec:
https://api.insights.earthdaily.com/openapi.json

## Your Task

1. **Analyze the codebase** to understand the architecture and identify where river data would be valuable
2. **Find relevant modules** that handle logistics, shipping, supply chain, weather, or environmental data
3. **Identify integration points** where water level data, forecasts, or discharge info would add value
4. **Create a mapping** between any existing location/port data and RiverSat station IDs
5. **Add the client library** to an appropriate location in the project
6. **Implement API calls** where the data should be fetched and displayed
7. **Handle authentication** by integrating with the project's existing auth/config patterns

Present your findings as a structured plan before implementing.