@open-loyalty/mcp-server 1.1.0 → 1.3.3

package/dist/tools/export.js

@@ -5,7 +5,7 @@ import { getConfig, getStoreCode } from "../config.js";
 import axios from "axios";
 // Input Schemas
 export const ExportCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     type: z.enum([
         "campaignCode",
         "member",
@@ -18,7 +18,7 @@ export const ExportCreateInputSchema = {
     perPage: z.number().optional().describe("Items per page for export."),
 };
 export const ExportListInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     exportId: z.string().optional().describe("Filter by export ID."),
@@ -32,11 +32,11 @@ export const ExportListInputSchema = {
     status: z.enum(["pending", "done", "failed", "error"]).optional().describe("Filter by export status."),
 };
 export const ExportGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     exportId: z.string().describe("The export ID (UUID) to retrieve."),
 };
 export const ExportDownloadInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     exportId: z.string().describe("The export ID (UUID) to download. Export must have status 'done'."),
 };
 // Handler functions
@@ -59,7 +59,7 @@ export async function exportCreate(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_export_create");
+        throw formatApiError(error, "ol_export_create");
     }
 }
 export async function exportList(input) {
@@ -82,7 +82,7 @@ export async function exportList(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_export_list");
+        throw formatApiError(error, "ol_export_list");
     }
 }
 export async function exportGet(input) {
@@ -92,7 +92,7 @@ export async function exportGet(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_export_get");
+        throw formatApiError(error, "ol_export_get");
     }
 }
 export async function exportDownload(input) {
@@ -112,13 +112,13 @@ export async function exportDownload(input) {
         };
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_export_download");
+        throw formatApiError(error, "ol_export_download");
     }
 }
 // Tool definitions
 export const exportToolDefinitions = [
     {
-        name: "openloyalty_export_create",
+        name: "ol_export_create",
         title: "Create Data Export",
         description: "Create a new data export. Returns exportId for async tracking. Export types: campaignCode (campaign redemption codes), member (member data), memberTier (member tier assignments), memberSegment (member segment membership), rewardFulfillment (reward fulfillment records). The export runs asynchronously - use export_get to check status and export_download when status is 'done'.",
         readOnly: false,
@@ -126,7 +126,7 @@ export const exportToolDefinitions = [
         handler: exportCreate,
     },
     {
-        name: "openloyalty_export_list",
+        name: "ol_export_list",
         title: "List Exports",
         description: "List exports with optional filtering. Returns paginated list of exports with exportId, type, status, createdAt, and finishedAt. Status values: pending, done, failed, error.",
         readOnly: true,
@@ -134,7 +134,7 @@ export const exportToolDefinitions = [
         handler: exportList,
     },
     {
-        name: "openloyalty_export_get",
+        name: "ol_export_get",
         title: "Get Export Details",
         description: "Get export details and status. Returns exportId, type, status, createdAt, finishedAt, exportedRows, and message. Check status before downloading - export must have status 'done'.",
         readOnly: true,
@@ -142,7 +142,7 @@ export const exportToolDefinitions = [
         handler: exportGet,
     },
     {
-        name: "openloyalty_export_download",
+        name: "ol_export_download",
         title: "Download Export File",
         description: "Download export file content. Returns CSV content. IMPORTANT: Only available when export status is 'done'. Check status with export_get first.",
         readOnly: true,

package/dist/tools/import.d.ts

@@ -77,7 +77,7 @@ export declare function importGet(input: {
     perPage?: number;
 }): Promise<ImportDetailsResponse>;
 export declare const importToolDefinitions: readonly [{
-    readonly name: "openloyalty_import_create";
+    readonly name: "ol_import_create";
     readonly title: "Create Bulk Import";
     readonly description: "Create a new bulk import from CSV content. Returns importId for async tracking. Import types: member (member data), groupValue (group values), segmentMembers (segment membership), unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), campaignCode (campaign codes), rewardCoupon (reward coupons). CSV format required - provide plain text CSV content.";
     readonly readOnly: false;
@@ -89,7 +89,7 @@ export declare const importToolDefinitions: readonly [{
     };
     readonly handler: typeof importCreate;
 }, {
-    readonly name: "openloyalty_import_list";
+    readonly name: "ol_import_list";
     readonly title: "List Imports";
     readonly description: "List imports with optional filtering. Returns paginated list of imports with importId, type, uploadedDate, fileName, and status information.";
     readonly readOnly: true;
@@ -102,7 +102,7 @@ export declare const importToolDefinitions: readonly [{
     };
     readonly handler: typeof importList;
 }, {
-    readonly name: "openloyalty_import_get";
+    readonly name: "ol_import_get";
     readonly title: "Get Import Details";
     readonly description: "Get import details and individual item statuses. Returns paginated list of import items with their success/failure status and error messages.";
     readonly readOnly: true;

package/dist/tools/import.js

@@ -3,9 +3,10 @@ import { apiGet } from "../client/http.js";
 import { formatApiError } from "../utils/errors.js";
 import { getConfig, getStoreCode } from "../config.js";
 import axios from "axios";
+import FormDataNode from "form-data";
 // Input Schemas
 export const ImportCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     type: z.enum([
         "member",
         "groupValue",
@@ -20,7 +21,7 @@ export const ImportCreateInputSchema = {
     fileName: z.string().optional().describe("Optional file name for the import (default: import.csv)."),
 };
 export const ImportListInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     importId: z.string().optional().describe("Filter by import ID."),
@@ -36,7 +37,7 @@ export const ImportListInputSchema = {
     ]).optional().describe("Filter by import type."),
 };
 export const ImportGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    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."),
     importId: z.string().describe("The import ID (UUID) to retrieve."),
     page: z.number().optional().describe("Page number for import items (default: 1)."),
     perPage: z.number().optional().describe("Items per page for import items (default: 25)."),
@@ -45,22 +46,29 @@ export const ImportGetInputSchema = {
 export async function importCreate(input) {
     const config = getConfig();
     const storeCode = getStoreCode(input.storeCode);
-    const fileName = input.fileName || "import.csv";
-    // Create form data for multipart upload
-    const formData = new FormData();
-    const blob = new Blob([input.fileContent], { type: "text/csv" });
-    formData.append("file", blob, fileName);
+    // Determine file extension and content type
+    // API accepts: application/xml, text/xml for member imports; text/csv for others
+    const fileName = input.fileName || "import.xml";
+    const isXml = fileName.endsWith('.xml') || input.fileContent.trim().startsWith('<?xml') || input.fileContent.trim().startsWith('<');
+    const contentType = isXml ? "application/xml" : "text/csv";
+    // Create form data for multipart upload using Node.js form-data package
+    // API expects field name "import[file]" per documentation
+    const formData = new FormDataNode();
+    formData.append("import[file]", Buffer.from(input.fileContent), {
+        filename: fileName,
+        contentType: contentType,
+    });
     try {
         const response = await axios.post(`${config.apiUrl}/${storeCode}/import/${input.type}`, formData, {
             headers: {
                 "X-AUTH-TOKEN": config.apiToken,
-                "Content-Type": "multipart/form-data",
+                ...formData.getHeaders(),
             },
         });
         return response.data;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_import_create");
+        throw formatApiError(error, "ol_import_create");
     }
 }
 export async function importList(input) {
@@ -81,7 +89,7 @@ export async function importList(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_import_list");
+        throw formatApiError(error, "ol_import_list");
     }
 }
 export async function importGet(input) {
@@ -98,13 +106,13 @@ export async function importGet(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_import_get");
+        throw formatApiError(error, "ol_import_get");
     }
 }
 // Tool definitions
 export const importToolDefinitions = [
     {
-        name: "openloyalty_import_create",
+        name: "ol_import_create",
         title: "Create Bulk Import",
         description: "Create a new bulk import from CSV content. Returns importId for async tracking. Import types: member (member data), groupValue (group values), segmentMembers (segment membership), unitTransferAdding (add points), unitTransferSpending (spend points), transaction (transactions), campaignCode (campaign codes), rewardCoupon (reward coupons). CSV format required - provide plain text CSV content.",
         readOnly: false,
@@ -112,7 +120,7 @@ export const importToolDefinitions = [
         handler: importCreate,
     },
     {
-        name: "openloyalty_import_list",
+        name: "ol_import_list",
         title: "List Imports",
         description: "List imports with optional filtering. Returns paginated list of imports with importId, type, uploadedDate, fileName, and status information.",
         readOnly: true,
@@ -120,7 +128,7 @@ export const importToolDefinitions = [
         handler: importList,
     },
     {
-        name: "openloyalty_import_get",
+        name: "ol_import_get",
         title: "Get Import Details",
         description: "Get import details and individual item statuses. Returns paginated list of import items with their success/failure status and error messages.",
         readOnly: true,

package/dist/tools/index.js

@@ -1,13 +1,13 @@
 import { walletTypeToolDefinitions } from "./wallet-type.js";
 import { tiersetToolDefinitions } from "./tierset.js";
-import { memberToolDefinitions } from "./member.js";
+import { memberToolDefinitions } from "./member/index.js";
 import { pointsToolDefinitions } from "./points.js";
-import { rewardToolDefinitions } from "./reward.js";
+import { rewardToolDefinitions } from "./reward/index.js";
 import { transactionToolDefinitions } from "./transaction.js";
 // Phase 2 tools
-import { campaignToolDefinitions } from "./campaign.js";
-import { segmentToolDefinitions } from "./segment.js";
-import { achievementToolDefinitions } from "./achievement.js";
+import { campaignToolDefinitions } from "./campaign/index.js";
+import { segmentToolDefinitions } from "./segment/index.js";
+import { achievementToolDefinitions } from "./achievement/index.js";
 import { badgeToolDefinitions } from "./badge.js";
 // Phase 3 tools
 import { analyticsToolDefinitions } from "./analytics.js";
@@ -20,6 +20,10 @@ import { storeToolDefinitions } from "./store.js";
 import { webhookToolDefinitions } from "./webhook.js";
 import { importToolDefinitions } from "./import.js";
 import { exportToolDefinitions } from "./export.js";
+// Custom event tools (needed for custom_event trigger in campaigns/achievements)
+import { customEventToolDefinitions } from "./custom-event.js";
+// Referral tools (needed for referral tracking between members)
+import { referralToolDefinitions } from "./referral/index.js";
 // Collect all tool definitions
 // Note: Single cast needed because tool handlers have specific input types
 // (e.g., { memberId: string }) while ToolDefinition uses generic Record<string, unknown>.
@@ -48,6 +52,10 @@ const allTools = [
     ...webhookToolDefinitions,
     ...importToolDefinitions,
     ...exportToolDefinitions,
+    // Custom event tools
+    ...customEventToolDefinitions,
+    // Referral tools
+    ...referralToolDefinitions,
 ];
 const toolHandlers = new Map();
 for (const tool of allTools) {

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

@@ -0,0 +1,111 @@
+import { Member } from "../../types/schemas/member.js";
+export declare function memberCreate(input: {
+    storeCode?: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    birthDate?: string;
+    gender?: string;
+    loyaltyCardNumber?: string;
+    agreement1?: boolean;
+    agreement2?: boolean;
+    agreement3?: boolean;
+    address?: {
+        street?: string;
+        city?: string;
+        postal?: string;
+        country?: string;
+        province?: string;
+    };
+}): Promise<{
+    memberId: string;
+    loyaltyCardNumber: string;
+    email: string;
+}>;
+export declare function memberGet(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<Member>;
+export declare function memberList(input: {
+    storeCode?: string;
+    cursor?: string;
+    page?: number;
+    perPage?: number;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    loyaltyCardNumber?: string;
+    active?: boolean;
+}): Promise<{
+    members: Array<{
+        memberId: string;
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        loyaltyCardNumber?: string;
+        active: boolean;
+    }>;
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+    cursor?: string;
+}>;
+export declare function memberUpdate(input: {
+    storeCode?: string;
+    memberId: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    birthDate?: string;
+    gender?: string;
+    address?: {
+        street?: string;
+        city?: string;
+        postal?: string;
+        country?: string;
+        province?: string;
+    };
+    agreement1?: boolean;
+    agreement2?: boolean;
+    agreement3?: boolean;
+}): Promise<void>;
+export declare function memberActivate(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<void>;
+export declare function memberDeactivate(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<void>;
+export declare function memberDelete(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<void>;
+export declare function memberGetTierProgress(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<{
+    currentTier?: {
+        levelId: string;
+        name: string;
+    };
+    nextTier?: {
+        levelId: string;
+        name: string;
+    };
+    currentValue: number;
+    requiredValue?: number;
+    progressPercent: number;
+}>;
+export declare function memberAssignTier(input: {
+    storeCode?: string;
+    memberId: string;
+    levelId: string;
+}): Promise<void>;
+export declare function memberRemoveManualTier(input: {
+    storeCode?: string;
+    memberId: string;
+}): Promise<void>;

package/dist/tools/member/handlers.js

@@ -0,0 +1,206 @@
+import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
+import { MemberSchema } from "../../types/schemas/member.js";
+import { formatApiError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+import { buildPaginationParams } from "../../utils/pagination.js";
+import { omitUndefined } from "../../utils/payload.js";
+export async function memberCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const payload = omitUndefined({
+        email: input.email,
+        firstName: input.firstName,
+        lastName: input.lastName,
+        phone: input.phone,
+        birthDate: input.birthDate,
+        gender: input.gender,
+        loyaltyCardNumber: input.loyaltyCardNumber,
+        agreement1: input.agreement1,
+        agreement2: input.agreement2,
+        agreement3: input.agreement3,
+        address: input.address,
+    });
+    try {
+        const response = await apiPost(`/${storeCode}/member`, { customer: payload });
+        return {
+            memberId: response.customerId,
+            loyaltyCardNumber: response.loyaltyCardNumber || "",
+            email: response.email,
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_create");
+    }
+}
+export async function memberGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/member/${input.memberId}`);
+        // Map API response to our schema
+        const data = response;
+        const mapped = {
+            memberId: data.customerId || data.memberId,
+            email: data.email,
+            firstName: data.firstName,
+            lastName: data.lastName,
+            phone: data.phone,
+            birthDate: data.birthDate,
+            gender: data.gender,
+            loyaltyCardNumber: data.loyaltyCardNumber,
+            active: data.active ?? true,
+            createdAt: data.createdAt,
+            address: data.address,
+            agreement1: data.agreement1,
+            agreement2: data.agreement2,
+            agreement3: data.agreement3,
+            levelId: data.levelId || data.level?.levelId,
+            levelName: data.levelName || data.level?.name,
+            points: data.points,
+        };
+        return MemberSchema.parse(mapped);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_get");
+    }
+}
+export async function memberList(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const params = new URLSearchParams();
+    // Use buildPaginationParams for cursor/page handling
+    buildPaginationParams({ cursor: input.cursor, page: input.page, perPage: input.perPage }, params);
+    if (input.email)
+        params.append("email", input.email);
+    if (input.firstName)
+        params.append("firstName", input.firstName);
+    if (input.lastName)
+        params.append("lastName", input.lastName);
+    if (input.phone)
+        params.append("phone", input.phone);
+    if (input.loyaltyCardNumber)
+        params.append("loyaltyCardNumber", input.loyaltyCardNumber);
+    if (input.active !== undefined)
+        params.append("active", String(input.active));
+    const queryString = params.toString();
+    const url = `/${storeCode}/member${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const members = (response.items || []).map((c) => {
+            const customer = c;
+            return {
+                memberId: (customer.customerId || customer.memberId),
+                email: customer.email,
+                firstName: customer.firstName,
+                lastName: customer.lastName,
+                loyaltyCardNumber: customer.loyaltyCardNumber,
+                active: (customer.active ?? true),
+            };
+        });
+        const total = response.total || {};
+        return {
+            members,
+            total: {
+                all: typeof total.all === 'number' ? total.all : undefined,
+                filtered: typeof total.filtered === 'number' ? total.filtered : undefined,
+            },
+            cursor: response.scroll,
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_list");
+    }
+}
+export async function memberUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // API requires email even for partial updates - fetch existing member to get it
+    const existingResponse = await apiGet(`/${storeCode}/member/${input.memberId}`);
+    const existingEmail = existingResponse.email;
+    const payload = omitUndefined({
+        email: existingEmail, // Required by API even for partial updates
+        firstName: input.firstName,
+        lastName: input.lastName,
+        phone: input.phone,
+        birthDate: input.birthDate,
+        gender: input.gender,
+        address: input.address,
+        agreement1: input.agreement1,
+        agreement2: input.agreement2,
+        agreement3: input.agreement3,
+    });
+    try {
+        await apiPut(`/${storeCode}/member/${input.memberId}`, { customer: payload });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_update");
+    }
+}
+export async function memberActivate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/member/${input.memberId}/activate`);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_activate");
+    }
+}
+export async function memberDeactivate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/member/${input.memberId}/deactivate`);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_deactivate");
+    }
+}
+export async function memberDelete(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiDelete(`/${storeCode}/member/${input.memberId}`);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_delete");
+    }
+}
+export async function memberGetTierProgress(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        // API uses /level endpoint, not /tier
+        const response = await apiGet(`/${storeCode}/member/${input.memberId}/level`);
+        // Response may have level data directly or nested
+        const currentLevel = (response.currentLevel || response.level);
+        const nextLevel = response.nextLevel;
+        return {
+            currentTier: currentLevel ? {
+                levelId: (currentLevel.levelId || currentLevel.id),
+                name: currentLevel.name,
+            } : undefined,
+            nextTier: nextLevel ? {
+                levelId: (nextLevel.levelId || nextLevel.id),
+                name: nextLevel.name,
+            } : undefined,
+            currentValue: (response.currentValue || response.value || 0),
+            requiredValue: (response.requiredValue || response.conditionValue),
+            progressPercent: (response.progressPercent || response.progress || 0),
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_get_tier_progress");
+    }
+}
+export async function memberAssignTier(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/member/${input.memberId}/tier`, { levelId: input.levelId });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_assign_tier");
+    }
+}
+export async function memberRemoveManualTier(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        // API uses POST to /remove-manually-level, not DELETE to /tier
+        await apiPost(`/${storeCode}/member/${input.memberId}/remove-manually-level`);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_member_remove_manual_tier");
+    }
+}