@open-loyalty/mcp-server 1.3.3 → 1.3.5

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

@@ -80,9 +80,17 @@ export async function pointsSpend(input) {
         return { transferId: response.transferId };
     }
     catch (error) {
-        // Check for insufficient points error
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        if (errorMessage.includes("NotEnoughPoints") || errorMessage.includes("insufficient")) {
+        // Check for insufficient points error - API returns various formats:
+        // "NotEnoughPoints", "insufficient", "not enough points" (lowercase)
+        // Must check error.message, data.message, AND data.errors array
+        const axiosError = error;
+        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",
@@ -110,8 +118,16 @@ export async function pointsTransfer(input) {
         return { transferId: response.transferId };
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        if (errorMessage.includes("NotEnoughPoints") || errorMessage.includes("insufficient")) {
+        // Check for insufficient points error - API returns various formats
+        // Must check error.message, data.message, AND data.errors array
+        const axiosError = error;
+        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,7 +46,8 @@ 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
     const payload = omitUndefined({
         translations: input.translations,
@@ -93,12 +94,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,11 +133,6 @@ export async function rewardUpdate(input) {
             visibilityPayload.to = existingVisibility.to;
         payload.visibility = visibilityPayload;
     }
-    // usageLimit: Required field, but only include perUser (API rejects extra fields)
-    // The GET response may include derived fields that PUT doesn't accept
-    payload.usageLimit = {
-        perUser: existingUsageLimit?.perUser ?? 1,
-    };
     // Coupon-specific fields (required for static_coupon, dynamic_coupon, conversion_coupon)
     if (existing.couponValue !== undefined)
         payload.couponValue = existing.couponValue;
@@ -212,8 +208,17 @@ export async function rewardBuy(input) {
         };
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        if (errorMessage.includes("NotEnoughPoints") || errorMessage.includes("insufficient")) {
+        // Check for insufficient points error - API returns various formats:
+        // "NotEnoughPoints", "insufficient", "not enough points" (lowercase)
+        // Must check error.message, data.message, AND data.errors array
+        const axiosError = error;
+        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, {
             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, {
         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,10 @@ 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)
 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."),
+}).describe("Usage limits. ⚠️ Only 'perUser' is supported - API rejects 'general' as extra field.");
 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 +37,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/tierset.d.ts

@@ -19,17 +19,6 @@ export declare const TierSetCreateInputSchema: {
         attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
         walletType?: string | undefined;
     }>, "many">;
-    downgrade: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodEnum<["none", "automatic", "x_days"]>;
-        days: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        mode: "none" | "automatic" | "x_days";
-        days?: number | undefined;
-    }, {
-        mode: "none" | "automatic" | "x_days";
-        days?: number | undefined;
-    }>>;
-    active: z.ZodOptional<z.ZodBoolean>;
 };
 export declare const TierSetGetInputSchema: {
     storeCode: z.ZodOptional<z.ZodString>;
@@ -107,11 +96,6 @@ type TierSetCreateInput = {
         attribute: string;
         walletType?: string;
     }[];
-    downgrade?: {
-        mode: string;
-        days?: number;
-    };
-    active?: boolean;
 };
 type TierSetGetInput = {
     storeCode?: string;
@@ -196,17 +180,6 @@ export declare const tiersetToolDefinitions: readonly [{
             attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
             walletType?: string | undefined;
         }>, "many">;
-        downgrade: z.ZodOptional<z.ZodObject<{
-            mode: z.ZodEnum<["none", "automatic", "x_days"]>;
-            days: z.ZodOptional<z.ZodNumber>;
-        }, "strip", z.ZodTypeAny, {
-            mode: "none" | "automatic" | "x_days";
-            days?: number | undefined;
-        }, {
-            mode: "none" | "automatic" | "x_days";
-            days?: number | undefined;
-        }>>;
-        active: z.ZodOptional<z.ZodBoolean>;
     };
     readonly handler: typeof tiersetCreate;
 }, {

package/dist/tools/tierset.js

@@ -20,11 +20,7 @@ export const TierSetCreateInputSchema = {
         walletType: z.string().optional().describe("Wallet type CODE (not UUID). Required for unit-based attributes (activeUnits, totalEarnedUnits, cumulatedEarnedUnits). " +
             "Use wallet_type_list to find walletType.code (e.g., 'default')."),
     })).describe("Array of conditions that define tier progression criteria. IMPORTANT: Use 'totalEarnedUnits' for lifetime points (NOT 'earnedUnits')."),
-    downgrade: z.object({
-        mode: DowngradeModeEnum.describe("Downgrade mode."),
-        days: z.number().optional().describe("Number of days for x_days mode (required if mode is x_days)."),
-    }).optional().describe("Downgrade configuration for the tier set."),
-    active: z.boolean().optional().describe("Whether the tier set is active. Defaults to true."),
+    // NOTE: downgrade and active are NOT supported at creation time - use tierset_update after creation
 };
 export const TierSetGetInputSchema = {
     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."),
@@ -87,25 +83,34 @@ export async function tiersetList(input) {
 }
 export async function tiersetCreate(input) {
     const storeCode = getStoreCode(input.storeCode);
-    // API requires tierSet wrapper with translations (at least en is required)
-    // Also include empty tiers array - some API versions require it
-    const payload = {
-        tierSet: {
-            translations: {
-                en: {
-                    name: input.name,
-                    description: input.description || "",
-                },
+    // API QUIRK: Only accepts specific fields at creation time.
+    // Fields NOT supported at creation: tiers, active, downgrade
+    // These must be set via tierset_update or tierset_update_tiers after creation.
+    //
+    // REQUIRED fields:
+    // - translations.en.name (string)
+    // - conditions (array with attribute, optionally walletType)
+    const tierSetPayload = {
+        translations: {
+            en: {
+                name: input.name,
+                description: input.description || "",
             },
-            conditions: input.conditions,
-            tiers: [], // Required by API - tiers are added separately via tierset_update_tiers
-            downgrade: input.downgrade,
-            active: input.active ?? true,
         },
+        conditions: input.conditions,
     };
+    const payload = { tierSet: tierSetPayload };
     try {
         const response = await apiPost(`/${storeCode}/tierSet`, payload);
-        const validated = TierSetSchema.parse(response);
+        // API QUIRK: Create endpoint only returns { tierSetId: string }
+        // We need to fetch the full tier set to get the conditionId values
+        const createResponse = response;
+        if (!createResponse.tierSetId) {
+            throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
+        }
+        // Fetch the created tier set to get condition IDs
+        const tierSetResponse = await apiGet(`/${storeCode}/tierSet/${createResponse.tierSetId}`);
+        const validated = TierSetSchema.parse(tierSetResponse);
         return {
             tierSetId: validated.tierSetId,
             conditions: validated.conditions.map((c) => ({
@@ -228,7 +233,9 @@ export const tiersetToolDefinitions = [
         description: "Create a new tier set (loyalty program structure). " +
             "⚠️ LIMIT: Maximum 3 ACTIVE tier sets per store. ALWAYS call tierset_list FIRST to check existing tier sets - if one exists that matches your needs, REUSE IT instead of creating a new one. " +
             "WORKFLOW: 1) tierset_list (check existing) → 2) tierset_create (only if needed) → 3) tierset_get (to get conditionId) → 4) tierset_update_tiers (to define thresholds). " +
-            "Valid attributes: 'totalEarnedUnits' (lifetime points), 'activeUnits' (current balance), 'totalSpending', 'monthsSinceJoiningProgram'. " +
+            "⚠️ API LIMITATION: Only 'name', 'description', and 'conditions' are accepted at creation time. " +
+            "Fields like 'active', 'downgrade', 'tiers' are NOT supported at creation - use tierset_update after creation to set these. " +
+            "Valid condition attributes: 'totalEarnedUnits' (lifetime points), 'activeUnits' (current balance), 'totalSpending', 'monthsSinceJoiningProgram'. " +
             "COMMON MISTAKE: Use 'totalEarnedUnits' NOT 'earnedUnits' for lifetime points. " +
             "For unit-based attributes, set walletType to 'default'.",
         readOnly: 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.3",
+  "version": "1.3.5",
   "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>",