# Compatibility notes

## Runtime requirements

- Node.js `>=20.0.0`
- Pi extension runtime (`@earendil-works/pi-coding-agent` `>=0.79.0 <0.81.0`)
- Outbound HTTPS access to `api.currentsapi.services`
- A valid `CURRENTS_API_KEY` environment variable

## Currents API version

This package targets the Currents **v2** endpoints:

- `https://api.currentsapi.services/v2/latest-news`
- `https://api.currentsapi.services/v2/search`

v2 is used because it exposes the canonical category taxonomy
(`general, society, science_technology, politics_government,
economy_business_finance, arts_culture_entertainment, lifestyle_leisure,
human_interest, sport, crime_law_justice, education, environment, labour,
health, automotive, real_estate`) that the category toggle list in this
package is built around. v1 category values are legacy and not used here.

## Authentication

Requests send `Authorization: Bearer <CURRENTS_API_KEY>`. Currents also
accepts `apiKey` as a query parameter, but this package never uses that form
so the key cannot leak into logs, proxies, or browser history.

## Rate limits

Currents enforces a daily request quota per API key (free tier: 1,000
requests/day at the time of writing). Every authenticated response includes
`X-RateLimit-Remaining` and `X-RateLimit-Limit` headers; this package reads
them and can surface the remaining quota in `/news_refresh` output. Because
`/v2/latest-news` accepts multiple `category` values in a single request,
enabling more categories does not increase request count — only refreshing
more often does.

## Known constraints

- `page_size` is capped by the Currents API at 300 per request and may be lower
  for some plans; this package conservatively requests 20 for latest-news and
  search so free-tier requests are accepted.
- `page_number * page_size` beyond roughly 5,000 is rejected by Currents'
  offset guardrail; this package only ever requests page 1.
- Search-only parameters (`keywords`, `query`, `start_date`, `end_date`,
  `cursor`, etc.) are rejected by `/latest-news`; this package never mixes
  them.
- Article `published` timestamps are provided in UTC (`+0000`); this package
  parses them directly with `Date.parse`, which accepts Currents'
  `YYYY-MM-DD HH:mm:ss +0000` format without transformation.

## Verifying compatibility locally

```bash
npm install
npm test
npm pack --dry-run
```

`npm test` runs typecheck, build, and the non-network unit suite. No suite in
this repository makes live calls to the Currents API.