@quizbase/client 0.2.3 → 0.4.0

package/dist/index.d.cts

@@ -38,7 +38,7 @@ interface paths {
         };
         /**
          * List categories
-         * @description 24 top-level categories with localized names. Public, no API key required.
+         * @description 24 top-level categories with localized names.
          */
         get: {
             parameters: {
@@ -61,8 +61,17 @@ interface paths {
                         "application/json": components["schemas"]["CategoriesResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -70,7 +79,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -107,7 +116,7 @@ interface paths {
         };
         /**
          * Aggregate dataset stats
-         * @description Total questions, per-language, per-source, per-category counters. Public, cached.
+         * @description Total questions, per-language, per-source, per-category counters. Cached.
          */
         get: {
             parameters: {
@@ -130,8 +139,17 @@ interface paths {
                         "application/json": components["schemas"]["StatsResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -139,7 +157,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -176,7 +194,7 @@ interface paths {
         };
         /**
          * Supported languages
-         * @description Whitelist of `?lang=` values with native names and counts. Public.
+         * @description Whitelist of `?lang=` values with native names and counts.
          */
         get: {
             parameters: {
@@ -199,8 +217,17 @@ interface paths {
                         "application/json": components["schemas"]["LanguagesResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -208,7 +235,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -245,7 +272,7 @@ interface paths {
         };
         /**
          * List curated topics
-         * @description 2,184 curated topics with aliases and counts. Public, no API key required.
+         * @description 2,184 curated topics with aliases and counts.
          */
         get: {
             parameters: {
@@ -272,8 +299,17 @@ interface paths {
                         "application/json": components["schemas"]["TopicsListResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -281,7 +317,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -344,8 +380,17 @@ interface paths {
                         "application/json": components["schemas"]["TopicDetailResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -362,7 +407,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -425,8 +470,17 @@ interface paths {
                         "application/json": components["schemas"]["TagsListResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -434,7 +488,7 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -497,8 +551,8 @@ interface paths {
                         "application/json": components["schemas"]["SubcategoriesListResponse"];
                     };
                 };
-                /** @description Invalid query parameters. */
-                400: {
+                /** @description Missing, malformed, invalid, or revoked API key. */
+                401: {
                     headers: {
                         [name: string]: unknown;
                     };
@@ -506,7 +560,16 @@ interface paths {
                         "application/problem+json": components["schemas"]["ProblemDetails"];
                     };
                 };
-                /** @description Rate limit exceeded. */
+                /** @description IP not allowed (per-key allowlist). */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/problem+json": components["schemas"]["ProblemDetails"];
+                    };
+                };
+                /** @description Rate limit exceeded. See `Retry-After` header. */
                 429: {
                     headers: {
                         [name: string]: unknown;
@@ -545,7 +608,7 @@ interface paths {
         put?: never;
         /**
          * Report a problem with a question
-         * @description Public submission for translation / factual / inappropriate / attribution / other reports. Rate-limited 5/min/IP.
+         * @description Anonymous submission for translation / factual / inappropriate / attribution / other reports. Rate-limited 5/min/IP. No API key required.
          */
         post: {
             parameters: {
@@ -784,7 +847,8 @@ interface paths {
                     limit?: number;
                     /** @description Display language for category names + slug labels (subcategories/tags) */
                     lang?: "en" | "pl";
-                    updated_since?: string | null;
+                    /** @description ISO 8601 datetime — only questions modified after this point. */
+                    updated_since?: string;
                     category?: string;
                     difficulty?: "easy" | "medium" | "hard";
                     type?: "multiple" | "boolean" | "text_input";
@@ -1091,6 +1155,21 @@ interface components {
             retryAfter?: number;
             /** @description URL to upgrade plan (429 only). */
             upgradeUrl?: string;
+            /**
+             * @description Rate limit ceiling that was exceeded (429 only).
+             * @example 5
+             */
+            limit?: number;
+            /**
+             * @description API tier whose limit was exceeded (429 only).
+             * @example free
+             */
+            tier?: string;
+            /**
+             * @description Number of requests in current window (429 only).
+             * @example 100
+             */
+            current?: number;
         };
         Question: {
             /**
@@ -1540,19 +1619,15 @@ interface components {
         ApiKeyInfo: {
             /** @example 01J3KXY1ZAB7CQNR8TP4Z9EXMQ */
             id: string;
-            /** @example Default test key */
+            /** @example Default key */
             name: string;
             /**
              * @description Masked display value.
-             * @example qb_test_pk_••••1234
+             * @example qb_pk_••••1234
              */
             prefix: string;
             /**
-             * @example test
-             * @enum {string}
-             */
-            env: "test" | "live";
-            /**
+             * @description `pk` (publishable, CORS-safe for browsers) or `sk` (secret, backend-only).
              * @example pk
              * @enum {string}
              */
@@ -1560,16 +1635,16 @@ interface components {
         };
         RateLimitInfo: {
             /**
-             * @description Per-minute window cap. Test keys report `Number.MAX_SAFE_INTEGER`.
-             * @example 60
+             * @description Burst window cap (10s sliding). Shared across all active keys of the user.
+             * @example 10
              */
             limit: number;
-            /** @example 58 */
+            /** @example 8 */
             remaining: number;
-            /** @example 42 */
+            /** @example 7 */
             resetInSeconds: number;
-            /** @example 60 */
-            perMinute: number;
+            /** @example 10 */
+            burstPer10s: number;
             /** @example 500 */
             perDay: number;
         };
@@ -1722,7 +1797,7 @@ type Schemas = components['schemas'];
 /** Logical endpoint identifiers — stable across path-param values, used for telemetry + per-endpoint timeouts. */
 type EndpointKey = 'questions.list' | 'questions.random' | 'questions.get' | 'categories.list' | 'languages.list' | 'topics.list' | 'topics.get' | 'tags.list' | 'subcategories.list' | 'stats.get' | 'me.get' | 'usage.get' | 'report.create';
 interface ClientOptions {
-    /** API key. Use `qb_test_pk_*` / `qb_test_sk_*` for development (free, unmetered) and `qb_live_*` in production. */
+    /** API key — `qb_pk_*` (publishable, CORS-safe for browsers) or `qb_sk_*` (secret, backend-only). Get one at https://quizbase.runriva.com/dashboard/keys. */
     apiKey: string;
     /** Override base URL. Defaults to `https://quizbase.runriva.com`. */
     baseUrl?: string;
@@ -1739,11 +1814,19 @@ interface ClientOptions {
     /** User-Agent suffix appended to the SDK identifier. */
     userAgent?: string;
 }
+type QuestionsListParams = paths['/api/v1/questions']['get']['parameters']['query'];
+type TopicsListParams = paths['/api/v1/topics']['get']['parameters']['query'];
+type TagsListParams = paths['/api/v1/tags']['get']['parameters']['query'];
+type SubcategoriesListParams = paths['/api/v1/subcategories']['get']['parameters']['query'];
 interface QuizbaseClient {
     questions: {
-        list(params?: paths['/api/v1/questions']['get']['parameters']['query']): Promise<Schemas['QuestionsListResponse']>;
+        list(params?: QuestionsListParams): Promise<Schemas['QuestionsListResponse']>;
         random(params?: paths['/api/v1/questions/random']['get']['parameters']['query']): Promise<Schemas['QuestionsRandomResponse']>;
         get(id: string, params?: paths['/api/v1/questions/{id}']['get']['parameters']['query']): Promise<Schemas['QuestionByIdResponse']>;
+        /** Iterate every page of `/questions`, auto-following `_links.next`. */
+        pages(params?: QuestionsListParams): AsyncIterableIterator<Schemas['QuestionsListResponse']>;
+        /** Iterate every question across all pages. */
+        listAll(params?: QuestionsListParams): AsyncIterableIterator<Schemas['Question']>;
     };
     categories: {
         list(params?: paths['/api/v1/categories']['get']['parameters']['query']): Promise<Schemas['CategoriesResponse']>;
@@ -1752,14 +1835,26 @@ interface QuizbaseClient {
         list(): Promise<Schemas['LanguagesResponse']>;
     };
     topics: {
-        list(params?: paths['/api/v1/topics']['get']['parameters']['query']): Promise<Schemas['TopicsListResponse']>;
+        list(params?: TopicsListParams): Promise<Schemas['TopicsListResponse']>;
         get(slug: string, params?: paths['/api/v1/topics/{slug}']['get']['parameters']['query']): Promise<Schemas['TopicDetailResponse']>;
+        /** Iterate every page of `/topics`, auto-following `_links.next`. */
+        pages(params?: TopicsListParams): AsyncIterableIterator<Schemas['TopicsListResponse']>;
+        /** Iterate every topic across all pages. */
+        listAll(params?: TopicsListParams): AsyncIterableIterator<Schemas['TopicEntry']>;
     };
     tags: {
-        list(params?: paths['/api/v1/tags']['get']['parameters']['query']): Promise<Schemas['TagsListResponse']>;
+        list(params?: TagsListParams): Promise<Schemas['TagsListResponse']>;
+        /** Iterate every page of `/tags`, auto-following `_links.next`. */
+        pages(params?: TagsListParams): AsyncIterableIterator<Schemas['TagsListResponse']>;
+        /** Iterate every tag across all pages. */
+        listAll(params?: TagsListParams): AsyncIterableIterator<Schemas['RawSlugEntry']>;
     };
     subcategories: {
-        list(params?: paths['/api/v1/subcategories']['get']['parameters']['query']): Promise<Schemas['SubcategoriesListResponse']>;
+        list(params?: SubcategoriesListParams): Promise<Schemas['SubcategoriesListResponse']>;
+        /** Iterate every page of `/subcategories`, auto-following `_links.next`. */
+        pages(params?: SubcategoriesListParams): AsyncIterableIterator<Schemas['SubcategoriesListResponse']>;
+        /** Iterate every subcategory across all pages. */
+        listAll(params?: SubcategoriesListParams): AsyncIterableIterator<Schemas['RawSlugEntry']>;
     };
     stats: {
         get(): Promise<Schemas['StatsResponse']>;