dgc-core 2.0.7 → 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/index.d.ts

@@ -2,8 +2,6 @@ export * from './types';
 export * from './db/mongo';
 export * from './db/mongo2';
 export * from './db/mongo3';
-export * from './tw/utils';
-export * from './tw/wallet';
 export * from './auth';
 export * from './chunk';
 export * from './env';

package/dist/index.js

@@ -18,8 +18,6 @@ __exportStar(require("./types"), exports);
 __exportStar(require("./db/mongo"), exports);
 __exportStar(require("./db/mongo2"), exports);
 __exportStar(require("./db/mongo3"), exports);
-__exportStar(require("./tw/utils"), exports);
-__exportStar(require("./tw/wallet"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./chunk"), exports);
 __exportStar(require("./env"), exports);

package/dist/pub.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishMessage = publishMessage;
 // src/pub.ts
 const pubsub_1 = require("@google-cloud/pubsub");
+const logger_1 = require("./logger");
 let cachedPubSub = null;
 function getPubSub(projectId) {
     if (!projectId)
@@ -26,11 +27,11 @@ async function publishMessage(projectId, topicName, envelope) {
         const messageId = await topic.publishMessage({
             data
         });
-        console.info(`INFO: Pub/Sub publish topic=${topicName} msg_id=${messageId}`);
+        (0, logger_1.log)(logger_1.LogLevel.INFO, 'Pub/Sub publish', { topicName, messageId });
         return messageId;
     }
     catch (err) {
-        console.error('ERROR: publish failed:', err);
+        (0, logger_1.log)(logger_1.LogLevel.ERROR, 'publish failed', { error: err });
         throw err;
     }
 }

package/dist/task.js

@@ -4,6 +4,7 @@ exports.isRetryableCloudTasks = isRetryableCloudTasks;
 exports.createTask = createTask;
 // src/cloud-tasks.ts
 const tasks_1 = require("@google-cloud/tasks");
+const logger_1 = require("./logger");
 const retry_1 = require("./retry");
 const tasksClient = new tasks_1.CloudTasksClient();
 // cloud-tasks errors can be gRPC-style (numeric code) or an Error with code string.
@@ -67,7 +68,11 @@ async function createTask(projectId, region, queueId, data, serviceAccount, audi
         timeoutMs: 15000,
         isRetryable: isRetryableCloudTasks,
         onRetry: (err, attempt, delay) => {
-            console.warn(`createTask retry #${attempt} in ${delay}ms — ${String(err?.message ?? err)}`);
+            (0, logger_1.log)(logger_1.LogLevel.WARNING, 'createTask retry', {
+                attempt,
+                delayMs: delay,
+                error: String(err?.message ?? err)
+            });
         },
         ...opts.retryOptions // allow overrides
     };
@@ -93,11 +98,13 @@ async function createTask(projectId, region, queueId, data, serviceAccount, audi
             if (err?.original?.code === 6 ||
                 err?.code === 6 ||
                 String(err?.original?.code).toUpperCase().includes('ALREADY_EXISTS')) {
-                console.warn('createTask — task already exists, returning existing name', expectedName);
+                (0, logger_1.log)(logger_1.LogLevel.WARNING, 'createTask — task already exists, returning existing name', {
+                    taskName: expectedName
+                });
                 return expectedName;
             }
         }
-        console.error('createTask — final failure after retries', { error: err?.message ?? err });
+        (0, logger_1.log)(logger_1.LogLevel.ERROR, 'createTask — final failure after retries', { error: err?.message ?? err });
         throw err; // rethrow (or return null if you prefer)
     }
 }

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.7",
+  "version": "2.0.9",
   "description": "Shared DGC contracts, business rules and server utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/tw/utils.d.ts

@@ -1 +0,0 @@
-export declare function isValidWebhookSignature(secret: string, body: string, signature: string): boolean;

package/dist/tw/utils.js

@@ -1,19 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isValidWebhookSignature = isValidWebhookSignature;
-const crypto_1 = __importDefault(require("crypto"));
-const generateSignature = (body, secret) => {
-    return crypto_1.default.createHmac('sha256', secret).update(body).digest('hex');
-};
-function isValidWebhookSignature(secret, body, signature) {
-    const expectedSignature = generateSignature(body, secret);
-    const expectedBuffer = Buffer.from(expectedSignature);
-    const signatureBuffer = Buffer.from(signature);
-    if (expectedBuffer.length !== signatureBuffer.length) {
-        return false;
-    }
-    return crypto_1.default.timingSafeEqual(expectedBuffer, signatureBuffer);
-}

package/dist/tw/wallet.d.ts

@@ -1 +0,0 @@
-export declare function pregenerateInAppWallet(twClientId: string, twSecretKey: string, email: string): Promise<string | null>;

package/dist/tw/wallet.js

@@ -1,57 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pregenerateInAppWallet = pregenerateInAppWallet;
-// src/tw/wallet.ts
-const axios_1 = __importDefault(require("axios"));
-const retry_1 = require("../retry");
-async function pregenerateInAppWallet(twClientId, twSecretKey, email) {
-    if (!twClientId || !twSecretKey || !email) {
-        console.error('Missing client id or secret or email');
-        return null;
-    }
-    const doRequest = async () => {
-        const res = await axios_1.default.post('https://in-app-wallet.thirdweb.com/api/v1/pregenerate', { strategy: 'email', email }, {
-            headers: {
-                'Content-Type': 'application/json',
-                'x-client-id': twClientId,
-                'x-secret-key': twSecretKey
-            },
-            timeout: 10000
-        });
-        const wallet = res.data?.wallet;
-        if (!wallet || !wallet.address) {
-            // server returned 2xx but unexpected shape — don't retry, treat as final failure
-            console.error('Invalid wallet response shape', { status: res.status, data: res.data });
-            throw new Error('Invalid wallet response');
-        }
-        return wallet.address;
-    };
-    const opts = {
-        retries: 3,
-        baseDelayMs: 300,
-        maxDelayMs: 2000,
-        timeoutMs: 15000,
-        isRetryable: retry_1.isRetryableAxios,
-        onRetry: (err, attempt, delay) => {
-            console.warn(`pregenerateInAppWallet: retry #${attempt} in ${delay}ms — ${String(err?.message)}`);
-        }
-    };
-    try {
-        const address = await (0, retry_1.retry)(() => doRequest(), opts);
-        return address;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    }
-    catch (err) {
-        // final failure after retries
-        console.error('pregenerateInAppWallet: final failure', {
-            message: err?.message,
-            // include axios response data when possible
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            responseData: err?.response?.data ?? err?.cause ?? err.original ?? null
-        });
-        return null;
-    }
-}