dgc-core 2.0.8 → 2.0.9

package/README.md

@@ -97,3 +97,24 @@ The shared RevenueCat catalog maps Rookie, Collector and Elite entitlement IDs f
 `createRevenueCatClient` accepts server-provided credentials and request limits. `verifyCreditGiveawayEntitlement` checks all eligible tiers using one paginated customer lookup. Null expiry represents non-expiring access; expired entitlements are excluded. Network, rate-limit and malformed-response failures throw a sanitized 503 without exposing credentials. The active entitlements endpoint has no environment filter; configure RevenueCat Sandbox Testing Access and test-account policy for the selected project.
 
 Credit winner selection, confirmation and replacement require an injected `checkCreditEligibility(userId)` callback in the optional third `GiveawayRepository` constructor argument. Missing verification is a 503, never a fallback to saved membership. Product operations do not call the verifier. Checks occur outside transactions; reviewed revisions, candidate identity and unexpired evidence are validated at commit. Random selection picks one candidate first, then checks their entitlement. Inactive candidates are retried without replacement up to `creditWinnerMaxAttempts` (default 5; integer 1-100). It never checks the whole entrant pool in advance. The 30-second draw budget remains in place. Transient RevenueCat network/429/5xx failures retry the same user and page up to three attempts with bounded backoff and Retry-After handling, sharing the existing total lookup deadline. Authorization, missing-resource and malformed-response failures are not retried or treated as inactive access. Evidence is stored on selections and winners. Existing confirmed claims and idempotent rewards do not recheck access.
+
+## Public mobile API contracts
+
+PriceChartingApiCard and PriceChartingVariantApiCard are defined in src/types/api.ts and remain available through dgc-core/types.
+
+The browser-safe types entry exports the public card, set, pricing, image-search,
+population and grading-response contracts from src/types/api.ts. They reuse
+the existing response envelopes and PriceCharting types while keeping nullable
+image-search fields separate from catalog cards. ApiCardResponse, ApiCardsResponse,
+ApiMarketHistoryResponse and the other response aliases model the actual HTTP
+envelopes without exposing stored database records.
+
+The dgc-web documentation generator reads these TypeScript contracts and preserves
+its client-facing descriptions as separate annotations. Change shared model fields
+here, then sync the dashboard's generated documentation. The package export tests
+and mobile API compile tests verify public availability, nullability, literal
+statuses and the browser import boundary.
+
+These additions follow the existing package release process. Publish a new core
+version before registry consumers import the new aliases; documentation can be
+generated from the reviewed local checkout before that release.

package/dist/giveaways/giveaway-repository.d.ts

@@ -61,9 +61,9 @@ export declare class GiveawayRepository {
     private advanceGiveaway;
     submitEntry(account: UserProfile, id: string, raw: unknown): Promise<{
         _id: string;
+        name: string;
         email: string;
         _collectorType: UserCollectorType | null;
-        name: string;
         giveawayId: import("../types").GiveawayObjectId;
         country?: string | undefined;
         enteredAt: string;

package/dist/types/api.d.ts

@@ -1,3 +1,5 @@
+import type { CardType } from '../enums/card';
+import type { PriceChartingImages, PriceChartingPrice } from './pricecharting';
 /** Successful non-paginated DGC API response. */
 export type ApiResponse<T> = {
     data: T;
@@ -10,3 +12,187 @@ export type PaginatedApiResponse<T> = {
     totalCount: number;
     data: T[];
 };
+export type PriceChartingApiCard = {
+    priceChartingId: number;
+    name: string;
+    set: string;
+    number: string | null;
+    releaseDate?: string;
+    price: PriceChartingPrice;
+    images?: PriceChartingImages;
+    type: CardType;
+    version: string;
+};
+export type PriceChartingVariantApiCard = PriceChartingApiCard & {
+    variant: string;
+};
+/** An unsuccessful API response. Use the HTTP status and message together. */
+export type ApiError = {
+    /** Message explaining why the request failed. */
+    error: string;
+};
+/** A grading change was accepted. Read the card again to show its current state. */
+export type ApiSuccess = {
+    success: true;
+};
+/** Available card image URLs. Missing image sizes are omitted. */
+export type ApiImages = NonNullable<PriceChartingApiCard['images']>;
+/** Prices in cents. Unavailable prices are null; missing price fields are omitted. */
+export type ApiPrice = Partial<PriceChartingPrice>;
+/** Card details for catalog screens. Optional fields are omitted when unavailable. */
+export type ApiCardCore = Partial<Omit<PriceChartingApiCard, 'price' | 'type'>> & {
+    /** Available prices in cents. */
+    price?: ApiPrice;
+    /** Card type, such as pokemon or baseball. */
+    type?: string;
+};
+/** Card details with an optional link to its set. */
+export type ApiCard = ApiCardCore & {
+    /** Set ID to use with /sets/{id}/cards. */
+    setId?: string;
+};
+/** A batch card result with its printing label when available. */
+export type ApiCardWithVariant = ApiCard & Partial<Pick<PriceChartingVariantApiCard, 'variant'>>;
+/** A card variant returned for a set, without a separate setId field. */
+export type ApiSetCardVariant = ApiCardCore & Partial<Pick<PriceChartingVariantApiCard, 'variant'>>;
+/** Paginated card search results. totalCount is capped at 1000. */
+export type ApiCardPage = PaginatedApiResponse<ApiCard>;
+/** Paginated cards in a set. totalCount is the full matching count. */
+export type ApiSetCardPage = PaginatedApiResponse<ApiCardCore>;
+/** Card IDs for a batch detail request. Supply at least one numeric ID. */
+export type ApiBatchRequest = {
+    ids: number[];
+};
+/** One legacy trading-card price observation. */
+export type ApiLegacyHistoryEntry = {
+    /** Price date, normally YYYY-MM-DD. */
+    date: string;
+    /** averageSellPrice is in dollars; the other values are zero placeholders. */
+    cardmarket: {
+        averageSellPrice?: number;
+        avg1?: 0;
+        avg30?: 0;
+        avg7?: 0;
+        germanProLow?: 0;
+        lowPrice?: 0;
+        lowPriceExPlus?: 0;
+        reverseHoloAvg1?: 0;
+        reverseHoloAvg30?: 0;
+        reverseHoloAvg7?: 0;
+        reverseHoloLow?: 0;
+        reverseHoloSell?: 0;
+        reverseHoloTrend?: 0;
+        suggestedPrice?: 0;
+        trendPrice?: 0;
+    };
+};
+/** One market-price observation for a UTC date. Prices are cents or null. */
+export type ApiMarketHistoryEntry = {
+    date: string;
+    price: Partial<Pick<PriceChartingPrice, 'loose' | 'retailLooseBuy' | 'retailLooseSell'>>;
+};
+/** The selected card, condition, printing and language for a price chart. */
+export type ApiConditionHistoryMeta = {
+    /** Requested ID: a number for numeric IDs, or a string for legacy Pokemon IDs. */
+    assetId: number | string;
+    priceChartingId: number;
+    tcgplayerId: string;
+    /** ID of the pricing variant used for this chart. */
+    id: string;
+    /** Full condition name, such as Near Mint. */
+    condition: string;
+    printing: string;
+    language: string;
+    /** Current price in cents, or null when unavailable. */
+    price: number | null;
+    /** Last price update as Unix time in seconds, or null when unavailable. */
+    lastUpdated: number | null;
+};
+/** Condition-specific prices, ordered oldest to newest, and chart labels. */
+export type ApiConditionHistoryResponse = ApiResponse<{
+    /** UTC price date in YYYY-MM-DD format. */
+    date: string;
+    /** Price in cents, or null when unavailable. */
+    price: Pick<PriceChartingPrice, 'loose'>;
+}[]> & {
+    meta: ApiConditionHistoryMeta;
+};
+/** A master set available for browsing. */
+export type ApiMasterSet = {
+    /** 24-character set ID to use with /sets/{id}/cards. */
+    id: string;
+    name: string;
+    /** Card type, such as pokemon. */
+    type: string;
+    releaseDate?: string;
+    logo?: string;
+};
+/** Paginated set search results. totalCount includes matches outside this page. */
+export type ApiMasterSetPage = PaginatedApiResponse<ApiMasterSet>;
+/** The master set available for one requested card ID. */
+export type ApiMasterRelationship = {
+    assetId: number;
+    /** Master-set ID, or null when no master set is available. */
+    masterIdentifier: string | null;
+    isExist: boolean;
+};
+/** A catalog group and its master sets. Empty groups have an empty sets array. */
+export type ApiGroup = {
+    name: string;
+    sets: ApiMasterSet[];
+};
+type MaterializedApiImages = {
+    [Key in keyof ApiImages]: ApiImages[Key];
+};
+interface ApiImageMetadata extends MaterializedApiImages {
+    [key: string]: unknown;
+}
+/** Card identified from a photo. Required nullable fields remain present as null. */
+export type ApiImageCard = Pick<PriceChartingApiCard, 'priceChartingId' | 'name' | 'number' | 'version'> & {
+    set: string | null;
+    releaseDate: string | null;
+    /** Available prices in cents, or null when unavailable. */
+    price: Record<string, unknown> | null;
+    images: ApiImageMetadata | null;
+    type: string | null;
+    /** Set ID to use with /sets/{id}/cards. Omitted when unavailable. */
+    setId?: string;
+};
+/** Photo search result. Open data only when matched is true. */
+export type ApiImageMatch = {
+    matched: boolean;
+    reason?: string;
+    score: number | null;
+    gap: number | null;
+    data: ApiImageCard | null;
+};
+/** Card count and percentage for one grade group. */
+export type ApiPopulationBucket = {
+    /** Grade from 0.5 to 10 in half-point steps. */
+    score: number;
+    count: number;
+    /** Percentage of the report total, rounded to two decimal places. */
+    percent: number;
+};
+/** Exactly 20 grade groups, ordered from 0.5 to 10, including empty groups. */
+export type ApiPopulation = {
+    status: 'success';
+    data: ApiPopulationBucket[];
+};
+/** Card details in the standard data envelope. */
+export type ApiCardResponse = ApiResponse<ApiCard>;
+/** Batch card details with variant labels in the standard data envelope. */
+export type ApiCardsResponse = ApiResponse<ApiCardWithVariant[]>;
+/** Legacy price observations in the priceData envelope. */
+export type ApiLegacyHistoryResponse = {
+    priceData: ApiLegacyHistoryEntry[];
+};
+/** Market-price observations in the standard data envelope. */
+export type ApiMarketHistoryResponse = ApiResponse<ApiMarketHistoryEntry[]>;
+/** Card variants in the standard data envelope. */
+export type ApiVariantsResponse = ApiResponse<ApiSetCardVariant[]>;
+/** Master-set relationships in the standard data envelope. */
+export type ApiMasterRelationshipsResponse = ApiResponse<ApiMasterRelationship[]>;
+/** Catalog groups and their master sets in the standard data envelope. */
+export type ApiGroupsResponse = ApiResponse<ApiGroup[]>;
+export {};

package/dist/types/pricecharting.d.ts

@@ -27,7 +27,7 @@ export type SalesVolumeEntry = {
     date: string;
     salesVolume: SalesVolume;
 };
-type Image = {
+export type PriceChartingImages = {
     tiny?: string;
     small?: string;
     normal?: string;
@@ -46,7 +46,7 @@ export type PriceChartingDbCard = {
     priceHistory: PriceChartingPriceEntry[];
     salesVolume: SalesVolume;
     salesVolumeHistory: SalesVolumeEntry[];
-    images?: Image;
+    images?: PriceChartingImages;
     uploadStatus?: {
         imagesUploaded?: boolean;
         noImage?: boolean;
@@ -62,20 +62,6 @@ export type PriceChartingDbCardDto = Omit<PriceChartingDbCard, 'createdAt' | 'up
     createdAt?: string;
     updatedAt: string;
 };
-export type PriceChartingApiCard = {
-    priceChartingId: number;
-    name: string;
-    set: string;
-    number: string | null;
-    releaseDate?: string;
-    price: PriceChartingPrice;
-    images?: Image;
-    type: CardType;
-    version: string;
-};
-export type PriceChartingVariantApiCard = PriceChartingApiCard & {
-    variant: string;
-};
 export type PriceChartingDbSet = {
     type: CardType;
     consoleName: string;
@@ -83,4 +69,3 @@ export type PriceChartingDbSet = {
     createdAt: Date;
     updatedAt: Date;
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dgc-core",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "Shared DGC contracts, business rules and server utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",