dgc-core 2.0.5 → 2.0.8

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;