@pokewallet/sdk 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -120,8 +120,8 @@ interface Card {
     variants: string[];
     /**
      * Set identifiers. `setId` is the numeric id (possibly negative); `setCode` the short code.
-     * Source: `card_info.set_id` / `card_info.set_code`, except for cards listed by a set, where both come
-     * from the response's `set` object (the Pokémon listing puts the numeric id in `card_info.set_code`).
+     * Source: `card_info.set_id` / `card_info.set_code`; for cards listed by a set, both come from the
+     * response's `set` object.
      * One Piece search and detail answers carry neither, so both are null there.
      */
     setId: string | null;
@@ -161,7 +161,7 @@ interface Page<T> {
     totalPages: number;
 }
 interface SearchPage extends Page<Card> {
-    /** Games only: the search stopped at its cap, refine the query instead of paging. */
+    /** Pokémon and games: the candidate list was cut at its cap, refine the query instead of paging. Always false for One Piece. */
     truncated: boolean;
 }
 interface SetPage extends Page<Card> {
@@ -255,7 +255,6 @@ interface TopCard {
     setId: string | null;
     setCode: string | null;
     price: number | null;
-    previousPrice7d: number | null;
     change7d: string | null;
     raw: unknown;
 }
@@ -286,10 +285,10 @@ type PricesOptions = {
     source?: 'tcg' | 'cm';
 };
 type StatisticsOptions = {
-    variant?: string;
+    variant?: 'normal' | 'foil';
 };
 type TrendingOptions = {
-    period?: '7d' | '30d';
+    period?: '7d';
     limit?: number;
 };
 type TopCardsOptions = {
@@ -368,8 +367,6 @@ interface World {
 interface CardWorldConfig {
     /** Route prefix: `''` for Pokémon, `/mtg` for a game. */
     prefix: string;
-    /** Pokémon accepts `period=30d` on trending; the other worlds only `7d`. */
-    periods: readonly ('7d' | '30d')[];
     /** Minimum search length: the games reject queries shorter than 2 characters. */
     minQuery: number;
 }
@@ -567,7 +564,7 @@ declare class UnavailableError extends PokeWalletError {
 declare class ServerError extends PokeWalletError {
 }
 
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.1.3";
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -623,9 +620,10 @@ interface paths {
         };
         /**
          * Search Pokémon cards by name, number, set or rarity
-         * @description Note: server-side range checks on `limit` and `page` differ from One Piece and the ten games.
-         *     Send `limit` between 1 and 100 and `page` of at least 1 (the SDKs enforce this before
-         *     sending); `total_pages` can be `null` for out-of-range input.
+         * @description `metadata.truncated` is true when the candidates were cut at 500: a more specific query is needed.
+         *     `page` and `limit`: a missing, non-numeric or lower-than-1 value falls back to the default, and a
+         *     value above the cap (100 for `limit`) is clamped. The SDKs still check both before sending.
+         *     A name may contain parentheses, e.g. `Pikachu (Cosmos Holo)`.
          */
         get: operations["pokemonSearch"];
         put?: never;
@@ -660,7 +658,10 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Sets with the strongest CardMarket price change (Pro or trial) */
+        /**
+         * Sets with the strongest CardMarket price change (Pro or trial)
+         * @description Same format in every world. Only `period=7d` exists; `30d` answers 400 `Invalid parameter`.
+         */
         get: operations["pokemonTrendingSets"];
         put?: never;
         post?: never;
@@ -685,8 +686,9 @@ interface paths {
          *     **200** with `disambiguation: true` and `matches`; on `/prices/{setCode}` it is **300**, on
          *     statistics and completion-value it is **409**. Disambiguate with `?language=` or the numeric `set_id`.
          *
-         *     Note: in this listing `card_info.set_code` holds the `set_id` ("1382"), while
-         *     `/cards/{id}` and `/search` hold the real code ("PLF"). `prices` is always `[]` here.
+         *     In this listing `card_info.set_code` and `card_info.set_id` hold the set's real code ("PLF") and
+         *     numeric id ("1382"), the same as in `/cards/{id}` and `/search`; the `set` object carries `set_id` too.
+         *     `prices` is always `[]` here.
          *
          *     Note: send `limit` and `page` within range (see `/search`).
          */
@@ -708,8 +710,9 @@ interface paths {
         };
         /**
          * Price and rarity statistics of a set (Pro or trial)
-         * @description Note: `set_info.set_code` is the numeric `set_id` ("1382"); in `completion-value` it is the code ("PLF").
-         *     Ambiguous set: **409**.
+         * @description Same format in every world: `set_info` is `{name, set_code, set_id, total_cards}` with the real set code;
+         *     `total_cards` counts cards (sealed products excluded), not finishes. `trend_direction` compares the
+         *     7-day with the 30-day average. Ambiguous set: **409**.
          */
         get: operations["pokemonSetStatistics"];
         put?: never;
@@ -727,7 +730,10 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Cost to complete a set (Pro or trial) */
+        /**
+         * Cost to complete a set (Pro or trial)
+         * @description One copy of each card, in its base finish. `set_info` has the same shape as in statistics.
+         */
         get: operations["pokemonSetCompletionValue"];
         put?: never;
         post?: never;
@@ -746,7 +752,8 @@ interface paths {
         };
         /**
          * Prices of every card in a set (Pro or trial; hundreds of rows)
-         * @description Ambiguous set: **300** with the `Disambiguation` body (no `error` field).
+         * @description The response carries both `set_id` and `group_id` (the same value).
+         *     Ambiguous set: **300** with the `Disambiguation` body (no `error` field).
          */
         get: operations["pokemonSetPrices"];
         put?: never;
@@ -767,7 +774,7 @@ interface paths {
         /**
          * Pokémon card detail
          * @description `id` is `pk_<hex>`, a 64-character hex CardMarket `encrypted_id`, or a plain card number
-         *     (`086`, `086/078`) to be combined with `set_code`. An id from another game (`op_`, `mtg_`...)
+         *     (`086`, `086/078`, `010a/073`) to be combined with `set_code`. An id from another game (`op_`, `mtg_`...)
          *     gives 400 with a hint to the right route.
          */
         get: operations["pokemonGetCard"];
@@ -803,7 +810,14 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Ranking by price or growth (Pro or trial) */
+        /**
+         * Ranking by price or growth (Pro or trial)
+         * @description Same item format in every world: `{id, card_info, current_price, change_7d?}` (`change_7d` only for growth).
+         *     `card_info` is the full common card info. Price ranking uses the TCGPlayer market price (`tcg`) or the
+         *     CardMarket trend price (`cm`). A CardMarket row linked to a TCGPlayer card carries that card's `pk_` id,
+         *     the others the CardMarket encrypted id; both open with `/cards/{id}`. Growth with `source=tcg` exists
+         *     for Pokémon only.
+         */
         get: operations["pokemonTopCards"];
         put?: never;
         post?: never;
@@ -823,7 +837,8 @@ interface paths {
         /**
          * Search One Piece cards
          * @description Flat pagination `{data,total,page,limit}` (differs from Pokémon, which nests it in `pagination`).
-         *     `page`/`limit` are validated with `Math.max(1, …)`.
+         *     `page` and `limit`: a missing, non-numeric or lower-than-1 value falls back to the default, and a
+         *     value above the cap is clamped. A name may contain parentheses, e.g. `Buggy (Reprint)`.
          */
         get: operations["opSearch"];
         put?: never;
@@ -957,6 +972,7 @@ interface paths {
          * Prices of every card in a set (Pro or trial)
          * @description The set goes in the query (`set_code` or `group_id`), not in the path as on other routes.
          *     At least one of the two is required, otherwise 400.
+         *     Like the other worlds, the response has `source`, `set_code`, `set_id` and a `product_type` on every row.
          */
         get: operations["opSetPrices"];
         put?: never;
@@ -1261,8 +1277,8 @@ interface components {
         };
         /**
          * @description Common fields. The ten games add their own fields in snake_case (`mtg`: `p`,`t`,`sub_type`;
-         *     `ygo`: `attack`,`defense`...). Note: `set_id` is missing in a Pokémon set listing, where
-         *     `set_code` holds the numeric id; `card_text` and `card_type` are often `null`.
+         *     `ygo`: `attack`,`defense`...). `set_code` is the set's real code and `set_id` its numeric id,
+         *     also in Pokémon set listings; `card_text` and `card_type` are often `null`.
          */
         CardInfo: {
             name: string;
@@ -1275,6 +1291,7 @@ interface components {
             card_type?: string | null;
             /** @description `card` or sealed product. */
             product_type?: string | null;
+            /** @description Finishes, `Normal` first, then alphabetical. Present in Pokémon search and detail too. */
             variants?: string[];
             card_text?: string | null;
             hp?: string | null;
@@ -1321,7 +1338,7 @@ interface components {
                 tcg_only?: number;
                 cardmarket_only?: number;
                 both_sources?: number;
-                /** @description Games only. */
+                /** @description True when the candidate list was cut at its cap (500 for Pokémon): use a more specific query. */
                 truncated?: boolean;
             };
         };
@@ -1382,12 +1399,13 @@ interface components {
             tcgplayer?: components["schemas"]["TcgplayerPrice"] | null;
             cardmarket?: components["schemas"]["CardmarketPrice"] | null;
         };
-        /** @description The set id is called `group_id` here (`set_id` in the games). */
+        /** @description Carries both `set_id` and `group_id` (the same value). */
         PokemonPricesResponse: {
             success?: boolean;
             /** @enum {string} */
             source?: "both" | "tcg" | "cm";
             set_code?: string | null;
+            set_id?: string;
             group_id?: string;
             data?: components["schemas"]["PriceRow"][];
             total?: number;
@@ -1402,11 +1420,13 @@ interface components {
             total?: number;
         };
         StatisticsResponse: {
-            /** @description Pokémon: `set_code` is the numeric `set_id`; `set_id` is missing. */
+            /** @description Same in every world. */
             set_info: {
                 name?: string;
+                /** @description The real set code. */
                 set_code?: string | null;
                 set_id?: string;
+                /** @description Cards, not finishes; sealed products excluded. */
                 total_cards?: number;
             };
             price_statistics: {
@@ -1424,7 +1444,6 @@ interface components {
             min_price?: number;
             max_price?: number;
             most_expensive?: {
-                /** @description Missing in Pokémon. */
                 id?: string;
                 name?: string;
                 price?: number;
@@ -1436,7 +1455,10 @@ interface components {
         }) | null;
         CompletionValueResponse: {
             set_info: {
-                [key: string]: unknown;
+                name?: string;
+                set_code?: string | null;
+                set_id?: string;
+                total_cards?: number;
             };
             completion_cost: {
                 tcgplayer?: {
@@ -1465,7 +1487,6 @@ interface components {
             trending_sets: {
                 set_name?: string | null;
                 set_code?: string | null;
-                /** @description Missing in Pokémon. */
                 set_id?: string;
                 card_count?: number;
                 cardmarket?: {
@@ -1478,7 +1499,7 @@ interface components {
                         change?: string;
                     }[];
                 };
-                /** @description `{status:'work_in_progress'}` or `null` (CardMarket-only sets). */
+                /** @description `{status, message}` (TCGPlayer history is not available yet) or `null`. */
                 tcgplayer?: {
                     [key: string]: unknown;
                 } | null;
@@ -1493,7 +1514,6 @@ interface components {
                 id: string;
                 card_info: components["schemas"]["CardInfo"];
                 current_price: number;
-                previous_price_7d?: number;
                 change_7d?: string;
             }[];
         };
@@ -1526,7 +1546,7 @@ interface components {
                 };
             };
         } | null;
-        /** @description Flat card: no `card_info`, `ext_*` fields; `prices` is a single object (Pokémon: an array per finish). */
+        /** @description Flat card: no `card_info`, `ext_*` fields; `prices` is a single object (Pokémon: an array per finish). CardMarket prices are attached to the cards of the English sets too (OP15, OP14, PRB-02, EB04), so more search and detail answers carry a `cardmarket` block. */
         OpCard: {
             /** @description `op_<hex>` */
             id: string;
@@ -1584,6 +1604,10 @@ interface components {
         };
         OpPricesResponse: {
             success?: boolean;
+            /** @enum {string} */
+            source?: "both" | "tcg" | "cm";
+            set_code?: string | null;
+            set_id?: string;
             group_id?: string | number;
             data?: components["schemas"]["PriceRow"][];
             total?: number;
@@ -1591,8 +1615,8 @@ interface components {
     };
     responses: {
         /**
-         * @description Missing or invalid parameter. The body shape differs by family: Pokémon and One Piece send `{error}`,
-         *     the games send `{error,message,docs}`.
+         * @description Missing or invalid parameter. A bad parameter value answers `{error: 'Invalid parameter', message, docs}`
+         *     in every world. Other 400 bodies may carry only `{error}`.
          */
         BadRequest: {
             headers: {
@@ -1685,7 +1709,10 @@ interface components {
         Game: components["schemas"]["GameCode"];
         /** @description `set_code` (`PLF`) or numeric `set_id`, possibly negative. */
         SetCode: string;
+        /** @description Missing, non-numeric or lower than 1 falls back to 1. */
         Page: number;
+        /** @description `normal` or `foil`; anything else gives 400 `Invalid parameter`. On Pokémon `holo` is still accepted as a legacy alias of `foil`. */
+        Variant: "normal" | "foil";
         /** @description Set language (`eng`, `jap`, `chn`, `en`, `jp`...): the vocabulary is not uniform between Pokémon and One Piece. */
         Language: string;
         Metric: "price" | "growth";
@@ -1760,6 +1787,7 @@ interface operations {
         parameters: {
             query: {
                 q: string;
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
             };
@@ -1831,7 +1859,8 @@ interface operations {
     pokemonTrendingSets: {
         parameters: {
             query?: {
-                period?: "7d" | "30d";
+                /** @description Only 7d (30d gives 400). */
+                period?: "7d";
                 limit?: number;
             };
             header?: never;
@@ -1867,6 +1896,7 @@ interface operations {
     pokemonGetSet: {
         parameters: {
             query?: {
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
                 /** @description Set language (`eng`, `jap`, `chn`, `en`, `jp`...): the vocabulary is not uniform between Pokémon and One Piece. */
@@ -1908,7 +1938,8 @@ interface operations {
     pokemonSetStatistics: {
         parameters: {
             query?: {
-                variant?: "normal" | "holo";
+                /** @description `normal` or `foil`; anything else gives 400 `Invalid parameter`. On Pokémon `holo` is still accepted as a legacy alias of `foil`. */
+                variant?: components["parameters"]["Variant"];
             };
             header?: never;
             path: {
@@ -2144,6 +2175,7 @@ interface operations {
         parameters: {
             query: {
                 q: string;
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
             };
@@ -2252,6 +2284,7 @@ interface operations {
     opGetSet: {
         parameters: {
             query?: {
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
             };
@@ -2290,7 +2323,8 @@ interface operations {
     opSetStatistics: {
         parameters: {
             query?: {
-                variant?: "normal" | "foil";
+                /** @description `normal` or `foil`; anything else gives 400 `Invalid parameter`. On Pokémon `holo` is still accepted as a legacy alias of `foil`. */
+                variant?: components["parameters"]["Variant"];
             };
             header?: never;
             path: {
@@ -2474,6 +2508,7 @@ interface operations {
         parameters: {
             query: {
                 q: string;
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
             };
@@ -2587,6 +2622,7 @@ interface operations {
     gameGetSet: {
         parameters: {
             query?: {
+                /** @description Missing, non-numeric or lower than 1 falls back to 1. */
                 page?: components["parameters"]["Page"];
                 limit?: number;
             };
@@ -2626,7 +2662,8 @@ interface operations {
     gameSetStatistics: {
         parameters: {
             query?: {
-                variant?: "normal" | "foil";
+                /** @description `normal` or `foil`; anything else gives 400 `Invalid parameter`. On Pokémon `holo` is still accepted as a legacy alias of `foil`. */
+                variant?: components["parameters"]["Variant"];
             };
             header?: never;
             path: {