@pfdev/api-types 3.0.21 → 3.0.23

package/package.json

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

package/v3.ts

@@ -89,7 +89,8 @@ export const CardSchema = Type.Object(
     cardid: Type.String({ description: 'Unique card identifier' }),
     name: Type.String({ description: 'Card name' }),
     number: Type.String({ description: 'Card number within set' }),
-    rarity: Type.Optional(Type.String({ description: 'Card rarity' })),
+    rarity: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Card rarity, the same for every language (no _JP suffix). None when the card has no rarity; null when not set.' })),
+    language: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Card language code (EN, JP)' })),
     artist: Type.Optional(Type.String({ description: 'Card artist' })),
     images: CardImagesSchema,
     setid: Type.String({ description: 'Set this card belongs to' }),
@@ -137,20 +138,82 @@ 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. A rarity matches cards in every language.' })),
+  language: Type.Optional(Type.String({ description: 'Comma-separated language codes (EN, JP; max 50)' })),
+  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, language 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); languages English first. 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' }),
+    variant_total: Type.Integer({ description: 'Non-hidden variants on those cards, counted like variant_count. With variant_id, only the selected variants count.' }),
+    facets: Type.Object({
+      rarity: Type.Array(CardFacetOptionSchema, { description: 'Cards with no rarity have the value None, labelled "No rarity". Cards with rarity unset are counted in total but have no option.' }),
+      language: Type.Array(CardFacetOptionSchema, { description: 'Value is the language code, label its name (e.g. JP, Japanese)' }),
+      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,
@@ -166,7 +229,8 @@ export const CardDetailSchema = Type.Object(
     cardid: Type.String({ description: 'Unique card identifier' }),
     name: Type.String({ description: 'Card name' }),
     number: Type.String({ description: 'Card number within set' }),
-    rarity: Type.Optional(Type.String({ description: 'Card rarity' })),
+    rarity: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Card rarity, the same for every language (no _JP suffix). None when the card has no rarity; null when not set.' })),
+    language: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: 'Card language code (EN, JP)' })),
     images: CardImagesSchema,
     setid: Type.String({ description: 'Set this card belongs to' }),
     setname: Type.String({ description: 'Name of the set' }),