@pfdev/api-types 3.0.27 → 3.0.30

package/package.json

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

package/v3.ts

@@ -457,7 +457,7 @@ export const SealedItemSchema = Type.Object(
     set_name: Type.Optional(Type.String({ description: 'Name of the set' })),
     product_slug: Type.Optional(Type.String({ description: 'Product URL slug' })),
     set_slug: Type.Optional(Type.String({ description: 'Set URL slug' })),
-    image: Type.Optional(Type.String({ description: 'Product image URL' })),
+    image: Type.Optional(Type.String({ description: 'Product image URL (WebP on the Pokefolio CDN). Not every product has an image there yet.' })),
     tcgp_id: Type.Optional(Type.Number({ description: 'TCGPlayer product ID' })),
     language: Type.Optional(Type.String({ description: 'Product language' })),
     price: Type.Optional(Type.Number({ description: 'Current market price' })),
@@ -473,7 +473,7 @@ export const SealedItemSchema = Type.Object(
     change_3m_value: Type.Optional(Type.Number({ description: '90-day price change in dollars' })),
     change_6m_value: Type.Optional(Type.Number({ description: '180-day price change in dollars' })),
     change_1y_value: Type.Optional(Type.Number({ description: '1-year price change in dollars' })),
-    price_updated: Type.Optional(Type.String({ description: 'Timestamp of last price update' }))
+    price_updated: Type.Optional(Type.String({ description: 'Date (YYYY-MM-DD) the price was last updated' }))
   },
   {
     title: 'SealedItem',
@@ -497,18 +497,89 @@ export const SealedListResponseSchema = Type.Object(
 
 export type SealedListResponse = Static<typeof SealedListResponseSchema>;
 
+export const SealedListSortSchema = Type.Union([
+  Type.Literal('name_asc'),
+  Type.Literal('name_desc'),
+  Type.Literal('price_asc'),
+  Type.Literal('price_desc'),
+  Type.Literal('change_asc'),
+  Type.Literal('change_desc'),
+  Type.Literal('release_desc'),
+  Type.Literal('release_asc'),
+  Type.Literal('release_desc_price_desc')
+], {
+  default: 'name_asc',
+  description: 'Sort order. change_* sorts by 1-day percentage price change. release_asc/desc sort by set release date, then name. release_desc_price_desc sorts by newest set, then price descending. Products with no price come last in every price and change sort. Defaults to name_asc.'
+});
+
+export type SealedListSort = Static<typeof SealedListSortSchema>;
+
+// Filters shared by /sealed and /sealed/facets. Each is a comma-separated list:
+// values within one param match with OR, different params combine with AND.
+const SealedListFilterFields = {
+  setid: Type.Optional(Type.String({ description: 'Comma-separated set IDs (max 500)' })),
+  language: Type.Optional(Type.String({ description: 'Comma-separated language codes (EN, JP; max 50)' })),
+  search: Type.Optional(Type.String({ minLength: 1, description: 'Search by product name. Every word must match.' })),
+  name: Type.Optional(Type.String({ minLength: 1, description: 'Alias for search. Ignored when search is sent.' }))
+};
+
 export const SealedListQuerySchema = Type.Object(
   {
-    setid: Type.Optional(Type.String({ description: 'Filter by set ID' })),
-    name: Type.Optional(Type.String({ description: 'Search by product name' })),
+    ...SealedListFilterFields,
+    sort: Type.Optional(SealedListSortSchema),
     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 name must be provided' }
+  { description: 'With no search or filters, lists every published product' }
 );
 
 export type SealedListQuery = Static<typeof SealedListQuerySchema>;
 
+export const SealedFacetsQuerySchema = Type.Object(
+  SealedListFilterFields,
+  { description: 'Same search and filters as /sealed. With none, returns the facets for every published product' }
+);
+
+export type SealedFacetsQuery = Static<typeof SealedFacetsQuerySchema>;
+
+export const SealedFacetGroupSchema = Type.Object(
+  {
+    value: Type.String({ description: 'Group id, e.g. the series name' }),
+    label: Type.String({ description: 'Heading to show users' })
+  },
+  { title: 'SealedFacetGroup' }
+);
+
+export const SealedFacetOptionSchema = 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: 'Products this option matches, ignoring this facet\'s own selection' }),
+    order: Type.Optional(Type.Integer({ description: 'Display order, ascending: sets by release date, newest first (0 = newest); languages English first.' })),
+    group: Type.Optional(SealedFacetGroupSchema),
+    language: Type.Optional(Type.String({ description: 'Language code of the set (EN, JP). Set options only.' }))
+  },
+  { title: 'SealedFacetOption' }
+);
+
+export type SealedFacetOption = Static<typeof SealedFacetOptionSchema>;
+
+export const SealedFacetsResponseSchema = Type.Object(
+  {
+    total: Type.Integer({ description: 'Products matching search and all filters' }),
+    facets: Type.Object({
+      language: Type.Array(SealedFacetOptionSchema, { description: 'Value is the language code, label its name (e.g. JP, Japanese)' }),
+      set: Type.Array(SealedFacetOptionSchema, { description: 'Each option carries its series in group, omitted when the set has no series' })
+    })
+  },
+  {
+    title: 'SealedFacetsResponse',
+    description: 'Filter options for a sealed product search, with counts'
+  }
+);
+
+export type SealedFacetsResponse = Static<typeof SealedFacetsResponseSchema>;
+
 // Path parameters
 export const SealedDetailParamSchema = Type.Object({
   sealedid: Type.String({ format: 'uuid', description: 'Sealed product ID' })
@@ -640,6 +711,192 @@ export const SetDetailParamSchema = Type.Object({
 
 export type SetDetailParam = Static<typeof SetDetailParamSchema>;
 
+// ============= COLLECTION =============
+
+
+export const CollectionRangeSchema = Type.Union(
+  [
+    Type.Literal('1W'),
+    Type.Literal('1M'),
+    Type.Literal('3M'),
+    Type.Literal('6M'),
+    Type.Literal('1Y'),
+    Type.Literal('ALL')
+  ],
+  { description: 'Chart window and comparison period' }
+);
+
+export type CollectionRange = Static<typeof CollectionRangeSchema>;
+
+export const CollectionGainersRangeSchema = Type.Union(
+  [
+    Type.Literal('1D'),
+    Type.Literal('1W'),
+    Type.Literal('1M'),
+    Type.Literal('3M'),
+    Type.Literal('6M'),
+    Type.Literal('1Y'),
+    Type.Literal('ALL')
+  ],
+  { description: 'Comparison period' }
+);
+
+export type CollectionGainersRange = Static<typeof CollectionGainersRangeSchema>;
+
+const ComparisonRangeSchema = Type.Union(
+  [
+    Type.Literal('1D'),
+    Type.Literal('1W'),
+    Type.Literal('1M'),
+    Type.Literal('3M'),
+    Type.Literal('6M'),
+    Type.Literal('1Y')
+  ],
+  { description: 'Period the change was measured over. ALL is measured over 1Y, the longest past price available.' }
+);
+
+const AllocationFields = {
+  value: Type.Number({ description: 'Market value in USD' }),
+  items: Type.Integer({ description: 'Items owned, counting each copy' }),
+  no_price_count: Type.Integer({ description: 'Copies with no current price, counted in items but adding nothing to value' })
+};
+
+export const CollectionAllocationSchema = Type.Object(AllocationFields, { title: 'CollectionAllocation' });
+
+export const CollectionCardAllocationSchema = Type.Object(
+  {
+    ...AllocationFields,
+    assumed_raw_count: Type.Integer({
+      description: 'Graded copies valued at the raw price because their grade has no current price'
+    })
+  },
+  { title: 'CollectionCardAllocation' }
+);
+
+export const CollectionSummaryResponseSchema = Type.Object(
+  {
+    total_value: Type.Number({ description: 'Market value of everything owned, in USD' }),
+    items: Type.Integer({ description: 'Items owned, counting each copy' }),
+    allocation: Type.Object({
+      cards: CollectionCardAllocationSchema,
+      sealed: CollectionAllocationSchema
+    })
+  },
+  { title: 'CollectionSummaryResponse' }
+);
+
+export type CollectionSummaryResponse = Static<typeof CollectionSummaryResponseSchema>;
+
+export const CollectionGainerSchema = 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.' }),
+    grade: Type.Union([Type.String(), Type.Null()], { description: 'Null for ungraded copies' }),
+    quantity: Type.Integer({ description: 'Copies owned of this card, variant and grade' }),
+    name: Type.String(),
+    number: Type.Union([Type.String(), Type.Null()]),
+    image: Type.Union([Type.String(), Type.Null()], { description: 'Small card image URL' }),
+    setid: Type.Union([Type.String(), Type.Null()]),
+    setname: Type.Union([Type.String(), Type.Null()]),
+    current_price: Type.Number({ description: 'Current market price of one copy, in USD' }),
+    past_price: Type.Number({ description: 'Market price of one copy at the start of the period, in USD' }),
+    change_value: Type.Number({ description: 'Price change of one copy over the period, in USD' }),
+    change_percent: Type.Number({ description: 'Price change over the period, as a percentage of past_price' })
+  },
+  { title: 'CollectionGainer' }
+);
+
+export type CollectionGainer = Static<typeof CollectionGainerSchema>;
+
+export const CollectionChartPointSchema = Type.Object(
+  {
+    date: Type.String({ description: 'YYYY-MM-DD' }),
+    value: Type.Number({ description: 'Collection value in USD' })
+  },
+  { title: 'CollectionChartPoint' }
+);
+
+export type CollectionChartPoint = Static<typeof CollectionChartPointSchema>;
+
+export const CollectionPerformanceQuerySchema = Type.Object({
+  range: Type.Optional(Type.Union(CollectionRangeSchema.anyOf, { default: '1M', description: 'Chart window and comparison period' }))
+});
+
+export type CollectionPerformanceQuery = Static<typeof CollectionPerformanceQuerySchema>;
+
+export const CollectionPerformanceResponseSchema = Type.Object(
+  {
+    range: CollectionRangeSchema,
+    comparison_range: ComparisonRangeSchema,
+    current_value: Type.Number({ description: 'Market value of everything owned, in USD' }),
+    change_value: Type.Number({ description: 'Market price change of what is owned now, in USD. Adding or removing items does not move it.' }),
+    change_percent: Type.Union([Type.Number(), Type.Null()], { description: 'change_value as a percentage of the items\' past value. Null when no item has a past price.' }),
+    points: Type.Array(CollectionChartPointSchema, { description: 'Collection value over time, oldest first, at most 180 points. The last point is the current value.' }),
+    gainers: Type.Array(CollectionGainerSchema, { description: 'Top 4 cards by price change in USD' })
+  },
+  { title: 'CollectionPerformanceResponse' }
+);
+
+export type CollectionPerformanceResponse = Static<typeof CollectionPerformanceResponseSchema>;
+
+export const CollectionGainersSortSchema = Type.Union(
+  [Type.Literal('value'), Type.Literal('percent')],
+  { description: 'value = largest USD change first, percent = largest percentage change first' }
+);
+
+export type CollectionGainersSort = Static<typeof CollectionGainersSortSchema>;
+
+export const CollectionGainersQuerySchema = Type.Object({
+  range: Type.Optional(Type.Union(CollectionGainersRangeSchema.anyOf, { default: '1M', description: 'Comparison period' })),
+  sort: Type.Optional(Type.Union(CollectionGainersSortSchema.anyOf, { default: 'value', description: 'value = largest USD change first, percent = largest percentage change first' })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, default: 25, description: 'Max results to return' })),
+  offset: Type.Optional(Type.Integer({ minimum: 0, default: 0 }))
+});
+
+export type CollectionGainersQuery = Static<typeof CollectionGainersQuerySchema>;
+
+export const CollectionGainersResponseSchema = Type.Object(
+  {
+    range: CollectionGainersRangeSchema,
+    comparison_range: ComparisonRangeSchema,
+    total: Type.Integer({ description: 'Cards that gained over the period, across all pages' }),
+    items: Type.Array(CollectionGainerSchema)
+  },
+  { title: 'CollectionGainersResponse' }
+);
+
+export type CollectionGainersResponse = Static<typeof CollectionGainersResponseSchema>;
+
+export const CollectionSetsQuerySchema = Type.Object({
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 250, default: 3, description: 'Max results to return' })),
+  offset: Type.Optional(Type.Integer({ minimum: 0, default: 0 }))
+});
+
+export type CollectionSetsQuery = Static<typeof CollectionSetsQuerySchema>;
+
+export const CollectionSetSchema = Type.Object(
+  {
+    setid: Type.String(),
+    name: Type.String(),
+    slug: Type.Union([Type.String(), Type.Null()]),
+    imglogo: Type.Union([Type.String(), Type.Null()]),
+    imgsymbol: Type.Union([Type.String(), Type.Null()]),
+    total: Type.Integer({ description: 'Cards in the set' }),
+    collected: Type.Integer({ description: 'Distinct cards of this set the user owns' }),
+    percent: Type.Number({ description: 'collected as a percentage of total, at most 100' })
+  },
+  { title: 'CollectionSet' }
+);
+
+export type CollectionSet = Static<typeof CollectionSetSchema>;
+
+export const CollectionSetsResponseSchema = Type.Array(CollectionSetSchema, {
+  title: 'CollectionSetsResponse',
+  description: 'Sets the user has started, most collected cards first.'
+});
+
+export type CollectionSetsResponse = Static<typeof CollectionSetsResponseSchema>;
+
 // ============= LISTS =============
 
 
@@ -882,6 +1139,9 @@ export const InventorySummaryItemSchema = Type.Object(
     status: Type.Union([Type.Number(), Type.Null()], {
       description: 'Numeric status code. <100 = active, >=100 = sold/past. Null when no details row exists yet.'
     }),
+    grade: Type.Union([Type.String(), Type.Null()], {
+      description: 'Grade of this copy (e.g. "PSA 10"), matching a key of variants[].graded. Null when ungraded or no details row exists yet.'
+    }),
     acquired: Type.Union([Type.String(), Type.Null()], {
       description: 'User-entered acquired date. Null when not set or no details row exists yet.'
     }),
@@ -1014,6 +1274,84 @@ export const InventoryPatchRequestSchema = Type.Object(
 
 export type InventoryPatchRequest = Static<typeof InventoryPatchRequestSchema>;
 
+// ============= SEALED =============
+
+
+export const SealedQuantitiesQuerySchema = Type.Object({
+  setid: Type.Optional(Type.String({ minLength: 1, description: 'Only products in this set. If omitted, returns every product the user owns.' }))
+});
+
+export type SealedQuantitiesQuery = Static<typeof SealedQuantitiesQuerySchema>;
+
+export const SealedQuantitySchema = Type.Object(
+  {
+    sealedid: Type.String({ format: 'uuid', description: 'Sealed product ID' }),
+    quantity: Type.Integer({ description: 'Copies the user currently owns. Sold copies are not counted.' })
+  },
+  { title: 'SealedQuantity' }
+);
+
+export const SealedQuantitiesResponseSchema = Type.Array(SealedQuantitySchema, {
+  title: 'SealedQuantitiesResponse',
+  description: 'One entry per product the user owns. Products they don\'t own are left out.'
+});
+
+export const SealedInventoryAddRequestSchema = Type.Object(
+  {
+    sealedid: Type.String({ format: 'uuid', description: 'Published sealed product to add one copy of' })
+  },
+  { title: 'SealedInventoryAddRequest' }
+);
+
+export type SealedInventoryAddRequest = Static<typeof SealedInventoryAddRequestSchema>;
+
+export const SealedInventoryRowSchema = Type.Object(
+  {
+    uuid: Type.String({ format: 'uuid', description: 'Unique ID of this copy' }),
+    sealedid: Type.String({ format: 'uuid', description: 'Sealed product this copy belongs to' }),
+    status: Type.Union([Type.Number(), Type.Null()], {
+      description: 'Numeric status code. <100 = active, >=100 = sold/past. Null when not set.'
+    }),
+    acquired: Type.Union([Type.String(), Type.Null()], {
+      description: 'User-entered acquired date (YYYY-MM-DD). Null when not set.'
+    }),
+    created_at: Type.String({ description: 'When this copy was added' })
+  },
+  { title: 'SealedInventoryRow' }
+);
+
+export const SealedInventoryItemsQuerySchema = Type.Object({
+  sealedid: Type.String({ format: 'uuid', description: 'Sealed product to fetch copies for' })
+});
+
+export type SealedInventoryItemsQuery = Static<typeof SealedInventoryItemsQuerySchema>;
+
+export const SealedInventoryItemSchema = Type.Object(
+  {
+    ...SealedInventoryRowSchema.properties,
+    notes: Type.Union([Type.String(), Type.Null()]),
+    total_cost_usd: Type.Number(),
+    total_income_usd: Type.Number(),
+    profit_loss_usd: Type.Number(),
+    transactions: Type.Array(InventoryTransactionSchema)
+  },
+  {
+    title: 'SealedInventoryItem',
+    description: 'One owned copy of a sealed product, including transactions and aggregated totals.'
+  }
+);
+
+export const SealedInventoryItemsResponseSchema = Type.Array(SealedInventoryItemSchema, {
+  title: 'SealedInventoryItemsResponse',
+  description: 'Copies the user currently owns of one product, newest first. Sold copies are left out, so the length matches quantity.'
+});
+
+export const SealedInventoryDeleteParamSchema = Type.Object({
+  uuid: Type.String({ format: 'uuid', description: 'UUID of the copy to delete' })
+});
+
+export type SealedInventoryDeleteParam = Static<typeof SealedInventoryDeleteParamSchema>;
+
 // ============= VISION =============