@open-loyalty/mcp-server 1.5.3 → 1.7.0

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

@@ -0,0 +1,45 @@
+import { BadgeTypeListItem, MemberBadge } from "../../types/schemas/badge.js";
+export declare function badgeList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    name?: string;
+    badgeTypeId?: string;
+}): Promise<{
+    badges: BadgeTypeListItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function badgeGet(input: {
+    storeCode?: string;
+    badgeTypeId: string;
+}): Promise<Record<string, unknown>>;
+interface BadgeUpdateInput {
+    storeCode?: string;
+    badgeTypeId: string;
+    name?: string;
+    translations?: Record<string, {
+        name: string;
+        description?: string;
+    }>;
+    imageUrl?: string;
+    active?: boolean;
+}
+export declare function badgeUpdate(input: BadgeUpdateInput): Promise<void>;
+export declare function badgeGetMemberBadges(input: {
+    storeCode?: string;
+    memberId: string;
+    page?: number;
+    perPage?: number;
+    name?: string;
+    badgeTypeId?: string;
+}): Promise<{
+    badges: MemberBadge[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export {};

package/dist/tools/badge/handlers.js

@@ -0,0 +1,135 @@
+import { apiGet, apiPut } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+import { getStoreCode } from "../../config.js";
+export async function badgeList(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.name)
+        params.append("name", input.name);
+    if (input.badgeTypeId)
+        params.append("badgeTypeId", input.badgeTypeId);
+    const queryString = params.toString();
+    const url = `/${storeCode}/badge-type${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const badges = (response.items || []).map((item) => ({
+            badgeTypeId: item.badgeTypeId,
+            name: item.name,
+            createdAt: item.createdAt,
+            updatedAt: item.updatedAt,
+        }));
+        const total = response.total || {};
+        return {
+            badges,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "STORE_NOT_FOUND",
+                message: "Cannot list badges - store not found",
+                hint: "Use ol_store_list() to verify the store code is correct.",
+                relatedTool: "ol_badge_list",
+            });
+        }
+        if (axios.isAxiosError(error) && error.response?.status === 403) {
+            throw new OpenLoyaltyError({
+                code: "BADGE_PERMISSION_DENIED",
+                message: "You don't have permission to view badges",
+                hint: "Badge access requires the ACHIEVEMENT:VIEW permission. Use ol_admin_get_permissions() to check your access.",
+                relatedTool: "ol_badge_list",
+            });
+        }
+        throw formatApiError(error, "ol_badge_list");
+    }
+}
+export async function badgeGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/badge-type/${input.badgeTypeId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Badge type '${input.badgeTypeId}' not found`,
+                hint: "Use ol_badge_list() to find existing badge types and their IDs.", relatedTool: "ol_badge_get" });
+        }
+        throw formatApiError(error, "ol_badge_get");
+    }
+}
+export async function badgeUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const badgePayload = {};
+    // API requires name as direct field, not nested in translations
+    // Extract from translations.en.name if name not provided directly
+    let badgeName = input.name;
+    if (!badgeName && input.translations?.en?.name) {
+        badgeName = input.translations.en.name;
+    }
+    if (badgeName !== undefined)
+        badgePayload.name = badgeName;
+    // Note: API does not accept nested translations - only direct fields
+    if (input.imageUrl !== undefined)
+        badgePayload.imageUrl = input.imageUrl;
+    if (input.active !== undefined)
+        badgePayload.active = input.active;
+    try {
+        // CRITICAL: Wrap body as { badgeType: {...} }
+        await apiPut(`/${storeCode}/badge-type/${input.badgeTypeId}`, { badgeType: badgePayload });
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Badge type '${input.badgeTypeId}' not found`,
+                hint: "Use ol_badge_list() to find existing badge types and their IDs.", relatedTool: "ol_badge_update" });
+        }
+        throw formatApiError(error, "ol_badge_update");
+    }
+}
+export async function badgeGetMemberBadges(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.page)
+        params.append("_page", String(input.page));
+    if (input.perPage)
+        params.append("_itemsOnPage", String(input.perPage));
+    if (input.name)
+        params.append("name", input.name);
+    if (input.badgeTypeId)
+        params.append("badgeTypeId", input.badgeTypeId);
+    const queryString = params.toString();
+    const url = `/${storeCode}/member/${input.memberId}/badge${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const badges = (response.items || []).map((item) => ({
+            badgeTypeId: item.badgeTypeId,
+            name: item.name,
+            completedCount: item.completedCount,
+            createdAt: item.createdAt,
+            updatedAt: item.updatedAt,
+        }));
+        const total = response.total || {};
+        return {
+            badges,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Member '${input.memberId}' not found`,
+                hint: "Use ol_member_list() to search for the member by email, name, or phone.", relatedTool: "ol_badge_get_member_badges" });
+        }
+        throw formatApiError(error, "ol_badge_get_member_badges");
+    }
+}

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

@@ -0,0 +1,68 @@
+export { BadgeListInputSchema, BadgeGetInputSchema, BadgeUpdateInputSchema, BadgeGetMemberBadgesInputSchema, } from "./schemas.js";
+export { badgeList, badgeGet, badgeUpdate, badgeGetMemberBadges, } from "./handlers.js";
+import { badgeList, badgeGet, badgeUpdate, badgeGetMemberBadges } from "./handlers.js";
+export declare const badgeToolDefinitions: readonly [{
+    readonly name: "ol_badge_list";
+    readonly title: "List Badges";
+    readonly description: "List badge types. Badges are visual rewards linked to achievements. When a member completes an achievement with a badgeTypeId, they earn that badge. Use for displaying available badges.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        badgeTypeId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof badgeList;
+}, {
+    readonly name: "ol_badge_get";
+    readonly title: "Get Badge Details";
+    readonly description: "Get badge type details including name, image URL, and linked achievements count.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        badgeTypeId: import("zod").ZodString;
+    };
+    readonly handler: typeof badgeGet;
+}, {
+    readonly name: "ol_badge_update";
+    readonly title: "Update Badge";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        badgeTypeId: import("zod").ZodString;
+        name: import("zod").ZodString;
+        translations: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
+            name: import("zod").ZodString;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            name: string;
+            description?: string | undefined;
+        }, {
+            name: string;
+            description?: string | undefined;
+        }>>>;
+        imageUrl: import("zod").ZodOptional<import("zod").ZodString>;
+        active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    readonly handler: typeof badgeUpdate;
+}, {
+    readonly name: "ol_badge_get_member_badges";
+    readonly title: "Get Member Badges";
+    readonly description: "Get badges earned by a member. Returns each badge with completedCount showing how many times it was earned. Use for displaying member's badge collection.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        memberId: import("zod").ZodString;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        badgeTypeId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof badgeGetMemberBadges;
+}];

package/dist/tools/badge/index.js

@@ -0,0 +1,47 @@
+// Re-export schemas
+export { BadgeListInputSchema, BadgeGetInputSchema, BadgeUpdateInputSchema, BadgeGetMemberBadgesInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { badgeList, badgeGet, badgeUpdate, badgeGetMemberBadges, } from "./handlers.js";
+// Imports for tool definitions
+import { BadgeListInputSchema, BadgeGetInputSchema, BadgeUpdateInputSchema, BadgeGetMemberBadgesInputSchema, } from "./schemas.js";
+import { badgeList, badgeGet, badgeUpdate, badgeGetMemberBadges, } from "./handlers.js";
+// Tool definitions
+export const badgeToolDefinitions = [
+    {
+        name: "ol_badge_list",
+        title: "List Badges",
+        description: "List badge types. Badges are visual rewards linked to achievements. When a member completes an achievement with a badgeTypeId, they earn that badge. Use for displaying available badges.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: BadgeListInputSchema,
+        handler: badgeList,
+    },
+    {
+        name: "ol_badge_get",
+        title: "Get Badge Details",
+        description: "Get badge type details including name, image URL, and linked achievements count.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: BadgeGetInputSchema,
+        handler: badgeGet,
+    },
+    {
+        name: "ol_badge_update",
+        title: "Update Badge",
+        description: "Update badge type configuration. Badge types are created automatically when referenced by achievements. " +
+            "FIELD FORMAT: Pass 'name' as a direct top-level string, NOT inside translations. The API requires { name: 'Badge Name' }, NOT { translations: { en: { name: '...' } } }.",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: BadgeUpdateInputSchema,
+        handler: badgeUpdate,
+    },
+    {
+        name: "ol_badge_get_member_badges",
+        title: "Get Member Badges",
+        description: "Get badges earned by a member. Returns each badge with completedCount showing how many times it was earned. Use for displaying member's badge collection.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: BadgeGetMemberBadgesInputSchema,
+        handler: badgeGetMemberBadges,
+    },
+];

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const BadgeListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    badgeTypeId: z.ZodOptional<z.ZodString>;
+};
+export declare const BadgeGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    badgeTypeId: z.ZodString;
+};
+export declare const BadgeUpdateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    badgeTypeId: z.ZodString;
+    name: z.ZodString;
+    translations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+    }>>>;
+    imageUrl: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const BadgeGetMemberBadgesInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    memberId: z.ZodString;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    badgeTypeId: z.ZodOptional<z.ZodString>;
+};

package/dist/tools/badge/schemas.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export const BadgeListInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 10)."),
+    name: z.string().optional().describe("Filter by badge name."),
+    badgeTypeId: z.string().optional().describe("Filter by specific badge type ID."),
+};
+export const BadgeGetInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    badgeTypeId: z.string().describe("The badge type ID (UUID) to retrieve."),
+};
+export const BadgeUpdateInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    badgeTypeId: z.string().describe("The badge type ID (UUID) to update."),
+    name: z.string().describe("Badge name (REQUIRED). API requires name as a direct field."),
+    translations: z.record(z.string(), z.object({
+        name: z.string(),
+        description: z.string().optional(),
+    })).optional().describe("Badge translations (for convenience - will extract name from translations.en.name if name not provided directly)."),
+    imageUrl: z.string().optional().describe("URL to badge image."),
+    active: z.boolean().optional().describe("Whether badge type is active."),
+};
+export const BadgeGetMemberBadgesInputSchema = {
+    storeCode: z.string().optional().describe("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    memberId: z.string().describe("The member ID (UUID)."),
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 10)."),
+    name: z.string().optional().describe("Filter by badge name."),
+    badgeTypeId: z.string().optional().describe("Filter by specific badge type ID."),
+};

package/dist/tools/campaign/handlers.js

@@ -62,6 +62,15 @@ export async function campaignGet(input) {
         return response;
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Campaign '${input.campaignId}' not found`,
+                hint: "Use ol_campaign_list() to find existing campaigns and their IDs.",
+                relatedTool: "ol_campaign_get",
+            });
+        }
         throw formatApiError(error, "ol_campaign_get");
     }
 }
@@ -140,6 +149,23 @@ export async function campaignUpdate(input) {
         await apiPut(`/${storeCode}/campaign/${campaignId}`, { campaign: campaignPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Campaign '${campaignId}' not found`,
+                hint: "Use ol_campaign_list() to find existing campaigns and their IDs.", relatedTool: "ol_campaign_update" });
+        }
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [error instanceof Error ? error.message : "", axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)].join(" ").toLowerCase();
+        if (allMessages.includes("trigger") && allMessages.includes("choice")) {
+            throw new OpenLoyaltyError({ code: "INVALID_TRIGGER", message: "Invalid campaign trigger type",
+                hint: "Valid trigger values: 'transaction', 'custom_event', 'geolocation', 'time', 'achievement'.", relatedTool: "ol_campaign_update" });
+        }
+        if (allMessages.includes("operator") || (allMessages.includes("condition") && allMessages.includes("choice"))) {
+            throw new OpenLoyaltyError({ code: "INVALID_CONDITION", message: "Invalid rule condition in campaign",
+                hint: "Use full operator names: 'is_greater_or_equal' (NOT 'gte'). Use full attribute paths: 'transaction.grossValue' (NOT 'grossValue').",
+                relatedTool: "ol_campaign_update" });
+        }
         throw formatApiError(error, "ol_campaign_update");
     }
 }
@@ -154,6 +180,11 @@ export async function campaignPatch(input) {
         await apiPatch(`/${storeCode}/campaign/${input.campaignId}`, { campaign: patchPayload });
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Campaign '${input.campaignId}' not found`,
+                hint: "Use ol_campaign_list() to find existing campaigns and their IDs.", relatedTool: "ol_campaign_patch" });
+        }
         throw formatApiError(error, "ol_campaign_patch");
     }
 }
@@ -163,6 +194,11 @@ export async function campaignDelete(input) {
         await apiDelete(`/${storeCode}/campaign/${input.campaignId}`);
     }
     catch (error) {
+        const axiosError = error;
+        if (axiosError.response?.status === 404) {
+            throw new OpenLoyaltyError({ code: "NOT_FOUND", message: `Campaign '${input.campaignId}' not found`,
+                hint: "Use ol_campaign_list() to find existing campaigns and their IDs.", relatedTool: "ol_campaign_delete" });
+        }
         throw formatApiError(error, "ol_campaign_delete");
     }
 }
@@ -252,6 +288,31 @@ export async function campaignSimulate(input) {
         };
     }
     catch (error) {
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const allMessages = [
+            error instanceof Error ? error.message : "",
+            axiosError.response?.data?.message || "",
+            ...apiErrors.map(e => `${e.path || ""}: ${e.message}`)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("transaction") && (allMessages.includes("required") || allMessages.includes("missing") || allMessages.includes("should not be blank"))) {
+            throw new OpenLoyaltyError({
+                code: "MISSING_TRANSACTION_DATA",
+                message: "Transaction data is required for simulation with transaction trigger",
+                hint: "For trigger='transaction', provide transaction data: { grossValue: 100, documentNumber: 'SIM-001', " +
+                    "purchasedAt: '2026-01-01T10:00:00Z', items: [{ sku: 'SKU-1', name: 'Product', grossValue: 100, qty: 1 }] }. " +
+                    "Also provide customer: { customerId: 'member-uuid' } to identify the member.",
+                relatedTool: "ol_campaign_simulate",
+            });
+        }
+        if (allMessages.includes("customer") && (allMessages.includes("not found") || allMessages.includes("required"))) {
+            throw new OpenLoyaltyError({
+                code: "MEMBER_NOT_FOUND",
+                message: "The specified member was not found for simulation",
+                hint: "Provide a valid member ID in customer.customerId. Use ol_member_list() to find members.",
+                relatedTool: "ol_campaign_simulate",
+            });
+        }
         throw formatApiError(error, "ol_campaign_simulate");
     }
 }

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

@@ -9,6 +9,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "List Campaigns";
     readonly description: "List all campaigns. Filter by type (direct/referral) or trigger (transaction/custom_event/time/etc). Use campaign_get for full configuration including rules and effects.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         page: import("zod").ZodOptional<import("zod").ZodNumber>;
@@ -23,6 +24,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Create Campaign";
     readonly description: string;
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         type: import("zod").ZodEnum<["direct", "referral"]>;
@@ -313,6 +315,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Get Campaign Details";
     readonly description: "Get full campaign configuration including all rules, conditions, effects, and targeting.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -323,6 +326,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Update Campaign";
     readonly description: "Full update of campaign configuration. Requires all campaign fields. Use campaign_get first to retrieve current configuration, modify it, then send the complete object.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -603,6 +607,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Patch Campaign";
     readonly description: "Partial update of campaign - only active status and displayOrder can be patched. For full updates, use campaign_update.";
     readonly readOnly: false;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -616,6 +621,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly description: "Permanently delete a campaign. This cannot be undone. Consider deactivating instead if you may need the campaign later.";
     readonly readOnly: false;
     readonly destructive: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -624,6 +630,7 @@ export declare const campaignToolDefinitions: readonly [{
 }, {
     readonly name: "ol_campaign_simulate";
     readonly title: "Simulate Campaign Effects";
+    readonly idempotent: true;
     readonly description: string;
     readonly readOnly: true;
     readonly inputSchema: {
@@ -785,6 +792,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Generate Campaign Codes";
     readonly description: "Generate unique redemption codes for a campaign. Use for promotions requiring unique codes. Codes are auto-generated and can be retrieved with campaign_list_codes.";
     readonly readOnly: false;
+    readonly idempotent: false;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -796,6 +804,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "List Campaign Codes";
     readonly description: "List redemption codes for a campaign. Filter by status (active/used) or specific code. Returns code details including usage status.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;
@@ -810,6 +819,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Get Available Campaigns for Member";
     readonly description: "Get campaigns available to a specific member. Returns campaigns the member can participate in based on their tier, segments, and campaign targeting rules. Includes limitReached indicator.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -824,6 +834,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Get Visible Campaigns for Member";
     readonly description: "Get campaigns visible to a specific member. May include campaigns not yet available (e.g., upcoming campaigns or those requiring certain conditions). Use get_available for campaigns the member can currently participate in.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         memberId: import("zod").ZodString;
@@ -837,6 +848,7 @@ export declare const campaignToolDefinitions: readonly [{
     readonly title: "Get Campaign Leaderboard";
     readonly description: "Get leaderboard rankings for a campaign. Returns ranked list of members with scores and positions. Use for leaderboard-type campaigns to show competition standings.";
     readonly readOnly: true;
+    readonly idempotent: true;
     readonly inputSchema: {
         storeCode: import("zod").ZodOptional<import("zod").ZodString>;
         campaignId: import("zod").ZodString;

package/dist/tools/campaign/index.js

@@ -14,6 +14,7 @@ export const campaignToolDefinitions = [
         title: "List Campaigns",
         description: "List all campaigns. Filter by type (direct/referral) or trigger (transaction/custom_event/time/etc). Use campaign_get for full configuration including rules and effects.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignListInputSchema,
         handler: campaignList,
     },
@@ -27,8 +28,16 @@ export const campaignToolDefinitions = [
             "3. Audience -- all members, or specific tiers/segments? " +
             "4. End date -- campaigns without endsAt run forever, which is a budget commitment. " +
             "REQUIRED: type, trigger, translations.en.name, activity.startsAt, rules with effects. " +
-            "In effects array, use key 'effect' (NOT 'type'). pointsRule is a STRING: '100' not 100.",
+            "For trigger='custom_event': ALSO set event='your_event_code' (must match existing schema from custom_event_schema_list). " +
+            "EFFECT KEY: Use 'effect' NOT 'type' in effects array: { effect: 'give_points', pointsRule: '100' }. pointsRule MUST be a STRING: '100' not 100. " +
+            "RULE CONDITIONS EXAMPLES: " +
+            "{ conditions: [{ operator: 'is_greater_or_equal', attribute: 'transaction.grossValue', data: 100 }] }. " +
+            "For labels: { operator: 'has_at_least_one_label', attribute: 'transaction.labels', data: [{key: 'category', value: 'electronics'}] }. " +
+            "For between: { operator: 'is_between', attribute: 'transaction.grossValue', data: {from: 50, to: 200} }. " +
+            "AUDIENCE: OMIT entirely for all members. Do NOT pass audience: { target: 'all' } -- the API rejects 'all'. Only use audience for tier/segment targeting. " +
+            "VISIBILITY vs AUDIENCE: visibility = who can see the campaign. audience = who can participate. Both accept target='tier' or 'segment'. OMIT audience for all members.",
         readOnly: false,
+        idempotent: false,
         inputSchema: CampaignCreateInputSchema,
         handler: campaignCreate,
     },
@@ -37,6 +46,7 @@ export const campaignToolDefinitions = [
         title: "Get Campaign Details",
         description: "Get full campaign configuration including all rules, conditions, effects, and targeting.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignGetInputSchema,
         handler: campaignGet,
     },
@@ -45,6 +55,7 @@ export const campaignToolDefinitions = [
         title: "Update Campaign",
         description: "Full update of campaign configuration. Requires all campaign fields. Use campaign_get first to retrieve current configuration, modify it, then send the complete object.",
         readOnly: false,
+        idempotent: true,
         inputSchema: CampaignUpdateInputSchema,
         handler: campaignUpdate,
     },
@@ -53,6 +64,7 @@ export const campaignToolDefinitions = [
         title: "Patch Campaign",
         description: "Partial update of campaign - only active status and displayOrder can be patched. For full updates, use campaign_update.",
         readOnly: false,
+        idempotent: true,
         inputSchema: CampaignPatchInputSchema,
         handler: campaignPatch,
     },
@@ -62,12 +74,14 @@ export const campaignToolDefinitions = [
         description: "Permanently delete a campaign. This cannot be undone. Consider deactivating instead if you may need the campaign later.",
         readOnly: false,
         destructive: true,
+        idempotent: true,
         inputSchema: CampaignDeleteInputSchema,
         handler: campaignDelete,
     },
     {
         name: "ol_campaign_simulate",
         title: "Simulate Campaign Effects",
+        idempotent: true,
         description: "Simulate campaign effects without executing them. Use to preview what points/rewards a transaction would earn. " +
             "Example for transaction trigger: { trigger: 'transaction', " +
             "transaction: { grossValue: 100, documentNumber: 'SIM-001', purchasedAt: '2026-01-01T10:00:00Z', " +
@@ -83,6 +97,7 @@ export const campaignToolDefinitions = [
         title: "Generate Campaign Codes",
         description: "Generate unique redemption codes for a campaign. Use for promotions requiring unique codes. Codes are auto-generated and can be retrieved with campaign_list_codes.",
         readOnly: false,
+        idempotent: false,
         inputSchema: CampaignGenerateCodesInputSchema,
         handler: campaignGenerateCodes,
     },
@@ -91,6 +106,7 @@ export const campaignToolDefinitions = [
         title: "List Campaign Codes",
         description: "List redemption codes for a campaign. Filter by status (active/used) or specific code. Returns code details including usage status.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignListCodesInputSchema,
         handler: campaignListCodes,
     },
@@ -99,6 +115,7 @@ export const campaignToolDefinitions = [
         title: "Get Available Campaigns for Member",
         description: "Get campaigns available to a specific member. Returns campaigns the member can participate in based on their tier, segments, and campaign targeting rules. Includes limitReached indicator.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignGetAvailableInputSchema,
         handler: campaignGetAvailable,
     },
@@ -107,6 +124,7 @@ export const campaignToolDefinitions = [
         title: "Get Visible Campaigns for Member",
         description: "Get campaigns visible to a specific member. May include campaigns not yet available (e.g., upcoming campaigns or those requiring certain conditions). Use get_available for campaigns the member can currently participate in.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignGetVisibleInputSchema,
         handler: campaignGetVisible,
     },
@@ -115,6 +133,7 @@ export const campaignToolDefinitions = [
         title: "Get Campaign Leaderboard",
         description: "Get leaderboard rankings for a campaign. Returns ranked list of members with scores and positions. Use for leaderboard-type campaigns to show competition standings.",
         readOnly: true,
+        idempotent: true,
         inputSchema: CampaignGetLeaderboardInputSchema,
         handler: campaignGetLeaderboard,
     },