@btrc/api-server 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bowler Racing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @btrc/api-server
+
+Typed server-side (Node 22+/SSR) client for the Bowler Racing BTRC API. Promise-based, non-throwing results, cursor pagination, retry with `retry-after` support. Built on the Zod contracts in [`@btrc/contracts`](https://www.npmjs.com/package/@btrc/contracts).
+
+```bash
+npm install @btrc/api-server
+```
+
+## Usage
+
+```ts
+import { createBtrcClient, routes } from '@btrc/api-server';
+
+const client = createBtrcClient({
+  baseUrl: 'https://api.specuro.com', // this is the default
+  version: 'v1',                           // default
+});
+
+const result = await client.drivers.list({ limit: 100, season: 2026 });
+if (result.isError) {
+  console.error(result.statusCode, result.error);
+} else {
+  console.log(result.data, result.meta.hasMore, result.rateLimit);
+}
+```
+
+Every call resolves (never throws) to a discriminated union:
+
+```ts
+{ isError: false, data, meta, links, error: null, statusCode, rateLimit }
+{ isError: true,  data: null, meta: null, links: null, error, statusCode, rateLimit }
+```
+
+`error.kind` is one of `http` (with RFC 9457 `problem`), `transport`, `timeout`, `aborted`, or `parse`.
+
+### Pagination
+
+```ts
+for await (const lap of client.paginate(routes.sessions.laps, { sessionId, valid_only: true })) {
+  // follows meta.nextCursor automatically
+}
+```
+
+`client.pages(...)` yields whole page results instead. Iterators throw `BtrcRequestError` on failure.
+
+### Config
+
+`{ baseUrl?, version?, fetch?, headers?, timeoutMs?, retry?: { retries, retryOn, baseDelayMs, maxDelayMs }, validate? }` — retries default to 2 attempts on 429/503/transport errors, honouring `retry-after`. `validate: true` runs response envelopes through their Zod schemas.
+
+### Escape hatch
+
+`client.request<T>('/some/path', { query })` for anything not in the route table.
+
+For browsers and React (`isPending`/`isLoading` states), use [`@btrc/api-client`](https://www.npmjs.com/package/@btrc/api-client).

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import type { RouteDef, Routes } from '@btrc/contracts';
+import type { ClientConfig, ResolvedConfig } from './config.js';
+import type { PageItem } from './paginate.js';
+import type { RawRequestOptions, RequestOptions, RouteArgs, RouteResult } from './request.js';
+import type { ApiResult } from './result.js';
+type RequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+type RouteOp<R extends RouteDef> = [RequiredKeys<RouteArgs<R>>] extends [never] ? (args?: RouteArgs<R>, opts?: RequestOptions) => Promise<RouteResult<R>> : (args: RouteArgs<R>, opts?: RequestOptions) => Promise<RouteResult<R>>;
+type SuccessResult<R extends RouteDef> = Extract<RouteResult<R>, {
+    isError: false;
+}>;
+export type BtrcClient = {
+    readonly [G in keyof Routes]: {
+        readonly [K in keyof Routes[G]]: RouteOp<Routes[G][K] & RouteDef>;
+    };
+} & {
+    /** Escape hatch: GET an arbitrary path relative to the version segment. */
+    request<T = unknown>(path: string, opts?: RawRequestOptions): Promise<ApiResult<T, unknown>>;
+    /** Iterate successful page results, following cursors. Throws BtrcRequestError on failure. */
+    pages<R extends RouteDef>(route: R, args?: RouteArgs<R>, opts?: RequestOptions): AsyncGenerator<SuccessResult<R>, void>;
+    /** Iterate individual items across pages. Throws BtrcRequestError on failure. */
+    paginate<R extends RouteDef>(route: R, args?: RouteArgs<R>, opts?: RequestOptions): AsyncGenerator<PageItem<R>, void>;
+    readonly config: ResolvedConfig;
+};
+export declare function createBtrcClient(config?: ClientConfig): BtrcClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,KAAK,YAAY,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzF,KAAK,OAAO,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC3E,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GACvE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3E,KAAK,aAAa,CAAC,CAAC,SAAS,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;KAAE;CACpG,GAAG;IACF,2EAA2E;IAC3E,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7F,8FAA8F;IAC9F,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACxH,iFAAiF;IACjF,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACtH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,YAAiB,GAAG,UAAU,CAsBtE"}

package/dist/client.js

@@ -0,0 +1,20 @@
+import { routes } from '@btrc/contracts';
+import { paginateItems, paginatePages } from './paginate.js';
+import { createRequester } from './request.js';
+export function createBtrcClient(config = {}) {
+    const requester = createRequester(config);
+    const client = {
+        config: requester.config,
+        request: requester.request,
+        pages: (route, args, opts) => paginatePages(requester, route, args, opts),
+        paginate: (route, args, opts) => paginateItems(requester, route, args, opts),
+    };
+    for (const [namespaceName, defs] of Object.entries(routes)) {
+        const namespace = {};
+        for (const [opName, route] of Object.entries(defs)) {
+            namespace[opName] = (args, opts) => requester.call(route, args, opts);
+        }
+        client[namespaceName] = namespace;
+    }
+    return client;
+}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+export interface RetryConfig {
+    /** Extra attempts after the first failure. Default 2. */
+    retries?: number;
+    /** HTTP status codes that trigger a retry. Default [429, 503]. Transport errors always retry. */
+    retryOn?: number[];
+    /** First backoff delay in ms when no retry-after header is present. Default 250. */
+    baseDelayMs?: number;
+    /** Backoff ceiling in ms. Default 10_000. */
+    maxDelayMs?: number;
+}
+export interface ClientConfig {
+    /** Origin of the API, without version segment. Default 'https://api.specuro.com'. */
+    baseUrl?: string;
+    /** Version path segment. Default 'v1'. */
+    version?: string;
+    /** Injectable fetch implementation (tests, polyfills). Default globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Per-attempt timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    retry?: RetryConfig;
+    /** When true, response envelopes are validated with their Zod schema. Default false. */
+    validate?: boolean;
+}
+export interface ResolvedConfig {
+    baseUrl: string;
+    version: string;
+    fetch: typeof fetch;
+    headers: Record<string, string>;
+    timeoutMs: number;
+    retry: Required<RetryConfig>;
+    validate: boolean;
+}
+export declare const DEFAULT_BASE_URL = "https://api.specuro.com";
+export declare function resolveConfig(config?: ClientConfig): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,wBAAgB,aAAa,CAAC,MAAM,GAAE,YAAiB,GAAG,cAAc,CAevE"}

package/dist/config.js

@@ -0,0 +1,17 @@
+export const DEFAULT_BASE_URL = 'https://api.specuro.com';
+export function resolveConfig(config = {}) {
+    return {
+        baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        version: (config.version ?? 'v1').replace(/^\/+|\/+$/g, ''),
+        fetch: config.fetch ?? globalThis.fetch.bind(globalThis),
+        headers: config.headers ?? {},
+        timeoutMs: config.timeoutMs ?? 30_000,
+        retry: {
+            retries: config.retry?.retries ?? 2,
+            retryOn: config.retry?.retryOn ?? [429, 503],
+            baseDelayMs: config.retry?.baseDelayMs ?? 250,
+            maxDelayMs: config.retry?.maxDelayMs ?? 10_000,
+        },
+        validate: config.validate ?? false,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createBtrcClient } from './client.js';
+export type { BtrcClient } from './client.js';
+export { createRequester, buildRouteUrl } from './request.js';
+export type { DataOf, MetaOf, RawRequestOptions, Requester, RequestOptions, RouteArgs, RouteResult, } from './request.js';
+export { paginateItems, paginatePages } from './paginate.js';
+export type { PageItem } from './paginate.js';
+export { BtrcRequestError } from './result.js';
+export type { ApiLinks, ApiResult, BtrcError, RateLimitInfo } from './result.js';
+export { DEFAULT_BASE_URL, resolveConfig } from './config.js';
+export type { ClientConfig, ResolvedConfig, RetryConfig } from './config.js';
+export { routes, API_VERSION } from '@btrc/contracts';
+export type { Routes, RouteDef, PathParams, ProblemDetails } from '@btrc/contracts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC9D,YAAY,EACV,MAAM,EACN,MAAM,EACN,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createBtrcClient } from './client.js';
+export { createRequester, buildRouteUrl } from './request.js';
+export { paginateItems, paginatePages } from './paginate.js';
+export { BtrcRequestError } from './result.js';
+export { DEFAULT_BASE_URL, resolveConfig } from './config.js';
+export { routes, API_VERSION } from '@btrc/contracts';

package/dist/paginate.d.ts

@@ -0,0 +1,15 @@
+import type { RouteDef } from '@btrc/contracts';
+import type { RequestOptions, Requester, RouteArgs, RouteResult } from './request.js';
+type SuccessResult<R extends RouteDef> = Extract<RouteResult<R>, {
+    isError: false;
+}>;
+export type PageItem<R extends RouteDef> = SuccessResult<R>['data'] extends (infer I)[] ? I : never;
+/**
+ * Yields each successful page result, following meta.nextCursor while meta.hasMore.
+ * Throws BtrcRequestError on any error result (generators cannot return the union usefully).
+ */
+export declare function paginatePages<R extends RouteDef>(requester: Requester, route: R, args?: RouteArgs<R>, opts?: RequestOptions): AsyncGenerator<SuccessResult<R>, void>;
+/** Yields individual items across pages. Same error semantics as paginatePages. */
+export declare function paginateItems<R extends RouteDef>(requester: Requester, route: R, args?: RouteArgs<R>, opts?: RequestOptions): AsyncGenerator<PageItem<R>, void>;
+export {};
+//# sourceMappingURL=paginate.d.ts.map

package/dist/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGtF,KAAK,aAAa,CAAC,CAAC,SAAS,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,QAAQ,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAOpG;;;GAGG;AACH,wBAAuB,aAAa,CAAC,CAAC,SAAS,QAAQ,EACrD,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,CAAC,EACR,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,IAAI,CAAC,EAAE,cAAc,GACpB,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAaxC;AAED,mFAAmF;AACnF,wBAAuB,aAAa,CAAC,CAAC,SAAS,QAAQ,EACrD,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,CAAC,EACR,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,IAAI,CAAC,EAAE,cAAc,GACpB,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAKnC"}

package/dist/paginate.js

@@ -0,0 +1,27 @@
+import { BtrcRequestError } from './result.js';
+/**
+ * Yields each successful page result, following meta.nextCursor while meta.hasMore.
+ * Throws BtrcRequestError on any error result (generators cannot return the union usefully).
+ */
+export async function* paginatePages(requester, route, args, opts) {
+    let cursor;
+    do {
+        opts?.signal?.throwIfAborted();
+        const requestArgs = (cursor === undefined ? { ...args } : { ...args, cursor });
+        const result = await requester.call(route, requestArgs, opts);
+        if (result.isError) {
+            throw new BtrcRequestError(result.error, result.statusCode, result.rateLimit);
+        }
+        yield result;
+        const meta = (result.meta ?? {});
+        cursor = meta.hasMore === true && typeof meta.nextCursor === 'string' ? meta.nextCursor : undefined;
+    } while (cursor !== undefined);
+}
+/** Yields individual items across pages. Same error semantics as paginatePages. */
+export async function* paginateItems(requester, route, args, opts) {
+    for await (const page of paginatePages(requester, route, args, opts)) {
+        const items = (Array.isArray(page.data) ? page.data : []);
+        for (const item of items)
+            yield item;
+    }
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,5 @@
+import type { RateLimitInfo } from './result.js';
+export declare function parseRateLimit(headers: Headers): RateLimitInfo;
+/** Returns the retry-after delay in milliseconds, or null when absent/invalid. */
+export declare function parseRetryAfter(headers: Headers): number | null;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAU9D;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAM/D"}

package/dist/rate-limit.js

@@ -0,0 +1,23 @@
+export function parseRateLimit(headers) {
+    const limitRaw = headers.get('ratelimit-limit');
+    const remainingRaw = headers.get('ratelimit-remaining');
+    const resetRaw = headers.get('ratelimit-reset');
+    if (limitRaw === null || remainingRaw === null || resetRaw === null)
+        return null;
+    const limit = Number(limitRaw);
+    const remaining = Number(remainingRaw);
+    const reset = Number(resetRaw);
+    if (!Number.isFinite(limit) || !Number.isFinite(remaining) || !Number.isFinite(reset))
+        return null;
+    return { limit, remaining, reset };
+}
+/** Returns the retry-after delay in milliseconds, or null when absent/invalid. */
+export function parseRetryAfter(headers) {
+    const value = headers.get('retry-after');
+    if (value === null)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    return null;
+}

package/dist/request.d.ts

@@ -0,0 +1,31 @@
+import type { PathParams, RouteDef } from '@btrc/contracts';
+import type { z } from 'zod';
+import type { ClientConfig, ResolvedConfig } from './config.js';
+import type { ApiResult } from './result.js';
+export type RouteArgs<R extends RouteDef> = PathParams<R['path']> & (R['query'] extends z.ZodTypeAny ? z.input<R['query']> : Record<never, never>);
+export type DataOf<R extends RouteDef> = R extends {
+    binary: true;
+} ? ArrayBuffer : z.infer<R['response']> extends {
+    data: infer D;
+} ? D : unknown;
+export type MetaOf<R extends RouteDef> = R extends {
+    binary: true;
+} ? null : z.infer<R['response']> extends {
+    meta: infer M;
+} ? M : unknown;
+export type RouteResult<R extends RouteDef> = ApiResult<DataOf<R>, MetaOf<R>>;
+export interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+export interface RawRequestOptions extends RequestOptions {
+    query?: Record<string, unknown>;
+}
+export interface Requester {
+    config: ResolvedConfig;
+    call<R extends RouteDef>(route: R, args?: RouteArgs<R>, opts?: RequestOptions): Promise<RouteResult<R>>;
+    request<T = unknown>(path: string, opts?: RawRequestOptions): Promise<ApiResult<T, unknown>>;
+}
+export declare function createRequester(config?: ClientConfig): Requester;
+export declare function buildRouteUrl(cfg: ResolvedConfig, route: RouteDef, args?: Record<string, unknown>): string;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAY,SAAS,EAAa,MAAM,aAAa,CAAC;AAElE,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAC/D,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEjF,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAC/D,WAAW,GACX,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9C,CAAC,GACD,OAAO,CAAC;AAEd,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAC/D,IAAI,GACJ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9C,CAAC,GACD,OAAO,CAAC;AAEd,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAQD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACxG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9F;AAED,wBAAgB,eAAe,CAAC,MAAM,GAAE,YAAiB,GAAG,SAAS,CAmBpE;AAOD,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAgB1G"}

package/dist/request.js

@@ -0,0 +1,171 @@
+import { ProblemDetailsSchema } from '@btrc/contracts';
+import { resolveConfig } from './config.js';
+import { parseRateLimit, parseRetryAfter } from './rate-limit.js';
+export function createRequester(config = {}) {
+    const cfg = resolveConfig(config);
+    async function call(route, args, opts) {
+        const url = buildRouteUrl(cfg, route, args);
+        return (await execute(cfg, url, route, opts));
+    }
+    async function request(path, opts) {
+        const url = new URL(joinPath(cfg, path));
+        if (opts?.query)
+            appendQuery(url, opts.query);
+        return (await execute(cfg, url.toString(), null, opts));
+    }
+    return { config: cfg, call, request };
+}
+function joinPath(cfg, path) {
+    const suffix = path === '/' || path === '' ? '' : path.startsWith('/') ? path : `/${path}`;
+    return `${cfg.baseUrl}/${cfg.version}${suffix}`;
+}
+export function buildRouteUrl(cfg, route, args) {
+    const supplied = { ...(args ?? {}) };
+    const interpolated = route.path.replace(/\{([^}]+)\}/g, (_match, name) => {
+        const value = supplied[name];
+        if (value === undefined || value === null) {
+            throw new TypeError(`Missing path parameter "${name}" for ${route.path}`);
+        }
+        delete supplied[name];
+        return encodeURIComponent(String(value));
+    });
+    const url = new URL(joinPath(cfg, interpolated));
+    if (route.query) {
+        const parsed = route.query.parse(supplied);
+        appendQuery(url, parsed);
+    }
+    return url.toString();
+}
+function appendQuery(url, params) {
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > 0)
+                url.searchParams.set(key, value.map(String).join(','));
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+}
+async function execute(cfg, url, route, opts) {
+    const { retries, baseDelayMs, maxDelayMs } = cfg.retry;
+    let attempt = 0;
+    for (;;) {
+        const outcome = await attemptOnce(cfg, url, route, opts);
+        if (!outcome.retryable || attempt >= retries)
+            return outcome.result;
+        const delay = outcome.delayMs ?? backoffDelay(baseDelayMs, maxDelayMs, attempt);
+        await sleep(delay);
+        attempt += 1;
+    }
+}
+async function attemptOnce(cfg, url, route, opts) {
+    const timeoutSignal = AbortSignal.timeout(cfg.timeoutMs);
+    const signal = opts?.signal ? AbortSignal.any([timeoutSignal, opts.signal]) : timeoutSignal;
+    let response;
+    try {
+        response = await cfg.fetch(url, {
+            method: 'GET',
+            headers: { accept: 'application/json', ...cfg.headers, ...opts?.headers },
+            signal,
+        });
+    }
+    catch (cause) {
+        if (opts?.signal?.aborted) {
+            return { result: errorResult({ kind: 'aborted' }, null, null), retryable: false, delayMs: null };
+        }
+        if (timeoutSignal.aborted) {
+            return { result: errorResult({ kind: 'timeout' }, null, null), retryable: true, delayMs: null };
+        }
+        return { result: errorResult({ kind: 'transport', cause }, null, null), retryable: true, delayMs: null };
+    }
+    const rateLimit = parseRateLimit(response.headers);
+    if (!response.ok) {
+        const problem = await readProblem(response, url);
+        const retryable = cfg.retry.retryOn.includes(response.status);
+        return {
+            result: errorResult({ kind: 'http', problem }, response.status, rateLimit),
+            retryable,
+            delayMs: retryable ? parseRetryAfter(response.headers) : null,
+        };
+    }
+    if (route?.binary) {
+        const data = await response.arrayBuffer();
+        return {
+            result: {
+                isError: false,
+                data,
+                meta: null,
+                links: { self: url },
+                error: null,
+                statusCode: response.status,
+                rateLimit,
+            },
+            retryable: false,
+            delayMs: null,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        return { result: errorResult({ kind: 'parse', cause }, response.status, rateLimit), retryable: false, delayMs: null };
+    }
+    if (cfg.validate && route) {
+        const checked = route.response.safeParse(body);
+        if (!checked.success) {
+            return {
+                result: errorResult({ kind: 'parse', cause: checked.error }, response.status, rateLimit),
+                retryable: false,
+                delayMs: null,
+            };
+        }
+        body = checked.data;
+    }
+    const envelope = (body ?? {});
+    return {
+        result: {
+            isError: false,
+            data: envelope.data,
+            meta: envelope.meta,
+            links: envelope.links ?? { self: url },
+            error: null,
+            statusCode: response.status,
+            rateLimit,
+        },
+        retryable: false,
+        delayMs: null,
+    };
+}
+async function readProblem(response, url) {
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = null;
+    }
+    const parsed = ProblemDetailsSchema.safeParse(body);
+    if (parsed.success)
+        return parsed.data;
+    return {
+        type: 'about:blank',
+        title: response.statusText || 'Request failed',
+        status: response.status,
+        detail: `Request to ${url} failed with status ${response.status}`,
+        instance: new URL(url).pathname,
+        requestId: response.headers.get('x-request-id') ?? 'unknown',
+    };
+}
+function errorResult(error, statusCode, rateLimit) {
+    return { isError: true, data: null, meta: null, links: null, error, statusCode, rateLimit };
+}
+function backoffDelay(baseDelayMs, maxDelayMs, attempt) {
+    const exponential = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    return exponential + Math.random() * exponential * 0.2;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/result.d.ts

@@ -0,0 +1,52 @@
+import type { ProblemDetails } from '@btrc/contracts';
+/** Parsed `ratelimit-*` response headers; null when the server sent none. */
+export type RateLimitInfo = {
+    limit: number;
+    remaining: number;
+    /** Epoch seconds at which the current window resets. */
+    reset: number;
+} | null;
+export type BtrcError = {
+    kind: 'http';
+    problem: ProblemDetails;
+} | {
+    kind: 'transport';
+    cause: unknown;
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'aborted';
+} | {
+    kind: 'parse';
+    cause: unknown;
+};
+export type ApiLinks = {
+    self: string;
+    next?: string | null;
+};
+export type ApiResult<TData, TMeta> = {
+    isError: false;
+    data: TData;
+    meta: TMeta;
+    links: ApiLinks;
+    error: null;
+    statusCode: number;
+    rateLimit: RateLimitInfo;
+} | {
+    isError: true;
+    data: null;
+    meta: null;
+    links: null;
+    error: BtrcError;
+    statusCode: number | null;
+    rateLimit: RateLimitInfo;
+};
+/** Thrown by iterators and the react layer, which cannot return result unions. */
+export declare class BtrcRequestError extends Error {
+    readonly error: BtrcError;
+    readonly statusCode: number | null;
+    readonly rateLimit: RateLimitInfo;
+    constructor(error: BtrcError, statusCode: number | null, rateLimit?: RateLimitInfo);
+    get problem(): ProblemDetails | null;
+}
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,IAAI,CAAC;AAET,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtC,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,KAAK,IAC9B;IACE,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,IAAI,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,aAAa,CAAC;CAC1B,GACD;IACE,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC;CAC1B,CAAC;AAEN,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAElC,YAAY,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,GAAE,aAAoB,EAMvF;IAED,IAAI,OAAO,IAAI,cAAc,GAAG,IAAI,CAEnC;CACF"}

package/dist/result.js

@@ -0,0 +1,30 @@
+/** Thrown by iterators and the react layer, which cannot return result unions. */
+export class BtrcRequestError extends Error {
+    error;
+    statusCode;
+    rateLimit;
+    constructor(error, statusCode, rateLimit = null) {
+        super(describeError(error));
+        this.name = 'BtrcRequestError';
+        this.error = error;
+        this.statusCode = statusCode;
+        this.rateLimit = rateLimit;
+    }
+    get problem() {
+        return this.error.kind === 'http' ? this.error.problem : null;
+    }
+}
+function describeError(error) {
+    switch (error.kind) {
+        case 'http':
+            return `BTRC API request failed: ${error.problem.status} ${error.problem.title}`;
+        case 'transport':
+            return 'BTRC API request failed: network error';
+        case 'timeout':
+            return 'BTRC API request failed: timed out';
+        case 'aborted':
+            return 'BTRC API request failed: aborted';
+        case 'parse':
+            return 'BTRC API request failed: response did not match the expected envelope';
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@btrc/api-server",
+  "version": "0.0.2",
+  "description": "Typed server-side (Node/SSR) client for the Bowler Racing BTRC API",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ReeceCenturion/BTRC.git",
+    "directory": "packages/api-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.25.67",
+    "@btrc/contracts": "^0.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.0.1",
+    "typescript": "7.0.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo lint skipped: typescript-eslint does not yet support TypeScript 7 (TODO: restore eslint . when @typescript-eslint ships TS7 support)",
+    "test": "vitest run",
+    "clean": "rimraf .turbo dist coverage"
+  }
+}