@open-loyalty/mcp-server 1.1.0 → 1.3.3

package/dist/tools/reward/schemas.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+export const RewardListInputSchema = {
+    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: 10)."),
+    active: z.boolean().optional().describe("Filter by active status."),
+    type: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).optional().describe("Filter by reward type."),
+    categoryId: z.string().optional().describe("Filter by category ID."),
+};
+// Translations schema for rewards (API requires translations.en at minimum)
+// Note: translations.en must ONLY contain name, description is a separate field at top level
+const RewardTranslationsInputSchema = z.object({
+    en: z.object({
+        name: z.string().describe("Reward name in English (required)."),
+    }),
+}).passthrough().describe("Translations object with at least 'en' key containing { name }. Description goes at top level.");
+// Activity period schema (REQUIRED by API)
+// API requires datetime format: YYYY-MM-DD HH:mm (NOT just YYYY-MM-DD)
+const RewardActivityInputSchema = z.object({
+    from: z.string().describe("Start datetime (format: 'YYYY-MM-DD HH:mm', e.g., '2026-01-01 00:00'). REQUIRED."),
+    to: z.string().describe("End datetime (format: 'YYYY-MM-DD HH:mm', e.g., '2026-12-31 23:59'). REQUIRED."),
+});
+// Visibility period schema (REQUIRED by API)
+// API requires datetime format: YYYY-MM-DD HH:mm (NOT just YYYY-MM-DD)
+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
+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."),
+});
+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."),
+    reward: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).describe("Reward type: static_coupon (fixed discount), dynamic_coupon (variable value), " +
+        "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."),
+    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)."),
+    categories: z.array(z.string()).optional().describe("Array of category UUIDs."),
+    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs that can see/redeem."),
+    segments: z.array(z.string()).optional().describe("Array of segment UUIDs that can see/redeem."),
+    target: z.enum(["level", "segment"]).nullable().optional().describe("Target type for visibility: level (tier-based), segment (segment-based), or null (all)."),
+    couponValue: z.number().optional().describe("Coupon value (required for static_coupon)."),
+    couponValueType: z.enum(["money", "percentage"]).optional().describe("Coupon value type: 'money' or 'percentage' (lowercase)."),
+    daysValid: z.number().optional().describe("Days the coupon remains valid after purchase."),
+};
+export const RewardGetInputSchema = {
+    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."),
+    rewardId: z.string().describe("The reward ID (UUID) to retrieve."),
+};
+export const RewardUpdateInputSchema = {
+    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."),
+    rewardId: z.string().describe("The reward ID (UUID) to update."),
+    name: z.string().optional().describe("Reward name."),
+    costInPoints: z.number().optional().describe("Points required to redeem."),
+    description: z.string().optional().describe("Reward description."),
+    active: z.boolean().optional().describe("Whether reward is active."),
+    categories: z.array(z.string()).optional().describe("Array of category UUIDs."),
+    levels: z.array(z.string()).optional().describe("Array of tier level UUIDs."),
+    segments: z.array(z.string()).optional().describe("Array of segment UUIDs."),
+};
+export const RewardIdInputSchema = {
+    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."),
+    rewardId: z.string().describe("The reward ID (UUID)."),
+};
+export const RewardBuyInputSchema = {
+    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."),
+    rewardId: z.string().describe("The reward ID (UUID) to purchase."),
+    memberId: z.string().describe("The member ID (UUID) purchasing the reward."),
+    quantity: z.number().optional().describe("Number of rewards to purchase (1-32, default: 1)."),
+    couponValue: z.number().optional().describe("Coupon value (for dynamic coupons)."),
+    withoutPoints: z.boolean().optional().describe("Admin only: skip points deduction."),
+};
+export const RewardRedeemInputSchema = {
+    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."),
+    memberId: z.string().describe("The member ID (UUID) redeeming the coupon."),
+    couponCode: z.string().describe("The coupon code to redeem."),
+};
+export const RewardCategoryListInputSchema = {
+    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: 10)."),
+    active: z.boolean().optional().describe("Filter by active status."),
+};

package/dist/tools/role.d.ts

@@ -89,7 +89,7 @@ export declare function aclGetResources(): Promise<{
     total?: Record<string, unknown>;
 }>;
 export declare const roleToolDefinitions: readonly [{
-    readonly name: "openloyalty_role_list";
+    readonly name: "ol_role_list";
     readonly title: "List Roles";
     readonly description: "List all roles with optional filtering. Returns paginated list of roles with id, name, permissions, master status, and default status.";
     readonly readOnly: true;
@@ -102,7 +102,7 @@ export declare const roleToolDefinitions: readonly [{
     };
     readonly handler: typeof roleList;
 }, {
-    readonly name: "openloyalty_role_create";
+    readonly name: "ol_role_create";
     readonly title: "Create Role";
     readonly description: "Create a new role with permissions. Requires name. Optionally specify permissions (array of {resource, access, filterQuery}) and stores. Returns void on success (201 Created).";
     readonly readOnly: false;
@@ -126,7 +126,7 @@ export declare const roleToolDefinitions: readonly [{
     };
     readonly handler: typeof roleCreate;
 }, {
-    readonly name: "openloyalty_role_get";
+    readonly name: "ol_role_get";
     readonly title: "Get Role Details";
     readonly description: "Get full role details by ID. Returns role with name, permissions array, master status, default status, and stores.";
     readonly readOnly: true;
@@ -135,7 +135,7 @@ export declare const roleToolDefinitions: readonly [{
     };
     readonly handler: typeof roleGet;
 }, {
-    readonly name: "openloyalty_role_update";
+    readonly name: "ol_role_update";
     readonly title: "Update Role";
     readonly description: "Update a role's name, permissions, or stores. Returns void on success (204 No Content).";
     readonly readOnly: false;
@@ -160,7 +160,7 @@ export declare const roleToolDefinitions: readonly [{
     };
     readonly handler: typeof roleUpdate;
 }, {
-    readonly name: "openloyalty_role_delete";
+    readonly name: "ol_role_delete";
     readonly title: "Delete Role (Permanent)";
     readonly description: "Delete a role by ID. Returns void on success (204 No Content). Cannot delete roles that are assigned to admin users.";
     readonly readOnly: false;
@@ -170,7 +170,7 @@ export declare const roleToolDefinitions: readonly [{
     };
     readonly handler: typeof roleDelete;
 }, {
-    readonly name: "openloyalty_acl_get_resources";
+    readonly name: "ol_acl_get_resources";
     readonly title: "Get ACL Resources";
     readonly description: "Get list of available ACL resources. Returns items with code and name for each resource type. Use this to discover available permissions before creating roles.";
     readonly readOnly: true;

package/dist/tools/role.js

@@ -56,7 +56,7 @@ export async function roleList(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_role_list");
+        throw formatApiError(error, "ol_role_list");
     }
 }
 export async function roleCreate(input) {
@@ -73,7 +73,7 @@ export async function roleCreate(input) {
         await apiPost("/acl/role", { role: payload });
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_role_create");
+        throw formatApiError(error, "ol_role_create");
     }
 }
 export async function roleGet(input) {
@@ -82,7 +82,7 @@ export async function roleGet(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_role_get");
+        throw formatApiError(error, "ol_role_get");
     }
 }
 export async function roleUpdate(input) {
@@ -99,7 +99,7 @@ export async function roleUpdate(input) {
         await apiPut(`/acl/role/${input.roleId}`, { role: payload });
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_role_update");
+        throw formatApiError(error, "ol_role_update");
     }
 }
 export async function roleDelete(input) {
@@ -107,7 +107,7 @@ export async function roleDelete(input) {
         await apiDelete(`/acl/role/${input.roleId}`);
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_role_delete");
+        throw formatApiError(error, "ol_role_delete");
     }
 }
 export async function aclGetResources() {
@@ -116,13 +116,13 @@ export async function aclGetResources() {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_acl_get_resources");
+        throw formatApiError(error, "ol_acl_get_resources");
     }
 }
 // Tool definitions
 export const roleToolDefinitions = [
     {
-        name: "openloyalty_role_list",
+        name: "ol_role_list",
         title: "List Roles",
         description: "List all roles with optional filtering. Returns paginated list of roles with id, name, permissions, master status, and default status.",
         readOnly: true,
@@ -130,7 +130,7 @@ export const roleToolDefinitions = [
         handler: roleList,
     },
     {
-        name: "openloyalty_role_create",
+        name: "ol_role_create",
         title: "Create Role",
         description: "Create a new role with permissions. Requires name. Optionally specify permissions (array of {resource, access, filterQuery}) and stores. Returns void on success (201 Created).",
         readOnly: false,
@@ -138,7 +138,7 @@ export const roleToolDefinitions = [
         handler: roleCreate,
     },
     {
-        name: "openloyalty_role_get",
+        name: "ol_role_get",
         title: "Get Role Details",
         description: "Get full role details by ID. Returns role with name, permissions array, master status, default status, and stores.",
         readOnly: true,
@@ -146,7 +146,7 @@ export const roleToolDefinitions = [
         handler: roleGet,
     },
     {
-        name: "openloyalty_role_update",
+        name: "ol_role_update",
         title: "Update Role",
         description: "Update a role's name, permissions, or stores. Returns void on success (204 No Content).",
         readOnly: false,
@@ -154,7 +154,7 @@ export const roleToolDefinitions = [
         handler: roleUpdate,
     },
     {
-        name: "openloyalty_role_delete",
+        name: "ol_role_delete",
         title: "Delete Role (Permanent)",
         description: "Delete a role by ID. Returns void on success (204 No Content). Cannot delete roles that are assigned to admin users.",
         readOnly: false,
@@ -163,7 +163,7 @@ export const roleToolDefinitions = [
         handler: roleDelete,
     },
     {
-        name: "openloyalty_acl_get_resources",
+        name: "ol_acl_get_resources",
         title: "Get ACL Resources",
         description: "Get list of available ACL resources. Returns items with code and name for each resource type. Use this to discover available permissions before creating roles.",
         readOnly: true,

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

@@ -0,0 +1,87 @@
+import { SegmentListItem } from "../../types/schemas/segment.js";
+export declare function segmentList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+    name?: string;
+}): Promise<{
+    segments: SegmentListItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+interface SegmentCreateInput {
+    storeCode?: string;
+    name: string;
+    description?: string;
+    active?: boolean;
+    parts: Array<{
+        segmentPartId?: string;
+        criteria: Array<Record<string, unknown>>;
+    }>;
+}
+export declare function segmentCreate(input: SegmentCreateInput): Promise<{
+    segmentId: string;
+}>;
+export declare function segmentGet(input: {
+    storeCode?: string;
+    segmentId: string;
+}): Promise<Record<string, unknown>>;
+interface SegmentUpdateInput {
+    storeCode?: string;
+    segmentId: string;
+    name: string;
+    description?: string;
+    active?: boolean;
+    parts: Array<{
+        segmentPartId?: string;
+        criteria: Array<Record<string, unknown>>;
+    }>;
+}
+export declare function segmentUpdate(input: SegmentUpdateInput): Promise<void>;
+export declare function segmentDelete(input: {
+    storeCode?: string;
+    segmentId: string;
+}): Promise<void>;
+interface SegmentMember {
+    customerId: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    loyaltyCardNumber?: string;
+    active?: boolean;
+}
+export declare function segmentGetMembers(input: {
+    storeCode?: string;
+    segmentId: string;
+    page?: number;
+    perPage?: number;
+}): Promise<{
+    members: SegmentMember[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function segmentActivate(input: {
+    storeCode?: string;
+    segmentId: string;
+}): Promise<void>;
+export declare function segmentDeactivate(input: {
+    storeCode?: string;
+    segmentId: string;
+}): Promise<void>;
+interface SegmentResource {
+    resourceId: string;
+    resourceType: string;
+    name?: string;
+}
+export declare function segmentGetResources(input: {
+    storeCode?: string;
+    segmentId: string;
+}): Promise<{
+    resources: SegmentResource[];
+}>;
+export {};

package/dist/tools/segment/handlers.js

@@ -0,0 +1,174 @@
+import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
+import { formatApiError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+const DEFAULT_TRANSACTION_COUNT_MAX = 999999;
+function normalizeSegmentParts(parts) {
+    return parts.map((part) => ({
+        ...part,
+        criteria: part.criteria.map((criterion) => {
+            if (!criterion || typeof criterion !== "object") {
+                return criterion;
+            }
+            const normalized = { ...criterion };
+            if (normalized.type === "transaction_count" &&
+                normalized.min !== undefined &&
+                normalized.max === undefined) {
+                normalized.max = DEFAULT_TRANSACTION_COUNT_MAX;
+            }
+            return normalized;
+        }),
+    }));
+}
+export async function segmentList(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));
+    if (input.name)
+        params.append("name", input.name);
+    const queryString = params.toString();
+    const url = `/${storeCode}/segment${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const segments = (response.items || []).map((item) => ({
+            segmentId: item.segmentId,
+            name: item.name,
+            description: item.description,
+            active: item.active,
+            customersCount: item.customersCount,
+            createdAt: item.createdAt,
+        }));
+        const total = response.total || {};
+        return {
+            segments,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_list");
+    }
+}
+export async function segmentCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const segmentPayload = {
+        name: input.name,
+        parts: normalizeSegmentParts(input.parts),
+    };
+    if (input.description)
+        segmentPayload.description = input.description;
+    if (input.active !== undefined)
+        segmentPayload.active = input.active;
+    try {
+        // CRITICAL: Wrap body as { segment: {...} }
+        const response = await apiPost(`/${storeCode}/segment`, { segment: segmentPayload });
+        return { segmentId: response.segmentId };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_create");
+    }
+}
+export async function segmentGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/segment/${input.segmentId}`);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_get");
+    }
+}
+export async function segmentUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const segmentPayload = {
+        name: input.name,
+        parts: normalizeSegmentParts(input.parts),
+    };
+    if (input.description !== undefined)
+        segmentPayload.description = input.description;
+    if (input.active !== undefined)
+        segmentPayload.active = input.active;
+    try {
+        // CRITICAL: Wrap body as { segment: {...} }
+        await apiPut(`/${storeCode}/segment/${input.segmentId}`, { segment: segmentPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_update");
+    }
+}
+export async function segmentDelete(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiDelete(`/${storeCode}/segment/${input.segmentId}`);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_delete");
+    }
+}
+export async function segmentGetMembers(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));
+    const queryString = params.toString();
+    const url = `/${storeCode}/segment/${input.segmentId}/members${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        const members = (response.items || []).map((item) => ({
+            customerId: item.customerId,
+            firstName: item.firstName,
+            lastName: item.lastName,
+            email: item.email,
+            loyaltyCardNumber: item.loyaltyCardNumber,
+            active: item.active,
+        }));
+        const total = response.total || {};
+        return {
+            members,
+            total: {
+                all: typeof total.all === "number" ? total.all : undefined,
+                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_get_members");
+    }
+}
+export async function segmentActivate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/segment/${input.segmentId}/activate`, {});
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_activate");
+    }
+}
+export async function segmentDeactivate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiPost(`/${storeCode}/segment/${input.segmentId}/deactivate`, {});
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_deactivate");
+    }
+}
+export async function segmentGetResources(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/segment/${input.segmentId}/resources`);
+        const resources = response.items || response.resources || [];
+        return { resources };
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_segment_get_resources");
+    }
+}