Radicade Public Code

docs/GIFT-CONTEXT-DUMP.md

@@ -0,0 +1,160 @@
+# Gift context dump and implementation handoff
+
+Snapshot: 2026-10-08. Source: current local server checkout.
+This is the complete server GiftContext enum, not an independently verified client enum dump.
+Numeric gaps are intentional. Context identifies a gift's source; it does not supply its item or implement its challenge.
+
+## Friendotron
+
+- There is no enum member named Friendotron.
+- POST /econ/api/freegifts/v1/sendmultiple currently returns an empty array and does not grant anything (Server/API/Compatibility/CompatibilityAPI.cs).
+- GET /api/config/v1/freegiftbutton currently returns false (Server/API/Config/ConfigAPI.cs).
+- The placeholder config contains Friendotron_AllowSelfGifting and Friendotron_MaxUsersPerSession (Server/DB/DBConfig.cs). Placeholder entries do not establish the live database configuration.
+- Notification enum FreeGiftButtonItemsAdded = 110 exists in Server/RecNet/Enums/Messages.
+- Local inspection log .tmp-gift.log identifies RecNet.MultiRecipientFreeGiftRequestDTO, DIEKLMGBLKA.RequestPurchaseForFreeGiftButtonDTO and DIEKLMGBLKA.GiftItemDTO. Their names are leads, not a verified request schema.
+- Next implementation work: inspect the target client's request/response/config schemas and context choice; implement recipient validation, eligibility/cooldowns, gift selection, durable grants and retry deduplication; then enable the feature with the expected config payload. Do not assume Purchased_Gift_A is Friendotron's context merely because it is used for purchased gifts.
+
+## Weeklys
+
+- All_Weekly_Challenge_Complete = 4.
+- Weekly_Challenge_Complete = 6.
+- RewardType.WeeklyCompleteButHaveSkin = 4 is a DIFFERENT enum from GiftContext.
+- Server/API/Progression/Challenges/V2/ChallengeV2.cs has GET getCurrent returning {} and POST updateProgress returning an empty successful response, under both /api/challenge/v2 and /econ/api/challenge/v2.
+- Server/API/GameRewards/V1/GameRewardsAPI.cs maps WeeklyCompleteButHaveSkin to All_Weekly_Challenge_Complete. Its BuildReward method constructs token choices of 300, 600 and 900 for that reward type; this does not implement weekly challenge progress or a weekly skin award.
+- Next implementation work: recover the target client's challenge DTOs/objectives; provide current weekly definitions, period dates and reward items; persist authenticated progress and completion; grant the configured reward once per period; verify the already-owned-skin fallback and rollover behavior.
+
+## Gift delivery and wire format
+
+- Server/RecNet/Avatar/Gift.cs stores Context as GiftContext and exposes integer GiftContext as an alias. Id and GiftPackageId alias GiftDropId; Message aliases Tooltip; GiftRarity aliases Rarity.
+- Item payloads include AvatarItemDesc, ConsumableItemDesc, EquipmentPrefabName / EquipmentModificationGuid, and CurrencyType / Currency. A context alone does not specify a skin.
+- POST /api/avatar/v2/gifts/generate (also /econ/api/avatar/v2/gifts/generate) accepts GiftContext or MFPELEJLJLD; AlternateGiftContext or CIEHFJEIOJJ; Message or DPAJDIEBNKM; and Xp / XP. The alternate context is parsed but is not used to select the reward in this method.
+- Generation first looks for an outstanding reward, a pending box, or a recently handed-over box; supported activity contexts can resolve a room reward. Otherwise BuildGeneratedGift makes a random token box of 10, 25, 50, 100, 250 or 500. Sending context 4 or 6 alone is therefore not a weekly-skin implementation.
+- Generated gifts are persisted with notify:false because the response hands the box to the client.
+- Server/API/Storefront/StorefrontShared.cs provides PersistGiftBoxAsync and SendGiftPackageNotificationAsync. Reuse the existing grant/claim lifecycle rather than inventing a separate inventory path.
+- Server/Utils/GameRewardRedemption.cs handles outstanding/pending/recent reward reuse; Server/Utils/RroRewardPools.cs maps activity contexts and pools.
+- AvatarV2 also implements gift claim and consume routes. Exercise generation, notification, claim, consume, retries and reconnects with the target client before declaring a new reward flow complete.
+
+## Full GiftContext enum
+
+| Value | Name |
+| ---: | --- |
+| -1 | None |
+| 0 | Default |
+| 1 | First_Activity |
+| 2 | Game_Drop |
+| 3 | All_Daily_Challenges_Complete |
+| 4 | All_Weekly_Challenge_Complete |
+| 5 | Daily_Challenge_Complete |
+| 6 | Weekly_Challenge_Complete |
+| 10 | Unassigned_Equipment |
+| 11 | Unassigned_Avatar |
+| 12 | Unassigned_Consumable |
+| 20 | Reacquisition |
+| 21 | Membership |
+| 30 | NUX_TokensAndDressUp |
+| 31 | NUX_Experiment1 |
+| 32 | NUX_Experiment2 |
+| 33 | NUX_Experiment3 |
+| 34 | NUX_Experiment4 |
+| 35 | NUX_Experiment5 |
+| 50 | GameRewards |
+| 51 | GameRewards_Tokens |
+| 100 | LevelUp |
+| 500 | Purchased_Gift_A |
+| 501 | Purchased_Gift_B |
+| 502 | Purchased_Gift_C |
+| 503 | Purchased_Gift_D |
+| 1000 | Holiday |
+| 1001 | Contest |
+| 1002 | Promotion |
+| 1003 | SubscribersOnly |
+| 1100 | Deprecated |
+| 1200 | RecRoyale |
+| 2000 | DEPRECATED_Paintball_ClearCut |
+| 2001 | DEPRECATED_Paintball_Homestead |
+| 2002 | DEPRECATED_Paintball_Quarry |
+| 2003 | DEPRECATED_Paintball_River |
+| 2004 | DEPRECATED_Paintball_Dam |
+| 2005 | DEPRECATED_Paintball_DriveIn |
+| 2010 | Paintball_ClearCut |
+| 2011 | Paintball_Homestead |
+| 2012 | Paintball_Quarry |
+| 2013 | Paintball_River |
+| 2014 | Paintball_Dam |
+| 2015 | Paintball_DriveIn |
+| 3000 | DEPRECATED_Discgolf_Propulsion |
+| 3001 | DEPRECATED_Discgolf_Lake |
+| 3010 | Discgolf_Propulsion |
+| 3011 | Discgolf_Lake |
+| 3500 | Discgolf_Mode_CoopCatch |
+| 4000 | Quest_Goblin_A |
+| 4001 | Quest_Goblin_B |
+| 4002 | Quest_Goblin_C |
+| 4003 | Quest_Goblin_S |
+| 4004 | Quest_Goblin_Consumable |
+| 4010 | Quest_Cauldron_A |
+| 4011 | Quest_Cauldron_B |
+| 4012 | Quest_Cauldron_C |
+| 4013 | Quest_Cauldron_S |
+| 4014 | Quest_Cauldron_Consumable |
+| 4100 | Quest_Pirate1_A |
+| 4101 | Quest_Pirate1_B |
+| 4102 | Quest_Pirate1_C |
+| 4103 | Quest_Pirate1_S |
+| 4104 | Quest_Pirate1_X |
+| 4105 | Quest_Pirate1_Consumable |
+| 4200 | Quest_Dracula1_A |
+| 4201 | Quest_Dracula1_B |
+| 4202 | Quest_Dracula1_C |
+| 4203 | Quest_Dracula1_S |
+| 4204 | Quest_Dracula1_X |
+| 4205 | Quest_Dracula1_Consumable |
+| 4206 | Quest_Dracula1_SS |
+| 4500 | Quest_SciFi_A |
+| 4501 | Quest_SciFi_B |
+| 4502 | Quest_SciFi_C |
+| 4503 | Quest_SciFi_S |
+| 4504 | Quest_Scifi_Consumable |
+| 5000 | DEPRECATED_Charades |
+| 5001 | Charades |
+| 6000 | DEPRECATED_Soccer |
+| 6001 | Soccer |
+| 7000 | DEPRECATED_Paddleball |
+| 7001 | Paddleball |
+| 8000 | DEPRECATED_Dodgeball |
+| 8001 | Dodgeball |
+| 9000 | DEPRECATED_Lasertag |
+| 9001 | Lasertag |
+| 10000 | DEPRECATED_Bowling |
+| 10001 | Bowling |
+| 11000 | StuntRunner_TheMainEvent_A |
+| 11001 | StuntRunner_TheMainEvent_B |
+| 11002 | StuntRunner_TheMainEvent_C |
+| 11003 | StuntRunner_TheMainEvent_D |
+| 11004 | StuntRunner_TheMainEvent_S |
+| 11005 | StuntRunner_TheMainEvent_X |
+| 11006 | StuntRunner_TheMainEvent_Consumable |
+| 11007 | StuntRunner_TheMainEvent_SS |
+| 100000 | Store_LaserTag |
+| 100010 | Store_RecCenter |
+| 110000 | Consumable |
+| 110100 | Token |
+| 110200 | Punchcard_Challenge_Complete |
+| 110201 | All_Punchcard_Challenges_Complete |
+| 200000 | Commerce_Purchase |
+
+## RewardType enum (separate numeric namespace)
+
+| Value | Name |
+| ---: | --- |
+| 0 | FirstActivityOfDay |
+| 1 | DailyChallengesComplete |
+| 2 | PostGameActivity |
+| 3 | PostQuestActivity |
+| 4 | WeeklyCompleteButHaveSkin |
+| 5 | Levelup |
+| 6 | ReferralReward |
+
+## Scope and validation
+
+Enum values were expanded directly from the C# source, including explicit resets and implicit increments. JSON is in docs/gift-context.json. No runtime code or live data was changed. Friendotron's exact client contract and weekly challenge payloads still require client inspection; this document does not claim those features work.