@moncircle/sdk 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# MON Loyalty API
+
+A production-ready, multi-tenant loyalty infrastructure for e-commerce platforms.
+
+## Core Features
+- **Reward Isolation**: Isolated balances per platform and seller.
+- **Flexible Modes**:
+  - `SINGLE`: Unified rewards at the platform level.
+  - `MULTI`: Isolated reward pools for different sellers.
+  - `HYBRID`: Split rewards between platform and seller pools (70/30).
+- **Stripe-Level API**: Secure API key authentication and clean REST endpoints.
+
+## Tech Stack
+- Node.js & Express
+- TypeScript
+- Prisma ORM (PostgreSQL)
+- JWT-based Auth
+
+## Getting Started
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Configure Environment
+Copy `.env.example` to `.env` and provide your `DATABASE_URL`.
+```bash
+cp .env.example .env
+```
+
+### 3. Database Migration
+```bash
+npx prisma migrate dev --name init
+```
+
+### 4. Run Development Server
+```bash
+npm run dev
+```
+
+## API Usage Example
+
+### Create a Platform
+```bash
+POST /v1/platforms
+{
+  "name": "Stond Emporium",
+  "mode": "HYBRID",
+  "platformRewardRate": 0.0002
+}
+```
+
+### Create a Seller (MULTI/HYBRID only)
+**Header**: `Authorization: Bearer sk_xxxx`
+```bash
+POST /v1/sellers
+{
+  "name": "Nike Official",
+  "rewardRate": 0.0005
+}
+```
+
+### Record an Order
+**Header**: `Authorization: Bearer sk_xxxx`
+```bash
+POST /v1/orders
+{
+  "platformId": "...",
+  "sellerId": "...",
+  "userId": "user_123",
+  "amount": 5000,
+  "orderId": "ord_001"
+}
+```
+
+### Check Balance
+```bash
+GET /v1/users/user_123/balance?platformId=...&sellerId=...
+```
+
+## License
+MIT

package/dist/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+"use strict";
+// src/bin.ts — CLI entry point for Option B (standalone server)
+// Run with: npx mon-loyalty-api start
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const express_1 = __importDefault(require("express"));
+const index_1 = require("./index");
+const mongoUri = process.env.MONGODB_URI;
+const port = parseInt(process.env.PORT || "4000", 10);
+if (!mongoUri) {
+    console.error("\n[mon-loyalty-api] ❌ MONGODB_URI is not set in .env\n");
+    console.error("  Add MONGODB_URI to your .env file and try again.\n");
+    process.exit(1);
+}
+const app = (0, express_1.default)();
+app.use("/v1", (0, index_1.createMonLoyalty)({ mongoUri }));
+app.listen(port, () => {
+    console.log(`\n🚀 MON Loyalty API running on http://localhost:${port}`);
+    console.log(`   Health: http://localhost:${port}/v1/health\n`);
+});

package/dist/index.js

@@ -0,0 +1,96 @@
+"use strict";
+// src/index.ts — Public npm package entry point
+// Supports both:
+//   Option A: Embeddable middleware → app.use('/loyalty', createMonLoyalty({ ... }))
+//   Option B: Standalone → handled by src/bin.ts / src/server.ts
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RewardService = exports.Order = exports.User = exports.Seller = exports.Platform = void 0;
+exports.createMonLoyalty = createMonLoyalty;
+const express_1 = __importStar(require("express"));
+const mongoose_1 = __importDefault(require("mongoose"));
+const cors_1 = __importDefault(require("cors"));
+const platform_routes_1 = __importDefault(require("./routes/platform.routes"));
+const seller_routes_1 = __importDefault(require("./routes/seller.routes"));
+const order_routes_1 = __importDefault(require("./routes/order.routes"));
+const user_routes_1 = __importDefault(require("./routes/user.routes"));
+const withdraw_routes_1 = __importDefault(require("./routes/withdraw.routes"));
+/**
+ * createMonLoyalty — Embeddable Express Router (Option A)
+ *
+ * @example
+ * import { createMonLoyalty } from "mon-loyalty-api"
+ * app.use("/loyalty", createMonLoyalty({ mongoUri: process.env.MONGODB_URI }))
+ */
+function createMonLoyalty(config) {
+    if (!config.mongoUri)
+        throw new Error("[mon-loyalty-api] mongoUri is required");
+    // Connect to MongoDB (idempotent)
+    if (mongoose_1.default.connection.readyState === 0) {
+        mongoose_1.default.connect(config.mongoUri).then(() => {
+            console.log("[mon-loyalty-api] ✅ MongoDB connected");
+        }).catch((err) => {
+            console.error("[mon-loyalty-api] ❌ MongoDB connection failed:", err.message);
+        });
+    }
+    const router = (0, express_1.Router)();
+    if (config.cors !== false) {
+        router.use((0, cors_1.default)());
+    }
+    router.use(express_1.default.json());
+    router.use("/platforms", platform_routes_1.default);
+    router.use("/sellers", seller_routes_1.default);
+    router.use("/orders", order_routes_1.default);
+    router.use("/users", user_routes_1.default);
+    router.use("/withdraw", withdraw_routes_1.default);
+    router.get("/health", (_req, res) => {
+        res.json({ status: "ok", package: "mon-loyalty-api" });
+    });
+    return router;
+}
+// Re-export models for advanced use
+var Platform_1 = require("./models/Platform");
+Object.defineProperty(exports, "Platform", { enumerable: true, get: function () { return Platform_1.Platform; } });
+var Seller_1 = require("./models/Seller");
+Object.defineProperty(exports, "Seller", { enumerable: true, get: function () { return Seller_1.Seller; } });
+var User_1 = require("./models/User");
+Object.defineProperty(exports, "User", { enumerable: true, get: function () { return User_1.User; } });
+var Order_1 = require("./models/Order");
+Object.defineProperty(exports, "Order", { enumerable: true, get: function () { return Order_1.Order; } });
+var reward_service_1 = require("./services/reward.service");
+Object.defineProperty(exports, "RewardService", { enumerable: true, get: function () { return reward_service_1.RewardService; } });

package/dist/middleware/auth.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authenticate = void 0;
+const Platform_1 = require("../models/Platform");
+const authenticate = async (req, res, next) => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith("Bearer ")) {
+        return res.status(401).json({ error: "Missing or invalid API key" });
+    }
+    const secretKey = authHeader.split(" ")[1];
+    try {
+        const platform = await Platform_1.Platform.findOne({ secretKey });
+        if (!platform)
+            return res.status(403).json({ error: "Unauthorized" });
+        req.platform = platform;
+        next();
+    }
+    catch {
+        res.status(500).json({ error: "Authentication error" });
+    }
+};
+exports.authenticate = authenticate;

package/dist/models/Order.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Order = void 0;
+const mongoose_1 = __importStar(require("mongoose"));
+const OrderSchema = new mongoose_1.Schema({
+    orderId: { type: String, required: true, unique: true },
+    platformId: { type: String, required: true },
+    sellerId: { type: String, default: null },
+    userId: { type: String, required: true },
+    amount: { type: Number, required: true },
+    earned: { type: Number, required: true },
+    createdAt: { type: Date, default: Date.now }
+});
+exports.Order = mongoose_1.default.model("Order", OrderSchema);

package/dist/models/Platform.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Platform = void 0;
+const mongoose_1 = __importStar(require("mongoose"));
+const PlatformSchema = new mongoose_1.Schema({
+    name: { type: String, required: true },
+    publicKey: { type: String, required: true, unique: true },
+    secretKey: { type: String, required: true, unique: true },
+    mode: { type: String, enum: ["SINGLE", "MULTI", "HYBRID"], required: true },
+    platformRewardRate: { type: Number, default: 0.0002 },
+    monadWalletAddress: { type: String, default: null },
+    createdAt: { type: Date, default: Date.now }
+});
+exports.Platform = mongoose_1.default.model("Platform", PlatformSchema);

package/dist/models/Seller.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Seller = void 0;
+const mongoose_1 = __importStar(require("mongoose"));
+const SellerSchema = new mongoose_1.Schema({
+    name: { type: String, required: true },
+    platformId: { type: String, required: true, index: true },
+    rewardRate: { type: Number, default: 0.0002 },
+    createdAt: { type: Date, default: Date.now }
+});
+exports.Seller = mongoose_1.default.model("Seller", SellerSchema);

package/dist/models/User.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.User = void 0;
+const mongoose_1 = __importStar(require("mongoose"));
+const UserSchema = new mongoose_1.Schema({
+    userId: { type: String, required: true },
+    platformId: { type: String, required: true },
+    sellerId: { type: String, default: null },
+    balance: { type: Number, default: 0 },
+    lastActive: { type: Date, default: Date.now }
+});
+// Compound unique index — this is the scoping logic
+// A user has one record per (userId + platformId + sellerId) combination
+UserSchema.index({ userId: 1, platformId: 1, sellerId: 1 }, { unique: true });
+exports.User = mongoose_1.default.model("User", UserSchema);

package/dist/prisma.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectDB = void 0;
+require("dotenv/config");
+const mongoose_1 = __importDefault(require("mongoose"));
+let isConnected = false;
+const connectDB = async () => {
+    if (isConnected)
+        return;
+    const uri = process.env.MONGODB_URI;
+    if (!uri)
+        throw new Error("MONGODB_URI is not defined in .env");
+    await mongoose_1.default.connect(uri);
+    isConnected = true;
+    console.log("✅ MongoDB connected");
+};
+exports.connectDB = connectDB;
+exports.default = mongoose_1.default;

package/dist/routes/order.routes.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const Order_1 = require("../models/Order");
+const auth_1 = require("../middleware/auth");
+const reward_service_1 = require("../services/reward.service");
+const router = (0, express_1.Router)();
+router.post("/", auth_1.authenticate, async (req, res) => {
+    const { platformId, sellerId, userId, amount, orderId } = req.body;
+    const platform = req.platform;
+    if (platform._id.toString() !== platformId) {
+        return res.status(403).json({ error: "platformId mismatch" });
+    }
+    if (!userId || !amount || !orderId) {
+        return res.status(400).json({ error: "Missing required fields: userId, amount, orderId" });
+    }
+    try {
+        const { platformEarned, sellerEarned } = await reward_service_1.RewardService.calculateReward(platformId, amount, sellerId);
+        await Order_1.Order.create({
+            orderId,
+            platformId,
+            sellerId: sellerId || null,
+            userId,
+            amount,
+            earned: platformEarned + sellerEarned
+        });
+        const newBalances = await reward_service_1.RewardService.updateBalances(platformId, userId, platformEarned, sellerEarned, sellerId);
+        res.json({
+            earned: { platform: platformEarned, seller: sellerEarned },
+            newBalances
+        });
+    }
+    catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+exports.default = router;

package/dist/routes/platform.routes.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const Platform_1 = require("../models/Platform");
+const uuid_1 = require("uuid");
+const router = (0, express_1.Router)();
+router.post("/", async (req, res) => {
+    const { name, mode, platformRewardRate, monadWalletAddress } = req.body;
+    if (!name || !mode)
+        return res.status(400).json({ error: "name and mode are required" });
+    try {
+        const platform = await Platform_1.Platform.create({
+            name,
+            mode,
+            platformRewardRate: platformRewardRate || 0.0002,
+            monadWalletAddress: monadWalletAddress || null,
+            publicKey: "pk_" + (0, uuid_1.v4)().replace(/-/g, ""),
+            secretKey: "sk_" + (0, uuid_1.v4)().replace(/-/g, "")
+        });
+        res.status(201).json(platform);
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+exports.default = router;

package/dist/routes/seller.routes.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const Seller_1 = require("../models/Seller");
+const auth_1 = require("../middleware/auth");
+const router = (0, express_1.Router)();
+router.post("/", auth_1.authenticate, async (req, res) => {
+    const { name, rewardRate } = req.body;
+    const platform = req.platform;
+    if (platform.mode === "SINGLE") {
+        return res.status(400).json({ error: "Sellers are not used in SINGLE mode" });
+    }
+    if (!name)
+        return res.status(400).json({ error: "name is required" });
+    try {
+        const seller = await Seller_1.Seller.create({
+            name,
+            platformId: platform._id.toString(),
+            rewardRate: rewardRate || 0.0002
+        });
+        res.status(201).json(seller);
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+exports.default = router;

package/dist/routes/user.routes.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const User_1 = require("../models/User");
+const auth_1 = require("../middleware/auth");
+const reward_service_1 = require("../services/reward.service");
+const router = (0, express_1.Router)();
+// GET /v1/users/:userId/balance?platformId=...&sellerId=...
+router.get("/:userId/balance", async (req, res) => {
+    const { userId } = req.params;
+    const { platformId, sellerId } = req.query;
+    if (!platformId)
+        return res.status(400).json({ error: "platformId is required" });
+    try {
+        const user = await User_1.User.findOne({
+            userId,
+            platformId,
+            sellerId: sellerId || null
+        });
+        res.json({ balance: user?.balance || 0 });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+// POST /v1/users/redeem
+router.post("/redeem", auth_1.authenticate, async (req, res) => {
+    const { platformId, sellerId, userId, amount } = req.body;
+    const platform = req.platform;
+    if (platform._id.toString() !== platformId) {
+        return res.status(403).json({ error: "platformId mismatch" });
+    }
+    if (!userId || !amount) {
+        return res.status(400).json({ error: "Missing required fields: userId, amount" });
+    }
+    try {
+        const newBalance = await reward_service_1.RewardService.redeem(platformId, userId, amount, sellerId);
+        res.json({ message: "Redemption successful", newBalance });
+    }
+    catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+exports.default = router;

package/dist/routes/withdraw.routes.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const auth_1 = require("../middleware/auth");
+const reward_service_1 = require("../services/reward.service");
+const router = (0, express_1.Router)();
+/**
+ * POST /v1/withdraw
+ *
+ * Off-chain: Deducts user balance from DB.
+ * On-chain (future): Will trigger Monad smart contract to mint/transfer MON tokens.
+ *
+ * Architecture: Hybrid — track in DB, settle on-chain on request.
+ */
+router.post("/", auth_1.authenticate, async (req, res) => {
+    const { platformId, sellerId, userId, amount, walletAddress } = req.body;
+    const platform = req.platform;
+    if (platform._id.toString() !== platformId) {
+        return res.status(403).json({ error: "platformId mismatch" });
+    }
+    if (!userId || !amount || !walletAddress) {
+        return res.status(400).json({ error: "Missing required fields: userId, amount, walletAddress" });
+    }
+    try {
+        // Step 1: Deduct balance in MongoDB (off-chain)
+        const newBalance = await reward_service_1.RewardService.redeem(platformId, userId, amount, sellerId);
+        // Step 2: TODO — Monad on-chain settlement
+        // Will call MonLoyalty smart contract to mint/transfer MON tokens
+        // const tx = await monadService.settle(walletAddress, amount)
+        const withdrawal = {
+            userId,
+            platformId,
+            sellerId: sellerId || null,
+            amount,
+            walletAddress,
+            status: "PENDING_CHAIN", // Becomes "SETTLED" after Monad TX
+            newBalance
+        };
+        res.json({
+            message: "Withdrawal initiated (off-chain deducted, on-chain settlement pending)",
+            withdrawal
+        });
+    }
+    catch (err) {
+        res.status(400).json({ error: err.message });
+    }
+});
+exports.default = router;

package/dist/server.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const express_1 = __importDefault(require("express"));
+const index_1 = require("./index");
+// Standalone dev server — uses the same factory as the npm package
+const app = (0, express_1.default)();
+const PORT = process.env.PORT || 4000;
+app.use("/v1", (0, index_1.createMonLoyalty)({
+    mongoUri: process.env.MONGODB_URI
+}));
+// Global error handler
+app.use((err, _req, res, _next) => {
+    console.error(err.stack);
+    res.status(err.status || 500).json({ error: err.message || "Internal Server Error" });
+});
+app.listen(PORT, () => {
+    console.log(`🚀 MON Loyalty API running on http://localhost:${PORT}`);
+    console.log(`   Health: http://localhost:${PORT}/v1/health`);
+});

package/dist/services/reward.service.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RewardService = void 0;
+const Platform_1 = require("../models/Platform");
+const Seller_1 = require("../models/Seller");
+const User_1 = require("../models/User");
+class RewardService {
+    static async calculateReward(platformId, amount, sellerId) {
+        const platform = await Platform_1.Platform.findById(platformId);
+        if (!platform)
+            throw new Error("Platform not found");
+        let platformEarned = 0;
+        let sellerEarned = 0;
+        if (platform.mode === "SINGLE") {
+            platformEarned = amount * platform.platformRewardRate;
+        }
+        else if (platform.mode === "MULTI") {
+            if (!sellerId)
+                throw new Error("sellerId required for MULTI mode");
+            const seller = await Seller_1.Seller.findById(sellerId);
+            if (!seller || seller.platformId !== platformId)
+                throw new Error("Seller not found");
+            sellerEarned = amount * seller.rewardRate;
+        }
+        else if (platform.mode === "HYBRID") {
+            if (!sellerId)
+                throw new Error("sellerId required for HYBRID mode");
+            const seller = await Seller_1.Seller.findById(sellerId);
+            if (!seller || seller.platformId !== platformId)
+                throw new Error("Seller not found");
+            sellerEarned = amount * seller.rewardRate * 0.7;
+            platformEarned = amount * platform.platformRewardRate * 0.3;
+        }
+        return { platformEarned, sellerEarned, mode: platform.mode };
+    }
+    static async updateBalances(platformId, userId, platformEarned, sellerEarned, sellerId) {
+        const results = [];
+        // Platform-level balance (sellerId = null)
+        if (platformEarned > 0) {
+            const user = await User_1.User.findOneAndUpdate({ userId, platformId, sellerId: null }, { $inc: { balance: platformEarned }, $set: { lastActive: new Date() } }, { upsert: true, new: true });
+            results.push({ scope: "PLATFORM", newBalance: user.balance });
+        }
+        // Seller-level balance
+        if (sellerEarned > 0 && sellerId) {
+            const user = await User_1.User.findOneAndUpdate({ userId, platformId, sellerId }, { $inc: { balance: sellerEarned }, $set: { lastActive: new Date() } }, { upsert: true, new: true });
+            results.push({ scope: "SELLER", sellerId, newBalance: user.balance });
+        }
+        return results;
+    }
+    static async redeem(platformId, userId, amount, sellerId) {
+        const user = await User_1.User.findOne({ userId, platformId, sellerId: sellerId || null });
+        if (!user || user.balance < amount)
+            throw new Error("Insufficient balance");
+        user.balance -= amount;
+        user.lastActive = new Date();
+        await user.save();
+        return user.balance;
+    }
+}
+exports.RewardService = RewardService;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@moncircle/sdk",
+  "version": "1.0.0",
+  "description": "Self-hosted MON loyalty reward infrastructure for e-commerce platforms. Supports SINGLE, MULTI, and HYBRID reward modes with Monad on-chain settlement.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mon-loyalty-api": "dist/bin.js",
+    "mon-loyalty-setup": "scripts/setup.js"
+  },
+  "files": [
+    "dist/**/*",
+    "scripts/setup.js",
+    "scripts/postinstall.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "setup": "node scripts/setup.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/bin.ts",
+    "build": "tsc",
+    "start": "node dist/bin.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "loyalty",
+    "rewards",
+    "monad",
+    "web3",
+    "ecommerce",
+    "mon"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.6",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "mongoose": "^8.0.0",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.3.0",
+    "@types/uuid": "^10.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * mon-loyalty-api postinstall hook
+ *
+ * Runs automatically after: npm install mon-loyalty-api
+ * Smart detection:
+ *  - Skips in CI environments (CI=true)
+ *  - Skips if .env already exists in the consumer's project
+ *  - Skips if not running in an interactive terminal (piped/non-TTY)
+ *  - Writes .env to INIT_CWD (the consumer's project root, not node_modules)
+ */
+
+const fs = require("fs")
+const path = require("path")
+const { execSync } = require("child_process")
+
+const CYAN = "\x1b[36m"
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+const BOLD = "\x1b[1m"
+const RESET = "\x1b[0m"
+
+// Where the consumer ran `npm install` (their project root)
+const projectRoot = process.env.INIT_CWD || process.cwd()
+const envPath = path.join(projectRoot, ".env")
+const setupScript = path.join(__dirname, "setup.js")
+
+console.log(`\n${BOLD}${CYAN}  mon-loyalty-api installed!${RESET}`)
+
+// Skip in CI
+if (process.env.CI === "true" || process.env.CI === "1") {
+    console.log(`  ${YELLOW}⚠  CI environment detected — skipping interactive setup.${RESET}`)
+    console.log(`  Run ${CYAN}npx mon-loyalty-setup${RESET} manually to configure your .env\n`)
+    process.exit(0)
+}
+
+// Skip if not interactive TTY (e.g. piped output)
+if (!process.stdin.isTTY) {
+    console.log(`  ${YELLOW}⚠  Non-interactive terminal — skipping setup wizard.${RESET}`)
+    console.log(`  Run ${CYAN}npm run setup${RESET} to configure your .env\n`)
+    process.exit(0)
+}
+
+// Skip if .env already exists (don't overwrite a dev's existing config)
+if (fs.existsSync(envPath)) {
+    console.log(`  ${GREEN}✓  .env already exists at: ${envPath}${RESET}`)
+    console.log(`  Run ${CYAN}npm run setup${RESET} to reconfigure.\n`)
+    process.exit(0)
+}
+
+// Run the interactive setup wizard
+console.log(`  ${BOLD}Let's configure your environment...\n${RESET}`)
+try {
+    execSync(`node ${setupScript}`, {
+        stdio: "inherit",
+        cwd: projectRoot,
+        env: { ...process.env, MON_LOYALTY_ENV_PATH: envPath }
+    })
+} catch {
+    // User may have Ctrl+C'd — that's fine
+    console.log(`\n  ${YELLOW}Setup cancelled. Run ${CYAN}npm run setup${RESET}${YELLOW} anytime to configure.${RESET}\n`)
+}

package/scripts/setup.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * mon-loyalty-api setup script
+ * Run: npm run setup  OR  npx mon-loyalty-api setup
+ *
+ * Walks the dev through all required ENV vars and writes them to .env
+ */
+
+const readline = require("readline")
+const fs = require("fs")
+const path = require("path")
+
+const ENV_PATH = process.env.MON_LOYALTY_ENV_PATH || path.join(process.cwd(), ".env")
+
+const CYAN = "\x1b[36m"
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+const RED = "\x1b[31m"
+const BOLD = "\x1b[1m"
+const RESET = "\x1b[0m"
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+const ask = (question, defaultVal = "") =>
+    new Promise((resolve) => {
+        const hint = defaultVal ? ` ${YELLOW}[${defaultVal}]${RESET}` : ""
+        rl.question(`  ${question}${hint}: `, (answer) => {
+            resolve(answer.trim() || defaultVal)
+        })
+    })
+
+const fields = [
+    {
+        key: "MONGODB_URI",
+        label: "MongoDB URI",
+        hint: "e.g. mongodb+srv://user:pass@cluster.mongodb.net/mon-loyalty",
+        required: true,
+        default: ""
+    },
+    {
+        key: "PORT",
+        label: "Server Port",
+        hint: "Port to run the API on",
+        required: false,
+        default: "4000"
+    },
+    {
+        key: "JWT_SECRET",
+        label: "JWT Secret",
+        hint: "Any long random string for signing tokens",
+        required: false,
+        default: "change_me_in_production_" + Math.random().toString(36).slice(2)
+    },
+    {
+        key: "MONAD_RPC_URL",
+        label: "Monad RPC URL",
+        hint: "Your Monad node RPC endpoint (required for on-chain withdrawals)",
+        required: false,
+        default: "https://testnet-rpc.monad.xyz"
+    },
+    {
+        key: "MONAD_PRIVATE_KEY",
+        label: "Monad Private Key",
+        hint: "Your master wallet private key (used for on-chain settlement — KEEP SECRET)",
+        required: false,
+        default: ""
+    },
+    {
+        key: "MONAD_CONTRACT_ADDRESS",
+        label: "MonLoyalty Contract Address",
+        hint: "Deployed MonLoyalty smart contract address (leave blank for now)",
+        required: false,
+        default: ""
+    }
+]
+
+async function loadExistingEnv() {
+    if (!fs.existsSync(ENV_PATH)) return {}
+    const content = fs.readFileSync(ENV_PATH, "utf-8")
+    const existing = {}
+    for (const line of content.split("\n")) {
+        const match = line.match(/^([^#=]+)=(.*)$/)
+        if (match) existing[match[1].trim()] = match[2].trim().replace(/^"|"$/g, "")
+    }
+    return existing
+}
+
+function writeEnv(values) {
+    const lines = [
+        "# Generated by mon-loyalty-api setup",
+        "# Run: npx mon-loyalty-api setup  to reconfigure",
+        "",
+        "# ── Required ─────────────────────────────────",
+        `MONGODB_URI="${values.MONGODB_URI}"`,
+        "",
+        "# ── Server ───────────────────────────────────",
+        `PORT=${values.PORT}`,
+        `NODE_ENV=development`,
+        "",
+        "# ── Auth ─────────────────────────────────────",
+        `JWT_SECRET="${values.JWT_SECRET}"`,
+        "",
+        "# ── Monad On-Chain (for withdrawal/settlement) ─",
+        `MONAD_RPC_URL="${values.MONAD_RPC_URL}"`,
+        `MONAD_PRIVATE_KEY="${values.MONAD_PRIVATE_KEY}"`,
+        `MONAD_CONTRACT_ADDRESS="${values.MONAD_CONTRACT_ADDRESS}"`,
+        ""
+    ]
+    fs.writeFileSync(ENV_PATH, lines.join("\n"), "utf-8")
+}
+
+async function main() {
+    console.log(`\n${BOLD}${CYAN}╔══════════════════════════════════════════════╗`)
+    console.log(`║       MON Loyalty API — Setup Wizard         ║`)
+    console.log(`╚══════════════════════════════════════════════╝${RESET}\n`)
+    console.log(`  This will create a ${BOLD}.env${RESET} file in: ${YELLOW}${process.cwd()}${RESET}\n`)
+
+    const existing = await loadExistingEnv()
+    const hasExisting = Object.keys(existing).length > 0
+
+    if (hasExisting) {
+        console.log(`  ${YELLOW}⚠  An existing .env was found. Press Enter to keep current values.${RESET}\n`)
+    }
+
+    const values = {}
+
+    for (const field of fields) {
+        const currentVal = existing[field.key] || field.default
+        const requiredTag = field.required ? ` ${RED}*required${RESET}` : ""
+        console.log(`  ${BOLD}${field.label}${RESET}${requiredTag}`)
+        console.log(`  ${CYAN}${field.hint}${RESET}`)
+
+        let val = ""
+        while (true) {
+            val = await ask(`  → Enter value`, currentVal)
+            if (field.required && !val) {
+                console.log(`  ${RED}✖ This field is required.${RESET}`)
+            } else {
+                break
+            }
+        }
+
+        values[field.key] = val
+        console.log()
+    }
+
+    writeEnv(values)
+
+    console.log(`${GREEN}${BOLD}  ✅ .env file written successfully!${RESET}\n`)
+    console.log(`  Next steps:`)
+    console.log(`   ${CYAN}npm run dev${RESET}     — start the development server`)
+    console.log(`   ${CYAN}npm run build${RESET}   — build for production`)
+    console.log(`   ${CYAN}npm start${RESET}       — run production build\n`)
+
+    rl.close()
+}
+
+main().catch((err) => {
+    console.error(`\n${RED}Setup failed:${RESET}`, err.message)
+    rl.close()
+    process.exit(1)
+})