@pfdev/api-types 3.0.19 → 3.0.21

package/package.json

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

package/v3.ts

@@ -22,20 +22,42 @@ 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' }
 );
 
-const GradedVariantPricesSchema = Type.Record(
-  Type.String(),
-  Type.Record(Type.String(), PriceStatsSchema),
-  { description: 'Graded prices and period changes keyed by variant then grade' }
-);
-
 // 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)' })),
@@ -49,17 +71,17 @@ const CardFilterFields = {
   set_slug: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'URL slug for the set' }))
 };
 
-const PriceVariantSchema = Type.Optional(Type.Union([Type.String(), Type.Null()], {
-  description: 'Variant that price, change_1d and change_1d_value come from (the lowest-priced variant)'
+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'
+  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 (per-variant prices and period changes), graded_variants_prices (graded prices keyed by variant then grade)'
+  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(
@@ -76,18 +98,9 @@ export const CardSchema = Type.Object(
     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' })),
-    price_variant: PriceVariantSchema,
+    price_variant_id: PriceVariantIdSchema,
     price_date: PriceDateSchema,
-    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.'
-      })
-    ),
-    graded_variants_prices: Type.Optional({
-      ...GradedVariantPricesSchema,
-      description: 'Graded prices and period changes keyed by variant then grade. Only present when requested via include=graded_variants_prices; empty when the card has no graded prices.'
-    })
+    variants: CardVariantsSchema
   },
   {
     title: 'Card',
@@ -180,16 +193,15 @@ export const CardDetailSchema = Type.Object(
     series: CardFilterFields.series,
     slug: CardFilterFields.slug,
     set_slug: CardFilterFields.set_slug,
-    price_variant: PriceVariantSchema,
+    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(GradedVariantPricesSchema)
+    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',
@@ -209,7 +221,7 @@ const PricePointSchema = Type.Object(
   {
     date: Type.String({ description: 'Date of the price point' }),
     price: Type.Number({ description: 'Price on this date' }),
-    variant: Type.String({ description: 'Card variant' }),
+    variant_id: Type.Union([Type.Integer(), Type.Null()], { description: 'Variant id (variants[].id on the card). Null when the variant text has no definition.' }),
     grade: Type.Optional(Type.String({ description: 'Grade (graded cards only)' }))
   },
   { title: 'PricePoint' }
@@ -217,7 +229,7 @@ const PricePointSchema = Type.Object(
 
 export const CardPricesQuerySchema = Type.Object({
   interval: Type.Number({ minimum: 1, maximum: 1825, default: 30, description: 'Number of days of price history to return' }),
-  variant: Type.Optional(Type.String({ description: 'Variant name. If omitted, returns all variants.' })),
+  variant_id: Type.Optional(Type.Integer({ minimum: 1, description: 'Variant id (variants[].id on the card). If omitted, returns all variants.' })),
   grade: Type.Optional(Type.String({ description: 'Grade (e.g. "PSA 10", "BGS 9.5"). Omit or use "RAW" for ungraded.' })),
   source: Type.Optional(Type.Union(
     [Type.Literal('tcgplayer'), Type.Literal('ebay')],
@@ -230,7 +242,7 @@ export type CardPricesQuery = Static<typeof CardPricesQuerySchema>;
 export const CardPricesResponseSchema = Type.Object(
   {
     cardid: Type.String({ description: 'Card ID' }),
-    variant: Type.Optional(Type.String({ description: 'Filtered variant, if specified' })),
+    variant_id: Type.Optional(Type.Integer({ description: 'Filtered variant id, if specified' })),
     grade: Type.String({ description: 'Resolved grade used for the query' }),
     source: Type.String({ description: 'Resolved price source used for the query' }),
     interval: Type.Number({ description: 'Number of days of history returned' }),
@@ -249,7 +261,7 @@ const SaleRecordSchema = Type.Object(
     sold_date: Type.String({ description: 'Date the card was sold' }),
     price: Type.Number({ description: 'Sale price' }),
     grade: Type.String({ description: 'Grade at time of sale' }),
-    variant: Type.String({ description: 'Card variant' }),
+    variant_id: Type.Union([Type.Integer(), Type.Null()], { description: 'Variant id (variants[].id on the card). Null when the variant text has no definition.' }),
     title: Type.Optional(Type.String({ description: 'eBay listing title' })),
     url: Type.Optional(Type.String({ description: 'eBay listing URL' })),
     image_url: Type.Optional(Type.String({ description: 'Listing image URL' })),
@@ -260,7 +272,7 @@ const SaleRecordSchema = Type.Object(
 
 export const CardSalesQuerySchema = Type.Object({
   grade: Type.Optional(Type.String({ description: 'Filter by grade (e.g. "PSA 10"). Returns all grades if omitted.' })),
-  variant: Type.Optional(Type.String({ description: 'Filter by variant. Returns all variants if omitted.' })),
+  variant_id: Type.Optional(Type.Integer({ minimum: 1, description: 'Filter by variant id (variants[].id on the card). Returns all variants if omitted.' })),
   limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 25, description: 'Max results to return' })),
   offset: Type.Optional(Type.Number({ minimum: 0, default: 0, description: 'Pagination offset' }))
 });
@@ -271,7 +283,7 @@ export const CardSalesResponseSchema = Type.Object(
   {
     cardid: Type.String({ description: 'Card ID' }),
     grade: Type.Optional(Type.String({ description: 'Filtered grade, if specified' })),
-    variant: Type.Optional(Type.String({ description: 'Filtered variant, if specified' })),
+    variant_id: Type.Optional(Type.Integer({ description: 'Filtered variant id, if specified' })),
     data: Type.Array(SaleRecordSchema, { description: 'Individual eBay sold listings, most recent first' }),
     total: Type.Number({ description: 'Total matching sales records' }),
     count: Type.Number({ description: 'Records returned in this response' })
@@ -309,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>;
@@ -560,7 +572,7 @@ export type ListType = Static<typeof ListTypeSchema>;
 export const ListCoverCardSchema = Type.Object(
   {
     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.' }),
     image: Type.Union([Type.String(), Type.Null()], { description: 'Small card image URL' })
   },
   { title: 'ListCoverCard' }
@@ -688,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' }
 );
@@ -701,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.'
     }),
@@ -725,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' }
 );
@@ -759,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()]),
@@ -840,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' }),
@@ -868,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' }