🎁 Redeema

Powerful and intuitive, this event-driven system unlocks the next generation of digital reward experiences.
Built for high-performance applications and interactive ecosystems, it streamlines the creation, tracking, and claiming of redeemable codes with seamless storage, dynamic validation, and persistent analytics. By revolutionizing game drops, loyalty programs, event activations, and limited-time promotional rewards, it empowers developers to engage users with precision, control, and legendary scalability.

Features

• 🔑 Create and manage redeemable codes tied to rewards or actions
• 🧠 Register custom reward resolvers with full dynamic logic
• 🔄 Track redemption usage with built-in claim validation, multipliers, and per-user limits
• 🕰️ Set expiration timestamps, decay rates, and max/min reward thresholds
• 📊 Persistent analytics with real-time group stat tracking
• 🧠 Custom validation logic per code
• 🧪 Full support for in-memory and persistent vault storage
• 📡 Event-driven architecture for hook-based integration

API Specifications

new Redeema({
     analyticsCollectionName : "Redeemalytics",      // (default: "Redeemalytics")
     collectionName : "redeema_redeemits",  // Main redeem code collection
     eventNames : {                     // Override internal event labels
          issued  : "redeemit:issued",
          claimed : "redeemit:claimed",
          updated : "redeemit:updated",
          revoked : "redeemit:revoked"
     },
     customValidator : null,                 // Async validator function for codes
     generateCode : () => Math.random().toString(36).substr(2, 8), // Custom code generator
     group : "default",            // Logical group name
     vaultOptions : {                     // StarVault options
          dbPath : "./Redeema_Data",
          logPath : "./Redeema_Logs",
          shardCount : 4,
          maxLogSize : "869MB",
          logRetention : "30d",
          options : {
               enableEncryption : true,
               vaultPath : "./redeema-vault.json",
               masterKey : "redeema-codes"
          }
     },
     storage : null,                 // Custom StarVault instance (optional)
     useInMemory : false                 // Only use in-memory session state (optional)
});

| Config Option | Type | Default | Description | |---------------|------|---------|-------------| | collectionName | string | "redeema_redeemits" | Main collection where redeemable codes are stored | | analyticsCollectionName | string | "Redeemalytics" | Collection where persistent stats are saved | | group | string | "default" | Logical namespace to separate rewards by context | | generateCodeFn | function | Random alphanumeric | Custom function to generate code strings | | customValidator | function|null | null | Optional validator to reject codes at claim time | | eventNames | object | { issued, claimed, updated, revoked } | Custom names for emitted events | | vaultOptions | object | {} | Options passed to StarVault instance | | storage | StarVault|null | null | Optional custom StarVault instance | | useInMemory | boolean | false | If true, avoids persistent storage |

vaultOptions (Object, passed to StarVault internally)

| Property | Type | Default | Description | |--------------------------|------------|------------------------------------|-----------------------------------------------------------------------------| | dbPath | string | "./Redeema_Data" | Directory for StarVault's storage data. | | logPath | string | "./Redeema_Logs" | Directory for StarVault's write-ahead logs. | | shardCount | number | 4 | Number of data shards used for partitioning records. | | maxLogSize | string | "869MB" | Maximum size per log file before rotation. | | logRetention | string | "30d" | How long logs are retained before being purged. | | options.enableEncryption | boolean| true | Enables encryption for stored vault records. | | options.vaultPath | string | "./redeema-vault.json" | Path to store the StarVault encryption key. | | options.masterKey | string | "redeema-codes" | The default encryption key label used for vault records. |

Redeema Functions

Core Code Methods

| Method | Returns | Description | |--------|---------|-------------| | registerRewardResolver(id, fn) | true if registered successfully | Registers a dynamic reward resolver for a specific rewardActionID. | | unregisterRewardResolver(id) | true if removed | Removes a previously registered reward resolver. | | issueRedeemit(actionInfo, clientAuth, options) | Promise<object> containing the issued code data | Issues a new redeemable code with full configuration. | | registerRedeemit(code, actionInfo, clientAuth, options) | Promise<object> containing the registered code data | Manually registers a code with custom settings. | | claimRedeemit(code, actionInfo, clientAuth) | Promise<object> with { success, code, reward, multiplier, redeemit } or error metadata | Claims a code and resolves the reward logic. | | previewRedeemitReward(code, actionInfo, clientAuth) | Promise<object> with { success, code, reward, multiplier } | Returns the reward data without affecting code usage. | | viewRedeemit(code, actionInfo) | object|null | Returns code metadata or null if not found. | | updateRedeemit(code, updates, actionInfo, clientAuth) | Promise<object> updated code data | Updates the data of an existing code. | | deleteRedeemit(code, actionInfo, clientAuth) | Promise<boolean> | Permanently deletes the code and its memory reference. | | listRedeemits(filterFn?) | Promise<object[]> | Lists all active or stored codes for the current group. | | cleanupExpiredRedeemits() | Promise<number> | Removes expired codes and returns how many were deleted. |

Redeemalytics Methods

| Method | Returns | Description | |--------|---------|-------------| | getGroupStats(group?) | object | Returns in-memory session stats for the group | | saveRedeemalytics(group, actionInfo, clientAuth) | Promise<boolean> | Saves in-memory stats to persistent storage | | loadRedeemalytics(group, actionInfo) | Promise<boolean> | Loads persisted stats into memory | | getAllTimeRedeemalytics(group, actionInfo) | Promise<object[]> | Returns full historical stats from storage | | clearRedeemalytics(group, actionInfo, clientAuth) | Promise<boolean> | Clears both in-memory and persisted stats |

📦 Installation

npm install @trap_stevo/redeema

Usage Examples

1. 🧠 Dynamic Reward Code Creation

const Redeema = require("@trap_stevo/redeema");

const redeema = new Redeema({ group : "MysticLoot" });

function rewardMysticBox() {
     return { item : "Mystic Lootbox", rarity : "legendary" };
}

redeema.registerRewardResolver("mystic-box", rewardMysticBox);

const issued = await redeema.issueRedeemit({}, null, {
     uses           : 5,
     multiplier     : 2,
     rewardActionID : "mystic-box",
     reward         : rewardMysticBox,
     metadata       : { origin : "event", tier : "legendary" }
});

console.log("Issued:", issued);

2. 📌 Using a Predefined Code

const preCode = "GOLDEN77";

await redeema.registerRedeemit(preCode, {}, null, {
     uses           : 1,
     rewardActionID : "mystic-box",
     reward         : rewardMysticBox
});

const claimResult = await redeema.claimRedeemit(preCode);
console.log("Claim Result:", claimResult);

3. 📊 Redeemalytics (Group Stats)

const stats = redeema.getGroupStats(); // Real-time session stats
console.log("Current Session Stats:", stats);

await redeema.saveRedeemalytics(); // Persist to StarVault

const allTime = await redeema.getAllTimeRedeemalytics("MysticLoot");
console.log("All-Time Stats:", allTime);

4. Redeema Events

Redeema uses an event-driven architecture, allowing subscriptions to key lifecycle events to build rich, reactive systems.

Available Events

Each event utilizes a namespace by group (e.g., redeemit:issued:default):

| Event | Description | |------------------------|------------------------------------------------------------------| | redeemit:issued:<group> | Triggered when a new redeemable code is issued. | | redeemit:claimed:<group> | Triggered when a code is successfully claimed. | | redeemit:updated:<group> | Triggered when a code is updated. | | redeemit:revoked:<group> | Triggered when a code is deleted or revoked. |

Registering for Events

You can attach listeners using the built-in onRedeemaEvent and offRedeemaEvent methods:

// Subscribe to a claimed code in group "SeasonX"
redeema.onRedeemaEvent("redeemit:claimed", "SeasonX", (codeID, data) => {
     console.log(`[Event] Code Claimed:`, codeID, data);
});

// Unsubscribe when needed
redeema.offRedeemaEvent("redeemit:claimed", "SeasonX", handlerFunction);

License

See License in LICENSE.md