# SDK Requirements

V1 levert handgeschreven Python (`sdk/python`, pakket `ragcore-sdk`) en
TypeScript (`sdk/typescript`, pakket `@ragcore/sdk`) clients tegen de
pinned OpenAPI-specificatie, elk scoped tot de drie echt geïmplementeerde
retrieval-endpoints (`search`/`context`/`answers`) -- `/v1/citations/{id}`
en `/v1/jobs/{id}` staan wel in `docs/contracts/openapi.yaml`, maar zijn
nooit als echte route geïmplementeerd, dus geen van beide SDK's doet
alsof ze bestaan.

Beide SDK's:

- accepteren het bearer token veilig zonder het ooit te loggen (Python:
  nooit buiten de request-headers; TypeScript: een echt privé class field
  `#token`, niet TypeScript's compile-time-only `private`, dus niet
  zichtbaar via `console.log`/spread/`JSON.stringify`);
- ondersteunen timeouts (beide) en cancellation via de standaard taal-
  mechanismen (Python: normale `asyncio`-cancellation; TypeScript: een
  interne `AbortController` per request) -- geen aparte cancellation-API
  bovenop wat de taal al biedt;
- exposen typed problem details (`ProblemDetails`/`RAGCoreAPIError`) voor
  elke non-2xx-response, die allemaal dezelfde RFC7807-vorm hebben;
- modelleren de search/context/answer-types volledig, inclusief citations;
- handelen de SSE-answerstream af (`event: <type>\ndata: <json>\n\n`,
  zoals `answers/routes.py::_sse_body` het echt verstuurt);
- retryen alleen de non-streaming requestpaden, en alleen bij een
  connectiefout of een `503` -- nooit een `4xx`, nooit een al gestarte
  SSE-stream (zie beide SDK's eigen moduledocstring voor de redenering);
- sturen een eigen versie-identifier mee: Python zet een echte
  `User-Agent: ragcore-sdk-python/<versie>` header; TypeScript zet in
  plaats daarvan `X-RAGCore-SDK-Version: <versie>`, omdat browsers
  pogingen om `User-Agent` via `fetch` te zetten stilzwijgend negeren
  (Node accepteert het wel, wat een inconsistent gedrag tussen runtimes
  zou opleveren als `User-Agent` zelf gebruikt was).

Geen SDK exposet Qdrant- of databaseconcepten.

## Bewust niet geleverd

Twee requirements uit een eerdere versie van dit document zijn bewust
losgelaten, omdat ze niet passen bij wat er echt bestaat:

- **Idempotency keys.** `search`/`context`/`answers` zijn stateless,
  side-effect-vrije queries (geen enkele schrijft iets weg) -- een
  idempotency key is een mechanisme tegen dubbele *schrijf*-operaties bij
  een retry, en heeft dus geen functie hier. De retry-policy hierboven is
  om diezelfde reden al veilig zonder een key.
- **Cursor-iterators.** Geen van de drie endpoints heeft cursor-based
  paginering (search/context/answers geven een vast-begrensde
  resultatenset terug, geen paginated lijst); er is dus niets om te
  itereren.