@pokewallet/sdk 0.1.1 → 0.1.5

package/dist/index.d.ts

@@ -9,6 +9,12 @@ interface ClientOptions {
     baseUrl?: string;
     /** Sent on every request. Some network layers reject the default user agents of HTTP libraries. */
     userAgent?: string;
+    /**
+     * Sent as `X-PokeWallet-Client`, so the API can tell which integration made a call. Browsers
+     * cannot set `User-Agent`, so this is the only identification they can send. Default
+     * `pokewallet-sdk-ts/<version>`.
+     */
+    client?: string;
     /** Custom `fetch`, mainly for tests. Defaults to the global one. */
     fetch?: FetchLike;
     /** Retries after a 429 (with `Retry-After`) or a 503. Default 2. */
@@ -34,6 +40,7 @@ declare class HttpClient {
     lastRateLimit: RateLimitInfo | null;
     private readonly baseUrl;
     private readonly userAgent;
+    private readonly client;
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly capSeconds;
@@ -120,8 +127,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 +168,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 +262,6 @@ interface TopCard {
     setId: string | null;
     setCode: string | null;
     price: number | null;
-    previousPrice7d: number | null;
     change7d: string | null;
     raw: unknown;
 }
@@ -286,10 +292,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 +374,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 +571,7 @@ declare class UnavailableError extends PokeWalletError {
 declare class ServerError extends PokeWalletError {
 }
 
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.1.5";
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -623,9 +627,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 +665,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 +693,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 +717,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 +737,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 +759,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 +781,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 +817,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 +844,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 +979,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 +1284,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 +1298,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 +1345,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 +1406,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 +1427,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 +1451,6 @@ interface components {
             min_price?: number;
             max_price?: number;
             most_expensive?: {
-                /** @description Missing in Pokémon. */
                 id?: string;
                 name?: string;
                 price?: number;
@@ -1436,7 +1462,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 +1494,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 +1506,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 +1521,6 @@ interface components {
                 id: string;
                 card_info: components["schemas"]["CardInfo"];
                 current_price: number;
-                previous_price_7d?: number;
                 change_7d?: string;
             }[];
         };
@@ -1526,7 +1553,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 +1611,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 +1622,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 +1716,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 +1794,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 +1866,8 @@ interface operations {
     pokemonTrendingSets: {
         parameters: {
             query?: {
-                period?: "7d" | "30d";
+                /** @description Only 7d (30d gives 400). */
+                period?: "7d";
                 limit?: number;
             };
             header?: never;
@@ -1867,6 +1903,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 +1945,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 +2182,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 +2291,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 +2330,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 +2515,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 +2629,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 +2669,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: {

package/dist/index.js

@@ -141,7 +141,7 @@ function errorFromResponse(ctx) {
 }
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.5";
 var DEFAULT_BASE_URL = "https://api.pokewallet.io";
 var DEFAULT_USER_AGENT = `pokewallet-sdk-ts/${VERSION}`;
 
@@ -177,6 +177,7 @@ var HttpClient = class {
   #key;
   baseUrl;
   userAgent;
+  client;
   fetchImpl;
   maxRetries;
   capSeconds;
@@ -186,6 +187,7 @@ var HttpClient = class {
     this.#key = readKey(options);
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    this.client = options.client ?? DEFAULT_USER_AGENT;
     const g = globalThis;
     const f = options.fetch ?? (g.fetch ? g.fetch.bind(globalThis) : void 0);
     if (!f) throw new ValidationError("No fetch available: pass options.fetch (Node 18+ has one built in)");
@@ -238,6 +240,7 @@ var HttpClient = class {
         headers: {
           ...this.#key === void 0 ? {} : { "X-API-Key": this.#key },
           "User-Agent": this.userAgent,
+          "X-PokeWallet-Client": this.client,
           Accept: "application/json"
         },
         signal: AbortSignal.timeout(this.timeoutMs)
@@ -566,7 +569,6 @@ function normalizeTopCards(raw) {
       setId: pair.id,
       setCode: pair.code,
       price: num2(c.current_price),
-      previousPrice7d: num2(c.previous_price_7d),
       change7d: str2(c.change_7d),
       raw: item
     };
@@ -643,6 +645,15 @@ function checkLimit(limit, max) {
   }
   return limit;
 }
+function checkPeriod(period) {
+  if (period !== void 0 && period !== "7d") throw new ValidationError(`period ${period} is not available (only 7d)`);
+  return "7d";
+}
+function checkVariant(variant) {
+  if (variant === void 0) return void 0;
+  if (variant !== "normal" && variant !== "foil") throw new ValidationError(`variant must be normal or foil (got ${variant})`);
+  return variant;
+}
 function checkText(name, value, min = 1) {
   if (typeof value !== "string" || value.trim().length < min) {
     throw new ValidationError(`${name} must be at least ${min} character${min === 1 ? "" : "s"} long`);
@@ -715,14 +726,13 @@ var CardWorld = class {
     return normalizeSetPrices(await this.http.get(this.path(`/prices/${seg(code)}`), { source: options.source }));
   }
   async statistics(code, options = {}) {
-    return normalizeStatistics(await this.http.get(this.path(`/sets/${seg(code)}/statistics`), { variant: options.variant }));
+    return normalizeStatistics(await this.http.get(this.path(`/sets/${seg(code)}/statistics`), { variant: checkVariant(options.variant) }));
   }
   async completionValue(code) {
     return normalizeCompletionValue(await this.http.get(this.path(`/sets/${seg(code)}/completion-value`)));
   }
   async trending(options = {}) {
-    const period = options.period ?? "7d";
-    if (!this.config.periods.includes(period)) throw new ValidationError(`period ${period} is not available here (use ${this.config.periods.join(" or ")})`);
+    const period = checkPeriod(options.period);
     return normalizeTrending(await this.http.get(this.path("/sets/trending"), { period, limit: checkLimit(options.limit, LIMITS.trending) }));
   }
   async topCards(options = {}) {
@@ -790,14 +800,14 @@ var OnePieceWorld = class {
     return normalizeSetPrices(await this.http.get("/op/prices", query));
   }
   async statistics(code, options = {}) {
-    return normalizeStatistics(await this.http.get(`/op/sets/${seg(code)}/statistics`, { variant: options.variant }));
+    return normalizeStatistics(await this.http.get(`/op/sets/${seg(code)}/statistics`, { variant: checkVariant(options.variant) }));
   }
   async completionValue(code) {
     return normalizeCompletionValue(await this.http.get(`/op/sets/${seg(code)}/completion-value`));
   }
   async trending(options = {}) {
-    if (options.period === "30d") throw new ValidationError("period 30d is not available for One Piece");
-    return normalizeTrending(await this.http.get("/op/sets/trending", { period: "7d", limit: checkLimit(options.limit, LIMITS.trending) }));
+    const period = checkPeriod(options.period);
+    return normalizeTrending(await this.http.get("/op/sets/trending", { period, limit: checkLimit(options.limit, LIMITS.trending) }));
   }
   async topCards(options = {}) {
     return normalizeTopCards(
@@ -813,7 +823,7 @@ var OnePieceWorld = class {
 // src/worlds/pokemon-world.ts
 var PokemonWorld = class extends CardWorld {
   constructor(http) {
-    super(http, { prefix: "", periods: ["7d", "30d"], minQuery: 1 });
+    super(http, { prefix: "", minQuery: 1 });
   }
   /**
    * Card by id, or by plain card number together with `setCode` (`card('086/078', { setCode: 'SV8a' })`).
@@ -844,7 +854,7 @@ var PokeWallet = class {
     this.onepiece = new OnePieceWorld(this.#http);
     const games = {};
     for (const code of GAME_CODES) {
-      games[code] = new CardWorld(this.#http, { prefix: `/${code}`, periods: ["7d"], minQuery: 2 });
+      games[code] = new CardWorld(this.#http, { prefix: `/${code}`, minQuery: 2 });
     }
     this.games = games;
   }