@databallr/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 databallr
+
+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

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @databallr/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for the [databallr API](https://api.databallr.com/docs):
+NBA and WNBA stats, player and team data, WOWY, shot quality, and SixRings.
+
+```bash
+npm install @databallr/sdk@next
+```
+
+Releases are 0.x on the `next` dist-tag while method names settle, so a minor
+version may break.
+
+```ts
+import { Databallr } from "@databallr/sdk";
+
+const dbr = new Databallr({ apiKey: process.env.DATABALLR_API_KEY });
+
+// One method per operation: path and query parameters in one object.
+const players = await dbr.nba.players.search({ q: "jokic", limit: 5 });
+const stats = await dbr.nba.players.byPlayerIdStats({ player_id: 203999, year: 2026 });
+const combos = await dbr.nba.pbp.lineupCombos({ team_abbr: "DEN" });
+
+// Or any path directly.
+const standings = await dbr.get("/v1/nba/standings", { query: { season: 2026 } });
+```
+
+- Create a key at https://accounts.databallr.com/account/api-keys. Keys start
+  with `dbrk_` and call `https://api.databallr.com`. `baseUrl` (or
+  `DATABALLR_BASE_URL`) points the client at another host.
+- Paths, parameters, bodies, and responses are typed from the API's OpenAPI
+  document. Only operations a personal API key can call are included.
+- A 429 is retried after its `Retry-After`; a 502, 503, 504, timeout, or
+  network error is retried with backoff. `maxRetries` (default 2) and
+  `timeoutMs` (default 30 s, per attempt) can be set on the client or per
+  call, along with `signal` and `headers`.
+- Non-2xx responses throw `DataballrError` (`status`, `code`, `message`,
+  `requestId`, `requiredScope`, `retryAfter`). Network failures throw
+  `DataballrConnectionError`, and timeouts its subclass
+  `DataballrTimeoutError`.
+- Responses are returned exactly as the API sends them.
+- The client refuses to run in a browser, where the key would be public,
+  unless you pass `allowBrowser: true`.
+
+MIT licensed.

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import { methods } from "./generated/methods.ts";
+import type { Call, Methods } from "./types.ts";
+export declare const PRODUCTION_BASE_URL = "https://api.databallr.com";
+/** Mirrors `@databallr/api-schemas/api-key-prefix`; a spec keeps them equal. */
+export declare const PRODUCTION_API_KEY_PREFIX = "dbrk_";
+export interface DataballrOptions {
+    /** A personal API key. Defaults to `process.env.DATABALLR_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Defaults to `process.env.DATABALLR_BASE_URL`, then
+     * `https://api.databallr.com` (which accepts only `dbrk_` keys).
+     */
+    baseUrl?: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Per attempt, including reading the body. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /**
+     * Retries after a 429 (once its `Retry-After` passes), a 502, 503 or 504, a
+     * timeout, or a network error. Every operation is a read, so a retry is
+     * safe, but it counts against the key's rate limit. Defaults to 2.
+     */
+    maxRetries?: number;
+    /**
+     * A key in a browser bundle is readable by anyone who loads the page, so
+     * construction in a browser throws unless this is set.
+     */
+    allowBrowser?: boolean;
+}
+/**
+ * Generated methods, e.g. `dbr.nba.players.search({ q: "jokic" })`. The
+ * constructor assigns every one from the same table, so none is left unset.
+ */
+export interface Databallr extends Methods<typeof methods> {
+}
+export declare class Databallr {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: DataballrOptions);
+    /** `GET` any key-callable path, typed from the API's OpenAPI document. */
+    readonly get: Call<"get">;
+    /** `POST` one of the read-only query operations. */
+    readonly post: Call<"post">;
+}

package/dist/client.js

@@ -0,0 +1,199 @@
+import { DataballrConnectionError, DataballrTimeoutError, errorFromResponse } from "./errors.js";
+import { methods } from "./generated/methods.js";
+export const PRODUCTION_BASE_URL = "https://api.databallr.com";
+export const PRODUCTION_API_KEY_PREFIX = "dbrk_";
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const MAX_RETRY_AFTER_MS = 60_000;
+export class Databallr {
+    baseUrl;
+    #apiKey;
+    #fetch;
+    #timeoutMs;
+    #maxRetries;
+    constructor(options = {}) {
+        if (!options.allowBrowser && isBrowser()) {
+            throw new Error("Databallr: refusing to run in a browser, where the API key would be public. " +
+                "Call the API from a server, or pass allowBrowser: true if you accept that.");
+        }
+        const apiKey = options.apiKey ?? env("DATABALLR_API_KEY");
+        if (!apiKey) {
+            throw new Error("Databallr: no API key. Pass { apiKey } or set DATABALLR_API_KEY. " +
+                "Create one at https://accounts.databallr.com/account/api-keys.");
+        }
+        const baseUrl = trimSlash(options.baseUrl ?? env("DATABALLR_BASE_URL") ?? PRODUCTION_BASE_URL);
+        if (baseUrl === PRODUCTION_BASE_URL && !apiKey.startsWith(PRODUCTION_API_KEY_PREFIX)) {
+            throw new Error(`Databallr: ${PRODUCTION_BASE_URL} accepts only keys that start with ${PRODUCTION_API_KEY_PREFIX}.`);
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("Databallr: no global fetch. Pass { fetch } on this runtime.");
+        }
+        this.baseUrl = baseUrl;
+        this.#apiKey = apiKey;
+        this.#fetch = fetchImpl;
+        this.#timeoutMs = options.timeoutMs ?? 30_000;
+        this.#maxRetries = options.maxRetries ?? 2;
+        Object.assign(this, this.#bind(methods));
+    }
+    get = (path, ...[options]) => this.#request("GET", path, options);
+    post = (path, ...[options]) => this.#request("POST", path, options);
+    #bind(table) {
+        return Object.fromEntries(Object.entries(table).map(([name, target]) => {
+            if (typeof target !== "string")
+                return [name, this.#bind(target)];
+            if (target.startsWith("POST ")) {
+                const path = target.slice("POST ".length);
+                return [
+                    name,
+                    (body, options) => this.#request("POST", path, { ...options, body }),
+                ];
+            }
+            const placeholders = new Set(Array.from(target.matchAll(/\{([^}]+)\}/g), (m) => m[1]));
+            return [
+                name,
+                (params = {}, options) => {
+                    const path = {};
+                    const query = {};
+                    for (const [key, value] of Object.entries(params)) {
+                        (placeholders.has(key) ? path : query)[key] = value;
+                    }
+                    return this.#request("GET", target, { ...options, path, query });
+                },
+            ];
+        }));
+    }
+    async #request(method, path, options) {
+        const url = new URL(this.baseUrl + fillPath(path, options?.path));
+        appendQuery(url, options?.query);
+        const headers = {
+            accept: "application/json",
+            ...options?.headers,
+            authorization: `Bearer ${this.#apiKey}`,
+        };
+        let body;
+        if (options?.body !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(options.body);
+        }
+        const signal = options?.signal;
+        const timeoutMs = options?.timeoutMs ?? this.#timeoutMs;
+        const maxRetries = options?.maxRetries ?? this.#maxRetries;
+        for (let attempt = 0;; attempt++) {
+            let result;
+            try {
+                result = await this.#attempt(url, { method, headers, body }, signal, timeoutMs);
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                const failure = error instanceof DataballrTimeoutError
+                    ? error
+                    : new DataballrConnectionError(`${method} ${url.pathname} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                if (attempt >= maxRetries)
+                    throw failure;
+                await sleep(backoffMs(attempt), signal);
+                continue;
+            }
+            const { response, content } = result;
+            if (response.ok) {
+                if (typeof content !== "string")
+                    return content;
+                return isJson(response) ? JSON.parse(content) : content;
+            }
+            const error = errorFromResponse(response, typeof content === "string" ? content : new TextDecoder().decode(content));
+            const retryAfterMs = error.retryAfter === undefined ? undefined : error.retryAfter * 1000;
+            const retryable = RETRY_STATUSES.has(response.status) &&
+                (retryAfterMs === undefined || retryAfterMs <= MAX_RETRY_AFTER_MS);
+            if (!retryable || attempt >= maxRetries)
+                throw error;
+            await sleep(retryAfterMs ?? backoffMs(attempt), signal);
+        }
+    }
+    async #attempt(url, init, signal, timeoutMs) {
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal?.reason);
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const response = await this.#fetch(url, { ...init, signal: controller.signal });
+            const content = isJson(response) || (response.headers.get("content-type") ?? "").startsWith("text/")
+                ? await response.text()
+                : await response.arrayBuffer();
+            return { response, content };
+        }
+        catch (error) {
+            if (timedOut) {
+                throw new DataballrTimeoutError(`${init.method} ${url.pathname} timed out after ${timeoutMs} ms`, { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+}
+function backoffMs(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) * (1 - Math.random() * 0.25);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function isJson(response) {
+    return (response.headers.get("content-type") ?? "").includes("json");
+}
+function fillPath(template, params) {
+    return template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = params?.[name];
+        if (value === undefined || value === null) {
+            throw new Error(`Databallr: missing path parameter "${name}" for ${template}`);
+        }
+        return encodeURIComponent(String(value));
+    });
+}
+function appendQuery(url, query) {
+    if (!query)
+        return;
+    for (const [name, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(name, String(item));
+        }
+        else {
+            url.searchParams.set(name, String(value));
+        }
+    }
+}
+function env(name) {
+    const vars = globalThis.process
+        ?.env;
+    return vars?.[name] || undefined;
+}
+function isBrowser() {
+    const g = globalThis;
+    return typeof g.window !== "undefined" && typeof g.document !== "undefined";
+}
+function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+interface DataballrErrorFields {
+    readonly status: number;
+    /** The shared envelope's `error`, or `http_error` when the body is not that envelope. */
+    readonly code: string;
+    readonly requestId: string | undefined;
+    /** The scope a 403 says would allow the call, from `WWW-Authenticate`. */
+    readonly requiredScope: string | undefined;
+    /** Seconds to wait before retrying, from `Retry-After`. */
+    readonly retryAfter: number | undefined;
+    /** The parsed JSON body, or the raw text when it was not JSON. */
+    readonly body: unknown;
+}
+/**
+ * Thrown for every non-2xx response. `code` is `invalid_token`,
+ * `insufficient_scope`, `rate_limited`, ... or `http_error`.
+ */
+export declare class DataballrError extends Error implements DataballrErrorFields {
+    readonly name = "DataballrError";
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly requiredScope: string | undefined;
+    readonly retryAfter: number | undefined;
+    readonly body: unknown;
+    constructor(message: string, fields: DataballrErrorFields);
+}
+/**
+ * The request never produced a response: DNS, TLS, a reset, or a timeout,
+ * after any retries. Aborting with your own `signal` rejects with its reason
+ * instead.
+ */
+export declare class DataballrConnectionError extends Error {
+    readonly name: string;
+}
+/** An attempt ran past `timeoutMs`, after any retries. */
+export declare class DataballrTimeoutError extends DataballrConnectionError {
+    readonly name = "DataballrTimeoutError";
+}
+export declare function errorFromResponse(response: Response, text: string): DataballrError;
+export {};

package/dist/errors.js

@@ -0,0 +1,45 @@
+export class DataballrError extends Error {
+    name = "DataballrError";
+    constructor(message, fields) {
+        super(message);
+        Object.assign(this, fields);
+    }
+}
+export class DataballrConnectionError extends Error {
+    name = "DataballrConnectionError";
+}
+export class DataballrTimeoutError extends DataballrConnectionError {
+    name = "DataballrTimeoutError";
+}
+export function errorFromResponse(response, text) {
+    let body = text;
+    try {
+        body = JSON.parse(text);
+    }
+    catch { }
+    const envelope = isEnvelope(body) ? body : undefined;
+    const code = envelope?.error ?? "http_error";
+    return new DataballrError(stringOrUndefined(envelope?.message) ??
+        (envelope ? code : `Request failed with status ${response.status}`), {
+        status: response.status,
+        code,
+        requestId: stringOrUndefined(envelope?.request_id),
+        requiredScope: response.headers.get("www-authenticate")?.match(/\bscope="([^"]*)"/)?.[1],
+        retryAfter: secondsFromRetryAfter(response.headers.get("retry-after")),
+        body,
+    });
+}
+function secondsFromRetryAfter(header) {
+    if (header === null)
+        return undefined;
+    const seconds = Number(header);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+function isEnvelope(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.error === "string");
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}