@sc-db/sdk 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @sc-db/sdk — TypeScript SDK
+
+Typed client for the SCDB API. Types are generated from the API's OpenAPI spec,
+so the SDK always matches the server.
+
+```ts
+import { createScdb } from "@sc-db/sdk";
+
+const scdb = createScdb({ baseUrl: "http://127.0.0.1:8000" });
+
+await scdb.stats();
+await scdb.types();
+await scdb.records({ type: "EntityClassDefinition", name: "gladius", is_main: true });
+await scdb.record(guid);     // full record + raw body
+await scdb.refs(guid);       // outgoing references
+await scdb.refsIn(guid);     // incoming references
+```
+
+## Dev
+```bash
+npm install
+npm run gen     # regenerate src/schema.ts from openapi.json
+npm run build   # tsc -> dist/
+node example.mjs   # smoke test (API must be running)
+```
+
+Refresh `openapi.json` after API changes:
+```bash
+# from repo root
+uv run python -c "import json; from api.main import app; json.dump(app.openapi(), open('sdk/js/openapi.json','w'), indent=2)"
+```
+
+Other language SDKs will live alongside this one: `sdk/python/`, etc.

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import type { paths, components } from "./schema.js";
+export type Stats = components["schemas"]["Stats"];
+export type Meta = components["schemas"]["Meta"];
+export type TypeCount = components["schemas"]["TypeCount"];
+export type RecordSummary = components["schemas"]["RecordSummary"];
+export type ScdbRecord = components["schemas"]["Record"];
+export type RecordPage = components["schemas"]["RecordPage"];
+export type Edge = components["schemas"]["Edge"];
+export type ShipSummary = components["schemas"]["ShipSummary"];
+export type ShipDetail = components["schemas"]["ShipDetail"];
+export type ShipPage = components["schemas"]["ShipPage"];
+export type ItemSummary = components["schemas"]["ItemSummary"];
+export type ItemDetail = components["schemas"]["ItemDetail"];
+export type ItemPage = components["schemas"]["ItemPage"];
+export type ItemCompareRow = components["schemas"]["ItemCompareRow"];
+export type ItemFacets = components["schemas"]["ItemFacets"];
+export type MissionSummary = components["schemas"]["MissionSummary"];
+export type MissionDetail = components["schemas"]["MissionDetail"];
+export type MissionPage = components["schemas"]["MissionPage"];
+export type ContractSummary = components["schemas"]["ContractSummary"];
+export type ContractDetail = components["schemas"]["ContractDetail"];
+export type ContractPage = components["schemas"]["ContractPage"];
+export type BlueprintSummary = components["schemas"]["BlueprintSummary"];
+export type BlueprintDetail = components["schemas"]["BlueprintDetail"];
+export type BlueprintPage = components["schemas"]["BlueprintPage"];
+export type StarmapSummary = components["schemas"]["StarmapSummary"];
+export type StarmapDetail = components["schemas"]["StarmapDetail"];
+export type StarmapPage = components["schemas"]["StarmapPage"];
+export type Location = components["schemas"]["Location"];
+export type LocationPage = components["schemas"]["LocationPage"];
+export type LocalizationEntry = components["schemas"]["LocalizationEntry"];
+export type LocalizationPage = components["schemas"]["LocalizationPage"];
+export type MiningOre = components["schemas"]["MiningOre"];
+export type MiningDeposit = components["schemas"]["MiningDeposit"];
+export type MiningBody = components["schemas"]["MiningBody"];
+export type MiningBodySummary = components["schemas"]["MiningBodySummary"];
+export type MiningProspect = components["schemas"]["MiningProspect"];
+export type CompareQuery = NonNullable<paths["/items/compare"]["get"]["parameters"]["query"]>;
+export type MissionsQuery = NonNullable<paths["/missions"]["get"]["parameters"]["query"]>;
+export type ContractsQuery = NonNullable<paths["/contracts"]["get"]["parameters"]["query"]>;
+export type BlueprintsQuery = NonNullable<paths["/blueprints"]["get"]["parameters"]["query"]>;
+export type StarmapQuery = NonNullable<paths["/starmap"]["get"]["parameters"]["query"]>;
+export type LocationsQuery = NonNullable<paths["/locations"]["get"]["parameters"]["query"]>;
+export type RecordsQuery = NonNullable<paths["/records"]["get"]["parameters"]["query"]>;
+export type LocalizationQuery = NonNullable<paths["/localization"]["get"]["parameters"]["query"]>;
+export type ShipsQuery = NonNullable<paths["/ships"]["get"]["parameters"]["query"]>;
+export type ItemsQuery = NonNullable<paths["/items"]["get"]["parameters"]["query"]>;
+export type ItemFacetsQuery = NonNullable<paths["/items/facets"]["get"]["parameters"]["query"]>;
+export interface ScdbOptions {
+    /** API base URL. Default: http://127.0.0.1:8000 */
+    baseUrl?: string;
+    /** Custom fetch (e.g. for SSR / auth). Default: global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * In-memory cache of GET responses (default: true). The whole DB is immutable
+     * within a game patch, so cached responses never go stale by time — instead the
+     * cache is flushed automatically the moment the API reports a new build
+     * (the `X-SCDB-Version` header changes), or manually via `clearCache()`.
+     */
+    cache?: boolean;
+}
+export declare class ScdbError extends Error {
+}
+export declare function createScdb(opts?: ScdbOptions): {
+    /** Underlying openapi-fetch client (escape hatch). */
+    raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
+    /** Drop every cached GET response (e.g. to force a refetch). */
+    clearCache: () => void;
+    /** Poll the API for a new game build; if it changed, flush the cache and
+     *  start busting the edge cache with the new version. Returns true on change.
+     *  Call it on app mount / window focus to keep clients fresh without any purge. */
+    checkVersion: () => Promise<boolean>;
+    stats(): Promise<Stats>;
+    /** Build provenance — the Star Citizen patch this database was extracted from. */
+    meta(): Promise<Meta>;
+    types(): Promise<TypeCount[]>;
+    records(query?: RecordsQuery): Promise<RecordPage>;
+    record(guid: string): Promise<ScdbRecord>;
+    /** Records this one points to (outgoing references). */
+    refs(guid: string): Promise<Edge[]>;
+    /** Records that point to this one (incoming references). */
+    refsIn(guid: string): Promise<Edge[]>;
+    /** Search the full global.ini table (key/value/q substring, or key prefix). */
+    localization(query?: LocalizationQuery): Promise<LocalizationPage>;
+    /** Resolve a single localization key (case-insensitive, '@' optional). */
+    localizationKey(key: string): Promise<LocalizationEntry>;
+    ships(query?: ShipsQuery): Promise<ShipPage>;
+    ship(guid: string): Promise<ShipDetail>;
+    /** Filter the item catalog. type + size = the compatible set for a slot. */
+    items(query?: ItemsQuery): Promise<ItemPage>;
+    /** Distinct sizes / subTypes / manufacturers for a category — sidebar facets. */
+    itemFacets(query?: ItemFacetsQuery): Promise<ItemFacets>;
+    item(className: string): Promise<ItemDetail>;
+    /** Items of a type (+size) with comparable stats — for the comparison table. */
+    compareItems(query: CompareQuery): Promise<ItemCompareRow[]>;
+    missions(query?: MissionsQuery): Promise<MissionPage>;
+    mission(guid: string): Promise<MissionDetail>;
+    contracts(query?: ContractsQuery): Promise<ContractPage>;
+    contractTypes(): Promise<TypeCount[]>;
+    contractFactions(): Promise<TypeCount[]>;
+    contract(guid: string): Promise<ContractDetail>;
+    blueprints(query?: BlueprintsQuery): Promise<BlueprintPage>;
+    blueprintCategories(): Promise<TypeCount[]>;
+    blueprint(guid: string): Promise<BlueprintDetail>;
+    starmap(query?: StarmapQuery): Promise<StarmapPage>;
+    starmapSystems(): Promise<TypeCount[]>;
+    starmapObject(className: string): Promise<StarmapDetail>;
+    locations(query?: LocationsQuery): Promise<LocationPage>;
+    locationTypes(query?: {
+        body?: string;
+        system?: string;
+    }): Promise<TypeCount[]>;
+    /** Bodies/fields with mineable resources — the mining picker. */
+    miningBodies(query?: {
+        system?: string;
+    }): Promise<MiningBodySummary[]>;
+    /** Full mining table for one body, grouped by method (ship/roc/fps). */
+    miningBody(body: string): Promise<MiningBody>;
+    /** Ore catalog with mining-minigame physics. */
+    miningElements(): Promise<MiningOre[]>;
+    /** Rock/asteroid compositions — ores per deposit, with probability. */
+    miningDeposits(): Promise<MiningDeposit[]>;
+    /** Prospecting planner: rank bodies for a wanted ore set (best single spot). */
+    miningProspect(ores: string[], opts?: {
+        method?: string;
+        system?: string;
+        limit?: number;
+    }): Promise<MiningProspect[]>;
+};
+export type ScdbClient = ReturnType<typeof createScdb>;

package/dist/index.js

@@ -0,0 +1,273 @@
+/**
+ * SCDB SDK — typed TypeScript client for the SCDB API.
+ *
+ *   import { createScdb } from "@sc-db/sdk";
+ *   const scdb = createScdb({ baseUrl: "http://127.0.0.1:8000" });
+ *   const page = await scdb.records({ type: "EntityClassDefinition", name: "gladius" });
+ */
+import createClient from "openapi-fetch";
+export class ScdbError extends Error {
+}
+function unwrap(data, error) {
+    if (error !== undefined || data === undefined) {
+        throw new ScdbError(`SCDB API error: ${JSON.stringify(error)}`);
+    }
+    return data;
+}
+export function createScdb(opts = {}) {
+    const baseUrl = opts.baseUrl ?? "http://127.0.0.1:8000";
+    const baseFetch = opts.fetch ?? globalThis.fetch;
+    const useCache = opts.cache !== false;
+    // url -> Response (kept un-consumed; every read returns a fresh clone)
+    const store = new Map();
+    let currentVersion = null;
+    let versionProbe = null;
+    function clearCache() {
+        store.clear();
+    }
+    // /version is served uncached — it's the cheap "has the game patched?" check.
+    async function fetchVersion() {
+        try {
+            const r = await baseFetch(`${baseUrl}/version`, { headers: { "cache-control": "no-cache" } });
+            if (r.ok)
+                return (await r.json()).version ?? null;
+        }
+        catch { /* network — fall through */ }
+        return null;
+    }
+    async function ensureVersion() {
+        if (currentVersion)
+            return currentVersion;
+        if (!versionProbe)
+            versionProbe = fetchVersion().then((v) => (currentVersion = v));
+        return versionProbe;
+    }
+    /**
+     * Re-check the API's build version. If the game has patched, the local cache is
+     * dropped and subsequent requests bust the edge (Cloudflare) cache via `?v=` —
+     * so data refreshes with no manual purge. Returns true if the version changed.
+     */
+    async function checkVersion() {
+        const v = await fetchVersion();
+        if (v && v !== currentVersion) {
+            currentVersion = v;
+            versionProbe = Promise.resolve(v);
+            store.clear();
+            return true;
+        }
+        return false;
+    }
+    const cachingFetch = async (input, init) => {
+        const isReq = typeof input === "object" && input instanceof Request;
+        const method = (init?.method ?? (isReq ? input.method : "GET")).toUpperCase();
+        let url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (method !== "GET")
+            return baseFetch(input, init);
+        // tag the request with the current build → a new patch = a new cache key,
+        // both in this Map and at the CDN edge (Cloudflare), so nothing goes stale.
+        const v = await ensureVersion();
+        if (v)
+            url += (url.includes("?") ? "&" : "?") + "v=" + encodeURIComponent(v);
+        const hit = store.get(url);
+        if (hit)
+            return hit.clone();
+        const res = await baseFetch(isReq ? new Request(url, input) : url, isReq ? undefined : init);
+        if (res.ok)
+            store.set(url, res.clone());
+        return res;
+    };
+    const client = createClient({
+        baseUrl,
+        fetch: useCache ? cachingFetch : baseFetch,
+    });
+    return {
+        /** Underlying openapi-fetch client (escape hatch). */
+        raw: client,
+        /** Drop every cached GET response (e.g. to force a refetch). */
+        clearCache,
+        /** Poll the API for a new game build; if it changed, flush the cache and
+         *  start busting the edge cache with the new version. Returns true on change.
+         *  Call it on app mount / window focus to keep clients fresh without any purge. */
+        checkVersion,
+        async stats() {
+            const { data, error } = await client.GET("/stats");
+            return unwrap(data, error);
+        },
+        /** Build provenance — the Star Citizen patch this database was extracted from. */
+        async meta() {
+            const { data, error } = await client.GET("/meta");
+            return unwrap(data, error);
+        },
+        async types() {
+            const { data, error } = await client.GET("/types");
+            return unwrap(data, error);
+        },
+        async records(query = {}) {
+            const { data, error } = await client.GET("/records", { params: { query } });
+            return unwrap(data, error);
+        },
+        async record(guid) {
+            const { data, error } = await client.GET("/records/{guid}", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        /** Records this one points to (outgoing references). */
+        async refs(guid) {
+            const { data, error } = await client.GET("/records/{guid}/refs", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        /** Records that point to this one (incoming references). */
+        async refsIn(guid) {
+            const { data, error } = await client.GET("/records/{guid}/refs-in", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        // ── localization (raw global.ini key→value table) ───────────────────────
+        /** Search the full global.ini table (key/value/q substring, or key prefix). */
+        async localization(query = {}) {
+            const { data, error } = await client.GET("/localization", { params: { query } });
+            return unwrap(data, error);
+        },
+        /** Resolve a single localization key (case-insensitive, '@' optional). */
+        async localizationKey(key) {
+            const { data, error } = await client.GET("/localization/{key}", {
+                params: { path: { key } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: ships ──────────────────────────────────────────────────────
+        async ships(query = {}) {
+            const { data, error } = await client.GET("/ships", { params: { query } });
+            return unwrap(data, error);
+        },
+        async ship(guid) {
+            const { data, error } = await client.GET("/ships/{guid}", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: items (catalog + compatibility) ────────────────────────────
+        /** Filter the item catalog. type + size = the compatible set for a slot. */
+        async items(query = {}) {
+            const { data, error } = await client.GET("/items", { params: { query } });
+            return unwrap(data, error);
+        },
+        /** Distinct sizes / subTypes / manufacturers for a category — sidebar facets. */
+        async itemFacets(query = {}) {
+            const { data, error } = await client.GET("/items/facets", { params: { query } });
+            return unwrap(data, error);
+        },
+        async item(className) {
+            const { data, error } = await client.GET("/items/{className}", {
+                params: { path: { className } },
+            });
+            return unwrap(data, error);
+        },
+        /** Items of a type (+size) with comparable stats — for the comparison table. */
+        async compareItems(query) {
+            const { data, error } = await client.GET("/items/compare", { params: { query } });
+            return unwrap(data, error);
+        },
+        // ── layer 2: missions ───────────────────────────────────────────────────
+        async missions(query = {}) {
+            const { data, error } = await client.GET("/missions", { params: { query } });
+            return unwrap(data, error);
+        },
+        async mission(guid) {
+            const { data, error } = await client.GET("/missions/{guid}", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: contracts (real procedural missions) ───────────────────────
+        async contracts(query = {}) {
+            const { data, error } = await client.GET("/contracts", { params: { query } });
+            return unwrap(data, error);
+        },
+        async contractTypes() {
+            const { data, error } = await client.GET("/contracts/types");
+            return unwrap(data, error);
+        },
+        async contractFactions() {
+            const { data, error } = await client.GET("/contracts/factions");
+            return unwrap(data, error);
+        },
+        async contract(guid) {
+            const { data, error } = await client.GET("/contracts/{guid}", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: blueprints (crafting) ──────────────────────────────────────
+        async blueprints(query = {}) {
+            const { data, error } = await client.GET("/blueprints", { params: { query } });
+            return unwrap(data, error);
+        },
+        async blueprintCategories() {
+            const { data, error } = await client.GET("/blueprints/categories");
+            return unwrap(data, error);
+        },
+        async blueprint(guid) {
+            const { data, error } = await client.GET("/blueprints/{guid}", {
+                params: { path: { guid } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: starmap ────────────────────────────────────────────────────
+        async starmap(query = {}) {
+            const { data, error } = await client.GET("/starmap", { params: { query } });
+            return unwrap(data, error);
+        },
+        async starmapSystems() {
+            const { data, error } = await client.GET("/starmap/systems");
+            return unwrap(data, error);
+        },
+        async starmapObject(className) {
+            const { data, error } = await client.GET("/starmap/{className}", {
+                params: { path: { className } },
+            });
+            return unwrap(data, error);
+        },
+        // ── layer 2: in-world locations (resource/derelict/outpost… from socpaks) ──
+        async locations(query = {}) {
+            const { data, error } = await client.GET("/locations", { params: { query } });
+            return unwrap(data, error);
+        },
+        async locationTypes(query = {}) {
+            const { data, error } = await client.GET("/locations/types", { params: { query } });
+            return unwrap(data, error);
+        },
+        // ── layer 2: mining (what's mineable where, with probabilities) ──────────
+        /** Bodies/fields with mineable resources — the mining picker. */
+        async miningBodies(query = {}) {
+            const { data, error } = await client.GET("/mining/bodies", { params: { query } });
+            return unwrap(data, error);
+        },
+        /** Full mining table for one body, grouped by method (ship/roc/fps). */
+        async miningBody(body) {
+            const { data, error } = await client.GET("/mining/{body}", { params: { path: { body } } });
+            return unwrap(data, error);
+        },
+        /** Ore catalog with mining-minigame physics. */
+        async miningElements() {
+            const { data, error } = await client.GET("/mining/elements");
+            return unwrap(data, error);
+        },
+        /** Rock/asteroid compositions — ores per deposit, with probability. */
+        async miningDeposits() {
+            const { data, error } = await client.GET("/mining/deposits");
+            return unwrap(data, error);
+        },
+        /** Prospecting planner: rank bodies for a wanted ore set (best single spot). */
+        async miningProspect(ores, opts = {}) {
+            const { data, error } = await client.GET("/mining/prospect", {
+                params: { query: { ores: ores.join(","), ...opts } },
+            });
+            return unwrap(data, error);
+        },
+    };
+}