/** * @fileoverview Open States API v3 REST client — auth, pagination, retry, response normalization. * @module services/openstates/openstates-service */ import type { Context } from '@cyanheads/mcp-ts-core'; import type { AppConfig } from '@cyanheads/mcp-ts-core/config'; import type { StorageService } from '@cyanheads/mcp-ts-core/storage'; import type { ServerConfig } from '../../config/server-config.js'; import type { Bill, BillListResponse, BillSearchParams, Committee, CommitteeListResponse, CommitteeSearchParams, Event, EventListResponse, EventSearchParams, Jurisdiction, JurisdictionListParams, JurisdictionListResponse, PeopleSearchParams, PersonListResponse } from './types.js'; /** * Derive a storage-safe cache key from a request URL. The raw URL carries `:?&=`, which the storage * key validator (`[A-Za-z0-9_.\-/]` only) rejects, so hash it to a hex digest under a valid prefix. * Web Crypto is a global in every supported runtime, keeping the hash cross-platform. */ export declare function cacheKeyForUrl(url: string): Promise; export declare class OpenStatesApiService { private readonly baseUrl; private readonly apiKey; private readonly rateLimiter; /** Per-attempt upstream deadline, from `OPENSTATES_REQUEST_TIMEOUT_MS`. */ private readonly requestTimeoutMs; /** * @param dailyRequestBudget - Fail-fast daily request budget for the shared API key. Defaults to * the configured `OPENSTATES_DAILY_REQUEST_BUDGET` value so a deployment's own setting applies * without the caller restating it; the explicit parameter stays for direct construction in * tests, where a small budget makes the guard cheap to exercise. */ constructor(appConfig: AppConfig, _storage: StorageService, serverConfig: ServerConfig, dailyRequestBudget?: number); private buildUrl; private fetchJson; /** * One upstream attempt, bounded by a deadline this service owns rather than the helper's. * * The deadline signal is composed with `ctx.signal` so either can cancel the request, but it * stays separately observable — `deadline.signal.aborted` distinguishes "this client ran out of * patience" from "the caller went away", which the composed signal alone cannot, and which the * error the helper produces does not reliably encode (see `FETCH_BACKSTOP_MULTIPLIER`). */ private fetchAttempt; /** * Re-stamps the upstream failures this service treats as deterministic so `withRetry` fails fast * instead of spending attempts — and shared-key budget — on requests that cannot succeed. * * - **Timeout.** Either this client's own deadline expiring (`deadlineExpired`, the arm that * fires in practice — upstream takes ~60s to answer `504`, so the deadline lands first) or an * upstream status that maps to `Timeout` (`504`, `408`, `425`). Retrying either just pays the * same wait again: whatever made the request exceed the ceiling — an over-broad query, a slow * gateway — still holds on the next attempt, and the shared-key budget is spent for nothing. * Carries the `upstream_timeout` reason plus the calling definition's recovery hint, which * names the narrowing the caller can act on. Keying on the owned signal first rather than on * the code keeps this correct however the helper classifies an abort. * - **RateLimited.** The shared key's cap: deterministic until the window rolls, so retrying * only burns the remaining budget against a capped endpoint. * * Everything else passes through with its default classification, so a genuinely transient * `502`/`503` still gets its retries. */ private classifyUpstreamFailure; /** * Fail-fast budget guard over the shared-key `RateLimiter`. Re-stamps the limiter's `RateLimited` * rejection with `retryable: false`: `withRetry` classifies `RateLimited` as transient by * default, so without the flag it would retry the guard's own rejection four times and defeat it. */ private checkRateBudget; searchBills(params: BillSearchParams, ctx: Context): Promise; getBillByPath(jurisdiction: string, session: string, billId: string, include: string[] | undefined, ctx: Context): Promise; getBillById(openstatesId: string, include: string[] | undefined, ctx: Context): Promise; /** * `org_classification=legislature` is in the upstream enum and is accepted input, but it * is never any *person's* current role — only `upper`/`lower` (chambers) and `executive` * (individual officials) are — so upstream matches nobody and returns an empty set. The * legislature is the union of the two chambers, resolved here; every other classification * passes through as a single upstream query. */ searchPeople(params: PeopleSearchParams, ctx: Context): Promise; /** One upstream `/people` page, normalized. */ private fetchPeoplePage; /** * Records `[start, start + count)` of one chamber, mapped onto the upstream's page-based * pagination. `head` is that chamber's page 1 at the same `per_page`, reused whenever the * range reaches into it. * * Upstream 404s (`invalid page, must be in [1, N]`) for any page above a chamber's * `max_page`, so the range is clamped to `head`'s `total_items` before any page number is * derived — every request this issues is inside the legal range by construction. */ private fetchChamberRange; /** * The `legislature` union: every `upper` member followed by every `lower` member, sliced to * the caller's page. * * Page 1 of each chamber is the only request that is legal before the chamber's size is * known, and it doubles as the head of the union — so both are fetched up front, and their * `total_items` bound every page request that follows. The caller's window is then sliced * out of the *merged* set: once it runs past `upper`, it reads into `lower` at the offset * the merge has actually reached. Threading the caller's offset into each chamber query * instead would skip that many records in both and silently drop legislators. * * Costs two upstream calls for the common first page, at most four for a deep one — never a * full drain of either chamber. */ private searchLegislature; getPeopleByGeo(lat: number, lng: number, include: string[] | undefined, ctx: Context): Promise; searchCommittees(params: CommitteeSearchParams, ctx: Context): Promise; getCommittee(committeeId: string, include: string[] | undefined, ctx: Context): Promise; searchEvents(params: EventSearchParams, ctx: Context): Promise; getEvent(eventId: string, include: string[] | undefined, ctx: Context): Promise; /** One upstream `/jurisdictions` page, as-is. */ private fetchJurisdictionsPage; /** * The `classification=state` inventory (50 states + DC + 5 US territories = 56) has outgrown * the upstream `per_page` ceiling of 52 (HTTP 400 above it), so the advertised one-call * inventory no longer fits a single page. For the default full-inventory request — page 1, * whose complete set spans at most `MAX_JURISDICTION_MERGE_PAGES` pages — the remaining pages * are fetched and merged into one synthesized response, the same reassembly `searchLegislature` * does for the chamber union. Explicit deep paging (`page > 1`) and collections too large to * complete within the bound (e.g. municipalities) fall through to plain single-page pagination. */ listJurisdictions(params: JurisdictionListParams, ctx: Context): Promise; getJurisdiction(jurisdictionId: string, include: string[] | undefined, ctx: Context): Promise; } export declare function initOpenStatesApiService(appConfig: AppConfig, storage: StorageService, serverConfig: ServerConfig): void; export declare function getOpenStatesApiService(): OpenStatesApiService; //# sourceMappingURL=openstates-service.d.ts.map