@open-loyalty/mcp-server 1.3.4 → 1.3.6

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

@@ -100,15 +100,15 @@ export declare const campaignToolDefinitions: readonly [{
             conditions: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
                 operator: import("zod").ZodString;
                 attribute: import("zod").ZodString;
-                data: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+                data: import("zod").ZodUnknown;
             }, "strip", import("zod").ZodTypeAny, {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }, {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }>, "many">>;
         }, "strip", import("zod").ZodTypeAny, {
             name: string;
@@ -124,7 +124,7 @@ export declare const campaignToolDefinitions: readonly [{
             conditions?: {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }[] | undefined;
             target?: "self" | "referrer" | undefined;
         }, {
@@ -141,7 +141,7 @@ export declare const campaignToolDefinitions: readonly [{
             conditions?: {
                 attribute: string;
                 operator: string;
-                data?: Record<string, unknown> | undefined;
+                data?: unknown;
             }[] | undefined;
             target?: "self" | "referrer" | undefined;
         }>, "many">;

package/dist/tools/campaign/index.js

@@ -27,8 +27,10 @@ export const campaignToolDefinitions = [
             "3. translations: { en: { name: 'Campaign Name' } }, " +
             "4. activity: { startsAt: '2026-01-01 00:00+00:00' }, " +
             "5. rules: [{ name: 'Rule Name', effects: [{ effect: 'give_points', pointsRule: 'transaction.grossValue * 10' }] }]. " +
-            "pointsRule is a STRING expression, not an object. Examples: '100' (fixed), 'transaction.grossValue * 10' (dynamic). " +
-            "To target ALL members, OMIT the audience parameter entirely - do not set audience.target='all'.",
+            "pointsRule is a STRING expression. Examples: '100' (fixed), 'transaction.grossValue * 10' (dynamic). " +
+            "CONDITIONS: Use operator='is_greater_or_equal' (NOT 'gte'), attribute='transaction.grossValue', data=100. " +
+            "For labels: operator='has_at_least_one_label', attribute='transaction.labels', data=[{key:'name',value:'val'}]. " +
+            "To target ALL members, OMIT the audience parameter entirely.",
         readOnly: false,
         inputSchema: CampaignCreateInputSchema,
         handler: campaignCreate,

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

@@ -495,15 +495,15 @@ export declare const CampaignCreateInputSchema: {
         conditions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             operator: z.ZodString;
             attribute: z.ZodString;
-            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            data: z.ZodUnknown;
         }, "strip", z.ZodTypeAny, {
             attribute: string;
             operator: string;
-            data?: Record<string, unknown> | undefined;
+            data?: unknown;
         }, {
             attribute: string;
             operator: string;
-            data?: Record<string, unknown> | undefined;
+            data?: unknown;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         name: string;
@@ -519,7 +519,7 @@ export declare const CampaignCreateInputSchema: {
         conditions?: {
             attribute: string;
             operator: string;
-            data?: Record<string, unknown> | undefined;
+            data?: unknown;
         }[] | undefined;
         target?: "self" | "referrer" | undefined;
     }, {
@@ -536,7 +536,7 @@ export declare const CampaignCreateInputSchema: {
         conditions?: {
             attribute: string;
             operator: string;
-            data?: Record<string, unknown> | undefined;
+            data?: unknown;
         }[] | undefined;
         target?: "self" | "referrer" | undefined;
     }>, "many">;

package/dist/tools/campaign/schemas.js

@@ -25,10 +25,23 @@ const CampaignEffectInputSchema = z.object({
     customAttributeValueRule: z.string().optional().describe("Custom attribute value rule."),
 });
 // Condition input schema
+// Valid operators: is_equal, is_not_equal, is_greater, is_greater_or_equal, is_less, is_less_or_equal,
+// contains, not_contains, contains_one_of, not_contains_one_of, has_at_least_one_label,
+// is_one_of, is_not_one_of, starts_with, ends_with, matches_regex,
+// is_day_of_week, is_month_of_year, is_day_of_month, is_between, is_not_between, is_after, is_before
 const CampaignConditionInputSchema = z.object({
-    operator: z.string().describe("Condition operator (is_equal, gte, lte, etc.)."),
-    attribute: z.string().describe("Attribute to check."),
-    data: z.record(z.unknown()).optional().describe("Condition-specific data."),
+    operator: z.string().describe("Condition operator. Valid values: " +
+        "is_equal, is_not_equal, is_greater, is_greater_or_equal, is_less, is_less_or_equal, " +
+        "contains, not_contains, has_at_least_one_label, is_one_of, is_not_one_of, " +
+        "starts_with, ends_with, matches_regex, is_between, is_not_between, is_after, is_before. " +
+        "⚠️ Do NOT use 'gte', 'eq' - use full names like 'is_greater_or_equal', 'is_equal'."),
+    attribute: z.string().describe("Attribute path to check (e.g., 'transaction.grossValue', 'transaction.labels', 'customer.email'). " +
+        "Use full path with context prefix."),
+    data: z.unknown().describe("Condition value. Format depends on operator: " +
+        "• Number for is_greater/is_less/etc: 100 " +
+        "• String for contains/starts_with/etc: 'value' " +
+        "• Array for is_one_of/contains_one_of: ['a', 'b'] " +
+        "• Label array for has_at_least_one_label: [{key: 'name', value: 'val'}]"),
 });
 // Rule input schema
 const CampaignRuleInputSchema = z.object({

package/dist/tools/points.js

@@ -82,12 +82,15 @@ export async function pointsSpend(input) {
     catch (error) {
         // Check for insufficient points error - API returns various formats:
         // "NotEnoughPoints", "insufficient", "not enough points" (lowercase)
-        // Must check both error.message AND axios response data
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Must check error.message, data.message, AND data.errors array
         const axiosError = error;
-        const responseMessage = axiosError.response?.data?.message || "";
-        const combinedMessage = `${errorMessage} ${responseMessage}`.toLowerCase();
-        if (combinedMessage.includes("notenoughpoints") || combinedMessage.includes("insufficient") || combinedMessage.includes("not enough points")) {
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : String(error),
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("notenoughpoints") || allMessages.includes("insufficient") || allMessages.includes("not enough points")) {
             throw new OpenLoyaltyError({
                 code: "INSUFFICIENT_BALANCE",
                 message: "Member does not have enough points to complete this operation",
@@ -116,12 +119,15 @@ export async function pointsTransfer(input) {
     }
     catch (error) {
         // Check for insufficient points error - API returns various formats
-        // Must check both error.message AND axios response data
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Must check error.message, data.message, AND data.errors array
         const axiosError = error;
-        const responseMessage = axiosError.response?.data?.message || "";
-        const combinedMessage = `${errorMessage} ${responseMessage}`.toLowerCase();
-        if (combinedMessage.includes("notenoughpoints") || combinedMessage.includes("insufficient") || combinedMessage.includes("not enough points")) {
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : String(error),
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("notenoughpoints") || allMessages.includes("insufficient") || allMessages.includes("not enough points")) {
             throw new OpenLoyaltyError({
                 code: "INSUFFICIENT_BALANCE",
                 message: "Sender does not have enough points to transfer",

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

@@ -35,9 +35,8 @@ export declare function rewardCreate(input: {
         from: string;
         to: string;
     };
-    usageLimit: {
+    usageLimit?: {
         perUser: number;
-        general?: number;
     };
     costInPoints?: number;
     usageInstruction?: string;

package/dist/tools/reward/handlers.js

@@ -46,14 +46,19 @@ export async function rewardList(input) {
 }
 export async function rewardCreate(input) {
     const storeCode = getStoreCode(input.storeCode);
-    // API requires: translations (name only), reward (type), activity, visibility, usageLimit.perUser
+    // API requires: translations (name only), reward (type), activity, visibility
+    // NOTE: usageLimit only accepts { perUser: N } - API rejects 'general' as extra field
     // 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: input.usageLimit,
+        usageLimit: sanitizedUsageLimit,
         costInPoints: input.costInPoints,
         usageInstruction: input.usageInstruction,
         active: input.active,
@@ -93,12 +98,12 @@ 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;
-    const existingUsageLimit = existing.usageLimit;
     // Build payload with only accepted fields - NEVER include undefined values
-    // Only include activity/visibility/usageLimit if they exist in GET response
+    // Only include activity/visibility if they exist in GET response
     const payload = {
         // translations - only include name (GET returns name at root level)
         translations: {
@@ -132,12 +137,6 @@ export async function rewardUpdate(input) {
             visibilityPayload.to = existingVisibility.to;
         payload.visibility = visibilityPayload;
     }
-    // usageLimit: BOTH perUser AND general are REQUIRED by the API
-    // The GET response may include derived fields that PUT doesn't accept
-    payload.usageLimit = {
-        perUser: existingUsageLimit?.perUser ?? 1,
-        general: existingUsageLimit?.general ?? 10000,
-    };
     // Coupon-specific fields (required for static_coupon, dynamic_coupon, conversion_coupon)
     if (existing.couponValue !== undefined)
         payload.couponValue = existing.couponValue;
@@ -215,12 +214,15 @@ export async function rewardBuy(input) {
     catch (error) {
         // Check for insufficient points error - API returns various formats:
         // "NotEnoughPoints", "insufficient", "not enough points" (lowercase)
-        // Must check both error.message AND axios response data
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Must check error.message, data.message, AND data.errors array
         const axiosError = error;
-        const responseMessage = axiosError.response?.data?.message || "";
-        const combinedMessage = `${errorMessage} ${responseMessage}`.toLowerCase();
-        if (combinedMessage.includes("notenoughpoints") || combinedMessage.includes("insufficient") || combinedMessage.includes("not enough points")) {
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : String(error),
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("notenoughpoints") || allMessages.includes("insufficient") || allMessages.includes("not enough points")) {
             throw new OpenLoyaltyError({
                 code: "INSUFFICIENT_BALANCE",
                 message: "Member does not have enough points to purchase this reward",

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

@@ -68,16 +68,13 @@ export declare const rewardToolDefinitions: readonly [{
             from: string;
             to: string;
         }>;
-        usageLimit: import("zod").ZodObject<{
+        usageLimit: import("zod").ZodOptional<import("zod").ZodObject<{
             perUser: import("zod").ZodNumber;
-            general: import("zod").ZodNumber;
-        }, "strip", import("zod").ZodTypeAny, {
+        }, "strict", import("zod").ZodTypeAny, {
             perUser: number;
-            general: number;
         }, {
             perUser: number;
-            general: number;
-        }>;
+        }>>;
         costInPoints: import("zod").ZodOptional<import("zod").ZodNumber>;
         usageInstruction: import("zod").ZodOptional<import("zod").ZodString>;
         active: import("zod").ZodOptional<import("zod").ZodBoolean>;

package/dist/tools/reward/index.js

@@ -24,9 +24,9 @@ export const rewardToolDefinitions = [
             "1. translations: { en: { name: 'Reward Name' } }, " +
             "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' }, " +
-            "5. usageLimit: { perUser: 5, general: 1000 } - BOTH perUser AND general are REQUIRED. " +
+            "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'].",
         readOnly: false,
         inputSchema: RewardCreateInputSchema,

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

@@ -55,16 +55,13 @@ export declare const RewardCreateInputSchema: {
         from: string;
         to: string;
     }>;
-    usageLimit: z.ZodObject<{
+    usageLimit: z.ZodOptional<z.ZodObject<{
         perUser: z.ZodNumber;
-        general: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         perUser: number;
-        general: number;
     }, {
         perUser: number;
-        general: number;
-    }>;
+    }>>;
     costInPoints: z.ZodOptional<z.ZodNumber>;
     usageInstruction: z.ZodOptional<z.ZodString>;
     active: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/reward/schemas.js

@@ -26,13 +26,11 @@ 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 (REQUIRED by API)
-// NOTE: API uses 'general' (not 'total') for total redemptions limit
-// BOTH perUser and general are REQUIRED by the API
+// 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. REQUIRED."),
-    general: z.number().describe("Total redemptions across all members. REQUIRED. Use a large number (e.g., 10000) if unlimited."),
-});
+    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.");
 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."),
@@ -40,7 +38,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.describe("Usage limits. ⚠️ BOTH perUser AND general are REQUIRED by the API."),
+    usageLimit: RewardUsageLimitInputSchema.optional().describe("Usage limits. Only perUser is supported by API."),
     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)."),

package/dist/tools/transaction.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { apiGet, apiPost } from "../client/http.js";
-import { formatApiError } from "../utils/errors.js";
+import { formatApiError, OpenLoyaltyError } from "../utils/errors.js";
 import { getStoreCode } from "../config.js";
 import { buildPaginationParams, normalizeDateToISO } from "../utils/pagination.js";
 // Input Schemas
@@ -95,6 +95,19 @@ export async function transactionCreate(input) {
         };
     }
     catch (error) {
+        // Check for duplicate document number error
+        // Must check axios response data, not just error.message
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allErrorMessages = apiErrors.map(e => e.message).join(" ").toLowerCase();
+        if (allErrorMessages.includes("document number") && allErrorMessages.includes("unique")) {
+            throw new OpenLoyaltyError({
+                code: "DUPLICATE_DOCUMENT",
+                message: `Transaction with document number '${input.header.documentNumber}' already exists`,
+                hint: `Each transaction must have a unique documentNumber. Use transaction_list(documentNumber: "${input.header.documentNumber}") to check if it exists, or generate a new unique document number (e.g., add timestamp suffix).`,
+                relatedTool: "ol_transaction_create",
+            });
+        }
         throw formatApiError(error, "ol_transaction_create");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-loyalty/mcp-server",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "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>",