@pfdev/api-types 3.0.18 → 3.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pfdev/api-types",
-  "version": "3.0.18",
+  "version": "3.0.20",
   "description": "TypeScript types for PF API V3",
   "main": "index.ts",
   "types": "index.ts",

package/v3.ts

@@ -10,6 +10,8 @@ import { Static, Type } from '@sinclair/typebox';
 export const PriceStatsSchema = Type.Object(
   {
     current_price: Type.Optional(Type.Number({ description: 'Current price' })),
+    price_date: Type.Optional(Type.String({ description: 'Date (YYYY-MM-DD) this price was last updated' })),
+    change_1d_value: Type.Optional(Type.Number({ description: '1-day price change in dollars' })),
     change_1d: Type.Optional(Type.Number({ description: '1-day price change as a percentage' })),
     change_7d: Type.Optional(Type.Number({ description: '7-day price change as a percentage' })),
     change_1m: Type.Optional(Type.Number({ description: '30-day price change as a percentage' })),
@@ -20,14 +22,68 @@ export const PriceStatsSchema = Type.Object(
   { title: 'PriceStats' }
 );
 
+const GradedPricesSchema = Type.Record(Type.String(), PriceStatsSchema, {
+  description: 'Graded prices and period changes keyed by grade (e.g. "PSA 10")'
+});
+
+export const CardVariantSchema = Type.Object(
+  {
+    id: Type.Integer({ description: 'Variant id (pfdata_variant_definitions.id). Matches variant_id on inventory and list rows.' }),
+    display_name: Type.String({ description: 'Label to show users' }),
+    short_name: Type.Union([Type.String(), Type.Null()], { description: 'Short label for tight spaces (e.g. RH)' }),
+    color: Type.Union([Type.String(), Type.Null()], { description: 'Hex color (#RRGGBB)' }),
+    sort_order: Type.Integer({ description: 'Variants are returned sorted by this, ascending' }),
+    hidden: Type.Boolean({ description: 'Not meant to be shown or picked (e.g. Unknown)' }),
+    prices: Type.Optional(Type.Union([PriceStatsSchema, Type.Null()], {
+      description: 'Prices and period changes. Only present with include=variant_prices; null when the variant has no price.'
+    })),
+    graded: Type.Optional(Type.Union([GradedPricesSchema, Type.Null()], {
+      description: 'Graded prices keyed by grade. Only present with include=graded_variants_prices; null when the variant has no graded prices.'
+    }))
+  },
+  { title: 'CardVariant' }
+);
+
+const CardVariantsSchema = Type.Array(CardVariantSchema, {
+  description: 'The card\'s variants (from the pricing map), sorted by sort_order. Hidden variants are included with hidden: true.'
+});
+
 const CardImagesSchema = Type.Object(
   {
     small: Type.String({ format: 'uri', description: 'Small card image URL' }),
-    large: Type.String({ format: 'uri', description: 'Large card image URL' })
+    large: Type.String({ format: 'uri', description: 'Large card image URL' }),
+    small_webp: Type.Optional(Type.String({ format: 'uri', description: 'Small card image as WebP. Not every card has one.' })),
+    large_webp: Type.Optional(Type.String({ format: 'uri', description: 'Large card image as WebP. Not every card has one.' }))
   },
   { title: 'CardImages' }
 );
 
+// Fields on every card used for filtering and for web URLs
+const CardFilterFields = {
+  supertype: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Supertype (Pokémon, Trainer, Energy)' })),
+  subtypes: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Null()], { description: 'Card subtypes' })),
+  types: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Null()], { description: 'Card types' })),
+  nationalPokedexNumbers: Type.Optional(Type.Union([Type.Array(Type.Number()), Type.Null()], { description: 'National Pokédex numbers' })),
+  regulationMark: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Regulation mark' })),
+  set_release_date: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Release date of the set' })),
+  series: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Series the set belongs to' })),
+  slug: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'URL slug for the card' })),
+  set_slug: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'URL slug for the set' }))
+};
+
+const PriceVariantIdSchema = Type.Optional(Type.Union([Type.Integer(), Type.Null()], {
+  description: 'Id of the variant that price, change_1d and change_1d_value come from (the lowest-priced variant that isn\'t hidden)'
+}));
+
+const PriceDateSchema = Type.Optional(Type.Union([Type.String(), Type.Null()], {
+  description: 'Date (YYYY-MM-DD) the price was last updated, for the variant in price_variant_id'
+}));
+
+const CardIncludeSchema = Type.Optional(Type.String({
+  pattern: '^(variant_prices|graded_variants_prices)(,(variant_prices|graded_variants_prices))*$',
+  description: 'Comma-separated extras to include on each card: variant_prices (prices on each variant), graded_variants_prices (graded prices on each variant, keyed by grade)'
+}));
+
 export const CardSchema = Type.Object(
   {
     cardid: Type.String({ description: 'Unique card identifier' }),
@@ -38,15 +94,13 @@ export const CardSchema = Type.Object(
     images: CardImagesSchema,
     setid: Type.String({ description: 'Set this card belongs to' }),
     setname: Type.String({ description: 'Name of the set' }),
+    ...CardFilterFields,
     price: Type.Optional(Type.Number({ description: 'Price of the lowest-priced variant' })),
     change_1d: Type.Optional(Type.Number({ description: '1-day price change as a percentage' })),
     change_1d_value: Type.Optional(Type.Number({ description: '1-day price change in dollars' })),
-    variants: Type.Optional(Type.Array(Type.String(), { description: 'Available variants for this card' })),
-    variant_prices: Type.Optional(
-      Type.Record(Type.String(), PriceStatsSchema, {
-        description: 'Prices and period changes keyed by variant name. Only present when requested via include=variant_prices. Variants without price data map to an empty object.'
-      })
-    )
+    price_variant_id: PriceVariantIdSchema,
+    price_date: PriceDateSchema,
+    variants: CardVariantsSchema
   },
   {
     title: 'Card',
@@ -88,7 +142,7 @@ export const CardListQuerySchema = Type.Object(
     setid: Type.Optional(Type.String({ description: 'Filter by set ID' })),
     search: Type.Optional(Type.String({ minLength: 1, description: 'Search by card name and/or number. Tokens with digits match card number; other tokens match card name.' })),
     sort: Type.Optional(CardListSortSchema),
-    include: Type.Optional(Type.Literal('variant_prices', { description: 'Include per-variant prices and period changes on each card' })),
+    include: CardIncludeSchema,
     limit: Type.Optional(Type.Number({ minimum: 1, maximum: 250, default: 50, description: 'Max results to return' })),
     offset: Type.Optional(Type.Number({ minimum: 0, default: 0, description: 'Pagination offset' }))
   },
@@ -102,7 +156,7 @@ export const CardBatchQuerySchema = Type.Object({
     minLength: 1,
     description: 'Comma-separated list of card IDs (e.g. "xy1-2,base1-4"). Duplicates are deduped. Max 200 IDs per request.'
   }),
-  include: Type.Optional(Type.Literal('variant_prices', { description: 'Include per-variant prices and period changes on each card' }))
+  include: CardIncludeSchema
 });
 
 export type CardBatchQuery = Static<typeof CardBatchQuerySchema>;
@@ -135,20 +189,19 @@ export const CardDetailSchema = Type.Object(
     nationalPokedexNumbers: Type.Optional(Type.Array(Type.Number(), { description: 'National Pokédex numbers' })),
     legalities: Type.Optional(Type.Any({ description: 'Format legalities' })),
     regulationMark: Type.Optional(Type.String({ description: 'Regulation mark' })),
+    set_release_date: CardFilterFields.set_release_date,
+    series: CardFilterFields.series,
+    slug: CardFilterFields.slug,
+    set_slug: CardFilterFields.set_slug,
+    price_variant_id: PriceVariantIdSchema,
+    price_date: PriceDateSchema,
     price: Type.Optional(Type.Number({ description: 'Price of the lowest-priced variant' })),
     change_1d: Type.Optional(Type.Number({ description: '1-day price change as a percentage' })),
     change_1d_value: Type.Optional(Type.Number({ description: '1-day price change in dollars' })),
-    variants: Type.Optional(Type.Array(Type.String(), { description: 'Available variants for this card' })),
-    variant_prices: Type.Optional(
-      Type.Record(Type.String(), PriceStatsSchema, { description: 'Prices and period changes keyed by variant name' })
-    ),
-    graded_variants_prices: Type.Optional(
-      Type.Record(
-        Type.String(),
-        Type.Record(Type.String(), PriceStatsSchema),
-        { description: 'Graded prices and period changes keyed by variant then grade' }
-      )
-    )
+    variants: {
+      ...CardVariantsSchema,
+      description: 'The card\'s variants (from the pricing map), sorted by sort_order, each with prices and graded. Hidden variants are included with hidden: true.'
+    }
   },
   {
     title: 'CardDetail',
@@ -268,14 +321,14 @@ export const DexCardSchema = Type.Intersect(
   [
     CardSchema,
     Type.Object({
-      variant_prices: Type.Record(Type.String(), PriceStatsSchema, {
-        description: 'Per-variant prices and period changes keyed by variant name'
+      variants: Type.Array(CardVariantSchema, {
+        description: 'The card\'s variants, sorted by sort_order, each with prices'
       })
     })
   ],
   {
     title: 'DexCard',
-    description: 'A card in a Pokémon dex view, with full per-variant price breakdown'
+    description: 'A card in a Pokémon dex view, with prices on each variant'
   }
 );
 export type DexCard = Static<typeof DexCardSchema>;
@@ -516,6 +569,17 @@ export const ListTypeSchema = Type.Union(
 
 export type ListType = Static<typeof ListTypeSchema>;
 
+export const ListCoverCardSchema = Type.Object(
+  {
+    cardid: Type.String(),
+    variant_id: Type.Union([Type.Integer(), Type.Null()], { description: 'Variant id (pfdata_variant_definitions.id); matches variants[].id on cards. Null when the variant has no definition.' }),
+    image: Type.Union([Type.String(), Type.Null()], { description: 'Small card image URL' })
+  },
+  { title: 'ListCoverCard' }
+);
+
+export type ListCoverCard = Static<typeof ListCoverCardSchema>;
+
 export const ListSchema = Type.Object(
   {
     uuid: Type.String({ format: 'uuid' }),
@@ -530,7 +594,11 @@ export const ListSchema = Type.Object(
     }),
     card_count: Type.Integer({ description: 'Total entries, including duplicates' }),
     unique_count: Type.Integer({ description: 'Distinct cardids' }),
-    total_value: Type.Number({ description: 'Sum of current USD prices of every entry' })
+    total_value: Type.Number({ description: 'Sum of current USD prices of every entry' }),
+    cover: Type.Array(ListCoverCardSchema, {
+      maxItems: 3,
+      description: 'Up to 3 cards for the list tile: the most recently added entries, or the first slots for binders. Empty when the list has no cards.'
+    })
   },
   { title: 'List' }
 );
@@ -632,7 +700,7 @@ export const DexCollectionItemSchema = Type.Object(
   {
     id: Type.Integer({ description: 'Pokémon id (matches /dex/ response.id)' }),
     collected: Type.Integer({ description: 'Distinct cardids the user owns for this Pokémon' }),
-    master_collected: Type.Integer({ description: 'Distinct (cardid, variant) pairs the user owns for this Pokémon' })
+    master_collected: Type.Integer({ description: 'Distinct (cardid, variant_id) pairs the user owns for this Pokémon' })
   },
   { title: 'DexCollectionItem' }
 );
@@ -645,7 +713,7 @@ export const InventorySummaryItemSchema = Type.Object(
   {
     uuid: Type.String({ description: 'Unique ID of this inventory row' }),
     cardid: Type.String({ description: 'Card ID this inventory row belongs to' }),
-    variant: Type.String({ description: 'Card variant (e.g. Normal, Holofoil, Reverse Holofoil)' }),
+    variant_id: Type.Union([Type.Integer(), Type.Null()], { description: 'Variant id (pfdata_variant_definitions.id); matches variants[].id on cards. Null when the variant has no definition.' }),
     status: Type.Union([Type.Number(), Type.Null()], {
       description: 'Numeric status code. <100 = active, >=100 = sold/past. Null when no details row exists yet.'
     }),
@@ -669,7 +737,7 @@ export type InventorySummaryResponse = Static<typeof InventorySummaryResponseSch
 export const InventoryAddRequestSchema = Type.Object(
   {
     cardid: Type.String({ minLength: 1, description: 'Card ID to add to inventory' }),
-    variant: Type.String({ minLength: 1, description: 'Card variant (e.g. Normal, Holofoil, Reverse Holofoil)' })
+    variant_id: Type.Integer({ minimum: 1, description: 'Variant id (variants[].id on the card). Must be one of the card\'s variants and not hidden.' })
   },
   { title: 'InventoryAddRequest' }
 );
@@ -703,7 +771,7 @@ export const InventoryItemDetailSchema = Type.Object(
   {
     uuid: Type.String({ format: 'uuid' }),
     cardid: Type.String(),
-    variant: Type.String(),
+    variant_id: Type.Union([Type.Integer(), Type.Null()], { description: 'Variant id (pfdata_variant_definitions.id); matches variants[].id on cards. Null when the variant has no definition.' }),
     status: Type.Union([Type.Number(), Type.Null()]),
     grade: Type.Union([Type.String(), Type.Null()]),
     acquired: Type.Union([Type.String(), Type.Null()]),
@@ -784,20 +852,6 @@ export type InventoryPatchRequest = Static<typeof InventoryPatchRequestSchema>;
 // ============= VISION =============
 
 
-const VariantPriceSchema = Type.Object(
-  {
-    variant: Type.String(),
-    current_price: Type.Optional(Type.Number()),
-    change_1d: Type.Optional(Type.Number()),
-    change_7d: Type.Optional(Type.Number()),
-    change_1m: Type.Optional(Type.Number()),
-    change_3m: Type.Optional(Type.Number()),
-    change_6m: Type.Optional(Type.Number()),
-    change_1y: Type.Optional(Type.Number())
-  },
-  { title: 'VisionVariantPrice' }
-);
-
 const DetectedCardSchema = Type.Object(
   {
     name: Type.String({ description: 'Card name from image recognition' }),
@@ -812,11 +866,9 @@ const DetectedCardSchema = Type.Object(
 
 const MatchedCardSchema = Type.Intersect(
   [
-    // Vision returns variant_prices as an array, not CardSchema's map
-    Type.Omit(CardSchema, ['variant_prices']),
+    CardSchema,
     Type.Object({
-      score: Type.Number({ description: 'Fuzzy match score — higher is a better match' }),
-      variant_prices: Type.Array(VariantPriceSchema, { description: 'Per-variant prices with extended period changes' })
+      score: Type.Number({ description: 'Fuzzy match score — higher is a better match' })
     })
   ],
   { title: 'MatchedCard' }