@quizbase/client 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @quizbase/client
 
-TypeScript SDK for the [QuizBase API](https://quizbase.runriva.com) — multilingual trivia API with 1.4M+ quiz-ready questions blended from 11 open-licensed sources, English and Polish at launch.
+TypeScript SDK for the [QuizBase API](https://quizbase.runriva.com) — a multilingual trivia API. 1.4M+ blended, deduped questions from 11 open datasets (CC, MIT), English and Polish at launch. Per-record license, author, and source on every response.
 
 [![npm](https://img.shields.io/npm/v/@quizbase/client.svg)](https://www.npmjs.com/package/@quizbase/client)
 [![types](https://img.shields.io/npm/types/@quizbase/client.svg)](https://www.npmjs.com/package/@quizbase/client)
@@ -28,7 +28,7 @@ const client = createClient({
 });
 
 const random = await client.questions.random({ category: 'science-and-nature', lang: 'en' });
-console.log(random.data.question);
+console.log(random.data[0].text);
 ```
 
 Get a key at [quizbase.runriva.com/dashboard/keys](https://quizbase.runriva.com/dashboard/keys). The free tier is **500 requests/day across all your keys** against full production data — enough to ship a real app. Paid tiers at [/pricing](https://quizbase.runriva.com/pricing).
@@ -58,6 +58,8 @@ client.report.create({ questionId, kind, comment });
 
 Full parameter docs: [docs.quizbase.runriva.com/docs](https://quizbase.runriva.com/docs) and the interactive [API Reference](https://quizbase.runriva.com/docs/api-reference).
 
+> **Tip:** every question has a stable UUID `id` that never changes. Save it client-side and compose it into multi-language quizzes, daily challenges, anti-cheat, and more — see [Client patterns](#client-patterns-with-stable-ids) below.
+
 ## Pagination
 
 `questions`, `topics`, `tags`, and `subcategories` are cursor-paginated. Use `listAll()` to iterate every item, or `pages()` to iterate page-by-page — both auto-follow `_links.next` and preserve filters across pages.
@@ -76,6 +78,58 @@ for await (const page of client.topics.pages({ lang: 'en' })) {
 
 Need manual control? `list()` still exposes `_links.next` and a `cursor` query param.
 
+## Client patterns with stable IDs
+
+Every question carries a stable UUID v7 `id` that never changes after import. The SDK is intentionally **thin** — no `?seed=`, no `?daily=`, no built-in deduplication. The stable id is the primitive you compose into mechanics. Six patterns cover most real apps:
+
+### Same question across languages
+
+```ts
+const en = await client.questions.random({ lang: 'en' });
+const id = en.data[0].id;
+const pl = await client.questions.get(id, { lang: 'pl' });
+const es = await client.questions.get(id, { lang: 'es' });
+// Same canonical question, three languages — UUID is the link.
+```
+
+### Don't repeat — exclude seen questions
+
+```ts
+const seen = new Set<string>();
+const batch = await client.questions.random({
+  category: 'science-and-nature',
+  amount: 20,
+  exclude: [...seen]
+});
+batch.data.forEach((q) => seen.add(q.id));
+```
+
+`exclude` accepts up to 250 UUIDs. For longer histories keep `seen` client-side and filter after the fetch.
+
+### Daily challenge — same question for everyone today
+
+```ts
+const day = new Date().toISOString().slice(0, 10); // "2026-05-19"
+const idx = [...day].reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 7);
+const pool = await client.questions.list({ category: 'history', limit: 50 });
+const todays = pool.data[Math.abs(idx) % pool.data.length];
+// Persist `todays.id` server-side so retries serve the same question.
+```
+
+### Multiplayer sync — both players see the same question
+
+Your matchmaker picks one `id` (via `random` or `list`), broadcasts to both clients, and both clients call `questions.get(id, { lang })`. Same UUID, per-player language preference. Zero state on QuizBase — your matchmaker owns the round.
+
+### Server-side anti-cheat — never ship `correctAnswer` to the client
+
+Use `qb_sk_*` (secret key) from your server to fetch full questions including `correctAnswer`. Forward only `id` + `text` + a shuffled `[correctAnswer, ...incorrectAnswers]` to the client. Validate the submitted answer server-side by re-fetching with the same `id`. Browsers cannot reach `qb_sk_*` — CORS blocks it.
+
+### Stable Anki / Quizlet flashcards across updates
+
+Save `{id, lang}` as your card key. When the upstream question changes (typo fix, distractor swap, translation refresh), `questions.get(id, { lang })` returns the updated content under the same id — your card auto-updates without re-import. Soft-deleted questions return 404; treat that as "card removed upstream".
+
+Full code samples and edge cases at [/docs/api/questions-by-id § What you can do with a stable id](https://quizbase.runriva.com/docs/api/questions-by-id). For MCP agents, the same playbook is exposed as the `client_mechanics_patterns` prompt.
+
 ## Errors
 
 Every non-2xx response throws `QuizbaseError` carrying the parsed [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457):
@@ -164,7 +218,7 @@ All responses are typed from the OpenAPI spec. Hover over `client.questions.rand
 - **GitHub:** [maciejdzierzek/quizbase-sdk-ts](https://github.com/maciejdzierzek/quizbase-sdk-ts)
 - **Issues / feedback:** [GitHub Issues](https://github.com/maciejdzierzek/quizbase-sdk-ts/issues)
 - **Releases:** automated by [release-please](https://github.com/googleapis/release-please) from conventional commits
-- **Drift guard:** the main repo [`tests/api/sdk-contract.spec.ts`](https://github.com/maciejdzierzek/quizbase) verifies the latest published SDK still matches `/openapi.json`
+- **Drift guard:** every release is verified against the live OpenAPI spec at [quizbase.runriva.com/openapi.json](https://quizbase.runriva.com/openapi.json) — types reflect the current API surface.
 
 ## License
 

package/dist/index.d.cts

@@ -857,9 +857,10 @@ interface paths {
                     topic?: string;
                     topics_any?: string;
                     subcategory?: string;
-                    quality?: "high";
+                    /** @description Quality preset: "high" (default) skips needs_review=true; "all" includes everything */
+                    quality?: "high" | "all";
                     regions?: string;
-                    source?: "opentdb" | "opentriviaqa" | "mkqa" | "mmlu-prox" | "wikipedia" | "community" | "runriva" | "ai-generated" | "purchased" | "quizbase";
+                    source?: "arc" | "creak" | "entityq" | "kqa-pro" | "mintaka" | "mkqa" | "nq-open" | "opentdb" | "opentriviaqa" | "qasc" | "quizbase" | "webq";
                     license?: "CC-BY-SA-4.0" | "CC-BY-SA-3.0" | "CC-BY-4.0" | "MIT" | "proprietary";
                     count?: "estimate" | "exact" | "none";
                 };
@@ -958,9 +959,10 @@ interface paths {
                     topic?: string;
                     topics_any?: string;
                     subcategory?: string;
-                    quality?: "high";
+                    /** @description Quality preset: "high" (default) skips needs_review=true; "all" includes everything */
+                    quality?: "high" | "all";
                     regions?: string;
-                    source?: "opentdb" | "opentriviaqa" | "mkqa" | "mmlu-prox" | "wikipedia" | "community" | "runriva" | "ai-generated" | "purchased" | "quizbase";
+                    source?: "arc" | "creak" | "entityq" | "kqa-pro" | "mintaka" | "mkqa" | "nq-open" | "opentdb" | "opentriviaqa" | "qasc" | "quizbase" | "webq";
                     license?: "CC-BY-SA-4.0" | "CC-BY-SA-3.0" | "CC-BY-4.0" | "MIT" | "proprietary";
                     exclude?: string;
                 };
@@ -1213,6 +1215,12 @@ interface components {
              */
             regions: string[];
             attribution: components["schemas"]["Attribution"];
+            /**
+             * @description Quality flag. Present only when the client requested non-default content via `?quality=all` (REST) or `quality: "all"` (MCP) — and always on `/api/v1/questions/{id}` deep-link responses. For default `?quality=high` all returned questions are by definition `high`, so the field is omitted to avoid redundancy. `needs_review` = flagged for moderation review (low-quality distractors, trivial answer-in-question patterns).
+             * @example high
+             * @enum {string}
+             */
+            quality?: "high" | "needs_review";
             /**
              * Format: uuid
              * @description Direct parent (usually English source) when this is a translation.

package/dist/index.d.ts

@@ -857,9 +857,10 @@ interface paths {
                     topic?: string;
                     topics_any?: string;
                     subcategory?: string;
-                    quality?: "high";
+                    /** @description Quality preset: "high" (default) skips needs_review=true; "all" includes everything */
+                    quality?: "high" | "all";
                     regions?: string;
-                    source?: "opentdb" | "opentriviaqa" | "mkqa" | "mmlu-prox" | "wikipedia" | "community" | "runriva" | "ai-generated" | "purchased" | "quizbase";
+                    source?: "arc" | "creak" | "entityq" | "kqa-pro" | "mintaka" | "mkqa" | "nq-open" | "opentdb" | "opentriviaqa" | "qasc" | "quizbase" | "webq";
                     license?: "CC-BY-SA-4.0" | "CC-BY-SA-3.0" | "CC-BY-4.0" | "MIT" | "proprietary";
                     count?: "estimate" | "exact" | "none";
                 };
@@ -958,9 +959,10 @@ interface paths {
                     topic?: string;
                     topics_any?: string;
                     subcategory?: string;
-                    quality?: "high";
+                    /** @description Quality preset: "high" (default) skips needs_review=true; "all" includes everything */
+                    quality?: "high" | "all";
                     regions?: string;
-                    source?: "opentdb" | "opentriviaqa" | "mkqa" | "mmlu-prox" | "wikipedia" | "community" | "runriva" | "ai-generated" | "purchased" | "quizbase";
+                    source?: "arc" | "creak" | "entityq" | "kqa-pro" | "mintaka" | "mkqa" | "nq-open" | "opentdb" | "opentriviaqa" | "qasc" | "quizbase" | "webq";
                     license?: "CC-BY-SA-4.0" | "CC-BY-SA-3.0" | "CC-BY-4.0" | "MIT" | "proprietary";
                     exclude?: string;
                 };
@@ -1213,6 +1215,12 @@ interface components {
              */
             regions: string[];
             attribution: components["schemas"]["Attribution"];
+            /**
+             * @description Quality flag. Present only when the client requested non-default content via `?quality=all` (REST) or `quality: "all"` (MCP) — and always on `/api/v1/questions/{id}` deep-link responses. For default `?quality=high` all returned questions are by definition `high`, so the field is omitted to avoid redundancy. `needs_review` = flagged for moderation review (low-quality distractors, trivial answer-in-question patterns).
+             * @example high
+             * @enum {string}
+             */
+            quality?: "high" | "needs_review";
             /**
              * Format: uuid
              * @description Direct parent (usually English source) when this is a translation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quizbase/client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript SDK for QuizBase API — typed client, retry, RFC 9457 errors, telemetry hook. Generated from openapi.json.",
   "license": "MIT",
   "author": "Maciej Dzierżek",