@radiusplus/api-sdk-v2 0.5.0

package/README.md

@@ -0,0 +1,75 @@
+# @radiusplus/api-sdk-v2
+
+TypeScript SDK for the Radius API v2. A fully-typed client generated from the OpenAPI spec, with
+built-in rate limiting and retries.
+
+## Install
+
+```bash
+npm install @radiusplus/api-sdk-v2
+```
+
+`zod` comes bundled as a dependency — no separate install needed.
+
+## Usage
+
+```ts
+import { createRadiusApi } from "@radiusplus/api-sdk-v2";
+
+const api = createRadiusApi({ auth: process.env.RADIUS_API_KEY });
+
+const { data } = await api.demographics.getDemographicsYears({
+  body: { geography: { type: "country", country: "US" } },
+});
+```
+
+`createRadiusApi` defaults to the production base URL and installs a rate-limited transport:
+
+- proactive backpressure from `X-RateLimit-*` headers (pauses before hitting a 429),
+- `maxConcurrent` / `minTime` request shaping,
+- 429 pause-and-retry driven by `X-RateLimit-Reset`,
+- 5xx and network-error retry with exponential backoff,
+- optional per-attempt timeout.
+
+```ts
+const api = createRadiusApi({
+  auth: key,
+  baseURL: "https://sandbox.api.radiusplus.com/v2", // override the default host
+  rateLimit: { maxConcurrent: 5, minTime: 50, timeoutMs: 10_000 },
+});
+```
+
+Pass `transport` to opt out of the built-in transport, or use `RadiusApiV2` directly for a bare
+client. Types and Zod schemas for every request/response are exported from the package root.
+
+## Pagination
+
+Cursor-paginated endpoints (search, facility/market pricing) can be walked lazily. The helpers
+thread `nextCursor` for you and fetch one page at a time — each page is a normal call, so rate
+limiting and retries apply.
+
+```ts
+import { paginateItems, paginatePages, collect } from "@radiusplus/api-sdk-v2";
+
+// Iterate items across all pages:
+for await (const facility of paginateItems(
+  (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+  (page) => page.data.facilities,
+  { limit: 250 },
+)) {
+  handle(facility);
+}
+
+// Or iterate whole pages (for metadata like resultCount / hasMore):
+for await (const page of paginatePages(
+  (pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data),
+)) { /* … */ }
+
+// Opt-in eager collection, capped to avoid runaway fetches:
+const firstThousand = await collect(
+  paginateItems((pagination) => api.search.searchFacilities({ body: { geography, pagination } }).then((r) => r.data), (p) => p.data.facilities),
+  1000,
+);
+```
+
+Pass an `AbortSignal` via the final `{ signal }` argument to stop a walk between pages.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@radiusplus/api-sdk-v2",
+  "version": "0.5.0",
+  "description": "TypeScript SDK for the Radius API v2 — generated client with built-in rate limiting and retries",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UnionRealtime/radius-api-spec.git"
+  },
+  "license": "UNLICENSED"
+}

package/src/_generated/.kubb/client.d.ts

@@ -0,0 +1,313 @@
+/**
+ * HTTP status codes treated as a success. A resolved call only ever carries a body from one of
+ * these; everything else is an error (thrown by default, or surfaced on `error`).
+ */
+export type SuccessStatusCode = '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226';
+/**
+ * The success members of a per-status responses record (`{ '200': ...; '404': ... }`).
+ */
+export type SuccessOf<TResponses> = TResponses[Extract<keyof TResponses, SuccessStatusCode>];
+/**
+ * The error members of a per-status responses record — every documented status that is not a 2xx.
+ */
+export type ErrorOf<TResponses> = TResponses[Exclude<keyof TResponses, SuccessStatusCode>];
+/**
+ * Converts a response record's string status key to its numeric literal (`'200'` becomes `200`).
+ * Non-numeric keys such as the OpenAPI `default` response stay `number`.
+ */
+export type ToStatusNumber<TStatus> = TStatus extends `${infer TNumber extends number}` ? TNumber : number;
+/**
+ * One result variant for a single documented status. `status` is the numeric literal at the top
+ * level, so a `switch (result.status)` narrows `data` (a 2xx status) or `error` (everything else) to
+ * that status's payload.
+ */
+export type ResultByStatus<TResponses, TStatus extends keyof TResponses, TRequest, TResponse> = TStatus extends SuccessStatusCode ? {
+    status: ToStatusNumber<TStatus>;
+    data: TResponses[TStatus];
+    error: undefined;
+    request: TRequest;
+    response: TResponse;
+} : {
+    status: ToStatusNumber<TStatus>;
+    data: undefined;
+    error: TResponses[TStatus];
+    request: TRequest;
+    response: TResponse;
+};
+/**
+ * The union of every documented status' result variant.
+ */
+export type ResultUnion<TResponses, TRequest, TResponse> = {
+    [TStatus in keyof TResponses]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>;
+}[keyof TResponses];
+/**
+ * The union of just the success (2xx) status variants. Selected by status code, not by `error`, so an
+ * untyped (`any`) error payload can never widen a success result's `data`.
+ */
+export type SuccessResultUnion<TResponses, TRequest, TResponse> = {
+    [TStatus in Extract<keyof TResponses, SuccessStatusCode>]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>;
+}[Extract<keyof TResponses, SuccessStatusCode>];
+/**
+ * The shape every generated function returns, discriminated by the top-level `status`. With
+ * `throwOnError` (the default) a resolved call always means success, so the result is the union of the
+ * 2xx variants and `error` is `undefined`; without it every documented status is a variant, so a
+ * `switch (result.status)` (or narrowing on `error`) narrows `data` and `error` to that status's
+ * payload. Operations with no typed responses fall back to a `status`/`request`/`response`-only result.
+ */
+export type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = Request, TResponse = Response> = ThrowOnError extends true ? [SuccessResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
+    status: number;
+    data: SuccessOf<TResponses>;
+    error: undefined;
+    request: TRequest;
+    response: TResponse;
+} : SuccessResultUnion<TResponses, TRequest, TResponse> : [ResultUnion<TResponses, TRequest, TResponse>] extends [never] ? {
+    status: number;
+    data: undefined;
+    error: undefined;
+    request: TRequest;
+    response: TResponse;
+} : ResultUnion<TResponses, TRequest, TResponse>;
+/**
+ * The data-shaped keys of the grouped options object. `Options` subtracts these from the runtime
+ * `RequestConfig` and adds them back, typed per operation, from the generated `<Name>Request` type.
+ */
+export type DataShape = {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+};
+export type HeaderValue = string | number | boolean | null | undefined | object;
+export type HeadersInit = Array<[string, HeaderValue]> | Record<string, HeaderValue>;
+export type RequestCredentials = 'omit' | 'same-origin' | 'include';
+export type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream';
+/**
+ * Serializes the query object into a search string. Array and object members follow the configured
+ * style (`form` with `explode` by default; `deepObject` for nested objects).
+ */
+export type QuerySerializer = (params: Record<string, unknown>) => string;
+/**
+ * Serializes the request body. JSON by default; `FormData`, `URLSearchParams`, `Blob`,
+ * `ArrayBuffer`, and string bodies pass through untouched.
+ */
+export type BodySerializer = (body: unknown, contentType?: string) => BodyInit | undefined;
+/**
+ * Parses a value before it is sent or after it is received, returning the parsed (and optionally
+ * transformed) value. Wires zod parsing through the per-call `parser.request` / `parser.response` /
+ * `parser.error` hooks (`error` runs on the error body when a non-2xx call does not throw).
+ */
+export type Parser<T = unknown> = (value: T) => T | Promise<T>;
+/**
+ * A resolved security scheme carried on each generated call's `security` array. The runtime passes it
+ * to the configured `auth` resolver and places the returned token accordingly.
+ */
+export type Auth = {
+    type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
+    scheme?: 'bearer' | 'basic';
+    name?: string;
+    in?: 'header' | 'query' | 'cookie';
+};
+/**
+ * The token a consumer returns for a scheme, or `undefined` to skip it. Bearer and basic schemes are
+ * prefixed by the runtime (basic is base64-encoded), so return the raw token or `user:password`.
+ */
+export type AuthToken = string | undefined;
+/**
+ * Resolves the token for a security scheme: either a static token used for every scheme, or a
+ * callback called once per scheme on a guarded operation until one returns a token.
+ */
+export type AuthResolver = AuthToken | ((auth: Auth) => AuthToken | Promise<AuthToken>);
+/**
+ * Extra `fetch` init the transport spreads onto every `Request`, an escape hatch for the fields the
+ * runtime does not set itself: `cache`, `mode`, `redirect`, `keepalive`, `duplex`, and Next.js's
+ * non-standard `next` (`{ revalidate, tags }`). `method`, `headers`, `body`, `signal`, and
+ * `credentials` are always controlled by the runtime and override anything set here.
+ */
+export type FetchOptions = RequestInit & {
+    next?: Record<string, unknown>;
+};
+/**
+ * The request a generated function hands to the runtime. `body` / `headers` / `path` / `query` come
+ * from the grouped options; everything else is plain request configuration.
+ */
+export type RequestConfig<TBody = unknown, TRequest = Request, TResponse = Response> = {
+    baseURL?: string;
+    url?: string;
+    method?: 'GET' | 'PUT' | 'PATCH' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD';
+    path?: Record<string, unknown>;
+    query?: unknown;
+    params?: unknown;
+    body?: TBody;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    credentials?: RequestCredentials;
+    options?: FetchOptions;
+    contentType?: string;
+    responseType?: ResponseType;
+    throwOnError?: boolean;
+    client?: ClientInstance<TRequest, TResponse>;
+    transport?: Transport<TRequest, TResponse>;
+    querySerializer?: QuerySerializer;
+    bodySerializer?: BodySerializer;
+    parser?: {
+        request?: Parser;
+        response?: Parser;
+        error?: Parser;
+    };
+    security?: Array<Auth>;
+    auth?: AuthResolver;
+};
+/**
+ * The grouped options object passed to every generated function: the request config minus the
+ * data-shaped keys and the literal `url`, plus the per-operation `<Name>Request`.
+ */
+export type Options<TData extends DataShape, ThrowOnError extends boolean = true, TRequest = Request, TResponse = Response> = Omit<RequestConfig<unknown, TRequest, TResponse>, keyof DataShape | 'url'> & TData & {
+    client?: ClientInstance<TRequest, TResponse>;
+    throwOnError?: ThrowOnError;
+};
+/**
+ * Client-level configuration shared by every call an instance makes. Per-call `RequestConfig`
+ * overrides these.
+ */
+export type ClientConfig<TRequest = Request, TResponse = Response> = {
+    baseURL?: string;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+    options?: FetchOptions;
+    throwOnError?: boolean;
+    transport?: Transport<TRequest, TResponse>;
+    querySerializer?: QuerySerializer;
+    bodySerializer?: BodySerializer;
+    auth?: AuthResolver;
+};
+/**
+ * The normalized request the transport receives. The shared core does all serialization, auth, and
+ * header work; the transport only performs the send.
+ */
+export type ResolvedRequest = {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: BodyInit;
+    signal?: AbortSignal;
+    credentials?: RequestCredentials;
+    options?: FetchOptions;
+    responseType?: ResponseType;
+};
+/**
+ * What a transport returns: the parsed body plus the native request/response objects, kept reachable
+ * so status, headers, and the raw body never have to grow the result type.
+ */
+export type TransportResult<TData = unknown, TRequest = Request, TResponse = Response> = {
+    data: TData;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    request: TRequest;
+    response: TResponse;
+};
+/**
+ * The per-plugin send. plugin-fetch wraps `globalThis.fetch`, plugin-axios an axios instance, and
+ * plugin-ky a ky instance. Supplied to `createClientCore` as `defaultTransport`.
+ */
+export type Transport<TRequest = Request, TResponse = Response> = (request: ResolvedRequest) => Promise<TransportResult<unknown, TRequest, TResponse>>;
+/**
+ * The result a resolved call produces before it is cast to `RequestResult` by the generated wrapper.
+ */
+export type CallResult<TRequest = Request, TResponse = Response> = {
+    status: number;
+    data: unknown;
+    error: unknown;
+    request: TRequest;
+    response: TResponse;
+};
+/**
+ * A registered interceptor with its ejection id.
+ */
+export type InterceptorFn<T> = (value: T) => T | Promise<T>;
+/**
+ * A single interceptor channel — request, response, or error — with a transport-agnostic
+ * `use` / `eject` / `update` API.
+ */
+export type InterceptorStack<T> = {
+    use: (fn: InterceptorFn<T>) => number;
+    eject: (id: number) => void;
+    update: (id: number, fn: InterceptorFn<T>) => void;
+    run: (value: T) => Promise<T>;
+};
+/**
+ * The three interceptor channels every client instance exposes.
+ */
+export type Interceptors<TRequest = Request, TResponse = Response> = {
+    request: InterceptorStack<ResolvedRequest>;
+    response: InterceptorStack<TransportResult<unknown, TRequest, TResponse>>;
+    error: InterceptorStack<ResponseError<unknown, TRequest, TResponse>>;
+};
+/**
+ * A client instance: the callable send plus configuration, interceptors, and an isolated
+ * `createClient` factory bound to the same transport.
+ */
+export type ClientInstance<TRequest = Request, TResponse = Response> = {
+    <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>>;
+    getConfig: () => ClientConfig<TRequest, TResponse>;
+    setConfig: (config: ClientConfig<TRequest, TResponse>) => ClientConfig<TRequest, TResponse>;
+    getUrl: <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>) => string;
+    interceptors: Interceptors<TRequest, TResponse>;
+    createClient: (config?: ClientConfig<TRequest, TResponse>) => ClientInstance<TRequest, TResponse>;
+};
+/**
+ * Thrown for responses outside the 2xx range, so a resolved call always means success. The parsed
+ * error body and the native request/response stay reachable on the error.
+ */
+export declare class ResponseError<TError = unknown, TRequest = Request, TResponse = Response> extends Error {
+    data: TError;
+    status: number;
+    statusText: string;
+    request: TRequest;
+    response: TResponse;
+    constructor(config: {
+        data: TError;
+        status: number;
+        statusText: string;
+        request: TRequest;
+        response: TResponse;
+    });
+}
+export type ResponseErrorConfig<TError = unknown> = ResponseError<TError>;
+/**
+ * Default body serializer: passes binary/form bodies through and JSON-serializes everything else.
+ * For `multipart/form-data` plain objects become `FormData` and for
+ * `application/x-www-form-urlencoded` they become `URLSearchParams`.
+ */
+export declare const defaultBodySerializer: BodySerializer;
+/**
+ * Default query serializer: arrays explode into repeated keys and nested objects use the
+ * `deepObject` style (`key[prop]=value`).
+ */
+export declare const defaultQuerySerializer: QuerySerializer;
+/**
+ * Creates a transport-agnostic interceptor channel. Interceptors run in registration order; `eject`
+ * removes one by id and `update` swaps its function in place without reordering.
+ */
+export declare function createInterceptorStack<T>(): InterceptorStack<T>;
+/**
+ * Walks the per-operation security in order and places the first resolved token on the request,
+ * mutating `headers` / `query` in place. Bearer (and oauth2 / openIdConnect) tokens become a `Bearer`
+ * Authorization header, basic credentials are base64-encoded, and an apiKey is placed under its
+ * `name` in the header, query, or cookie.
+ */
+export declare function resolveAuth(params: {
+    security: Array<Auth> | undefined;
+    auth: AuthResolver | undefined;
+    headers: Record<string, string>;
+    query: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Builds the shared client core bound to a transport. Each plugin calls this with its
+ * `defaultTransport` and exports the resulting instance as `client`, plus a `createClient` factory.
+ */
+export declare function createClientCore<TRequest = Request, TResponse = Response>(options: {
+    defaultTransport: Transport<TRequest, TResponse>;
+} & ClientConfig<TRequest, TResponse>): ClientInstance<TRequest, TResponse>;
+export declare const client: ClientInstance<Request, Response>;
+export declare const createClient: (config?: Parameters<typeof client.createClient>[0]) => ClientInstance<Request, Response>;