@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/auth/provider.js

@@ -272,11 +272,7 @@ function renderAuthorizationForm(params) {
       outline: none;
       border-color: #667eea;
     }
-    .help-text {
-      color: #6b7280;
-      font-size: 12px;
-      margin-top: 4px;
-    }
+    .help-text { color: #6b7280; font-size: 12px; margin-top: 4px; }
     button {
       width: 100%;
       padding: 14px 24px;
@@ -290,15 +286,7 @@ function renderAuthorizationForm(params) {
     }
     button:hover { opacity: 0.9; }
     button:disabled { opacity: 0.7; cursor: not-allowed; }
-    .error {
-      background: #fef2f2;
-      border: 1px solid #fecaca;
-      color: #dc2626;
-      padding: 12px;
-      border-radius: 8px;
-      margin-bottom: 20px;
-      display: none;
-    }
+    .error { background: #fef2f2; border: 1px solid #fecaca; color: #dc2626; padding: 12px; border-radius: 8px; margin-bottom: 20px; display: none; }
     .error.visible { display: block; }
   </style>
 </head>

package/dist/auth/storage.js

@@ -5,9 +5,24 @@
 import { Redis } from "ioredis";
 /**
  * In-memory storage for local development
+ * Includes periodic cleanup to prevent memory leaks from expired entries
  */
 class InMemoryStorage {
     data = new Map();
+    cleanupInterval;
+    constructor() {
+        // Periodic cleanup every 5 minutes to remove expired entries
+        this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+        this.cleanupInterval.unref(); // Don't prevent process exit
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.data) {
+            if (entry.expiresAt && entry.expiresAt < now) {
+                this.data.delete(key);
+            }
+        }
+    }
     async get(key) {
         const entry = this.data.get(key);
         if (!entry)
@@ -27,6 +42,13 @@ class InMemoryStorage {
     async delete(key) {
         this.data.delete(key);
     }
+    /**
+     * Close the storage and clean up resources
+     */
+    close() {
+        clearInterval(this.cleanupInterval);
+        this.data.clear();
+    }
 }
 /**
  * Redis storage for production

package/dist/client/http.d.ts

@@ -1,4 +1,9 @@
 import { AxiosInstance } from "axios";
+/**
+ * Redacts sensitive fields from data before logging.
+ * Replaces values of sensitive fields with "[REDACTED]".
+ */
+export declare function redactSensitiveData(data: unknown, depth?: number): unknown;
 export declare function resetHttpClient(): void;
 export declare function getAxiosInstance(): AxiosInstance;
 export declare function apiGet<T>(url: string): Promise<T>;

package/dist/client/http.js

@@ -1,5 +1,60 @@
 import axios from "axios";
+import https from "https";
 import { getConfig } from "../config.js";
+// Connection pool for HTTP keep-alive (50-80% latency improvement)
+const httpsAgent = new https.Agent({
+    keepAlive: true,
+    maxSockets: 50,
+    maxFreeSockets: 10,
+    timeout: 60000,
+    keepAliveMsecs: 30000,
+});
+// Fields that may contain PII and should be redacted in logs
+const SENSITIVE_FIELDS = new Set([
+    "email",
+    "phone",
+    "password",
+    "token",
+    "apiToken",
+    "apiKey",
+    "secret",
+    "address",
+    "street",
+    "city",
+    "postalCode",
+    "loyaltyCardNumber",
+    "firstName",
+    "lastName",
+    "birthDate",
+    "gender",
+]);
+/**
+ * Redacts sensitive fields from data before logging.
+ * Replaces values of sensitive fields with "[REDACTED]".
+ */
+export function redactSensitiveData(data, depth = 0) {
+    // Prevent infinite recursion on deeply nested objects
+    if (depth > 10)
+        return "[MAX_DEPTH]";
+    if (data === null || data === undefined)
+        return data;
+    if (Array.isArray(data)) {
+        return data.map((item) => redactSensitiveData(item, depth + 1));
+    }
+    if (typeof data === "object") {
+        const redacted = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (SENSITIVE_FIELDS.has(key)) {
+                redacted[key] = "[REDACTED]";
+            }
+            else {
+                redacted[key] = redactSensitiveData(value, depth + 1);
+            }
+        }
+        return redacted;
+    }
+    return data;
+}
 let client = null;
 // For testing: reset the client singleton
 export function resetHttpClient() {
@@ -13,16 +68,20 @@ function getClient() {
     if (client) {
         return client;
     }
-    const config = getConfig();
+    // Create client without baseURL - it will be set dynamically per request
+    // to support multi-tenant OAuth mode where each user has different API URLs
     client = axios.create({
-        baseURL: config.apiUrl,
         timeout: 30000,
+        httpsAgent,
         headers: {
             "Content-Type": "application/json",
         },
     });
     client.interceptors.request.use((requestConfig) => {
+        // Get current config (supports request-scoped overrides in OAuth mode)
         const cfg = getConfig();
+        // Set baseURL dynamically from current config (supports multi-tenant OAuth)
+        requestConfig.baseURL = cfg.apiUrl;
         requestConfig.headers.set("X-AUTH-TOKEN", cfg.apiToken);
         return requestConfig;
     }, (error) => {
@@ -33,7 +92,7 @@ function getClient() {
         if (error.response) {
             const status = error.response.status;
             const data = error.response.data;
-            console.error(`API Error [${status}]:`, JSON.stringify(data, null, 2));
+            console.error(`API Error [${status}]:`, JSON.stringify(redactSensitiveData(data), null, 2));
             if (status === 401) {
                 throw new Error("Authentication failed (401): Invalid or expired API token. " +
                     "Please check your OPENLOYALTY_API_TOKEN environment variable.");

package/dist/config.d.ts

@@ -14,16 +14,17 @@ declare const ConfigSchema: z.ZodObject<{
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 /**
- * Sets a config override for the current request (OAuth mode)
+ * Runs a function with a request-scoped config override (OAuth mode).
+ * This is thread-safe - concurrent requests each have their own isolated config.
  */
-export declare function setConfigOverride(override: {
+export declare function runWithConfig<T>(override: {
     apiUrl: string;
     apiToken: string;
     storeCode: string;
-}): void;
+}, fn: () => T | Promise<T>): T | Promise<T>;
 /**
- * Clears the config override after request completes
+ * Gets the store code, falling back to default from config if not provided.
  */
-export declare function clearConfigOverride(): void;
+export declare function getStoreCode(storeCode?: string): string;
 export declare function getConfig(): Config;
 export {};

package/dist/config.js

@@ -1,32 +1,36 @@
 import { z } from "zod";
+import { AsyncLocalStorage } from "async_hooks";
 const ConfigSchema = z.object({
     apiUrl: z.string().url(),
     apiToken: z.string().min(1),
     defaultStoreCode: z.string().min(1),
 });
 let config = null;
-// Per-request config override for OAuth mode
-let configOverride = null;
+// Request-scoped config storage using AsyncLocalStorage (thread-safe for concurrent requests)
+const configStorage = new AsyncLocalStorage();
 /**
- * Sets a config override for the current request (OAuth mode)
+ * Runs a function with a request-scoped config override (OAuth mode).
+ * This is thread-safe - concurrent requests each have their own isolated config.
  */
-export function setConfigOverride(override) {
-    configOverride = {
+export function runWithConfig(override, fn) {
+    const requestConfig = {
         apiUrl: override.apiUrl,
         apiToken: override.apiToken,
         defaultStoreCode: override.storeCode,
     };
+    return configStorage.run(requestConfig, fn);
 }
 /**
- * Clears the config override after request completes
+ * Gets the store code, falling back to default from config if not provided.
  */
-export function clearConfigOverride() {
-    configOverride = null;
+export function getStoreCode(storeCode) {
+    return storeCode || getConfig().defaultStoreCode;
 }
 export function getConfig() {
-    // Return override if set (OAuth mode)
-    if (configOverride) {
-        return configOverride;
+    // Return request-scoped config if set (OAuth mode)
+    const requestConfig = configStorage.getStore();
+    if (requestConfig) {
+        return requestConfig;
     }
     if (config) {
         return config;

package/dist/http.js

@@ -2,11 +2,13 @@
 import "dotenv/config";
 import express from "express";
 import cors from "cors";
+import helmet from "helmet";
+import rateLimit from "express-rate-limit";
 import { randomUUID } from "crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { createServer, SERVER_INSTRUCTIONS } from "./server.js";
-import { getConfig, setConfigOverride, clearConfigOverride } from "./config.js";
+import { getConfig, runWithConfig } from "./config.js";
 import { createOAuthProvider, completeAuthorization, validateOpenLoyaltyCredentials, getClientConfig, } from "./auth/provider.js";
 // Check if OAuth mode is enabled
 const OAUTH_ENABLED = process.env.OAUTH_ENABLED === "true";
@@ -22,16 +24,100 @@ if (!OAUTH_ENABLED) {
     }
 }
 const app = express();
-// CORS for ChatGPT
+// CORS configuration - defaults to "*" for MCP clients, configurable for enterprise
+const CORS_ORIGIN = process.env.CORS_ORIGIN || "*";
 app.use(cors({
-    origin: "*",
+    origin: CORS_ORIGIN,
     methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allowedHeaders: ["Content-Type", "Authorization", "MCP-Session-Id", "MCP-Protocol-Version"],
     exposedHeaders: ["MCP-Session-Id"],
 }));
-app.use(express.json());
+// Security headers
+app.use(helmet({
+    contentSecurityPolicy: {
+        directives: {
+            defaultSrc: ["'self'"],
+            scriptSrc: ["'self'"],
+            styleSrc: ["'self'", "'unsafe-inline'"], // Allow inline styles for OAuth form
+            imgSrc: ["'self'", "data:"],
+            connectSrc: ["'self'"],
+            fontSrc: ["'self'"],
+            objectSrc: ["'none'"],
+            frameAncestors: ["'none'"],
+        },
+    },
+    crossOriginEmbedderPolicy: false, // Disable for CORS compatibility
+    crossOriginResourcePolicy: { policy: "cross-origin" }, // Allow cross-origin for API
+}));
+// Rate limiting - global limit
+const globalLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    max: 100, // 100 requests per window
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: "Too many requests, please try again later." },
+});
+// Stricter rate limiting for auth endpoints (brute-force protection)
+const authLimiter = rateLimit({
+    windowMs: 60 * 1000, // 1 minute
+    max: 10, // 10 requests per minute
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: "Too many authentication attempts, please try again later." },
+});
+app.use(globalLimiter);
+// Body size limit to prevent DoS via large payloads (10MB generous for CSV imports)
+const BODY_LIMIT = process.env.BODY_LIMIT || "10mb";
+app.use(express.json({ limit: BODY_LIMIT }));
 // Store transports by session ID for stateful connections
 const transports = new Map();
+// Session TTL management to prevent memory leaks
+const SESSION_TTL_MS = parseInt(process.env.SESSION_TTL_MS || String(30 * 60 * 1000), 10); // Default: 30 minutes
+const SESSION_CLEANUP_INTERVAL_MS = parseInt(process.env.SESSION_CLEANUP_INTERVAL_MS || String(60 * 1000), 10); // Default: 1 minute
+const MAX_SESSIONS = parseInt(process.env.MAX_SESSIONS || "10000", 10); // Default: 10,000 sessions
+const sessionLastActivity = new Map();
+/**
+ * Evict oldest sessions when limit is reached to prevent memory exhaustion
+ */
+function evictOldestSessions() {
+    if (transports.size < MAX_SESSIONS)
+        return;
+    // Evict oldest 10% of sessions
+    const evictCount = Math.max(1, Math.floor(MAX_SESSIONS * 0.1));
+    const sortedSessions = [...sessionLastActivity.entries()]
+        .sort((a, b) => a[1] - b[1])
+        .slice(0, evictCount);
+    for (const [sessionId] of sortedSessions) {
+        const transport = transports.get(sessionId);
+        if (transport) {
+            try {
+                transport.close();
+            }
+            catch {
+                // Ignore close errors during eviction
+            }
+        }
+        transports.delete(sessionId);
+        sessionLastActivity.delete(sessionId);
+    }
+    console.warn(`Session limit reached (${MAX_SESSIONS}). Evicted ${sortedSessions.length} oldest sessions.`);
+}
+// Periodic cleanup of abandoned sessions
+const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [sessionId, lastActivity] of sessionLastActivity) {
+        if (now - lastActivity > SESSION_TTL_MS) {
+            const transport = transports.get(sessionId);
+            if (transport) {
+                transport.close();
+                transports.delete(sessionId);
+            }
+            sessionLastActivity.delete(sessionId);
+        }
+    }
+}, SESSION_CLEANUP_INTERVAL_MS);
+// Prevent cleanup interval from keeping the process alive
+cleanupInterval.unref();
 // Health check endpoint
 app.get("/health", (_req, res) => {
     res.json({ status: "ok", server: "openloyalty-mcp", oauth: OAUTH_ENABLED });
@@ -39,6 +125,10 @@ app.get("/health", (_req, res) => {
 // OAuth mode setup
 if (OAUTH_ENABLED) {
     const provider = createOAuthProvider(BASE_URL);
+    // Apply stricter rate limiting to auth endpoints
+    app.use("/authorize", authLimiter);
+    app.use("/token", authLimiter);
+    app.use("/register", authLimiter);
     // Add MCP SDK auth router (handles /.well-known/*, /authorize, /token, /register)
     app.use(mcpAuthRouter({
         provider,
@@ -46,7 +136,7 @@ if (OAUTH_ENABLED) {
         baseUrl: new URL(BASE_URL),
         serviceDocumentationUrl: new URL("https://github.com/OpenLoyalty/openloyalty-mcp"),
     }));
-    // Authorization form submission endpoint
+    // Authorization form submission endpoint (also rate limited via /authorize prefix)
     app.post("/authorize/submit", async (req, res) => {
         const { session_id, api_url, api_token, store_code } = req.body;
         if (!session_id || !api_url || !api_token || !store_code) {
@@ -88,9 +178,9 @@ if (OAUTH_ENABLED) {
                 res.status(401).json({ error: "Open Loyalty not configured. Please re-authorize." });
                 return;
             }
-            // Set config override for this request
-            setConfigOverride(config);
-            // Store clientId for cleanup
+            // Store config on request for use with runWithConfig() in handler
+            // This is thread-safe because each request has its own req object
+            req.oauthConfig = config;
             req.clientId = authInfo.clientId;
             next();
         }
@@ -103,73 +193,88 @@ if (OAUTH_ENABLED) {
     // Apply auth middleware to /mcp
     app.use("/mcp", authMiddleware);
 }
-// MCP endpoint - handles both initialization and messages
-app.all("/mcp", async (req, res) => {
+// Helper to handle MCP request processing
+async function handleMcpRequest(req, res) {
     const sessionId = req.headers["mcp-session-id"];
-    try {
-        // Handle GET requests for SSE streams
-        if (req.method === "GET") {
-            if (!sessionId || !transports.has(sessionId)) {
-                res.status(400).json({ error: "Invalid or missing session ID for SSE stream" });
-                return;
-            }
-            const transport = transports.get(sessionId);
-            await transport.handleRequest(req, res);
-            return;
-        }
-        // Handle DELETE requests for session cleanup
-        if (req.method === "DELETE") {
-            if (sessionId && transports.has(sessionId)) {
-                const transport = transports.get(sessionId);
-                await transport.close();
-                transports.delete(sessionId);
-                res.status(204).send();
-            }
-            else {
-                res.status(404).json({ error: "Session not found" });
-            }
+    // Handle GET requests for SSE streams
+    if (req.method === "GET") {
+        if (!sessionId || !transports.has(sessionId)) {
+            res.status(400).json({ error: "Invalid or missing session ID for SSE stream" });
             return;
         }
-        // Handle POST requests
-        if (req.method === "POST") {
-            // Check if this is an initialization request (no session ID)
-            if (!sessionId) {
-                // Create new session
-                const newSessionId = randomUUID();
-                const transport = new StreamableHTTPServerTransport({
-                    sessionIdGenerator: () => newSessionId,
-                });
-                // Create and connect server
-                const server = createServer();
-                await server.connect(transport);
-                // Store transport for future requests
-                transports.set(newSessionId, transport);
-                // Clean up on close
-                transport.onclose = () => {
-                    transports.delete(newSessionId);
-                };
-                // Handle the request
-                await transport.handleRequest(req, res, req.body);
-                return;
-            }
-            // Existing session - route to stored transport
+        const transport = transports.get(sessionId);
+        // Update last activity for TTL tracking
+        sessionLastActivity.set(sessionId, Date.now());
+        await transport.handleRequest(req, res);
+        return;
+    }
+    // Handle DELETE requests for session cleanup
+    if (req.method === "DELETE") {
+        if (sessionId && transports.has(sessionId)) {
             const transport = transports.get(sessionId);
-            if (!transport) {
-                res.status(404).json({ error: "Session not found. Initialize a new session first." });
-                return;
-            }
+            await transport.close();
+            transports.delete(sessionId);
+            sessionLastActivity.delete(sessionId);
+            res.status(204).send();
+        }
+        else {
+            res.status(404).json({ error: "Session not found" });
+        }
+        return;
+    }
+    // Handle POST requests
+    if (req.method === "POST") {
+        // Check if this is an initialization request (no session ID)
+        if (!sessionId) {
+            // Evict oldest sessions if limit reached (DoS protection)
+            evictOldestSessions();
+            // Create new session
+            const newSessionId = randomUUID();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => newSessionId,
+            });
+            // Create and connect server
+            const server = createServer();
+            await server.connect(transport);
+            // Store transport for future requests
+            transports.set(newSessionId, transport);
+            sessionLastActivity.set(newSessionId, Date.now());
+            // Clean up on close
+            transport.onclose = () => {
+                transports.delete(newSessionId);
+                sessionLastActivity.delete(newSessionId);
+            };
+            // Handle the request
             await transport.handleRequest(req, res, req.body);
             return;
         }
-        // Unsupported method
-        res.status(405).json({ error: "Method not allowed" });
+        // Existing session - route to stored transport
+        const transport = transports.get(sessionId);
+        if (!transport) {
+            res.status(404).json({ error: "Session not found. Initialize a new session first." });
+            return;
+        }
+        // Update last activity for TTL tracking
+        sessionLastActivity.set(sessionId, Date.now());
+        await transport.handleRequest(req, res, req.body);
+        return;
     }
-    finally {
-        // Clean up config override in OAuth mode
-        if (OAUTH_ENABLED) {
-            clearConfigOverride();
+    // Unsupported method
+    res.status(405).json({ error: "Method not allowed" });
+}
+// MCP endpoint - handles both initialization and messages
+app.all("/mcp", async (req, res) => {
+    // In OAuth mode, wrap request handling with runWithConfig for thread-safe config
+    if (OAUTH_ENABLED) {
+        const oauthConfig = req.oauthConfig;
+        if (oauthConfig) {
+            // Use runWithConfig for thread-safe, request-scoped config
+            await runWithConfig(oauthConfig, () => handleMcpRequest(req, res));
+            return;
         }
     }
+    // Non-OAuth mode or no config - use environment config
+    await handleMcpRequest(req, res);
 });
 // Server info endpoint
 app.get("/", (_req, res) => {

package/dist/instructions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * MCP Server Instructions - provides context and guidance for AI agents
+ * using the Open Loyalty MCP server.
+ */
+export declare const SERVER_INSTRUCTIONS = "\nOpen Loyalty MCP Server - Complete Loyalty Program Management\n\n## Domain Model\n\nMember (loyalty program participant)\n  \u2514\u2500\u2500 Points (wallet balance, transfers)\n  \u2514\u2500\u2500 Tier (current level: Bronze, Silver, Gold)\n  \u2514\u2500\u2500 Transactions (purchase history)\n  \u2514\u2500\u2500 Rewards (redeemed coupons)\n  \u2514\u2500\u2500 Achievements (gamification progress)\n  \u2514\u2500\u2500 Badges (visual rewards from achievements)\n\nTierSet (loyalty program structure)\n  \u2514\u2500\u2500 Conditions (criteria: activeUnits, totalSpending)\n  \u2514\u2500\u2500 Tiers (levels with thresholds)\n\nWalletType (points currency configuration)\n\nReward (redeemable items)\n  \u2514\u2500\u2500 Categories (reward groupings)\n\nCampaign (automated points/rewards rules)\n  \u2514\u2500\u2500 Type (earning, spending, custom, instant_reward)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer)\n  \u2514\u2500\u2500 Rules (SKU, category, transaction amount conditions)\n  \u2514\u2500\u2500 Effects (give_points, multiply_points, percentage_discount)\n  \u2514\u2500\u2500 Targeting (segments, tiers for audience)\n\nSegment (member audience grouping)\n  \u2514\u2500\u2500 Parts (groups of criteria - OR logic between parts)\n      \u2514\u2500\u2500 Criteria (conditions - AND logic within part)\n          Types: transaction_count (working; requires min+max). Other types may be rejected by the API.\n\nAchievement (gamification goals)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update)\n  \u2514\u2500\u2500 CompleteRule (periodGoal, period type, unique counting)\n  \u2514\u2500\u2500 Badge (visual reward when completed)\n\nBadge (visual recognition)\n  \u2514\u2500\u2500 Linked to achievements via badgeTypeId\n  \u2514\u2500\u2500 Auto-created when referenced by achievement\n\n## Key Workflows\n\n### 1. Create 3-tier Loyalty Program:\nwallet_type_list \u2192 tierset_create \u2192 tierset_get \u2192 tierset_update_tiers\n\n### 2. Register and Reward Member:\nmember_create \u2192 points_add (welcome bonus) \u2192 member_get (verify)\n\n### 3. Record Purchase and Earn Points:\ntransaction_create (with customerData) \u2192 triggers campaigns \u2192 points auto-added\n\n### 4. Redeem Reward:\nreward_list \u2192 reward_buy (deducts points) \u2192 reward_redeem (mark coupon used)\n\n### 5. Assign Unmatched Transaction:\ntransaction_list (matched=false) \u2192 transaction_assign_member \u2192 points earned\n\n### 6. Check Member Tier Progress:\nmember_get_tier_progress \u2192 shows current tier, next tier, progress %\n\n### 7. Double Points for VIP Members:\nsegment_create (with transaction_count criteria) \u2192 campaign_create (targeting that segment with give_points effect and pointsRule: \"transaction.grossValue * 2\")\n\n### 8. Purchase Achievement with Badge:\nbadge_list (find or note badgeTypeId) \u2192 achievement_create (type+trigger+aggregation+period required, badgeTypeId)\n\n### 9. Create Targeted Promotion:\nsegment_create (define audience) \u2192 campaign_create (type: earning, target: segment, segmentIds: [segmentId])\n\n### 10. Track Member Gamification:\nachievement_list_member_achievements \u2192 badge_get_member_badges \u2192 achievement_get_member_progress\n\n## Discovery Paths:\n- Members: member_list \u2192 member_get \u2192 points_get_balance\n- Tiers: tierset_list \u2192 tierset_get \u2192 tierset_get_tiers\n- Rewards: reward_category_list \u2192 reward_list \u2192 reward_get\n- Transactions: transaction_list \u2192 transaction_get\n- Campaigns: campaign_list \u2192 campaign_get \u2192 campaign_simulate\n- Segments: segment_list \u2192 segment_get \u2192 segment_get_members \u2192 campaign_create (audience targeting)\n- Achievements: achievement_list \u2192 badge_list \u2192 achievement_create (with badge)\n- Member Gamification: achievement_list_member_achievements \u2192 badge_get_member_badges\n\n## Important Patterns:\n- conditionId REQUIRED for tier thresholds - call tierset_get after tierset_create\n- Points operations: check balance with points_get_balance before spending\n- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used\n- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)\n\n### Pagination:\n- Traditional pagination: use page + perPage params\n- Cursor pagination: provide cursor from previous response for efficient deep pagination\n- Cursor-enabled tools: member_list, transaction_list, points_get_history\n- First scroll request: cursor=\"\" (empty string)\n- Subsequent requests: use cursor value from previous response\n- When cursor provided, page param is ignored\n\n### Campaign Patterns:\n- Campaign types: direct (standard), referral (referral programs)\n- Triggers: transaction (purchase), custom_event, time, achievement, etc.\n- Effects: give_points, give_reward, deduct_unit\n- Target campaigns to segments or tiers using audience.target: \"segment\" and audience.segments array\n- campaign_create requires activity.startsAt, rules[].name, and effects[].effect (use key effect, not type). pointsRule is a STRING expression.\n\n### Points Expression (pointsRule):\npointsRule is a STRING expression, not an object. Examples:\n- Fixed: \"100\"\n- Per dollar: \"transaction.grossValue * 10\"\n- Category-based: \"transaction.category('electronics').grossValue * 5\"\n- Capped: \"(transaction.grossValue * 2 >= 100) ? 100 : transaction.grossValue * 2\"\n- Rounded: \"round_up(0.1 * transaction.grossValue)\"\n\n### Segment Patterns:\n- Parts use OR logic (member matches ANY part)\n- Criteria within a part use AND logic (member must match ALL criteria in that part)\n- Common criteria: transaction_count (working; requires min+max). Other criteria may be rejected by the API.\n\n### Achievement Patterns:\n- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update\n- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)\n- period.type defines timeframe: day, week, month, year, last_day, calendarDays, calendarWeeks, calendarMonths, calendarYears\n- aggregation.type defines counting method: quantity (count events only)\n- Link to badge via badgeTypeId - badge auto-created if doesn't exist\n- uniqueAttribute for counting distinct values (e.g., unique products)\n\n### Achievement Period Types:\n- \"day\": Count all-time when consecutive=1\n- \"week\": Count per week (use consecutive=1 for all-time weekly tracking)\n- \"month\": Count per month\n- \"year\": Count per year\n- \"last_day\": Rolling window of N days (e.g., value: 7 for last 7 days)\n- \"calendarDays\": Reset daily at midnight\n- \"calendarWeeks\": Reset weekly (Monday)\n- \"calendarMonths\": Reset monthly (1st of month)\n- \"calendarYears\": Reset yearly (January 1st)\n\n### Streak Achievement Example (7-day login streak):\n{\n  \"rules\": [{\n    \"trigger\": \"custom_event\",\n    \"event\": \"app_login\",\n    \"type\": \"direct\",\n    \"aggregation\": {\"type\": \"quantity\"},\n    \"completeRule\": {\n      \"periodGoal\": 1,\n      \"period\": {\"type\": \"last_day\", \"value\": 7, \"consecutive\": 1}\n    },\n    \"limit\": {\n      \"interval\": {\"type\": \"calendarDays\", \"value\": 1},\n      \"value\": 1\n    }\n  }]\n}\n\n### Custom Event Workflows:\n\n#### Create Custom Event Campaign:\n1. custom_event_schema_list \u2192 Check if event type exists\n2. custom_event_schema_create (if needed) \u2192 Define event type and fields\n3. campaign_create with trigger: \"custom_event\", event: \"{event_type}\"\n4. Send events via custom_event_send to trigger campaign\n\n#### Create Achievement with Custom Event:\n1. custom_event_schema_create \u2192 Define event (e.g., \"location_visit\")\n2. achievement_create with:\n   - rules[].trigger: \"custom_event\"\n   - rules[].event: \"{event_type}\"\n   - rules[].type: \"direct\"\n   - rules[].aggregation.type: \"quantity\"\n   - rules[].completeRule.periodGoal: {count}\n   - rules[].completeRule.period: { type: \"day\", consecutive: 1 } (all-time)\n\n#### Create Campaign Triggered by Achievement:\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with effects (give_points, give_reward)\n\n### Condition Operators (for campaigns/achievements):\n- is_equal, is_not_equal\n- gte, gt, lte, lt\n- is_between, is_not_between\n- is_time_between\n- is_day_of_week, is_day_of_month\n- contains, not_contains\n- starts_with, ends_with\n- one_of, not_one_of\n- expression (for custom logic)\n\n## Common Campaign Patterns (Industry-Agnostic)\n\nThese patterns work for any loyalty program - retail, QSR, aviation, fan engagement, hospitality, etc.\n\n### Pattern 1: Count Events Toward Goal (Achievements)\nUse case: Track member actions (visits, purchases, logins, check-ins) toward a milestone.\n1. custom_event_schema_create \u2192 Define your action type (e.g., \"store_visit\", \"app_login\")\n2. achievement_create with:\n   - trigger: \"custom_event\"\n   - event: \"{your_event_code}\"\n   - aggregation: { type: \"quantity\" }\n   - completeRule: { periodGoal: {count}, period: { type: \"day\", consecutive: 1 } }\n3. custom_event_send to log each action\n\n### Pattern 2: Points Per Action (Instant Rewards)\nUse case: Award instant points for each qualifying action.\n1. custom_event_schema_create (if not using transaction)\n2. campaign_create with:\n   - trigger: \"custom_event\" (or \"transaction\")\n   - event: \"{event_code}\" (for custom events)\n   - rules: [{ effects: [{ effect: \"give_points\", pointsRule: \"50\" }] }]\n\n### Pattern 3: Conditional Rewards (Bonus Conditions)\nUse case: Award points only when a condition is met (e.g., early arrival, large purchase).\nUse ternary expressions in pointsRule instead of conditions array:\n- pointsRule: \"event.body.minutes_before >= 60 ? 25 : 0\"\n- pointsRule: \"transaction.grossValue >= 100 ? 50 : 0\"\n\n### Pattern 4: Execution Limits (Anti-Fraud)\nUse case: Limit rewards to prevent abuse (once per day, once per week).\nCampaign limits structure:\n{\n  \"limits\": {\n    \"executionsPerMember\": {\n      \"value\": 1,\n      \"interval\": { \"type\": \"calendarDays\", \"value\": 1 }\n    }\n  }\n}\nNote: Use \"calendarDays\" (not \"days\"), \"calendarWeeks\", \"calendarMonths\", \"calendarYears\".\nOmit interval entirely for lifetime/forever limit.\n\n### Pattern 5: Achievement-Triggered Bonus\nUse case: Award bonus points/rewards when member completes an achievement.\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with give_points or give_reward effect\n\n### Pattern 6: Tiered Milestones\nUse case: Multiple achievement levels (bronze/silver/gold, 5/10/25 visits).\nCreate multiple achievements with increasing periodGoal values,\neach linked to a different bonus campaign with increasing rewards.\n\n### Pattern 7: Time-Limited Promotion\nUse case: Seasonal or promotional campaigns.\n{\n  \"activity\": {\n    \"startsAt\": \"2026-01-01 00:00+00:00\",\n    \"endsAt\": \"2026-03-31 23:59+00:00\"\n  }\n}\n\n### Pattern 8: Streak Tracking\nUse case: Reward consecutive daily/weekly actions (login streaks, workout streaks).\nAchievement with:\n- completeRule.period: { type: \"last_day\", value: 7 } (rolling 7-day window)\n- limit: { value: 1, interval: { type: \"calendarDays\", value: 1 } } (max 1 per day)\n\n## Phase 3: Analytics, Admin, Roles & Stores\n\n### Domain Model (Extended)\n\nAdmin (system user)\n  \u2514\u2500\u2500 Roles (permission sets)\n      \u2514\u2500\u2500 Permissions (resource + access level)\n  \u2514\u2500\u2500 API Keys (programmatic access)\n\nStore (multi-tenant container)\n  \u2514\u2500\u2500 Members, Campaigns, Rewards (isolated per store)\n\nAudit Log (compliance tracking)\n  \u2514\u2500\u2500 eventType, entityType, entityId, username, timestamp\n\n### Analytics Workflows:\n\n#### 11. Get Program Overview:\nanalytics_dashboard \u2192 analytics_tiers \u2192 analytics_members\n\n#### 12. Analyze Points Economy:\nanalytics_points \u2192 analytics_units (per wallet) \u2192 points_get_histogram\n\n#### 13. Measure Campaign Performance:\nanalytics_campaigns \u2192 analytics_campaign_detail (specific campaign)\n\n#### 14. Track Transactions:\nanalytics_transactions \u2192 transaction_list (details)\n\n### Aggregation Queries (Top Spenders, Purchase Analysis):\n\nIMPORTANT: For queries like \"top 5 spenders in July 2025\", use this approach:\n\n#### 15. Find Top Spenders by Date Range:\n1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction\n2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions\n3. Aggregate grossValue by customerId in your code\n4. Sort by total spent, take top N\n5. member_get for each top spender to get names/details\n\nCRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:\n- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach\n- DO NOT skip pages or try to sample data - you will get inaccurate results\n- DO NOT use transaction_get individually - transaction_list already includes customerId\n- DO NOT try to find \"smarter\" analytics endpoints - they don't exist for per-customer aggregation\n- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty\n- Start with cursor='' (empty string), use returned cursor for next request, repeat until done\n\nExample: Top 5 spenders July 2025\n- First request: transaction_list(purchasedAtFrom: \"2025-07-01\", purchasedAtTo: \"2025-07-31\", perPage: 50, cursor: \"\")\n- Each result includes: transactionId, grossValue, customerId, purchasedAt\n- Keep fetching with returned cursor until response has no cursor or empty transactions\n- Even if there are 1500 transactions (30 pages), iterate through ALL of them\n- Group by customerId, sum grossValue, sort descending, take 5\n\n### Admin & Security Workflows:\n\n#### 15. Create Admin with Limited Role:\nacl_get_resources \u2192 role_create \u2192 admin_create (with roleId)\n\n#### 16. Generate API Key for Integration:\nadmin_get \u2192 apikey_create \u2192 SAVE TOKEN IMMEDIATELY (shown once!)\n\n#### 17. Audit User Actions:\naudit_list (filter by username/entity) \u2192 audit_export (compliance report)\n\n### Store Multi-Tenancy:\n\n#### 18. Create New Store:\nstore_create \u2192 configure campaigns/tiers \u2192 member_create (with storeCode)\n\n### Analytics Query Patterns:\n- All analytics tools support dateFrom/dateTo ISO date filters\n- analytics_dashboard: high-level program metrics\n- analytics_units: wallet-specific metrics (requires walletTypeCode)\n- analytics_campaign_detail: detailed metrics for single campaign\n\n### Admin \u2192 Role \u2192 Permission Model:\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  Admin  \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Role \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Permission \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n     \u2502                            \u2502\n     \u2502                       resource + access\n     \u2502                       (VIEW, MODIFY, etc.)\n     \u25BC\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 API Key \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n### Store Multi-Tenancy:\n- Each store is isolated: members, campaigns, rewards, transactions\n- storeCode parameter routes requests to correct tenant\n- Default store used when storeCode omitted\n- IMPORTANT: Do NOT pass storeCode parameter unless the user explicitly asks to work with a different store. The configured default store should always be used unless the user requests otherwise.\n\n## Phase 4: Webhooks, Import & Export\n\n### Domain Model (Extended)\n\nWebhook Subscription (event notification)\n  \u2514\u2500\u2500 eventName (event to subscribe to)\n  \u2514\u2500\u2500 url (callback endpoint)\n  \u2514\u2500\u2500 headers (custom HTTP headers)\n\nImport (bulk data upload)\n  \u2514\u2500\u2500 type: member, groupValue, segmentMembers, unitTransferAdding, etc.\n  \u2514\u2500\u2500 status: pending, processing, succeed, failed\n  \u2514\u2500\u2500 items (individual row results)\n\nExport (bulk data download)\n  \u2514\u2500\u2500 type: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n  \u2514\u2500\u2500 status: pending, done, failed, error\n  \u2514\u2500\u2500 CSV file (when status='done')\n\n### Webhook Workflows:\n\n#### 19. Subscribe to Member Events for CRM Sync:\nwebhook_events \u2192 webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')\n\n#### 20. List and Manage Subscriptions:\nwebhook_list \u2192 webhook_get \u2192 webhook_update or webhook_delete\n\n### Import Workflows:\n\n#### 21. Bulk Import Members from CSV:\nimport_create (type: 'member', fileContent: CSV data) \u2192 import_list \u2192 import_get (check status)\n\n#### 22. Bulk Add Points to Members:\nimport_create (type: 'unitTransferAdding', fileContent: CSV) \u2192 poll import_get until complete\n\n### Export Workflows:\n\n#### 23. Export Campaign Codes:\nexport_create (type: 'campaignCode', filters: { campaignId }) \u2192 poll export_get (until status='done') \u2192 export_download\n\n#### 24. Export Member Data:\nexport_create (type: 'member') \u2192 export_get \u2192 export_download (returns CSV)\n\n### Webhook Patterns:\n- Use webhook_events to discover available event types before subscribing\n- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }\n- Common events: member.created, member.updated, transaction.created, reward.purchased\n\n### Import Patterns:\n- Import is async: create returns importId, poll status with import_get\n- CSV format required - provide plain text, not base64\n- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon\n\n### Export Patterns:\n- Export is async: create returns exportId, poll status until 'done'\n- API body wrapper varies by type: { campaignCode: { filters... } }\n- Only call export_download when status='done'\n- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n";