@open-loyalty/mcp-server 1.7.0 → 1.12.0

package/dist/tools/channel/handlers.js

@@ -0,0 +1,130 @@
+import { apiGet, apiPost, apiPut, apiDelete } from "../../client/http.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import axios from "axios";
+import { getStoreCode } from "../../config.js";
+export async function channelList(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.identifier)
+        params.append("identifier", input.identifier);
+    const queryString = params.toString();
+    const url = `/${storeCode}/channel${queryString ? `?${queryString}` : ""}`;
+    try {
+        const response = await apiGet(url);
+        return response;
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_channel_list");
+    }
+}
+export async function channelCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const payload = {
+        name: input.name,
+        identifier: input.identifier,
+    };
+    if (input.description)
+        payload.description = input.description;
+    try {
+        const response = await apiPost(`/${storeCode}/channel`, { channel: payload });
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 400) {
+            const allMessages = [
+                error.response?.data?.message || "",
+                ...(error.response?.data?.errors || []).map((e) => e.message),
+            ].join(" ").toLowerCase();
+            if (allMessages.includes("identifier") && (allMessages.includes("unique") || allMessages.includes("exists") || allMessages.includes("already"))) {
+                throw new OpenLoyaltyError({
+                    code: "DUPLICATE_IDENTIFIER",
+                    message: `Channel with identifier '${input.identifier}' already exists`,
+                    hint: `Use ol_channel_list() to find the existing channel, or choose a different identifier.`,
+                    relatedTool: "ol_channel_create",
+                });
+            }
+        }
+        throw formatApiError(error, "ol_channel_create");
+    }
+}
+export async function channelGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/channel/${input.channelId}`);
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Channel '${input.channelId}' not found`,
+                hint: "Use ol_channel_list() to find existing channels and their IDs.",
+                relatedTool: "ol_channel_get",
+            });
+        }
+        throw formatApiError(error, "ol_channel_get");
+    }
+}
+export async function channelUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    const payload = {
+        name: input.name,
+        identifier: input.identifier,
+    };
+    if (input.description !== undefined)
+        payload.description = input.description;
+    try {
+        const response = await apiPut(`/${storeCode}/channel/${input.channelId}`, { channel: payload });
+        return response;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            if (error.response?.status === 404) {
+                throw new OpenLoyaltyError({
+                    code: "NOT_FOUND",
+                    message: `Channel '${input.channelId}' not found`,
+                    hint: "Use ol_channel_list() to find existing channels and their IDs.",
+                    relatedTool: "ol_channel_update",
+                });
+            }
+            if (error.response?.status === 400) {
+                const allMessages = [
+                    error.response?.data?.message || "",
+                    ...(error.response?.data?.errors || []).map((e) => e.message),
+                ].join(" ").toLowerCase();
+                if (allMessages.includes("identifier") && (allMessages.includes("unique") || allMessages.includes("exists") || allMessages.includes("already"))) {
+                    throw new OpenLoyaltyError({
+                        code: "DUPLICATE_IDENTIFIER",
+                        message: `Channel with identifier '${input.identifier}' already exists`,
+                        hint: `Use ol_channel_list() to find channels with that identifier, or choose a different identifier.`,
+                        relatedTool: "ol_channel_update",
+                    });
+                }
+            }
+        }
+        throw formatApiError(error, "ol_channel_update");
+    }
+}
+export async function channelDelete(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        await apiDelete(`/${storeCode}/channel/${input.channelId}`);
+    }
+    catch (error) {
+        if (axios.isAxiosError(error) && error.response?.status === 404) {
+            throw new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: `Channel '${input.channelId}' not found`,
+                hint: "Use ol_channel_list() to find existing channels and their IDs.",
+                relatedTool: "ol_channel_delete",
+            });
+        }
+        throw formatApiError(error, "ol_channel_delete");
+    }
+}

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

@@ -0,0 +1,68 @@
+export { ChannelListInputSchema, ChannelCreateInputSchema, ChannelGetInputSchema, ChannelUpdateInputSchema, ChannelDeleteInputSchema, } from "./schemas.js";
+export { channelList, channelCreate, channelGet, channelUpdate, channelDelete, } from "./handlers.js";
+import { channelList, channelCreate, channelGet, channelUpdate, channelDelete } from "./handlers.js";
+export declare const channelToolDefinitions: readonly [{
+    readonly name: "ol_channel_list";
+    readonly title: "List Channels";
+    readonly description: string;
+    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>;
+        identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof channelList;
+}, {
+    readonly name: "ol_channel_create";
+    readonly title: "Create Channel";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly idempotent: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        name: import("zod").ZodString;
+        identifier: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof channelCreate;
+}, {
+    readonly name: "ol_channel_get";
+    readonly title: "Get Channel Details";
+    readonly description: "Get full details of a specific channel by channelId.";
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        channelId: import("zod").ZodString;
+    };
+    readonly handler: typeof channelGet;
+}, {
+    readonly name: "ol_channel_update";
+    readonly title: "Update Channel";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        channelId: import("zod").ZodString;
+        name: import("zod").ZodString;
+        identifier: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof channelUpdate;
+}, {
+    readonly name: "ol_channel_delete";
+    readonly title: "Delete Channel (Permanent)";
+    readonly description: "Permanently delete a channel. This cannot be undone. Use ol_channel_list to find the channelId first.";
+    readonly readOnly: false;
+    readonly destructive: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        channelId: import("zod").ZodString;
+    };
+    readonly handler: typeof channelDelete;
+}];

package/dist/tools/channel/index.js

@@ -0,0 +1,59 @@
+// Re-export schemas
+export { ChannelListInputSchema, ChannelCreateInputSchema, ChannelGetInputSchema, ChannelUpdateInputSchema, ChannelDeleteInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { channelList, channelCreate, channelGet, channelUpdate, channelDelete, } from "./handlers.js";
+// Imports for tool definitions
+import { ChannelListInputSchema, ChannelCreateInputSchema, ChannelGetInputSchema, ChannelUpdateInputSchema, ChannelDeleteInputSchema, } from "./schemas.js";
+import { channelList, channelCreate, channelGet, channelUpdate, channelDelete, } from "./handlers.js";
+// Tool definitions
+export const channelToolDefinitions = [
+    {
+        name: "ol_channel_list",
+        title: "List Channels",
+        description: "List sales channels (e.g. Mobile App, Point of Sale, Web). Returns channelId, name, identifier, description. " +
+            "Filter by name or identifier.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: ChannelListInputSchema,
+        handler: channelList,
+    },
+    {
+        name: "ol_channel_create",
+        title: "Create Channel",
+        description: "Create a new sales channel. REQUIRED: name and identifier (must be unique within the store). " +
+            "Returns channelId on success.",
+        readOnly: false,
+        idempotent: false,
+        inputSchema: ChannelCreateInputSchema,
+        handler: channelCreate,
+    },
+    {
+        name: "ol_channel_get",
+        title: "Get Channel Details",
+        description: "Get full details of a specific channel by channelId.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: ChannelGetInputSchema,
+        handler: channelGet,
+    },
+    {
+        name: "ol_channel_update",
+        title: "Update Channel",
+        description: "Update a channel's name, identifier, or description. Both name and identifier are required (PUT replaces the full object). " +
+            "Returns channelId on success.",
+        readOnly: false,
+        idempotent: true,
+        inputSchema: ChannelUpdateInputSchema,
+        handler: channelUpdate,
+    },
+    {
+        name: "ol_channel_delete",
+        title: "Delete Channel (Permanent)",
+        description: "Permanently delete a channel. This cannot be undone. Use ol_channel_list to find the channelId first.",
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        inputSchema: ChannelDeleteInputSchema,
+        handler: channelDelete,
+    },
+];

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const ChannelListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    identifier: z.ZodOptional<z.ZodString>;
+};
+export declare const ChannelCreateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    identifier: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+};
+export declare const ChannelGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    channelId: z.ZodString;
+};
+export declare const ChannelUpdateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    channelId: z.ZodString;
+    name: z.ZodString;
+    identifier: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+};
+export declare const ChannelDeleteInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    channelId: z.ZodString;
+};

package/dist/tools/channel/schemas.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+const STORE_CODE = 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.");
+export const ChannelListInputSchema = {
+    storeCode: STORE_CODE,
+    page: z.number().optional().describe("Page number (default: 1)."),
+    perPage: z.number().optional().describe("Items per page (default: 25)."),
+    name: z.string().optional().describe("Filter by channel name."),
+    identifier: z.string().optional().describe("Filter by channel identifier."),
+};
+export const ChannelCreateInputSchema = {
+    storeCode: STORE_CODE,
+    name: z.string().describe("Channel name (required). E.g. 'Mobile App', 'Point of Sale'."),
+    identifier: z.string().describe("Unique channel identifier (required). E.g. 'mobile', 'pos', 'web'."),
+    description: z.string().optional().describe("Channel description."),
+};
+export const ChannelGetInputSchema = {
+    storeCode: STORE_CODE,
+    channelId: z.string().describe("Channel ID (UUID) to retrieve."),
+};
+export const ChannelUpdateInputSchema = {
+    storeCode: STORE_CODE,
+    channelId: z.string().describe("Channel ID (UUID) to update."),
+    name: z.string().describe("Channel name."),
+    identifier: z.string().describe("Channel identifier (unique)."),
+    description: z.string().optional().describe("Channel description."),
+};
+export const ChannelDeleteInputSchema = {
+    storeCode: STORE_CODE,
+    channelId: z.string().describe("Channel ID (UUID) to delete."),
+};

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

@@ -0,0 +1,49 @@
+import type { ContextGetInput } from "./schemas.js";
+interface TierSummary {
+    levelId: string;
+    name: string;
+    active: boolean;
+}
+interface TierSetSummary {
+    tierSetId: string;
+    name: string;
+    active: boolean;
+    tiers: TierSummary[];
+}
+interface ContextResult {
+    storeCode: string;
+    store?: {
+        code: string;
+        name: string;
+        currency?: string;
+    };
+    walletTypes: Array<{
+        code: string;
+        name: string;
+        unitSingularName?: string;
+    }>;
+    tierSets: TierSetSummary[];
+    activeSegments: Array<{
+        segmentId: string;
+        name: string;
+        customersCount?: number;
+    }>;
+    activeCampaigns: Array<{
+        campaignId: string;
+        name: string;
+        type: string;
+        trigger: string;
+    }>;
+    activeRewards: Array<{
+        rewardId: string;
+        name: string;
+        type: string;
+        costInPoints?: number;
+    }>;
+    rewardCategories: Array<{
+        categoryId: string;
+        name: string;
+    }>;
+}
+export declare function contextGet(input: ContextGetInput): Promise<ContextResult>;
+export {};

package/dist/tools/context/handlers.js

@@ -0,0 +1,131 @@
+import { apiGet } from "../../client/http.js";
+import { getStoreCode } from "../../config.js";
+function extractCampaignName(campaign) {
+    const translations = campaign.translations;
+    if (Array.isArray(translations)) {
+        const enT = translations.find((t) => t.locale === "en" || (t.locale ?? "").startsWith("en"));
+        return enT?.name || translations[0]?.name || campaign.name || "";
+    }
+    if (translations && typeof translations === "object") {
+        return translations.en?.name || campaign.name || "";
+    }
+    return campaign.name || "";
+}
+export async function contextGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // Parallel batch 1: fetch all list data simultaneously
+    const [walletTypesResult, tierSetsResult, segmentsResult, campaignsResult, rewardsResult, rewardCategoriesResult, storeResult,] = await Promise.allSettled([
+        apiGet(`/${storeCode}/walletType`),
+        apiGet(`/${storeCode}/tierSet?_itemsOnPage=10`),
+        apiGet(`/${storeCode}/segment?active=true&_itemsOnPage=50`),
+        apiGet(`/${storeCode}/campaign?active=true&_itemsOnPage=50`),
+        apiGet(`/${storeCode}/reward?active=true&_itemsOnPage=50`),
+        apiGet(`/${storeCode}/rewardCategory?_itemsOnPage=50`),
+        // Store info: best-effort — may fail if user lacks STORE:VIEW permission
+        apiGet(`/store?code=${encodeURIComponent(storeCode)}`),
+    ]);
+    // Process wallet types
+    const walletTypes = [];
+    if (walletTypesResult.status === "fulfilled") {
+        const rawList = walletTypesResult.value;
+        const items = Array.isArray(rawList) ? rawList : rawList.items ?? [];
+        for (const wt of items) {
+            const w = wt;
+            walletTypes.push({
+                code: w.code,
+                name: w.name,
+                unitSingularName: w.unitSingularName,
+            });
+        }
+    }
+    // Process tier sets — fetch each individually to get embedded tiers (max 3 per API limit)
+    const tierSets = [];
+    if (tierSetsResult.status === "fulfilled") {
+        const tierSetItems = tierSetsResult.value.items ?? [];
+        const tierSetDetails = await Promise.allSettled(tierSetItems.map((ts) => apiGet(`/${storeCode}/tierSet/${ts.tierSetId}`)));
+        for (let i = 0; i < tierSetItems.length; i++) {
+            const ts = tierSetItems[i];
+            const detail = tierSetDetails[i];
+            const tiers = [];
+            if (detail.status === "fulfilled" && detail.value.tiers) {
+                for (const tier of detail.value.tiers) {
+                    tiers.push({
+                        levelId: tier.levelId,
+                        name: tier.name,
+                        active: typeof tier.active === "boolean" ? tier.active : true,
+                    });
+                }
+            }
+            tierSets.push({ tierSetId: ts.tierSetId, name: ts.name, active: ts.active, tiers });
+        }
+    }
+    // Process active segments
+    const activeSegments = [];
+    if (segmentsResult.status === "fulfilled") {
+        for (const seg of segmentsResult.value.items ?? []) {
+            activeSegments.push({
+                segmentId: seg.segmentId,
+                name: seg.name,
+                customersCount: seg.customersCount,
+            });
+        }
+    }
+    // Process active campaigns
+    const activeCampaigns = [];
+    if (campaignsResult.status === "fulfilled") {
+        for (const c of campaignsResult.value.items ?? []) {
+            const campaign = c;
+            activeCampaigns.push({
+                campaignId: campaign.campaignId,
+                name: extractCampaignName(campaign),
+                type: campaign.type,
+                trigger: campaign.trigger,
+            });
+        }
+    }
+    // Process active rewards
+    const activeRewards = [];
+    if (rewardsResult.status === "fulfilled") {
+        for (const r of rewardsResult.value.items ?? []) {
+            const reward = r;
+            activeRewards.push({
+                rewardId: reward.rewardId,
+                name: reward.name,
+                type: (reward.reward || reward.type) ?? "",
+                costInPoints: reward.costInPoints,
+            });
+        }
+    }
+    // Process reward categories
+    const rewardCategories = [];
+    if (rewardCategoriesResult.status === "fulfilled") {
+        const rawCats = rewardCategoriesResult.value;
+        const catItems = (rawCats.items || rawCats.categories || []);
+        for (const c of catItems) {
+            const cat = c;
+            rewardCategories.push({
+                categoryId: (cat.rewardCategoryId || cat.categoryId) ?? "",
+                name: cat.name,
+            });
+        }
+    }
+    // Process store info (best-effort)
+    let store;
+    if (storeResult.status === "fulfilled") {
+        const storeItems = storeResult.value.items;
+        if (storeItems && storeItems.length > 0) {
+            const s = storeItems[0];
+            store = { code: s.code, name: s.name, currency: s.currency };
+        }
+    }
+    return {
+        storeCode,
+        store,
+        walletTypes,
+        tierSets,
+        activeSegments,
+        activeCampaigns,
+        activeRewards,
+        rewardCategories,
+    };
+}

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

@@ -0,0 +1,15 @@
+export { ContextGetInputSchema } from "./schemas.js";
+export type { ContextGetInput } from "./schemas.js";
+export { contextGet } from "./handlers.js";
+import { contextGet } from "./handlers.js";
+export declare const contextToolDefinitions: readonly [{
+    readonly name: "ol_context_get";
+    readonly title: "Get Store Context";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly idempotent: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    readonly handler: typeof contextGet;
+}];

package/dist/tools/context/index.js

@@ -0,0 +1,20 @@
+export { ContextGetInputSchema } from "./schemas.js";
+export { contextGet } from "./handlers.js";
+import { ContextGetInputSchema } from "./schemas.js";
+import { contextGet } from "./handlers.js";
+export const contextToolDefinitions = [
+    {
+        name: "ol_context_get",
+        title: "Get Store Context",
+        description: "Get current store state in a single call: wallet types, tier sets (with tier IDs), " +
+            "active segments, active campaigns, active rewards, and reward categories. " +
+            "Call this FIRST at the start of every session to surface IDs for targeting, " +
+            "prevent duplicate creation, and avoid 5+ individual discovery calls. " +
+            "Results contain the levelId values needed for reward/campaign tier targeting, " +
+            "segmentId values for audience targeting, and categoryId values for reward categorization.",
+        readOnly: true,
+        idempotent: true,
+        inputSchema: ContextGetInputSchema,
+        handler: contextGet,
+    },
+];

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

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const ContextGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+};
+export type ContextGetInput = {
+    storeCode?: string;
+};

package/dist/tools/context/schemas.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const ContextGetInputSchema = {
+    storeCode: z.string().optional().describe("Store code to get context for. Uses configured default store if not provided."),
+};

package/dist/tools/group-of-values/handlers.d.ts

@@ -0,0 +1,39 @@
+export declare function groupOfValuesList(input: {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+    active?: boolean;
+}): Promise<Record<string, unknown>>;
+export declare function groupOfValuesCreate(input: {
+    storeCode?: string;
+    name: string;
+    description?: string;
+    active?: boolean;
+}): Promise<{
+    groupOfValuesId: string;
+}>;
+export declare function groupOfValuesUpdate(input: {
+    storeCode?: string;
+    groupOfValuesId: string;
+    name?: string;
+    description?: string;
+    active?: boolean;
+}): Promise<Record<string, unknown>>;
+export declare function groupValueAdd(input: {
+    storeCode?: string;
+    groupOfValuesId: string;
+    value: string;
+    description?: string;
+}): Promise<{
+    valueId: string;
+}>;
+export declare function groupValueUpdate(input: {
+    storeCode?: string;
+    valueId: string;
+    value: string;
+    description?: string;
+}): Promise<Record<string, unknown>>;
+export declare function groupValueDelete(input: {
+    storeCode?: string;
+    valueId: string;
+}): Promise<void>;