@open-loyalty/mcp-server 1.3.6 → 1.3.7

package/dist/tools/achievement/index.js

@@ -17,16 +17,16 @@ export const achievementToolDefinitions = [
         name: "ol_achievement_create",
         title: "Create Achievement",
         description: "Create achievement with rules that track member progress. " +
-            "REQUIRED fields in each rule: " +
-            "1. type: 'direct' (or 'referral'), " +
-            "2. trigger: event type (transaction, custom_event, points_transfer, etc.), " +
-            "3. aggregation: { type: 'quantity' } (only 'quantity' is supported), " +
-            "4. completeRule: { periodGoal: number, period: { type: 'day', consecutive: 1 } }. " +
-            "period.type must be one of: day, week, month, year, last_day, calendarDays, calendarWeeks, calendarMonths, calendarYears. " +
-            "All-time tracking uses type='day' with consecutive=1. " +
-            "For custom_event trigger, also include event: 'your_event_code'. " +
-            "Example - Count 5 custom events: { type: 'direct', trigger: 'custom_event', event: 'app_checkin', aggregation: { type: 'quantity' }, completeRule: { periodGoal: 5, period: { type: 'day', consecutive: 1 } } }. " +
-            "For streaks, use consecutive > 1 with limit: { value: 1, interval: { type: 'calendarDays', value: 1 } }.",
+            "⭐ TWO MAIN PATTERNS: " +
+            "1️⃣ ONE-TIME BADGE (e.g., 'First Purchase', 'Welcome'): " +
+            "• Set achievement-level limit: { value: 1 } (earn once ever). " +
+            "• Rule completeRule: { periodGoal: 1, period: { type: 'day', consecutive: 1 } }. " +
+            "• NO rule-level limit needed. " +
+            "2️⃣ STREAK BADGE (e.g., '7-day streak'): " +
+            "• Rule completeRule: { periodGoal: 1, period: { type: 'calendarDays', consecutive: 7 } }. " +
+            "• Rule limit: { value: 1, interval: { type: 'calendarDays', value: 1 } } (count 1 per day). " +
+            "REQUIRED in each rule: type='direct', trigger (transaction/custom_event/etc), aggregation: { type: 'quantity' }, completeRule. " +
+            "⚠️ COMMON MISTAKE: Using streak pattern for one-time badges. For one-time, use consecutive=1 with NO rule limit.",
         readOnly: false,
         inputSchema: AchievementCreateInputSchema,
         handler: achievementCreate,

package/dist/tools/achievement/schemas.js

@@ -40,11 +40,15 @@ const AchievementRuleInputSchema = z.object({
     completeRule: z.object({
         periodGoal: z.union([z.number(), z.string()]).describe("Goal value to reach (e.g., 5 for 5 purchases, 100 for 100 points)."),
         period: z.object({
-            type: AchievementPeriodTypeEnum.describe("Period type: 'day' (all-time when consecutive=1), 'last_day' (rolling N days), " +
-                "'calendarDays' (reset daily), 'calendarWeeks' (reset weekly), 'calendarMonths' (reset monthly)."),
-            value: z.number().optional().describe("Period value (e.g., 7 for last 7 days when type='last_day')."),
-            consecutive: z.number().min(1).describe("Required consecutive periods. Use 1 for all-time tracking, 7 for weekly streaks, etc."),
-        }).describe("Period configuration. REQUIRED: both type and consecutive must be provided."),
+            type: AchievementPeriodTypeEnum.describe("Period type. For ONE-TIME achievements: use 'day'. For STREAKS: use 'calendarDays'. " +
+                "Options: 'day' (all-time), 'last_day' (rolling), 'calendarDays/Weeks/Months/Years' (calendar-based)."),
+            value: z.number().optional().describe("Period value (e.g., 7 for 'last 7 days' when type='last_day'). Usually omit for simple achievements."),
+            consecutive: z.number().min(1).describe("⭐ CONSECUTIVE PERIODS: For ONE-TIME achievements (first purchase): use consecutive=1. " +
+                "For STREAKS (7 consecutive days): use consecutive=7 with type='calendarDays'. " +
+                "consecutive=1 means 'no streak required' - just reach the goal once."),
+        }).describe("Period configuration. REQUIRED: both type and consecutive must be provided. " +
+            "ONE-TIME PATTERN: { type: 'day', consecutive: 1 } - reach goal anytime, no streak. " +
+            "STREAK PATTERN: { type: 'calendarDays', consecutive: 7 } - reach goal for 7 consecutive days."),
         uniqueAttribute: z.string().optional().describe("Attribute for unique counting (e.g., 'sku' to count unique products)."),
     }).describe("Completion goal configuration."),
     aggregation: z.object({
@@ -57,7 +61,8 @@ const AchievementRuleInputSchema = z.object({
             type: z.string().describe("Interval type: 'calendarDays', 'calendarWeeks', etc."),
             value: z.number().optional().describe("Interval value."),
         }).optional().describe("Time interval for the limit."),
-    }).optional().describe("Per-rule execution limit (use for streak patterns: limit 1 per day)."),
+    }).optional().describe("⚠️ RULE LIMIT - ONLY for STREAKS. For ONE-TIME achievements, DO NOT set rule limit. " +
+        "For STREAKS: use { value: 1, interval: { type: 'calendarDays', value: 1 } } to count max 1 event per day."),
     uniqueReferee: z.boolean().optional().describe("Whether referee must be unique (for referral achievements)."),
 });
 export const AchievementListInputSchema = {
@@ -80,12 +85,15 @@ export const AchievementCreateInputSchema = {
         operator: z.string().optional().describe("Activity condition operator."),
     }).optional().describe("Time period configuration."),
     limit: z.object({
-        value: z.number().optional().describe("Maximum completions."),
+        value: z.number().optional().describe("Maximum completions (e.g., 1 for one-time badges)."),
         interval: z.object({
             type: z.string(),
             value: z.number().optional(),
         }).optional(),
-    }).optional().describe("Overall limit configuration."),
+    }).optional().describe("⭐ ACHIEVEMENT LIMIT: How many times a member can earn this achievement. " +
+        "For ONE-TIME badges (like 'First Purchase'): set limit.value=1 with NO interval. " +
+        "For repeatable achievements: omit limit or set higher value. " +
+        "IMPORTANT: Without limit.value=1, members can earn the badge unlimited times!"),
     rules: z.array(AchievementRuleInputSchema).describe("Achievement rules defining completion criteria."),
     badgeTypeId: z.string().optional().describe("Badge type ID to award upon completion. " +
         "NOTE: This field may cause 'extra fields' validation errors in some API versions. " +

package/dist/tools/reward/handlers.d.ts

@@ -35,9 +35,6 @@ export declare function rewardCreate(input: {
         from: string;
         to: string;
     };
-    usageLimit?: {
-        perUser: number;
-    };
     costInPoints?: number;
     usageInstruction?: string;
     active?: boolean;
@@ -67,6 +64,7 @@ export declare function rewardUpdate(input: {
     categories?: string[];
     levels?: string[];
     segments?: string[];
+    usageLimitPerUser?: number;
 }): Promise<void>;
 export declare function rewardActivate(input: {
     storeCode?: string;

package/dist/tools/reward/handlers.js

@@ -47,18 +47,15 @@ export async function rewardList(input) {
 export async function rewardCreate(input) {
     const storeCode = getStoreCode(input.storeCode);
     // API requires: translations (name only), reward (type), activity, visibility
-    // NOTE: usageLimit only accepts { perUser: N } - API rejects 'general' as extra field
+    // NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
+    // Use reward_update after creation to set usageLimit
     // NOTE: description is NOT supported by the API at creation time
-    // Sanitize usageLimit - ONLY pass perUser, strip any other fields (like 'general')
-    const sanitizedUsageLimit = input.usageLimit?.perUser !== undefined
-        ? { perUser: input.usageLimit.perUser }
-        : undefined;
     const payload = omitUndefined({
         translations: input.translations,
         reward: input.reward,
         activity: input.activity,
         visibility: input.visibility,
-        usageLimit: sanitizedUsageLimit,
+        // usageLimit: NOT SUPPORTED at creation - use update after creation
         costInPoints: input.costInPoints,
         usageInstruction: input.usageInstruction,
         active: input.active,
@@ -98,7 +95,6 @@ export async function rewardUpdate(input) {
     const existing = await apiGet(`/${storeCode}/reward/${input.rewardId}`);
     // Extract only the fields that PUT accepts (API is strict about extra fields)
     // Note: GET returns name at root level, but PUT expects it in translations.en.name
-    // Note: usageLimit is NOT supported by the API - it rejects it as "extra fields"
     const existingName = existing.name;
     const existingActivity = existing.activity;
     const existingVisibility = existing.visibility;
@@ -168,6 +164,10 @@ export async function rewardUpdate(input) {
         payload.levels = input.levels;
     if (input.segments !== undefined)
         payload.segments = input.segments;
+    // usageLimit - only pass perUser (API rejects 'general' as extra field)
+    if (input.usageLimitPerUser !== undefined) {
+        payload.usageLimit = { perUser: input.usageLimitPerUser };
+    }
     try {
         await apiPut(`/${storeCode}/reward/${input.rewardId}`, { reward: payload });
     }

package/dist/tools/reward/index.d.ts

@@ -68,13 +68,6 @@ export declare const rewardToolDefinitions: readonly [{
             from: string;
             to: string;
         }>;
-        usageLimit: import("zod").ZodOptional<import("zod").ZodObject<{
-            perUser: import("zod").ZodNumber;
-        }, "strict", import("zod").ZodTypeAny, {
-            perUser: number;
-        }, {
-            perUser: number;
-        }>>;
         costInPoints: import("zod").ZodOptional<import("zod").ZodNumber>;
         usageInstruction: import("zod").ZodOptional<import("zod").ZodString>;
         active: import("zod").ZodOptional<import("zod").ZodBoolean>;
@@ -100,7 +93,7 @@ export declare const rewardToolDefinitions: readonly [{
 }, {
     readonly name: "ol_reward_update";
     readonly title: "Update Reward";
-    readonly description: "Update reward configuration. Cannot change reward type after creation.";
+    readonly description: string;
     readonly readOnly: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
@@ -112,6 +105,7 @@ export declare const rewardToolDefinitions: readonly [{
         categories: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         levels: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
         segments: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString, "many">>;
+        usageLimitPerUser: import("zod").ZodOptional<import("zod").ZodNumber>;
     };
     readonly handler: typeof rewardUpdate;
 }, {

package/dist/tools/reward/index.js

@@ -25,9 +25,10 @@ export const rewardToolDefinitions = [
             "2. reward: 'material' or 'static_coupon' or 'dynamic_coupon', " +
             "3. activity: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }, " +
             "4. visibility: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }. " +
-            "Types: material (physical goods), static_coupon (fixed discount), dynamic_coupon (variable value). " +
-            "For coupons: add couponValue, couponValueType ('money' or 'percentage'), daysValid. " +
-            "For tier targeting: set target='level' and levels=['tier-uuid-1', 'tier-uuid-2'].",
+            "Types: material (physical goods), static_coupon (fixed discount - requires couponValue), dynamic_coupon (variable value). " +
+            "For coupons: add couponValue (required!), couponValueType ('money' or 'percentage'), daysValid. " +
+            "For tier targeting: set target='level' and levels=['tier-uuid-1', 'tier-uuid-2']. " +
+            "⚠️ usageLimit is NOT supported at creation - use reward_update after creation to set limits.",
         readOnly: false,
         inputSchema: RewardCreateInputSchema,
         handler: rewardCreate,
@@ -43,7 +44,8 @@ export const rewardToolDefinitions = [
     {
         name: "ol_reward_update",
         title: "Update Reward",
-        description: "Update reward configuration. Cannot change reward type after creation.",
+        description: "Update reward configuration. Cannot change reward type after creation. " +
+            "Use usageLimitPerUser to set maximum redemptions per member (this is NOT supported at creation time).",
         readOnly: false,
         inputSchema: RewardUpdateInputSchema,
         handler: rewardUpdate,

package/dist/tools/reward/schemas.d.ts

@@ -55,13 +55,6 @@ export declare const RewardCreateInputSchema: {
         from: string;
         to: string;
     }>;
-    usageLimit: z.ZodOptional<z.ZodObject<{
-        perUser: z.ZodNumber;
-    }, "strict", z.ZodTypeAny, {
-        perUser: number;
-    }, {
-        perUser: number;
-    }>>;
     costInPoints: z.ZodOptional<z.ZodNumber>;
     usageInstruction: z.ZodOptional<z.ZodString>;
     active: z.ZodOptional<z.ZodBoolean>;
@@ -87,6 +80,7 @@ export declare const RewardUpdateInputSchema: {
     categories: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     levels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     segments: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    usageLimitPerUser: z.ZodOptional<z.ZodNumber>;
 };
 export declare const RewardIdInputSchema: {
     storeCode: z.ZodOptional<z.ZodString>;

package/dist/tools/reward/schemas.js

@@ -26,11 +26,8 @@ const RewardVisibilityInputSchema = z.object({
     from: z.string().describe("Visibility start datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
     to: z.string().describe("Visibility end datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
 });
-// Usage limit schema - API only accepts perUser (NOT general)
-// Using .strict() to reject extra fields with clear error
-const RewardUsageLimitInputSchema = z.object({
-    perUser: z.number().describe("Maximum redemptions per member. This is the ONLY supported field."),
-}).strict().describe("Usage limits. ⚠️ ONLY 'perUser' is supported. Do NOT pass 'general' or any other field - they will be rejected.");
+// NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
+// Use reward_update with usageLimitPerUser after creation instead
 export const RewardCreateInputSchema = {
     storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     translations: RewardTranslationsInputSchema.describe("Reward name translations. At least 'en' key with { name } is REQUIRED."),
@@ -38,7 +35,7 @@ export const RewardCreateInputSchema = {
         "conversion_coupon (converts points to coupon), material (physical goods), fortune_wheel (gamified)."),
     activity: RewardActivityInputSchema.describe("Activity period when reward can be purchased. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
     visibility: RewardVisibilityInputSchema.describe("Visibility period when reward is shown. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
-    usageLimit: RewardUsageLimitInputSchema.optional().describe("Usage limits. Only perUser is supported by API."),
+    // usageLimit: NOT SUPPORTED at creation - removed. Use reward_update after creation.
     costInPoints: z.number().optional().describe("Points required to redeem this reward."),
     usageInstruction: z.string().optional().describe("Instructions for using the reward."),
     active: z.boolean().optional().describe("Whether reward is active (default: false)."),
@@ -64,6 +61,7 @@ export const RewardUpdateInputSchema = {
     categories: z.array(z.string()).optional().describe("Array of category UUIDs."),
     levels: z.array(z.string()).optional().describe("Array of tier level UUIDs."),
     segments: z.array(z.string()).optional().describe("Array of segment UUIDs."),
+    usageLimitPerUser: z.number().optional().describe("Maximum redemptions per member. Set this after creation to limit usage."),
 };
 export const RewardIdInputSchema = {
     storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),

package/dist/tools/wallet-type.js

@@ -261,7 +261,8 @@ export const walletTypeToolDefinitions = [
             "• code: Unique identifier (auto-generated if omitted, cannot change later). " +
             "• allowNegativeBalance: true/false (default: false). " +
             "• unitExpiryDate: Annual expiry in 'MM-DD' format (e.g., '12-31'). " +
-            "• unitDaysLocked: Days before points become spendable (0 for immediate). " +
+            "• allTimeNotLocked: TRUE = 'No pending' (points immediately available). " +
+            "• unitDaysLocked: Only if allTimeNotLocked=false, set days for pending period. " +
             "⚠️ NOT SUPPORTED AT CREATION: 'active' and 'limits' - use ol_wallet_type_update after creation. " +
             "⏰ NOTE: New wallets are 'blocked' for ~2 minutes after creation - wait before updating. " +
             "💡 EXAMPLE: { translations: { en: { name: 'Bonus Points' } }, unitSingularName: 'point', " +
@@ -283,6 +284,7 @@ export const walletTypeToolDefinitions = [
             "• allowNegativeBalance: Allow/disallow negative balances. " +
             "• limits: Update earning limits (same format as create). " +
             "• Expiry settings: unitExpiryDate, unitDaysExpiryAfter, etc. " +
+            "• ⭐ PENDING: allTimeNotLocked=true for 'No pending', or =false with unitDaysLocked for pending period. " +
             "💡 TIP: Use ol_wallet_type_get(walletTypeId) first to see current configuration.",
         readOnly: false,
         inputSchema: WalletTypeUpdateInputSchema,

package/dist/types/schemas/wallet-type.js

@@ -75,9 +75,11 @@ export const WalletTypeCreateInputSchema = {
         "IMPORTANT: Use 'MM-DD' format, NOT 'YYYY-MM-DD'."),
     unitDaysActiveCount: z.number().int().nonnegative().optional().describe("Number of days points remain active after earning. Use with unitDaysExpiryAfter."),
     unitYearsActiveCount: z.number().int().nonnegative().optional().describe("Number of years points remain active after earning."),
-    unitDaysLocked: z.number().int().nonnegative().optional().describe("Number of days points are locked after earning before becoming spendable. " +
-        "Use 0 or omit for immediately available points."),
-    allTimeNotLocked: z.boolean().optional().describe("If true, points are never locked and immediately available. Overrides unitDaysLocked."),
+    unitDaysLocked: z.number().int().nonnegative().optional().describe("Number of days points are PENDING (locked) after earning before becoming spendable. " +
+        "Only used when allTimeNotLocked is false. Example: 7 for a 7-day pending period."),
+    allTimeNotLocked: z.boolean().optional().describe("⭐ PENDING METHOD: Set to TRUE for 'No pending' (points immediately available). " +
+        "Set to FALSE (or omit) for 'Pending for X days' mode, then set unitDaysLocked to the number of days. " +
+        "This maps to the 'Unit pending method' dropdown in the UI."),
 };
 export const WalletTypeUpdateInputSchema = {
     storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
@@ -93,6 +95,6 @@ export const WalletTypeUpdateInputSchema = {
     unitDaysExpiryAfter: z.string().optional().describe("Update days until expiry or 'all_time_active'."),
     unitDaysActiveCount: z.number().int().nonnegative().optional().describe("Update days active count."),
     unitYearsActiveCount: z.number().int().nonnegative().optional().describe("Update years active count."),
-    unitDaysLocked: z.number().int().nonnegative().optional().describe("Update locked days."),
-    allTimeNotLocked: z.boolean().optional().describe("Update not-locked setting."),
+    unitDaysLocked: z.number().int().nonnegative().optional().describe("Update pending period (days points are locked). Only applies when allTimeNotLocked is false."),
+    allTimeNotLocked: z.boolean().optional().describe("⭐ PENDING METHOD: Set TRUE for 'No pending' (immediate), FALSE for 'Pending for X days'."),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-loyalty/mcp-server",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "type": "module",
   "description": "MCP server for Open Loyalty API - enables AI agents to manage loyalty programs, members, points, rewards, and transactions",
   "author": "Marcin Dyguda <md@openloyalty.io>",