@sc-db/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,33 +1,88 @@
-# @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.
+# @sc-db/sdk
+
+Typed TypeScript client for the **[SCDB](https://sc-db.fr) API** — open, free data for
+[Star Citizen](https://robertsspaceindustries.com/), derived 100% from the game files
+(DataForge + the `Data.p4k` archive): ships, items, FPS gear, missions & contracts,
+crafting blueprints, the 3D starmap, and per-body mining tables.
+
+The API is public and read-only — **no API key, no auth**. Types are generated from the
+API's OpenAPI spec, so the client always matches the live server.
+
+## Install
+
+```bash
+npm i @sc-db/sdk
+```
+
+## Usage
+
+```ts
+import { createScdb } from "@sc-db/sdk";
+
+const scdb = createScdb();              // defaults to https://api.sc-db.fr
+
+// ships
+const ships = await scdb.ships({ name: "gladius" });
+const ship = await scdb.ship(guid);     // detail + default loadout
+
+// items / FPS gear (filter by type, size, manufacturer…)
+const rifles = await scdb.items({ category: "fps_weapon", size: 3 });
+
+// mining — what's mineable where, with probabilities
+const cellin = await scdb.miningBody("Stanton2a");
+const spots = await scdb.miningProspect(["Quantainium", "Taranite"]);  // best places
+
+// starmap
+const systems = await scdb.starmapSystems();
+const crusader = await scdb.starmapObject("Stanton2");
+```
+
+Point it at your own instance with `createScdb({ baseUrl: "https://…" })`.
+
+## What you can query
+
+| Area | Methods |
+| --- | --- |
+| Meta | `stats` · `meta` · `types` |
+| Records (raw + graph) | `records` · `record` · `refs` · `refsIn` |
+| Ships | `ships` · `ship` |
+| Items | `items` · `itemFacets` · `item` · `compareItems` |
+| Missions & contracts | `missions` · `mission` · `contracts` · `contract` · `contractTypes` · `contractFactions` |
+| Blueprints | `blueprints` · `blueprint` · `blueprintCategories` |
+| Starmap & locations | `starmap` · `starmapObject` · `starmapSystems` · `locations` · `locationTypes` |
+| Mining | `miningBodies` · `miningBody` · `miningElements` · `miningDeposits` · `miningProspect` |
+| Localization | `localization` · `localizationKey` |
+
+Every method is fully typed (request + response). Errors throw `ScdbError`.
+`scdb.raw` exposes the underlying [openapi-fetch](https://openapi-ts.dev/openapi-fetch/)
+client as an escape hatch.
+
+## Caching
+
+GET responses are cached in memory. The data only changes once per game patch, so the
+cache **never expires by time** — instead it's keyed on the build version and refreshes
+automatically when the API ships a new patch:
+
+```ts
+await scdb.checkVersion();   // poll for a new patch; flushes the cache if it changed
+scdb.clearCache();           // drop everything manually
+createScdb({ cache: false }); // opt out entirely
+```
+
+## Rate limit
+
+The public API is rate-limited per IP (120 requests / 60s by default). On `429` the
+response carries `Retry-After`. Please cache responses (the SDK does) rather than hammering
+it — and use this client instead of scraping the website.
+
+## Links
+
+- API reference (Swagger): https://api.sc-db.fr/docs
+- OpenAPI spec: https://api.sc-db.fr/openapi.json
+- Website: https://sc-db.fr
+- Source: https://github.com/Romain-Boudot/sc-db
+
+## License
+
+MIT · Unofficial project, not affiliated with Cloud Imperium Games. Data belongs to CIG;
+this only re-exposes what ships in the game client.

package/dist/index.d.ts

@@ -47,7 +47,7 @@ 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 */
+    /** API base URL. Default: https://api.sc-db.fr */
     baseUrl?: string;
     /** Custom fetch (e.g. for SSR / auth). Default: global fetch. */
     fetch?: typeof fetch;

package/dist/index.js

@@ -2,7 +2,7 @@
  * 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 scdb = createScdb();                       // defaults to https://api.sc-db.fr
  *   const page = await scdb.records({ type: "EntityClassDefinition", name: "gladius" });
  */
 import createClient from "openapi-fetch";
@@ -15,7 +15,7 @@ function unwrap(data, error) {
     return data;
 }
 export function createScdb(opts = {}) {
-    const baseUrl = opts.baseUrl ?? "http://127.0.0.1:8000";
+    const baseUrl = opts.baseUrl ?? "https://api.sc-db.fr";
     const baseFetch = opts.fetch ?? globalThis.fetch;
     const useCache = opts.cache !== false;
     // url -> Response (kept un-consumed; every read returns a fresh clone)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sc-db/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "TypeScript SDK for the SCDB API — open Star Citizen data (DataForge)",
   "keywords": ["star-citizen", "starcitizen", "dataforge", "scdb", "sdk", "api-client"],
   "license": "MIT",