@pfdev/api-types 3.0.20 → 3.0.22

package/package.json

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

package/v3.ts

@@ -137,20 +137,79 @@ export const CardListSortSchema = Type.Union([
 
 export type CardListSort = Static<typeof CardListSortSchema>;
 
+// Filters shared by /cards and /cards/facets. Each is a comma-separated list:
+// values within one param match with OR, different params combine with AND.
+const CardListFilterFields = {
+  setid: Type.Optional(Type.String({ description: 'Comma-separated set IDs (max 500). A single ID behaves as before.' })),
+  rarity: Type.Optional(Type.String({ description: 'Comma-separated rarities (max 50), matched exactly' })),
+  variant_id: Type.Optional(Type.String({ description: 'Comma-separated variant ids (variants[].id, max 50). Matches non-hidden variants only.' }))
+};
+
+const CardSearchField = 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.' }));
+
 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.' })),
+    ...CardListFilterFields,
+    search: CardSearchField,
     sort: Type.Optional(CardListSortSchema),
     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' }))
   },
-  { description: 'At least one of setid or search must be provided' }
+  { description: 'At least one of search, setid, rarity or variant_id must be provided' }
 );
 
 export type CardListQuery = Static<typeof CardListQuerySchema>;
 
+export const CardFacetsQuerySchema = Type.Object(
+  {
+    ...CardListFilterFields,
+    search: CardSearchField
+  },
+  { description: 'Same search and filters as /cards; at least one of them must be provided' }
+);
+
+export type CardFacetsQuery = Static<typeof CardFacetsQuerySchema>;
+
+export const CardFacetGroupSchema = Type.Object(
+  {
+    value: Type.String({ description: 'Group id, e.g. the series name' }),
+    label: Type.String({ description: 'Heading to show users' })
+  },
+  { title: 'CardFacetGroup' }
+);
+
+export const CardFacetOptionSchema = Type.Object(
+  {
+    value: Type.String({ description: 'Value to send back in the matching filter param' }),
+    label: Type.String({ description: 'Label to show users' }),
+    count: Type.Integer({ description: 'Cards this option matches, ignoring this facet\'s own selection' }),
+    variant_count: Type.Integer({ description: 'Non-hidden variants on those cards, same counting rule. With variant_id, only the selected variants count.' }),
+    order: Type.Optional(Type.Integer({ description: 'Display order, ascending: variant sort_order; sets by release date, newest first (0 = newest). Omitted for rarity.' })),
+    group: Type.Optional(CardFacetGroupSchema)
+  },
+  { title: 'CardFacetOption' }
+);
+
+export type CardFacetOption = Static<typeof CardFacetOptionSchema>;
+
+export const CardFacetsResponseSchema = Type.Object(
+  {
+    total: Type.Integer({ description: 'Cards matching search and all filters' }),
+    facets: Type.Object({
+      rarity: Type.Array(CardFacetOptionSchema),
+      variant: Type.Array(CardFacetOptionSchema),
+      set: Type.Array(CardFacetOptionSchema, { description: 'Each option carries its series in group, omitted when the set has no series' })
+    })
+  },
+  {
+    title: 'CardFacetsResponse',
+    description: 'Filter options for a card search, with counts'
+  }
+);
+
+export type CardFacetsResponse = Static<typeof CardFacetsResponseSchema>;
+
 export const CardBatchQuerySchema = Type.Object({
   ids: Type.String({
     minLength: 1,
@@ -221,7 +280,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' }
@@ -229,7 +288,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')],
@@ -242,7 +301,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' }),
@@ -261,7 +320,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' })),
@@ -272,7 +331,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' }))
 });
@@ -283,7 +342,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' })