@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/tools/campaign/index.js

@@ -0,0 +1,112 @@
+// Re-export schemas
+export { CampaignListInputSchema, CampaignGetInputSchema, CampaignCreateInputSchema, CampaignUpdateInputSchema, CampaignPatchInputSchema, CampaignDeleteInputSchema, CampaignSimulateInputSchema, CampaignGenerateCodesInputSchema, CampaignListCodesInputSchema, CampaignGetAvailableInputSchema, CampaignGetVisibleInputSchema, CampaignGetLeaderboardInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { campaignList, campaignGet, campaignCreate, campaignUpdate, campaignPatch, campaignDelete, campaignSimulate, } from "./handlers.js";
+export { campaignGenerateCodes, campaignListCodes, campaignGetAvailable, campaignGetVisible, campaignGetLeaderboard, } from "./member-handlers.js";
+// Imports for tool definitions
+import { CampaignListInputSchema, CampaignGetInputSchema, CampaignCreateInputSchema, CampaignUpdateInputSchema, CampaignPatchInputSchema, CampaignDeleteInputSchema, CampaignSimulateInputSchema, CampaignGenerateCodesInputSchema, CampaignListCodesInputSchema, CampaignGetAvailableInputSchema, CampaignGetVisibleInputSchema, CampaignGetLeaderboardInputSchema, } from "./schemas.js";
+import { campaignList, campaignGet, campaignCreate, campaignUpdate, campaignPatch, campaignDelete, campaignSimulate, } from "./handlers.js";
+import { campaignGenerateCodes, campaignListCodes, campaignGetAvailable, campaignGetVisible, campaignGetLeaderboard, } from "./member-handlers.js";
+// Tool definitions
+export const campaignToolDefinitions = [
+    {
+        name: "ol_campaign_list",
+        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,
+        inputSchema: CampaignListInputSchema,
+        handler: campaignList,
+    },
+    {
+        name: "ol_campaign_create",
+        title: "Create Campaign",
+        description: "Create campaign to automate engagement. Triggers: transaction (purchase-based), custom_event (for custom actions), time (scheduled). " +
+            "Effects: give_points, give_reward, deduct_unit. Rules define when/what happens. " +
+            "REQUIRED: activity.startsAt, rules[].name, effects[].effect. " +
+            "pointsRule is a STRING expression (e.g., 'transaction.grossValue * 2'), not an object.",
+        readOnly: false,
+        inputSchema: CampaignCreateInputSchema,
+        handler: campaignCreate,
+    },
+    {
+        name: "ol_campaign_get",
+        title: "Get Campaign Details",
+        description: "Get full campaign configuration including all rules, conditions, effects, and targeting.",
+        readOnly: true,
+        inputSchema: CampaignGetInputSchema,
+        handler: campaignGet,
+    },
+    {
+        name: "ol_campaign_update",
+        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,
+        inputSchema: CampaignUpdateInputSchema,
+        handler: campaignUpdate,
+    },
+    {
+        name: "ol_campaign_patch",
+        title: "Patch Campaign",
+        description: "Partial update of campaign - only active status and displayOrder can be patched. For full updates, use campaign_update.",
+        readOnly: false,
+        inputSchema: CampaignPatchInputSchema,
+        handler: campaignPatch,
+    },
+    {
+        name: "ol_campaign_delete",
+        title: "Delete Campaign (Permanent)",
+        description: "Permanently delete a campaign. This cannot be undone. Consider deactivating instead if you may need the campaign later.",
+        readOnly: false,
+        destructive: true,
+        inputSchema: CampaignDeleteInputSchema,
+        handler: campaignDelete,
+    },
+    {
+        name: "ol_campaign_simulate",
+        title: "Simulate Campaign Effects",
+        description: "Simulate campaign effects without executing them. Use to preview what points/rewards a transaction would earn. Provide trigger type, transaction/event data, and customer. Returns simulated effects grouped by campaign.",
+        readOnly: true,
+        inputSchema: CampaignSimulateInputSchema,
+        handler: campaignSimulate,
+    },
+    {
+        name: "ol_campaign_generate_codes",
+        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,
+        inputSchema: CampaignGenerateCodesInputSchema,
+        handler: campaignGenerateCodes,
+    },
+    {
+        name: "ol_campaign_list_codes",
+        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,
+        inputSchema: CampaignListCodesInputSchema,
+        handler: campaignListCodes,
+    },
+    {
+        name: "ol_campaign_get_available",
+        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,
+        inputSchema: CampaignGetAvailableInputSchema,
+        handler: campaignGetAvailable,
+    },
+    {
+        name: "ol_campaign_get_visible",
+        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,
+        inputSchema: CampaignGetVisibleInputSchema,
+        handler: campaignGetVisible,
+    },
+    {
+        name: "ol_campaign_get_leaderboard",
+        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,
+        inputSchema: CampaignGetLeaderboardInputSchema,
+        handler: campaignGetLeaderboard,
+    },
+];

package/dist/tools/campaign/member-handlers.d.ts

@@ -0,0 +1,60 @@
+import { CampaignCode, MemberCampaignItem, LeaderboardEntry } from "./types.js";
+export declare function campaignGenerateCodes(input: {
+    storeCode?: string;
+    campaignId: string;
+    quantity: number;
+}): Promise<{
+    codesGenerated: number;
+}>;
+export declare function campaignListCodes(input: {
+    storeCode?: string;
+    campaignId: string;
+    page?: number;
+    perPage?: number;
+    status?: string;
+    code?: string;
+}): Promise<{
+    codes: CampaignCode[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function campaignGetAvailable(input: {
+    storeCode?: string;
+    memberId: string;
+    page?: number;
+    perPage?: number;
+    type?: string;
+    trigger?: string;
+}): Promise<{
+    campaigns: MemberCampaignItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function campaignGetVisible(input: {
+    storeCode?: string;
+    memberId: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+}): Promise<{
+    campaigns: MemberCampaignItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function campaignGetLeaderboard(input: {
+    storeCode?: string;
+    campaignId: string;
+    type?: string;
+}): Promise<{
+    entries: LeaderboardEntry[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;

package/dist/tools/campaign/member-handlers.js

@@ -0,0 +1,159 @@
+import { apiGet, apiPost } from "../../client/http.js";
+import { formatApiError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+// Code management handlers
+export async function campaignGenerateCodes(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/campaign/${input.campaignId}/codes/generate`, { generate: { numberOfCodes: input.quantity } });
+        return { codesGenerated: input.quantity };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_campaign_generate_codes");
+    }
+}
+export async function campaignListCodes(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.status)
+        params.append("status", input.status);
+    if (input.code)
+        params.append("code", input.code);
+    const queryString = params.toString();
+    const url = `/${storeCode}/campaign/${input.campaignId}/codes${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const codes = (response.items || []).map((item) => ({
+            codeId: item.codeId,
+            code: item.code,
+            status: item.status,
+            usedAt: item.usedAt,
+            createdAt: item.createdAt,
+            createdBy: item.createdBy,
+        }));
+        const total = response.total || {};
+        return {
+            codes,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_campaign_list_codes");
+    }
+}
+// Member campaign handlers
+export async function campaignGetAvailable(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.type)
+        params.append("type", input.type);
+    if (input.trigger)
+        params.append("trigger", input.trigger);
+    const queryString = params.toString();
+    const url = `/${storeCode}/member/${input.memberId}/campaign${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const campaigns = (response.items || []).map((item) => ({
+            campaignId: item.campaignId,
+            name: item.name,
+            active: item.active,
+            type: item.type,
+            trigger: item.trigger,
+            limitReached: item.limitReached,
+            description: item.description,
+        }));
+        const total = response.total || {};
+        return {
+            campaigns,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_campaign_get_available");
+    }
+}
+export async function campaignGetVisible(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.active !== undefined)
+        params.append("active", String(input.active));
+    const queryString = params.toString();
+    const url = `/${storeCode}/member/${input.memberId}/campaign/visible${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const campaigns = (response.items || []).map((item) => ({
+            campaignId: item.campaignId,
+            name: item.name,
+            active: item.active,
+            type: item.type,
+            trigger: item.trigger,
+            description: item.description,
+        }));
+        const total = response.total || {};
+        return {
+            campaigns,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_campaign_get_visible");
+    }
+}
+export async function campaignGetLeaderboard(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    if (input.type)
+        params.append("type", input.type);
+    const queryString = params.toString();
+    const url = `/${storeCode}/campaign/${input.campaignId}/leaderboard${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const entries = (response.items || []).map((item) => ({
+            member: {
+                customerId: item.member.customerId,
+                firstName: item.member.firstName,
+                lastName: item.member.lastName,
+                email: item.member.email,
+                loyaltyCardNumber: item.member.loyaltyCardNumber,
+            },
+            ranking: {
+                score: item.ranking.score,
+                position: item.ranking.position,
+                recalculatedAt: item.ranking.recalculatedAt,
+                changedPositionAt: item.ranking.changedPositionAt,
+            },
+        }));
+        const total = response.total || {};
+        return {
+            entries,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_campaign_get_leaderboard");
+    }
+}