dgc-core 2.0.5 → 2.0.7

package/README.md

@@ -60,9 +60,15 @@ adapters stay in the application. Collection and index provisioning stays in
 `dgc-db-ops`.
 
 Giveaway documents use MongoDB ObjectIds, serialized as 24-character hexadecimal
-strings in APIs; entry IDs use 12 decimal characters and preserve leading zeros.
-Firebase `userId` identifies each entrant. Collector type is informational and
-never changes eligibility. Administrative entry and winner records contain
+strings in APIs; new entry IDs use DGC- plus 12 uppercase letters/digits. Existing 12-digit ticket IDs remain readable.
+Firebase `userId` identifies each entrant. Products have no collector-tier restriction for authenticated
+accounts, including accounts with a missing or unsupported tier. Credits allow only Rookie (1),
+Collector (3) and Elite (0); Free (2), non-members and missing or unsupported tiers cannot enter credits.
+Public `eligibleCollectorTypes` is `null` for unrestricted Products and `[1, 3, 0]` for Credits.
+Entry snapshots preserve known numeric tiers and use `null` for missing or unsupported values.
+Eligible entries have equal chances; credit winner selection uses the saved entry tier while product
+draws include all valid entries. Push-token audience filters belong to the delivery adapter and do not
+restrict entry submission. Administrative entry and winner records contain
 personal information and require authorized access; use `GiveawayPublic` for
 public app responses. `DomainError` and `HttpError` refer to the same constructor.
 
@@ -83,3 +89,11 @@ send notifications or connect to a live database.
 ## Giveaway MVP v2
 
 One ticket per Firebase account, one winner per giveaway, saved random/manual selection and explicit confirmation. Physical address and contact number are collected at claim only. Credit rewards snapshot `creditAmount` and use `fulfillGiveawayCredits` to atomically change Firebase `instantCredits` plus a permanent per-giveaway marker. Status reads reconcile without issuing credits. See dgc-giveaways/docs/api.md and integration.md for contracts and release order.
+
+## RevenueCat entitlement verification
+
+The shared RevenueCat catalog maps Rookie, Collector and Elite entitlement IDs for project `projb48c5a30`. It contains no API key. The browser-safe catalog and evidence types are available from `dgc-core/types`; the HTTP client is exported only from `dgc-core`.
+
+`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.

package/dist/constants/revenuecat.d.ts

@@ -0,0 +1,7 @@
+import type { RevenueCatEntitlementIds } from '../types/revenuecat';
+export declare const REVENUECAT_API_V2 = "https://api.revenuecat.com/v2";
+export declare const DGC_REVENUECAT_PROJECT_ID = "projb48c5a30";
+export declare const DGC_REVENUECAT_ELITE_ENTITLEMENT_ID = "entlb1b4b2ae6b";
+export declare const DGC_REVENUECAT_ENTITLEMENT_IDS: RevenueCatEntitlementIds;
+/** Non-secret catalog IDs are shared; callers can supply a separate test-project catalog. */
+export declare function createRevenueCatEntitlementIds(values?: Partial<RevenueCatEntitlementIds>): RevenueCatEntitlementIds;

package/dist/constants/revenuecat.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DGC_REVENUECAT_ENTITLEMENT_IDS = exports.DGC_REVENUECAT_ELITE_ENTITLEMENT_ID = exports.DGC_REVENUECAT_PROJECT_ID = exports.REVENUECAT_API_V2 = void 0;
+exports.createRevenueCatEntitlementIds = createRevenueCatEntitlementIds;
+exports.REVENUECAT_API_V2 = 'https://api.revenuecat.com/v2';
+exports.DGC_REVENUECAT_PROJECT_ID = 'projb48c5a30';
+exports.DGC_REVENUECAT_ELITE_ENTITLEMENT_ID = 'entlb1b4b2ae6b';
+exports.DGC_REVENUECAT_ENTITLEMENT_IDS = Object.freeze({
+    rookie: 'entl74fb3d3bc3',
+    collector: 'entl0bea318713',
+    elite: exports.DGC_REVENUECAT_ELITE_ENTITLEMENT_ID
+});
+/** Non-secret catalog IDs are shared; callers can supply a separate test-project catalog. */
+function createRevenueCatEntitlementIds(values = {}) {
+    const ids = {
+        rookie: (values.rookie ?? exports.DGC_REVENUECAT_ENTITLEMENT_IDS.rookie).trim(),
+        collector: (values.collector ?? exports.DGC_REVENUECAT_ENTITLEMENT_IDS.collector).trim(),
+        elite: (values.elite ?? exports.DGC_REVENUECAT_ENTITLEMENT_IDS.elite).trim()
+    };
+    if (Object.values(ids).some(id => typeof id !== 'string' || !/^entl[a-zA-Z0-9]+$/.test(id)))
+        throw new Error('Configure valid RevenueCat entitlement IDs for Rookie, Collector and Elite');
+    if (new Set(Object.values(ids)).size !== 3)
+        throw new Error('RevenueCat tier entitlement IDs must be distinct');
+    return Object.freeze(ids);
+}

package/dist/enums/giveaway.d.ts

@@ -39,11 +39,13 @@ export declare enum GiveawayNotificationStatus {
     Pending = "pending",
     Delivering = "delivering",
     Sent = "sent",
-    Failed = "failed"
+    Failed = "failed",
+    Skipped = "skipped"
 }
 export declare enum GiveawayNotificationDeliveryStatus {
     Pending = "pending",
-    Queued = "queued"
+    Queued = "queued",
+    Skipped = "skipped"
 }
 export declare enum GiveawayTicketResult {
     Pending = "pending",

package/dist/enums/giveaway.js

@@ -50,11 +50,13 @@ var GiveawayNotificationStatus;
     GiveawayNotificationStatus["Delivering"] = "delivering";
     GiveawayNotificationStatus["Sent"] = "sent";
     GiveawayNotificationStatus["Failed"] = "failed";
+    GiveawayNotificationStatus["Skipped"] = "skipped";
 })(GiveawayNotificationStatus || (exports.GiveawayNotificationStatus = GiveawayNotificationStatus = {}));
 var GiveawayNotificationDeliveryStatus;
 (function (GiveawayNotificationDeliveryStatus) {
     GiveawayNotificationDeliveryStatus["Pending"] = "pending";
     GiveawayNotificationDeliveryStatus["Queued"] = "queued";
+    GiveawayNotificationDeliveryStatus["Skipped"] = "skipped";
 })(GiveawayNotificationDeliveryStatus || (exports.GiveawayNotificationDeliveryStatus = GiveawayNotificationDeliveryStatus = {}));
 var GiveawayTicketResult;
 (function (GiveawayTicketResult) {

package/dist/giveaways/domain.d.ts

@@ -56,8 +56,8 @@ export declare function giveawayChanges(existing: Giveaway, updated: Giveaway):
 };
 export declare function transition(existing: Giveaway, action: GiveawayAction, revision: number): Giveaway;
 export declare function submitEntry(g: Giveaway, account: UserProfile, raw: unknown): Omit<Entry, '_id'>;
-export declare function confirmWinners(g: Giveaway, entries: Pick<Entry, '_id' | 'userId' | 'giveawayId'>[], alreadyConfirmed: boolean, actor: string, raw: unknown): Omit<Winner, '_id'>[];
-export declare function replaceWinner(g: Giveaway, old: Winner, entry: Pick<Entry, '_id' | 'giveawayId'>, alreadyWinner: boolean, actor: string, reason: string): {
+export declare function confirmWinners(g: Giveaway, entries: Pick<Entry, '_id' | 'userId' | 'giveawayId' | '_collectorType'>[], alreadyConfirmed: boolean, actor: string, raw: unknown): Omit<Winner, '_id'>[];
+export declare function replaceWinner(g: Giveaway, old: Winner, entry: Pick<Entry, '_id' | 'giveawayId' | '_collectorType'>, alreadyWinner: boolean, actor: string, reason: string): {
     previous: Winner;
     replacement: Omit<Winner, '_id'>;
 };

package/dist/giveaways/domain.js

@@ -17,6 +17,8 @@ const node_util_1 = require("node:util");
 const schemas_1 = require("./schemas");
 const http_error_1 = require("../http-error");
 Object.defineProperty(exports, "DomainError", { enumerable: true, get: function () { return http_error_1.HttpError; } });
+const eligibility_1 = require("./eligibility");
+const user_1 = require("../enums/user");
 function effectiveStatus(g, clock = new Date()) {
     if (g.status === giveaway_2.GiveawayStatus.Scheduled) {
         if (new Date(g.closesAt) <= clock)
@@ -37,6 +39,8 @@ function launchJob(g, now = new Date().toISOString()) {
         kind: giveaway_2.GiveawayNotificationKind.Launch,
         eventKey: giveaway_2.GiveawayNotificationKind.Launch,
         audience: giveaway_2.GiveawayNotificationAudience.All,
+        category: g.category,
+        expiresAt: g.closesAt,
         title: g.launch.title,
         message: g.launch.message,
         status: giveaway_2.GiveawayNotificationStatus.Pending,
@@ -179,13 +183,18 @@ function submitEntry(g, account, raw) {
         new Date(g.startsAt) > now ||
         new Date(g.closesAt) <= now)
         throw new http_error_1.HttpError('This giveaway is not accepting entries', 409);
+    if (!(0, eligibility_1.isGiveawayMemberEligible)(g.category, account._collectorType))
+        throw new http_error_1.HttpError('Your membership is not eligible for this giveaway', 403);
     const at = now.toISOString();
     return {
         giveawayId: g._id,
         userId: account.userId,
         name: [account.firstName?.trim(), account.lastName?.trim()].filter(Boolean).join(' '),
         email: account.email,
-        _collectorType: account._collectorType,
+        _collectorType: typeof account._collectorType === 'number' &&
+            Object.values(user_1.UserCollectorType).includes(account._collectorType)
+            ? account._collectorType
+            : null,
         enteredAt: at,
         rulesAcceptedAt: at,
         rulesSnapshot: g.rules,
@@ -211,6 +220,8 @@ function confirmWinners(g, entries, alreadyConfirmed, actor, raw) {
         const prize = g.prizes.find(prize => prize._id === assignment.prizeId);
         if (!entry || entry.giveawayId !== g._id || !prize)
             throw new http_error_1.HttpError('Invalid entrant or prize');
+        if (!(0, eligibility_1.isGiveawayMemberEligible)(g.category, entry._collectorType))
+            throw new http_error_1.HttpError('This entry is not eligible for the giveaway prize', 403);
         if (accounts.has(entry.userId))
             throw new http_error_1.HttpError('Each account can win only one prize');
         accounts.add(entry.userId);
@@ -241,6 +252,8 @@ function replaceWinner(g, old, entry, alreadyWinner, actor, reason) {
         throw new http_error_1.HttpError('Winner replacements require a closed giveaway');
     if (old.giveawayId !== g._id || old.replacedAt || entry.giveawayId !== g._id)
         throw new http_error_1.HttpError('Winner or entrant not found', 404);
+    if (!(0, eligibility_1.isGiveawayMemberEligible)(g.category, entry._collectorType))
+        throw new http_error_1.HttpError('This entry is not eligible for the giveaway prize', 403);
     if (reason.trim().length < 5)
         throw new http_error_1.HttpError('Provide a replacement reason (at least 5 characters)');
     if (old.status !== giveaway_2.GiveawayWinnerStatus.AwaitingClaim || old.claimedAt)

package/dist/giveaways/eligibility.d.ts

@@ -0,0 +1,5 @@
+import { GiveawayCategory } from '../enums/giveaway';
+import { UserCollectorType } from '../enums/user';
+/** Null means entry and winner eligibility has no collector-tier restriction. */
+export declare function giveawayEligibleCollectorTypes(category: GiveawayCategory): readonly UserCollectorType[] | null;
+export declare function isGiveawayMemberEligible(category: GiveawayCategory, collectorType: unknown): boolean;

package/dist/giveaways/eligibility.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.giveawayEligibleCollectorTypes = giveawayEligibleCollectorTypes;
+exports.isGiveawayMemberEligible = isGiveawayMemberEligible;
+const giveaway_1 = require("../enums/giveaway");
+const user_1 = require("../enums/user");
+const creditMembers = Object.freeze([
+    user_1.UserCollectorType.Rookie,
+    user_1.UserCollectorType.Collector,
+    user_1.UserCollectorType.Elite
+]);
+const noMembers = Object.freeze([]);
+/** Null means entry and winner eligibility has no collector-tier restriction. */
+function giveawayEligibleCollectorTypes(category) {
+    if (category === giveaway_1.GiveawayCategory.Products)
+        return null;
+    if (category === giveaway_1.GiveawayCategory.Credits)
+        return creditMembers;
+    return noMembers;
+}
+function isGiveawayMemberEligible(category, collectorType) {
+    const tiers = giveawayEligibleCollectorTypes(category);
+    return tiers === null || (typeof collectorType === 'number' && tiers.includes(collectorType));
+}

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

@@ -2,7 +2,12 @@ import { GiveawayAction, GiveawayCategory, GiveawaySelectionMethod, GiveawayStat
 import { UserCollectorType } from '../enums/user';
 import type { ClientSession, Db, MongoClient } from 'mongodb';
 import type { GiveawayPreset, GiveawayTicket, GiveawayClaim, PaginatedApiResponse } from '../types';
+import type { GiveawayCreditEligibilityEvidence } from '../types/revenuecat';
 import type { UserProfile, AuditEvent, DashboardData, Entry, EntryRecord, Giveaway, GiveawayDetailData, GiveawaySummary, NotificationJob, NotificationRecord, OverviewData, PageResult, Winner, WinnerRecord } from './types';
+export type GiveawayRepositoryOptions = {
+    checkCreditEligibility?: (userId: string) => Promise<GiveawayCreditEligibilityEvidence | null>;
+    creditWinnerMaxAttempts?: number;
+};
 type Stored<T extends {
     _id: string;
 }> = Omit<T, '_id'>;
@@ -15,13 +20,18 @@ export declare function pagination(params: URLSearchParams): {
 export declare class GiveawayRepository {
     private readonly db;
     private readonly client;
-    constructor(db: Db, client: MongoClient);
+    private readonly options;
+    constructor(db: Db, client: MongoClient, options?: GiveawayRepositoryOptions);
     private get giveaways();
     private get entries();
     private get winners();
     private get notifications();
     private get marketing();
     private get activity();
+    private checkCreditCandidate;
+    private assertFreshCreditEvidence;
+    private assertVerifiedCreditCandidate;
+    private verifiedCreditSelection;
     private transaction;
     private audit;
     getGiveaway(id: string, session?: ClientSession): Promise<Giveaway>;
@@ -107,11 +117,11 @@ export declare class GiveawayRepository {
     confirmWinners(actor: string, id: string, raw: unknown): Promise<{
         _id: string;
         giveawayId: import("../types").GiveawayObjectId;
+        category: GiveawayCategory;
         status: GiveawayWinnerStatus;
         claimedAt?: string | undefined;
         userId?: string | undefined;
         creditAmount?: number | undefined;
-        category: GiveawayCategory;
         selection?: import("../types").GiveawaySelection | undefined;
         entryId: import("../types").GiveawayEntryId;
         claimDeadline?: string | undefined;
@@ -123,6 +133,7 @@ export declare class GiveawayRepository {
         prizeId: import("../types").GiveawayObjectId;
         confirmedBy: string;
         confirmedAt: string;
+        creditEligibility?: GiveawayCreditEligibilityEvidence | undefined;
         rewardError?: string | undefined;
         replacedAt?: string | null | undefined;
         replacementReason?: string | undefined;
@@ -131,11 +142,11 @@ export declare class GiveawayRepository {
     replaceWinner(actor: string, id: string, winnerId: string, replacementEntryId: string, reason: string): Promise<{
         _id: string;
         giveawayId: import("../types").GiveawayObjectId;
+        category: GiveawayCategory;
         status: GiveawayWinnerStatus;
         claimedAt?: string | undefined;
         userId?: string | undefined;
         creditAmount?: number | undefined;
-        category: GiveawayCategory;
         selection?: import("../types").GiveawaySelection | undefined;
         entryId: import("../types").GiveawayEntryId;
         claimDeadline?: string | undefined;
@@ -147,6 +158,7 @@ export declare class GiveawayRepository {
         prizeId: import("../types").GiveawayObjectId;
         confirmedBy: string;
         confirmedAt: string;
+        creditEligibility?: GiveawayCreditEligibilityEvidence | undefined;
         rewardError?: string | undefined;
         replacedAt?: string | null | undefined;
         replacementReason?: string | undefined;
@@ -157,10 +169,10 @@ export declare class GiveawayRepository {
         courier: string;
         tracking: string;
         giveawayId: import("../types").GiveawayObjectId;
+        category: GiveawayCategory;
         claimedAt?: string | undefined;
         userId?: string | undefined;
         creditAmount?: number | undefined;
-        category: GiveawayCategory;
         selection?: import("../types").GiveawaySelection | undefined;
         entryId: import("../types").GiveawayEntryId;
         claimDeadline?: string | undefined;
@@ -170,6 +182,7 @@ export declare class GiveawayRepository {
         prizeId: import("../types").GiveawayObjectId;
         confirmedBy: string;
         confirmedAt: string;
+        creditEligibility?: GiveawayCreditEligibilityEvidence | undefined;
         rewardError?: string | undefined;
         replacedAt?: string | null | undefined;
         replacementReason?: string | undefined;
@@ -180,6 +193,7 @@ export declare class GiveawayRepository {
     selectWinner(actor: string, id: string, raw: unknown): Promise<{
         giveaway: {
             selection: {
+                creditEligibility?: GiveawayCreditEligibilityEvidence | undefined;
                 entryId: string;
                 method: GiveawaySelectionMethod;
                 reason: string;
@@ -243,9 +257,9 @@ export declare class GiveawayRepository {
         userId: string;
         creditAmount: number;
         giveawayId: import("../types").GiveawayObjectId;
+        category: GiveawayCategory;
         status: GiveawayWinnerStatus;
         claimedAt?: string | undefined;
-        category: GiveawayCategory;
         selection?: import("../types").GiveawaySelection | undefined;
         entryId: import("../types").GiveawayEntryId;
         claimDeadline?: string | undefined;
@@ -257,6 +271,7 @@ export declare class GiveawayRepository {
         prizeId: import("../types").GiveawayObjectId;
         confirmedBy: string;
         confirmedAt: string;
+        creditEligibility?: GiveawayCreditEligibilityEvidence | undefined;
         rewardError?: string | undefined;
         replacedAt?: string | null | undefined;
         replacementReason?: string | undefined;

package/dist/giveaways/giveaway-repository.js

@@ -9,6 +9,7 @@ const node_crypto_1 = require("node:crypto");
 const mongodb_1 = require("mongodb");
 const entry_id_1 = require("./entry-id");
 const api_pagination_1 = require("./api-pagination");
+const eligibility_1 = require("./eligibility");
 const domain_1 = require("./domain");
 const schemas_1 = require("./schemas");
 const projection = { entryVersion: 0 };
@@ -129,9 +130,10 @@ function filterCategory(filter, params) {
 }
 /** Each method reads only its own records. Transactions contain related writes only. */
 class GiveawayRepository {
-    constructor(db, client) {
+    constructor(db, client, options = {}) {
         this.db = db;
         this.client = client;
+        this.options = options;
     }
     get giveaways() {
         return this.db.collection('giveaways');
@@ -151,6 +153,111 @@ class GiveawayRepository {
     get activity() {
         return this.db.collection('audit');
     }
+    async checkCreditCandidate(entry) {
+        const check = this.options.checkCreditEligibility;
+        if (!check)
+            throw new domain_1.DomainError('RevenueCat entitlement verification is not configured', 503);
+        if (typeof entry.userId !== 'string' ||
+            !entry.userId ||
+            entry.userId.length > 128 ||
+            /[.#$[\]/]/.test(entry.userId))
+            throw new domain_1.DomainError('The entrant has no valid DGC account identity', 503);
+        let evidence;
+        try {
+            evidence = await check(entry.userId);
+        }
+        catch {
+            throw new domain_1.DomainError('Unable to verify active membership. Try again.', 503);
+        }
+        if (evidence === null)
+            return null;
+        if (!evidence ||
+            evidence.userId !== entry.userId ||
+            typeof evidence.entitlementId !== 'string' ||
+            !evidence.entitlementId.trim() ||
+            evidence.entitlementId.length > 255 ||
+            !(0, eligibility_1.isGiveawayMemberEligible)(giveaway_2.GiveawayCategory.Credits, evidence.collectorType) ||
+            typeof evidence.checkedAt !== 'string' ||
+            !Number.isFinite(Date.parse(evidence.checkedAt)) ||
+            Date.parse(evidence.checkedAt) > Date.now() + 5000 ||
+            (evidence.expiresAt !== null &&
+                (typeof evidence.expiresAt !== 'number' || !Number.isFinite(evidence.expiresAt))))
+            throw new domain_1.DomainError('Unable to verify active membership. Try again.', 503);
+        this.assertFreshCreditEvidence(evidence);
+        return {
+            userId: evidence.userId,
+            checkedAt: evidence.checkedAt,
+            entitlementId: evidence.entitlementId,
+            collectorType: evidence.collectorType,
+            expiresAt: evidence.expiresAt
+        };
+    }
+    assertFreshCreditEvidence(evidence) {
+        if (Date.now() - Date.parse(evidence.checkedAt) > 60000 ||
+            (evidence.expiresAt !== null && evidence.expiresAt <= Date.now()))
+            throw new domain_1.DomainError('Entitlement verification expired. Review and try again.', 409);
+    }
+    assertVerifiedCreditCandidate(g, reviewed, entry, verified) {
+        if (g.category !== reviewed.category || g.revision !== reviewed.revision)
+            throw new domain_1.DomainError('Giveaway changed. Review the selection again.', 409);
+        if (g.category !== giveaway_2.GiveawayCategory.Credits)
+            return;
+        if (!verified || verified.entryId !== entry._id || verified.evidence.userId !== entry.userId)
+            throw new domain_1.DomainError('Active membership must be verified before awarding credits', 503);
+        this.assertFreshCreditEvidence(verified.evidence);
+    }
+    async verifiedCreditSelection(g, input) {
+        if ((0, domain_1.effectiveStatus)(g) !== giveaway_2.GiveawayStatus.Closed)
+            throw new domain_1.DomainError('Close entries before selecting a winner', 409);
+        if (g.revision !== input.revision)
+            throw new domain_1.DomainError('Giveaway changed. Refresh before selecting.', 409);
+        if (g.selection ||
+            (await this.winners.findOne({ giveawayId: g._id, replacedAt: null }, { projection: { _id: 1 } })))
+            throw new domain_1.DomainError('A winner is already selected. Explicitly reset the selection to change it.', 409);
+        const maxAttempts = this.options.creditWinnerMaxAttempts ?? 5;
+        if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 100)
+            throw new domain_1.DomainError('Credit winner attempts must be an integer between 1 and 100', 503);
+        const tiers = (0, eligibility_1.giveawayEligibleCollectorTypes)(giveaway_2.GiveawayCategory.Credits);
+        const rejected = [];
+        const deadline = Date.now() + 30000;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (Date.now() >= deadline)
+                throw new domain_1.DomainError('Membership verification is taking too long. Try the draw again.', 503);
+            const eligible = {
+                giveawayId: g._id,
+                _collectorType: { $in: [...tiers] },
+                ...(rejected.length > 0 && { _id: { $nin: rejected } })
+            };
+            const count = await this.entries.countDocuments(eligible, {});
+            if (!count)
+                throw new domain_1.DomainError('This giveaway has no entries with an active eligible entitlement', 409);
+            const entry = input.method === giveaway_2.GiveawaySelectionMethod.Manual
+                ? await this.entries.findOne({ ...eligible, _id: input.entryId }, {})
+                : await this.entries
+                    .find(eligible, {
+                    projection: { _id: 1, userId: 1, giveawayId: 1, _collectorType: 1 }
+                })
+                    .sort({ _id: 1 })
+                    .skip((0, node_crypto_1.randomInt)(count))
+                    .limit(1)
+                    .next();
+            if (!entry)
+                throw new domain_1.DomainError('Select a valid entry in this giveaway', 422);
+            if (!(0, eligibility_1.isGiveawayMemberEligible)(g.category, entry._collectorType))
+                throw new domain_1.DomainError('This entry is not eligible for the giveaway prize', 403);
+            const evidence = await this.checkCreditCandidate(entry);
+            if (Date.now() >= deadline)
+                throw new domain_1.DomainError('Membership verification is taking too long. Try the draw again.', 503);
+            if (evidence)
+                return { entryId: entry._id, evidence, skipped: rejected.length };
+            if (input.method === giveaway_2.GiveawaySelectionMethod.Manual)
+                throw new domain_1.DomainError('This entrant has no active Rookie, Collector or Elite entitlement', 422);
+            rejected.push(entry._id);
+            if (count === 1)
+                throw new domain_1.DomainError('This giveaway has no entries with an active eligible entitlement', 409);
+        }
+        throw new domain_1.DomainError(`No verified winner found after checking ${maxAttempts} candidate${maxAttempts === 1 ? '' : 's'}. Try the draw again.`, 503);
+    }
     async transaction(operation) {
         const session = this.client.startSession();
         try {
@@ -579,6 +686,49 @@ class GiveawayRepository {
                 { $sort: { _id: -1 } },
                 { $skip: skip },
                 { $limit: limit },
+                {
+                    $lookup: {
+                        from: 'notification_deliveries',
+                        let: { notification: { $toString: '$_id' } },
+                        pipeline: [
+                            { $match: { $expr: { $eq: ['$notificationId', '$$notification'] } } },
+                            {
+                                $group: {
+                                    _id: null,
+                                    queued: {
+                                        $sum: {
+                                            $cond: [
+                                                { $eq: ['$status', giveaway_2.GiveawayNotificationDeliveryStatus.Queued] },
+                                                1,
+                                                0
+                                            ]
+                                        }
+                                    },
+                                    skipped: {
+                                        $sum: {
+                                            $cond: [
+                                                { $eq: ['$status', giveaway_2.GiveawayNotificationDeliveryStatus.Skipped] },
+                                                1,
+                                                0
+                                            ]
+                                        }
+                                    },
+                                    pending: {
+                                        $sum: {
+                                            $cond: [
+                                                { $eq: ['$status', giveaway_2.GiveawayNotificationDeliveryStatus.Pending] },
+                                                1,
+                                                0
+                                            ]
+                                        }
+                                    }
+                                }
+                            },
+                            { $project: { _id: 0, queued: 1, skipped: 1, pending: 1 } }
+                        ],
+                        as: 'deliveryTotals'
+                    }
+                },
                 {
                     $lookup: {
                         from: 'giveaways',
@@ -594,10 +744,13 @@ class GiveawayRepository {
                     $set: {
                         giveawayTitle: {
                             $ifNull: [{ $first: '$campaign.title' }, '$giveawayId']
+                        },
+                        deliveryCounts: {
+                            $ifNull: [{ $first: '$deliveryTotals' }, { queued: 0, skipped: 0, pending: 0 }]
                         }
                     }
                 },
-                { $unset: ['campaign', 'claimToken'] },
+                { $unset: ['campaign', 'claimToken', 'deliveryTotals'] },
                 stringId
             ])
                 .toArray(),
@@ -741,6 +894,20 @@ class GiveawayRepository {
     }
     async confirmWinners(actor, id, raw) {
         const input = schemas_1.assignmentsSchema.parse(raw);
+        const reviewed = await this.getGiveaway(id);
+        let verified;
+        if (reviewed.category === giveaway_2.GiveawayCategory.Credits) {
+            const rows = await this.entries
+                .find({ giveawayId: id, _id: { $in: input.assignments.map(a => a.entryId) } }, { projection: { _id: 1, userId: 1, giveawayId: 1, _collectorType: 1 } })
+                .limit(1)
+                .toArray();
+            const existing = await this.winners.findOne({ giveawayId: id, replacedAt: null }, { projection: { _id: 1 } });
+            (0, domain_1.confirmWinners)(reviewed, rows, !!existing, actor, input);
+            const evidence = await this.checkCreditCandidate(rows[0]);
+            if (!evidence)
+                throw new domain_1.DomainError('This entrant has no active Rookie, Collector or Elite entitlement', 422);
+            verified = { entryId: rows[0]._id, evidence, skipped: 0 };
+        }
         return this.transaction(async (session) => {
             const g = await this.getGiveaway(id, session);
             const rows = await this.entries
@@ -749,17 +916,25 @@ class GiveawayRepository {
                 _id: { $in: input.assignments.map(a => a.entryId) }
             }, {
                 session,
-                projection: { _id: 1, userId: 1, giveawayId: 1 }
+                projection: { _id: 1, userId: 1, giveawayId: 1, _collectorType: 1 }
             })
                 .limit(1000)
                 .toArray();
             const entries = rows;
             const existing = await this.winners.findOne({ giveawayId: id, replacedAt: null }, { session, projection: { _id: 1 } });
             const winners = (0, domain_1.confirmWinners)(g, entries, !!existing, actor, input);
+            this.assertVerifiedCreditCandidate(g, reviewed, entries[0], verified);
+            if (verified)
+                winners[0].creditEligibility = verified.evidence;
             await this.updateGiveaway({ ...g, status: giveaway_2.GiveawayStatus.AwaitingClaim, revision: g.revision + 1 }, g.revision, session);
             const result = await this.winners.insertMany(winners.map(winner => ({ ...winner })), { session });
-            await this.enqueueEvent(g, giveaway_2.GiveawayNotificationKind.Results, 'results:' + result.insertedIds[0].toHexString(), session);
-            await this.audit(actor, 'Winners confirmed', id, winners.length + ' prize assignments', session);
+            await this.enqueueEvent(g, giveaway_2.GiveawayNotificationKind.Results, 'results:' + result.insertedIds[0].toHexString(), session, winners[0].claimDeadline);
+            await this.audit(actor, 'Winners confirmed', id, verified
+                ? JSON.stringify({
+                    prizeAssignments: winners.length,
+                    creditEligibility: verified.evidence
+                })
+                : winners.length + ' prize assignments', session);
             return winners.map((winner, index) => ({
                 ...winner,
                 _id: result.insertedIds[index].toHexString()
@@ -767,22 +942,52 @@ class GiveawayRepository {
         });
     }
     async replaceWinner(actor, id, winnerId, replacementEntryId, reason) {
+        const reviewed = await this.getGiveaway(id);
+        let verified;
+        if (reviewed.category === giveaway_2.GiveawayCategory.Credits) {
+            const previous = await this.winners.findOne({
+                _id: objectId(winnerId),
+                giveawayId: id,
+                replacedAt: null
+            });
+            const entry = await this.entries.findOne({ _id: schemas_1.entryIdSchema.parse(replacementEntryId), giveawayId: id }, { projection: { _id: 1, userId: 1, giveawayId: 1, _collectorType: 1 } });
+            if (!previous || !entry)
+                throw new domain_1.DomainError('Winner or entrant not found', 404);
+            const existing = await this.winners.findOne({ giveawayId: id, entryId: replacementEntryId, replacedAt: null }, { projection: { _id: 1 } });
+            (0, domain_1.replaceWinner)(reviewed, serialize(previous), entry, !!existing, actor, reason);
+            const evidence = await this.checkCreditCandidate(entry);
+            if (!evidence)
+                throw new domain_1.DomainError('This entrant has no active Rookie, Collector or Elite entitlement', 422);
+            verified = { entryId: entry._id, evidence, skipped: 0 };
+        }
         return this.transaction(async (session) => {
             const g = await this.getGiveaway(id, session);
             const previousWinner = await this.winners.findOne({ _id: objectId(winnerId), giveawayId: id, replacedAt: null }, { session });
-            const entrant = await this.entries.findOne({ _id: schemas_1.entryIdSchema.parse(replacementEntryId), giveawayId: id }, { session, projection: { _id: 1, giveawayId: 1 } });
+            const entrant = await this.entries.findOne({ _id: schemas_1.entryIdSchema.parse(replacementEntryId), giveawayId: id }, { session, projection: { _id: 1, userId: 1, giveawayId: 1, _collectorType: 1 } });
             if (!previousWinner || !entrant)
                 throw new domain_1.DomainError('Winner or entrant not found', 404);
             const old = serialize(previousWinner);
             const entry = entrant;
             const existing = await this.winners.findOne({ giveawayId: id, entryId: replacementEntryId, replacedAt: null }, { session, projection: { _id: 1 } });
             const { previous, replacement } = (0, domain_1.replaceWinner)(g, old, entry, !!existing, actor, reason);
+            this.assertVerifiedCreditCandidate(g, reviewed, entry, verified);
+            replacement.userId = entry.userId;
+            if (verified) {
+                replacement.creditEligibility = verified.evidence;
+                replacement.selection.creditEligibility = verified.evidence;
+            }
             await this.updateGiveaway({ ...g, status: giveaway_2.GiveawayStatus.AwaitingClaim, revision: g.revision + 1 }, g.revision, session);
             const { _id, ...previousFields } = previous;
             await this.winners.updateOne({ _id: objectId(_id), replacedAt: null }, { $set: previousFields }, { session });
             const result = await this.winners.insertOne({ ...replacement }, { session });
-            await this.enqueueEvent(g, giveaway_2.GiveawayNotificationKind.Results, 'results:' + result.insertedId.toHexString(), session);
-            await this.audit(actor, 'Winner replaced', id, old._id + ': ' + reason.trim(), session);
+            await this.enqueueEvent(g, giveaway_2.GiveawayNotificationKind.Results, 'results:' + result.insertedId.toHexString(), session, replacement.claimDeadline);
+            await this.audit(actor, 'Winner replaced', id, verified
+                ? JSON.stringify({
+                    previousWinnerId: old._id,
+                    reason: reason.trim(),
+                    creditEligibility: verified.evidence
+                })
+                : old._id + ': ' + reason.trim(), session);
             return { ...replacement, _id: result.insertedId.toHexString() };
         });
     }
@@ -818,7 +1023,7 @@ class GiveawayRepository {
             return winner;
         });
     }
-    async enqueueEvent(g, kind, eventKey, session) {
+    async enqueueEvent(g, kind, eventKey, session, expiresAt) {
         const copy = g.reminders?.[kind];
         if (!copy?.enabled)
             return;
@@ -828,6 +1033,11 @@ class GiveawayRepository {
                 eventKey,
                 kind,
                 audience: giveaway_2.GiveawayNotificationAudience.Entrants,
+                category: g.category,
+                expiresAt: kind === giveaway_2.GiveawayNotificationKind.Closing
+                    ? g.closesAt
+                    : expiresAt ||
+                        new Date(Date.now() + (g.claimWindowDays || 14) * 86400000).toISOString(),
                 title: copy.title,
                 message: copy.message,
                 status: giveaway_2.GiveawayNotificationStatus.Pending,
@@ -837,6 +1047,10 @@ class GiveawayRepository {
     }
     async selectWinner(actor, id, raw) {
         const input = schemas_1.selectionSchema.parse(raw);
+        const reviewed = await this.getGiveaway(id);
+        const verified = reviewed.category === giveaway_2.GiveawayCategory.Credits
+            ? await this.verifiedCreditSelection(reviewed, input)
+            : undefined;
         return this.transaction(async (session) => {
             const g = await this.getGiveaway(id, session);
             if ((0, domain_1.effectiveStatus)(g) !== giveaway_2.GiveawayStatus.Closed)
@@ -846,29 +1060,47 @@ class GiveawayRepository {
             if (g.selection ||
                 (await this.winners.findOne({ giveawayId: id, replacedAt: null }, { session })))
                 throw new domain_1.DomainError('A winner is already selected. Explicitly reset the selection to change it.', 409);
-            const count = await this.entries.countDocuments({ giveawayId: id }, { session });
+            const collectorTypes = (0, eligibility_1.giveawayEligibleCollectorTypes)(g.category);
+            const eligible = {
+                giveawayId: id,
+                ...(collectorTypes !== null && { _collectorType: { $in: [...collectorTypes] } })
+            };
+            const count = verified ? 1 : await this.entries.countDocuments(eligible, { session });
             if (!count)
                 throw new domain_1.DomainError('This giveaway has no eligible entries', 409);
-            const entry = input.method === giveaway_2.GiveawaySelectionMethod.Manual
-                ? await this.entries.findOne({ giveawayId: id, _id: input.entryId }, { session })
+            const candidateId = verified?.entryId ||
+                (input.method === giveaway_2.GiveawaySelectionMethod.Manual ? input.entryId : undefined);
+            const entry = candidateId
+                ? await this.entries.findOne({ ...eligible, _id: candidateId }, { session })
                 : await this.entries
-                    .find({ giveawayId: id }, { session })
+                    .find(eligible, { session })
                     .sort({ _id: 1 })
                     .skip((0, node_crypto_1.randomInt)(count))
                     .limit(1)
                     .next();
             if (!entry)
                 throw new domain_1.DomainError('Select a valid entry in this giveaway', 422);
+            if (!(0, eligibility_1.isGiveawayMemberEligible)(g.category, entry._collectorType))
+                throw new domain_1.DomainError('This entry is not eligible for the giveaway prize', 403);
+            this.assertVerifiedCreditCandidate(g, reviewed, entry, verified);
             const selection = {
                 entryId: entry._id,
                 method: input.method,
                 reason: input.method === giveaway_2.GiveawaySelectionMethod.Manual ? input.reason : '',
                 selectedBy: actor,
-                selectedAt: new Date().toISOString()
+                selectedAt: new Date().toISOString(),
+                ...(verified && { creditEligibility: verified.evidence })
             };
             const updated = { ...g, selection, revision: g.revision + 1 };
             await this.updateGiveaway(updated, g.revision, session);
-            await this.audit(actor, 'Winner selected: ' + input.method, id, entry._id + (selection.reason ? ': ' + selection.reason : ''), session);
+            await this.audit(actor, 'Winner selected: ' + input.method, id, verified
+                ? JSON.stringify({
+                    entryId: entry._id,
+                    reason: selection.reason,
+                    creditEligibility: verified.evidence,
+                    skippedIneligibleEntries: verified.skipped
+                })
+                : entry._id + (selection.reason ? ': ' + selection.reason : ''), session);
             return { giveaway: updated, entry: normalizeEntry(entry) };
         });
     }
@@ -930,7 +1162,7 @@ class GiveawayRepository {
                     category: giveaway_2.GiveawayCategory.Credits,
                     creditAmount: amount,
                     countries: [],
-                    rules: 'One ticket per DGC account. All members have equal chances. One winner. The winner must claim within the stated claim window.',
+                    rules: 'One ticket per eligible DGC account. Eligible members have equal chances. One winner. The winner must claim within the stated claim window.',
                     deliveryInformation: '',
                     revision: 1,
                     createdAt: now,
@@ -1263,7 +1495,11 @@ class GiveawayRepository {
             const now = new Date().toISOString();
             const updated = await this.notifications.updateOne(filter, successful
                 ? {
-                    $set: { status: giveaway_2.GiveawayNotificationStatus.Sent, sentAt: now },
+                    $set: {
+                        status: giveaway_2.GiveawayNotificationStatus.Sent,
+                        sentAt: now,
+                        dispatchCompletedAt: now
+                    },
                     $unset: { error: '', claimToken: '' }
                 }
                 : {

package/dist/giveaways/index.d.ts

@@ -2,6 +2,7 @@
 export * from './domain';
 export * from './api-pagination';
 export * from './entry-id';
+export * from './eligibility';
 export * from './giveaway-repository';
 export * from './schemas';
 export * from './credit-award';

package/dist/giveaways/index.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./domain"), exports);
 __exportStar(require("./api-pagination"), exports);
 __exportStar(require("./entry-id"), exports);
+__exportStar(require("./eligibility"), exports);
 __exportStar(require("./giveaway-repository"), exports);
 __exportStar(require("./schemas"), exports);
 __exportStar(require("./credit-award"), exports);

package/dist/index.d.ts

@@ -20,3 +20,5 @@ export * from './validator';
 export * from './id';
 export * from './http-error';
 export * from './giveaways';
+export * from './constants/revenuecat';
+export * from './revenuecat';

package/dist/index.js

@@ -36,3 +36,5 @@ __exportStar(require("./validator"), exports);
 __exportStar(require("./id"), exports);
 __exportStar(require("./http-error"), exports);
 __exportStar(require("./giveaways"), exports);
+__exportStar(require("./constants/revenuecat"), exports);
+__exportStar(require("./revenuecat"), exports);

package/dist/revenuecat.d.ts

@@ -0,0 +1,16 @@
+import { HttpError } from './http-error';
+import type { GiveawayCreditEligibilityEvidence, RevenueCatClient, RevenueCatEntitlementIds } from './types/revenuecat';
+export type RevenueCatClientOptions = {
+    apiKey: string;
+    projectId: string;
+    timeoutMs?: number;
+    totalTimeoutMs?: number;
+    maxPages?: number;
+};
+/** Deliberately excludes the original HTTP error, which can contain the API key. */
+export declare class RevenueCatLookupError extends HttpError {
+    constructor();
+}
+export declare function createRevenueCatClient(options: RevenueCatClientOptions): RevenueCatClient;
+/** Resolve any eligible entitlement from one customer lookup; never infer Free from API failures. */
+export declare function verifyCreditGiveawayEntitlement(userId: string, client: RevenueCatClient, entitlementIds: RevenueCatEntitlementIds): Promise<GiveawayCreditEligibilityEvidence | null>;

package/dist/revenuecat.js

@@ -0,0 +1,206 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RevenueCatLookupError = void 0;
+exports.createRevenueCatClient = createRevenueCatClient;
+exports.verifyCreditGiveawayEntitlement = verifyCreditGiveawayEntitlement;
+const axios_1 = __importDefault(require("axios"));
+const revenuecat_1 = require("./constants/revenuecat");
+const user_1 = require("./enums/user");
+const http_error_1 = require("./http-error");
+/** Deliberately excludes the original HTTP error, which can contain the API key. */
+class RevenueCatLookupError extends http_error_1.HttpError {
+    constructor() {
+        super('Unable to verify RevenueCat entitlement access. Please try again.', 503);
+        this.name = 'RevenueCatLookupError';
+    }
+}
+exports.RevenueCatLookupError = RevenueCatLookupError;
+function positiveInteger(value, maximum) {
+    return Number.isInteger(value) && value > 0 && value <= maximum;
+}
+function validUserId(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        value.trim() === value &&
+        !/[.#$[\]/]/.test(value) &&
+        !Array.from(value).some(character => {
+            const code = character.charCodeAt(0);
+            return code < 32 || code === 127;
+        }));
+}
+function parsePage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new RevenueCatLookupError();
+    const page = value;
+    if (!Array.isArray(page.items) ||
+        (page.next_page != null && (typeof page.next_page !== 'string' || !page.next_page)))
+        throw new RevenueCatLookupError();
+    const items = page.items.map((raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new RevenueCatLookupError();
+        const entitlement = raw;
+        if (typeof entitlement.entitlement_id !== 'string' ||
+            !/^entl[a-zA-Z0-9]+$/.test(entitlement.entitlement_id) ||
+            (entitlement.expires_at !== null &&
+                (typeof entitlement.expires_at !== 'number' ||
+                    !Number.isSafeInteger(entitlement.expires_at) ||
+                    entitlement.expires_at < 0)))
+            throw new RevenueCatLookupError();
+        return {
+            entitlementId: entitlement.entitlement_id,
+            expiresAt: entitlement.expires_at
+        };
+    });
+    return { items, nextPage: page.next_page ?? null };
+}
+function retryAfterMs(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) && value >= 0 ? value * 1000 : null;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const text = value.trim();
+    if (/^\d+$/.test(text)) {
+        const seconds = Number(text);
+        return Number.isFinite(seconds) ? seconds * 1000 : null;
+    }
+    const date = Date.parse(text);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null;
+}
+/** Inspect only retry metadata; never retain or log the original transport error. */
+function requestRetryDelay(error, attempt) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const failure = error;
+    const response = failure.response && typeof failure.response === 'object'
+        ? failure.response
+        : undefined;
+    if (response) {
+        if (typeof response.status !== 'number' || ![429, 500, 502, 503, 504].includes(response.status))
+            return null;
+    }
+    else if (typeof failure.code !== 'string' ||
+        ![
+            'ECONNRESET',
+            'ETIMEDOUT',
+            'ECONNABORTED',
+            'EAI_AGAIN',
+            'ENOTFOUND',
+            'ERR_NETWORK',
+            'EPIPE',
+            'ECONNREFUSED'
+        ].includes(failure.code))
+        return null;
+    let headerDelay = null;
+    if (response?.headers && typeof response.headers === 'object') {
+        const headers = response.headers;
+        headerDelay = retryAfterMs(typeof headers.get === 'function'
+            ? headers.get('retry-after')
+            : (headers['retry-after'] ?? headers['Retry-After']));
+    }
+    const body = response?.data && typeof response.data === 'object'
+        ? response.data
+        : undefined;
+    const bodyDelay = typeof body?.backoff_ms === 'number' && Number.isFinite(body.backoff_ms) && body.backoff_ms >= 0
+        ? body.backoff_ms
+        : 0;
+    return Math.max(100 * 2 ** attempt, headerDelay ?? 0, bodyDelay);
+}
+async function requestPage(url, apiKey, timeoutMs, deadline) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            throw new RevenueCatLookupError();
+        try {
+            return await axios_1.default.get(url.href, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+                timeout: Math.min(timeoutMs, remainingMs),
+                signal: AbortSignal.timeout(remainingMs),
+                maxRedirects: 0,
+                maxContentLength: 1024 * 1024
+            });
+        }
+        catch (error) {
+            const delay = attempt < 2 ? requestRetryDelay(error, attempt) : null;
+            if (delay === null || delay >= deadline - Date.now())
+                throw new RevenueCatLookupError();
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw new RevenueCatLookupError();
+}
+function createRevenueCatClient(options) {
+    const apiKey = options.apiKey?.trim();
+    const projectId = options.projectId?.trim();
+    const timeoutMs = options.timeoutMs ?? 15000;
+    const totalTimeoutMs = options.totalTimeoutMs ?? 15000;
+    const maxPages = options.maxPages ?? 20;
+    if (!apiKey || /[\r\n]/.test(apiKey))
+        throw new Error('Configure the RevenueCat API key');
+    if (!projectId || projectId.length > 255 || !/^[a-zA-Z0-9_-]+$/.test(projectId))
+        throw new Error('Configure a valid RevenueCat project ID');
+    if (!positiveInteger(timeoutMs, 60000) ||
+        !positiveInteger(totalTimeoutMs, 120000) ||
+        !positiveInteger(maxPages, 100))
+        throw new Error('Configure valid RevenueCat request limits');
+    return {
+        async getActiveEntitlements(userId) {
+            if (!validUserId(userId))
+                throw new http_error_1.HttpError('Invalid DGC user ID', 400);
+            const endpoint = new URL(`${revenuecat_1.REVENUECAT_API_V2}/projects/${encodeURIComponent(projectId)}/customers/${encodeURIComponent(userId)}/active_entitlements`);
+            endpoint.searchParams.set('limit', '100');
+            const deadline = Date.now() + totalTimeoutMs;
+            const visited = new Set();
+            const entitlements = [];
+            let url = endpoint;
+            try {
+                while (url) {
+                    const remainingMs = deadline - Date.now();
+                    if (remainingMs <= 0 ||
+                        visited.size >= maxPages ||
+                        url.origin !== endpoint.origin ||
+                        url.pathname !== endpoint.pathname ||
+                        url.username ||
+                        url.password ||
+                        url.hash ||
+                        visited.has(url.href))
+                        throw new RevenueCatLookupError();
+                    visited.add(url.href);
+                    const response = await requestPage(url, apiKey, timeoutMs, deadline);
+                    const page = parsePage(response.data);
+                    entitlements.push(...page.items);
+                    url = page.nextPage ? new URL(page.nextPage, endpoint) : null;
+                }
+                const now = Date.now();
+                if (now >= deadline)
+                    throw new RevenueCatLookupError();
+                return entitlements.filter(item => item.expiresAt === null || item.expiresAt > now);
+            }
+            catch {
+                // Do not attach request/config/cause or log the customer payload.
+                throw new RevenueCatLookupError();
+            }
+        }
+    };
+}
+/** Resolve any eligible entitlement from one customer lookup; never infer Free from API failures. */
+async function verifyCreditGiveawayEntitlement(userId, client, entitlementIds) {
+    const ids = (0, revenuecat_1.createRevenueCatEntitlementIds)(entitlementIds);
+    const active = await client.getActiveEntitlements(userId);
+    const checkedAt = new Date().toISOString();
+    const now = Date.parse(checkedAt);
+    const tiers = [
+        [user_1.UserCollectorType.Elite, ids.elite],
+        [user_1.UserCollectorType.Collector, ids.collector],
+        [user_1.UserCollectorType.Rookie, ids.rookie]
+    ];
+    for (const [collectorType, entitlementId] of tiers) {
+        const match = active.find(item => item.entitlementId === entitlementId && (item.expiresAt === null || item.expiresAt > now));
+        if (match)
+            return { userId, checkedAt, collectorType, ...match };
+    }
+    return null;
+}

package/dist/types/giveaway.d.ts

@@ -1,6 +1,7 @@
 import type { GiveawayStatus, GiveawayCategory, GiveawaySelectionMethod, GiveawayWinnerStatus, GiveawayNotificationKind, GiveawayNotificationAudience, GiveawayNotificationStatus, GiveawayTicketResult, GiveawayAction, GiveawayNotificationChannel } from '../enums/giveaway';
 import type { FbUser } from './user';
 import type { UserCollectorType } from '../enums/user';
+import type { GiveawayCreditEligibilityEvidence } from './revenuecat';
 /** API identities are strings. MongoDB ObjectIds serialize as 24 lowercase hexadecimal characters. */
 export type GiveawayObjectId = string;
 /** New tickets use DGC- followed by twelve uppercase letters or digits. Existing numeric IDs remain readable. */
@@ -16,6 +17,7 @@ export type GiveawaySelection = {
     reason: string;
     selectedBy: string;
     selectedAt: string;
+    creditEligibility?: GiveawayCreditEligibilityEvidence;
 };
 export type GiveawayPrize = {
     _id: GiveawayObjectId;
@@ -78,7 +80,7 @@ export type GiveawayEntry = {
     contactNumber?: string;
     /** Retained only for historical entry records; new entries collect country at claim. */
     country?: string;
-    /** Null only for legacy entries whose exact collector tier was not recorded. */
+    /** Null when the account tier is missing or unsupported; product entries remain eligible. */
     _collectorType: UserCollectorType | null;
     enteredAt: string;
     rulesAcceptedAt: string;
@@ -96,6 +98,7 @@ export type GiveawayWinner = {
     status: GiveawayWinnerStatus;
     userId?: string;
     selection?: GiveawaySelection;
+    creditEligibility?: GiveawayCreditEligibilityEvidence;
     category: GiveawayCategory;
     creditAmount?: number;
     claimDeadline?: string;
@@ -127,6 +130,14 @@ export type GiveawayNotificationJob = {
     /** Stable event key supports replacements without resending a prior event. */
     eventKey?: string;
     audience?: GiveawayNotificationAudience;
+    /** Snapshots keep targeting and expiry stable throughout a broadcast. */
+    category?: GiveawayCategory;
+    expiresAt?: string;
+    dispatchAfter?: string;
+    dispatchGeneration?: number;
+    recipientsQueued?: number;
+    recipientsSkipped?: number;
+    dispatchCompletedAt?: string;
     status: GiveawayNotificationStatus;
     attempts: number;
     error?: string;
@@ -173,6 +184,12 @@ export type GiveawayWinnerRecord = GiveawayWinner & {
 };
 export type GiveawayNotificationRecord = Omit<GiveawayNotificationJob, 'claimToken'> & {
     giveawayTitle: string;
+    /** Queue acceptance counts, not confirmation of device delivery. */
+    deliveryCounts?: {
+        queued: number;
+        skipped: number;
+        pending: number;
+    };
 };
 export type GiveawayOverviewData = {
     days: {
@@ -182,8 +199,9 @@ export type GiveawayOverviewData = {
     liveGiveaways: GiveawaySummary[];
     needsSelection: Giveaway[];
 };
-export type GiveawayUserProfile = Pick<FbUser, 'email' | 'firstName' | 'lastName' | '_collectorType'> & {
+export type GiveawayUserProfile = Pick<FbUser, 'email' | 'firstName' | 'lastName'> & {
     userId: string;
+    _collectorType?: UserCollectorType | null;
 };
 export type GiveawayPhysicalClaim = {
     fullName: string;
@@ -279,6 +297,8 @@ export type GiveawayWinnerPreview = {
 };
 /** Public app response; excludes admin settings, prize values and personal data. */
 export type GiveawayPublic = Pick<Giveaway, '_id' | 'title' | 'description' | 'image' | 'status' | 'startsAt' | 'closesAt' | 'countries' | 'rules' | 'category' | 'creditAmount' | 'deliveryInformation'> & {
+    /** Null permits all authenticated accounts regardless of their stored tier. */
+    eligibleCollectorTypes: UserCollectorType[] | null;
     entryCount: number;
     images: string[];
     prizes: Pick<GiveawayPrize, 'name' | 'quantity'>[];

package/dist/types/index.d.ts

@@ -19,3 +19,5 @@ export * from './user';
 export * from './x-credit';
 export * from './giveaway';
 export * from '../enums/giveaway';
+export * from './revenuecat';
+export * from '../constants/revenuecat';

package/dist/types/index.js

@@ -35,3 +35,5 @@ __exportStar(require("./user"), exports);
 __exportStar(require("./x-credit"), exports);
 __exportStar(require("./giveaway"), exports);
 __exportStar(require("../enums/giveaway"), exports);
+__exportStar(require("./revenuecat"), exports);
+__exportStar(require("../constants/revenuecat"), exports);

package/dist/types/revenuecat.d.ts

@@ -0,0 +1,19 @@
+import type { UserCollectorType } from '../enums/user';
+export type RevenueCatActiveEntitlement = {
+    entitlementId: string;
+    /** RevenueCat uses milliseconds since epoch; null is non-expiring access. */
+    expiresAt: number | null;
+};
+export type RevenueCatEntitlementIds = Readonly<{
+    rookie: string;
+    collector: string;
+    elite: string;
+}>;
+export type RevenueCatClient = {
+    getActiveEntitlements(userId: string): Promise<RevenueCatActiveEntitlement[]>;
+};
+export type GiveawayCreditEligibilityEvidence = RevenueCatActiveEntitlement & {
+    userId: string;
+    checkedAt: string;
+    collectorType: UserCollectorType.Rookie | UserCollectorType.Collector | UserCollectorType.Elite;
+};

package/dist/types/revenuecat.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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