feat: add AccuWeather recipe and update backend-restapi documentation with roadmap items

Author: crapougnax

packages/backend-restapi-recipes/README.md

@@ -7,6 +7,7 @@ REST APIs have wildly different standards for pagination, filtering, and authent
 
 ## Available Recipes
 - **OpenWeatherMap**: Maps `city`, `lat`, and `lon` filters to the appropriate query strings (`q`, `lat`, `lon`), and automatically injects the `appid` key.
+- **AccuWeather**: Translates location searches (`q`, `city`, `locationKey`) and automatically injects `apikey`, `language`, and `details=true`.
 - **CoinGecko**: Translates standard Quatrain pagination into CoinGecko's `page` and `per_page` query parameters.
 
 ## Basic Usage

packages/backend-restapi-recipes/src/AccuweatherRecipe.ts

@@ -0,0 +1,44 @@
+import { Filters, Filter, SortAndLimit } from '@quatrain/backend'
+import { RestAdapterOptions, QuerySerializer } from '@quatrain/backend-restapi'
+import { RestApiRecipe } from './RestApiRecipe'
+
+export class AccuweatherRecipe implements RestApiRecipe {
+   public name = 'AccuWeather'
+   public defaultBaseUrl = 'http://dataservice.accuweather.com'
+
+   private apiKey: string
+
+   constructor(apiKey: string) {
+      this.apiKey = apiKey
+   }
+
+   public querySerializer: QuerySerializer = (filters: Filters | Filter[] | undefined, pagination: SortAndLimit | undefined) => {
+      const params: Record<string, string> = {
+         apikey: this.apiKey,
+         language: 'en-us',
+         details: 'true'
+      }
+
+      if (filters) {
+         const filterArray = Array.isArray(filters) ? filters : [filters]
+         for (const f of filterArray) {
+            if ('property' in f && 'value' in f) {
+               // AccuWeather often uses 'q' for location searches
+               if (f.property === 'q' || f.property === 'city') params['q'] = String(f.value)
+               // For geocoding or specific keys
+               if (f.property === 'locationKey') params['locationKey'] = String(f.value)
+            }
+         }
+      }
+
+      return params
+   }
+
+   public getOptions(overrides?: Partial<RestAdapterOptions>): RestAdapterOptions {
+      return {
+         baseUrl: this.defaultBaseUrl,
+         querySerializer: this.querySerializer,
+         ...overrides
+      }
+   }
+}

packages/backend-restapi-recipes/src/index.ts

@@ -1,3 +1,4 @@
 export * from './RestApiRecipe'
 export * from './OpenWeatherMapRecipe'
 export * from './CoinGeckoRecipe'
+export * from './AccuweatherRecipe'

packages/backend-restapi/README.md

@@ -48,3 +48,8 @@ class CustomRestAdapter extends RestBackendAdapter {
 
 ## Recipes
 See the `@quatrain/backend-restapi-recipes` package for community-maintained query serializers for famous APIs (OpenWeatherMap, CoinGecko, etc.).
+
+## TODO
+- [ ] **Multi-Format Parsing**: Evolve `ApiClient` to respect the `responseType` parameter (avoiding forced `.json()`) to allow ingesting `CSV` or `XML` payloads.
+- [ ] **Custom Response Parsers**: Introduce a `responseParser?: (rawResponse: any) => Record<string, any>[]` in `RestAdapterOptions` to parse exotic formats into Quatrain-compatible objects.
+- [ ] **Hypertext API Navigation**: Support HTML-based APIs by utilizing `@quatrain/ai` within the `responseParser` to extract JSON from unstructured web pages.