@open-loyalty/mcp-server 1.0.0

package/dist/tools/tierset.d.ts

@@ -0,0 +1,288 @@
+import { z } from "zod";
+import { TierSet, TierSetListItem, Tier } from "../types/schemas/tierset.js";
+export declare const TierSetListInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    perPage: z.ZodOptional<z.ZodNumber>;
+};
+export declare const TierSetCreateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    conditions: z.ZodArray<z.ZodObject<{
+        attribute: z.ZodEnum<["activeUnits", "totalEarnedUnits", "totalSpending", "monthsSinceJoiningProgram", "cumulatedEarnedUnits"]>;
+        walletType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+        walletType?: string | undefined;
+    }, {
+        attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+        walletType?: string | undefined;
+    }>, "many">;
+    downgrade: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<["none", "automatic", "x_days"]>;
+        days: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "none" | "automatic" | "x_days";
+        days?: number | undefined;
+    }, {
+        mode: "none" | "automatic" | "x_days";
+        days?: number | undefined;
+    }>>;
+    active: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const TierSetGetInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    tierSetId: z.ZodString;
+};
+export declare const TierSetUpdateInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    tierSetId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    downgrade: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<["none", "automatic", "x_days"]>;
+        days: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "none" | "automatic" | "x_days";
+        days?: number | undefined;
+    }, {
+        mode: "none" | "automatic" | "x_days";
+        days?: number | undefined;
+    }>>;
+};
+export declare const TierSetUpdateTiersInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    tierSetId: z.ZodString;
+    tiers: z.ZodArray<z.ZodObject<{
+        levelId: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        conditions: z.ZodArray<z.ZodObject<{
+            conditionId: z.ZodString;
+            value: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            value: number;
+            conditionId: string;
+        }, {
+            value: number;
+            conditionId: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        conditions: {
+            value: number;
+            conditionId: string;
+        }[];
+        active?: boolean | undefined;
+        description?: string | undefined;
+        levelId?: string | undefined;
+    }, {
+        name: string;
+        conditions: {
+            value: number;
+            conditionId: string;
+        }[];
+        active?: boolean | undefined;
+        description?: string | undefined;
+        levelId?: string | undefined;
+    }>, "many">;
+};
+export declare const TierSetGetTiersInputSchema: {
+    storeCode: z.ZodOptional<z.ZodString>;
+    tierSetId: z.ZodString;
+};
+type TierSetListInput = {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+};
+type TierSetCreateInput = {
+    storeCode?: string;
+    name: string;
+    description?: string;
+    conditions: {
+        attribute: string;
+        walletType?: string;
+    }[];
+    downgrade?: {
+        mode: string;
+        days?: number;
+    };
+    active?: boolean;
+};
+type TierSetGetInput = {
+    storeCode?: string;
+    tierSetId: string;
+};
+type TierSetUpdateInput = {
+    storeCode?: string;
+    tierSetId: string;
+    name?: string;
+    description?: string;
+    active?: boolean;
+    downgrade?: {
+        mode: string;
+        days?: number;
+    };
+};
+type TierSetUpdateTiersInput = {
+    storeCode?: string;
+    tierSetId: string;
+    tiers: {
+        levelId?: string;
+        name: string;
+        description?: string;
+        active?: boolean;
+        conditions: {
+            conditionId: string;
+            value: number;
+        }[];
+    }[];
+};
+export declare function tiersetList(input: TierSetListInput): Promise<{
+    items: TierSetListItem[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare function tiersetCreate(input: TierSetCreateInput): Promise<{
+    tierSetId: string;
+    conditions: {
+        conditionId: string;
+        attribute: string;
+    }[];
+}>;
+export declare function tiersetGet(input: TierSetGetInput): Promise<TierSet>;
+export declare function tiersetUpdate(input: TierSetUpdateInput): Promise<void>;
+export declare function tiersetUpdateTiers(input: TierSetUpdateTiersInput): Promise<void>;
+export declare function tiersetGetTiers(input: TierSetGetInput): Promise<{
+    items: Tier[];
+    total: {
+        all?: number;
+        filtered?: number;
+    };
+}>;
+export declare const tiersetToolDefinitions: readonly [{
+    readonly name: "openloyalty_tierset_list";
+    readonly description: "List all tier sets. Use tierset_get to fetch conditions needed for defining tiers. Returns tierSetId, name, active status, and tier count for each tier set.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        page: z.ZodOptional<z.ZodNumber>;
+        perPage: z.ZodOptional<z.ZodNumber>;
+    };
+    readonly handler: typeof tiersetList;
+}, {
+    readonly name: "openloyalty_tierset_create";
+    readonly description: "Create a new tier set (loyalty program structure). After creation, call tierset_get to obtain conditionId values, then tierset_update_tiers to define tier thresholds. Conditions define what metrics are used for tier progression (e.g., activeUnits for points balance).";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        conditions: z.ZodArray<z.ZodObject<{
+            attribute: z.ZodEnum<["activeUnits", "totalEarnedUnits", "totalSpending", "monthsSinceJoiningProgram", "cumulatedEarnedUnits"]>;
+            walletType: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+            walletType?: string | undefined;
+        }, {
+            attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+            walletType?: string | undefined;
+        }>, "many">;
+        downgrade: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<["none", "automatic", "x_days"]>;
+            days: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }>>;
+        active: z.ZodOptional<z.ZodBoolean>;
+    };
+    readonly handler: typeof tiersetCreate;
+}, {
+    readonly name: "openloyalty_tierset_get";
+    readonly description: "Get tier set details including conditionId values needed for tierset_update_tiers. Returns the full tier set with conditions array containing conditionId for each condition.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        tierSetId: z.ZodString;
+    };
+    readonly handler: typeof tiersetGet;
+}, {
+    readonly name: "openloyalty_tierset_update";
+    readonly description: "Update tier set metadata (name, description, active status, downgrade settings). Does not modify tiers - use tierset_update_tiers for that.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        tierSetId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        downgrade: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<["none", "automatic", "x_days"]>;
+            days: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }>>;
+    };
+    readonly handler: typeof tiersetUpdate;
+}, {
+    readonly name: "openloyalty_tierset_update_tiers";
+    readonly description: "Define tier thresholds for a tier set. PREREQUISITE: Call tierset_get first to obtain conditionId values. Each tier's conditions array uses conditionId from the parent tier set plus a threshold value.\n\nExample for a 3-tier program with points-based progression:\n- Bronze tier: conditions: [{ conditionId: \"xxx\", value: 400 }]\n- Silver tier: conditions: [{ conditionId: \"xxx\", value: 800 }]\n- Gold tier: conditions: [{ conditionId: \"xxx\", value: 1200 }]\n\nThe conditionId must match one from tierset_get response.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        tierSetId: z.ZodString;
+        tiers: z.ZodArray<z.ZodObject<{
+            levelId: z.ZodOptional<z.ZodString>;
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            active: z.ZodOptional<z.ZodBoolean>;
+            conditions: z.ZodArray<z.ZodObject<{
+                conditionId: z.ZodString;
+                value: z.ZodNumber;
+            }, "strip", z.ZodTypeAny, {
+                value: number;
+                conditionId: string;
+            }, {
+                value: number;
+                conditionId: string;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            conditions: {
+                value: number;
+                conditionId: string;
+            }[];
+            active?: boolean | undefined;
+            description?: string | undefined;
+            levelId?: string | undefined;
+        }, {
+            name: string;
+            conditions: {
+                value: number;
+                conditionId: string;
+            }[];
+            active?: boolean | undefined;
+            description?: string | undefined;
+            levelId?: string | undefined;
+        }>, "many">;
+    };
+    readonly handler: typeof tiersetUpdateTiers;
+}, {
+    readonly name: "openloyalty_tierset_get_tiers";
+    readonly description: "Get all tiers in a tier set. Returns levelId values that can be used for campaign targeting. Includes each tier's name and condition thresholds.";
+    readonly inputSchema: {
+        storeCode: z.ZodOptional<z.ZodString>;
+        tierSetId: z.ZodString;
+    };
+    readonly handler: typeof tiersetGetTiers;
+}];
+export {};

package/dist/tools/tierset.js

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPut } from "../client/http.js";
+import { TierSetSchema, TierSetListResponseSchema, TierListResponseSchema, TierSetAttributeEnum, DowngradeModeEnum, } from "../types/schemas/tierset.js";
+import { formatApiError } from "../utils/errors.js";
+import { getConfig } from "../config.js";
+import { buildPaginationQuery } from "../utils/pagination.js";
+export const TierSetListInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    page: z.number().optional().describe("Page number for pagination (starts at 1)."),
+    perPage: z.number().optional().describe("Number of items per page."),
+};
+export const TierSetCreateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    name: z.string().describe("Name of the tier set."),
+    description: z.string().optional().describe("Description of the tier set."),
+    conditions: z.array(z.object({
+        attribute: TierSetAttributeEnum.describe("The attribute to use for this condition."),
+        walletType: z.string().optional().describe("Wallet type code (required for unit-based attributes like activeUnits). Get this from wallet_type_list."),
+    })).describe("Array of conditions that define tier progression criteria."),
+    downgrade: z.object({
+        mode: DowngradeModeEnum.describe("Downgrade mode."),
+        days: z.number().optional().describe("Number of days for x_days mode (required if mode is x_days)."),
+    }).optional().describe("Downgrade configuration for the tier set."),
+    active: z.boolean().optional().describe("Whether the tier set is active. Defaults to true."),
+};
+export const TierSetGetInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    tierSetId: z.string().describe("The tier set ID to retrieve."),
+};
+export const TierSetUpdateInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    tierSetId: z.string().describe("The tier set ID to update."),
+    name: z.string().optional().describe("New name for the tier set."),
+    description: z.string().optional().describe("New description for the tier set."),
+    active: z.boolean().optional().describe("Whether the tier set is active."),
+    downgrade: z.object({
+        mode: DowngradeModeEnum.describe("Downgrade mode."),
+        days: z.number().optional().describe("Number of days for x_days mode."),
+    }).optional().describe("Downgrade configuration."),
+};
+export const TierSetUpdateTiersInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    tierSetId: z.string().describe("The tier set ID to update tiers for."),
+    tiers: z.array(z.object({
+        levelId: z.string().optional().describe("Existing level ID (for updates). Omit for new tiers."),
+        name: z.string().describe("Name of the tier (e.g., Bronze, Silver, Gold)."),
+        description: z.string().optional().describe("Description of the tier."),
+        active: z.boolean().optional().describe("Whether the tier is active. Defaults to true."),
+        conditions: z.array(z.object({
+            conditionId: z.string().describe("Condition ID from tierset_get response."),
+            value: z.number().describe("Threshold value for this condition (e.g., 400 points for Bronze)."),
+        })).describe("Array of condition thresholds. Each uses conditionId from tierset_get."),
+    })).describe("Array of tier definitions."),
+};
+export const TierSetGetTiersInputSchema = {
+    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    tierSetId: z.string().describe("The tier set ID to get tiers for."),
+};
+export async function tiersetList(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    const query = buildPaginationQuery({
+        page: input.page,
+        perPage: input.perPage,
+    });
+    try {
+        const response = await apiGet(`/${storeCode}/tierSet${query}`);
+        const validated = TierSetListResponseSchema.parse(response);
+        return {
+            items: validated.items.map((ts) => ({
+                tierSetId: ts.tierSetId,
+                name: ts.name,
+                active: ts.active,
+                tiersCount: ts.tiersCount,
+            })),
+            total: {
+                all: typeof validated.total.all === 'number' ? validated.total.all : undefined,
+                filtered: typeof validated.total.filtered === 'number' ? validated.total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_list");
+    }
+}
+export async function tiersetCreate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    // API requires tierSet wrapper with translations (at least en is required)
+    const payload = {
+        tierSet: {
+            translations: {
+                en: {
+                    name: input.name,
+                    description: input.description || "",
+                },
+            },
+            conditions: input.conditions,
+            downgrade: input.downgrade,
+            active: input.active ?? true,
+        },
+    };
+    try {
+        const response = await apiPost(`/${storeCode}/tierSet`, payload);
+        const validated = TierSetSchema.parse(response);
+        return {
+            tierSetId: validated.tierSetId,
+            conditions: validated.conditions.map((c) => ({
+                conditionId: c.id,
+                attribute: c.attribute,
+            })),
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_create");
+    }
+}
+export async function tiersetGet(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        const response = await apiGet(`/${storeCode}/tierSet/${input.tierSetId}`);
+        const validated = TierSetSchema.parse(response);
+        return validated;
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_get");
+    }
+}
+export async function tiersetUpdate(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    // API requires tierSet wrapper with translations (at least en is required)
+    const tierSetPayload = {};
+    // If name or description is provided, wrap in translations
+    if (input.name !== undefined || input.description !== undefined) {
+        tierSetPayload.translations = {
+            en: {
+                name: input.name || "",
+                description: input.description || "",
+            },
+        };
+    }
+    if (input.active !== undefined)
+        tierSetPayload.active = input.active;
+    if (input.downgrade !== undefined)
+        tierSetPayload.downgrade = input.downgrade;
+    try {
+        await apiPut(`/${storeCode}/tierSet/${input.tierSetId}`, { tierSet: tierSetPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_update");
+    }
+}
+export async function tiersetUpdateTiers(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    // API requires translations (at least en is required)
+    const payload = {
+        tiers: input.tiers.map((tier) => ({
+            levelId: tier.levelId,
+            active: tier.active ?? true,
+            conditions: tier.conditions.map((c) => ({
+                conditionId: c.conditionId,
+                value: c.value,
+            })),
+            translations: {
+                en: {
+                    name: tier.name,
+                    description: tier.description || "",
+                },
+            },
+        })),
+    };
+    try {
+        await apiPut(`/${storeCode}/tierSet/${input.tierSetId}/tiers`, payload);
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_update_tiers");
+    }
+}
+export async function tiersetGetTiers(input) {
+    const config = getConfig();
+    const storeCode = input.storeCode || config.defaultStoreCode;
+    try {
+        const response = await apiGet(`/${storeCode}/tierSet/${input.tierSetId}/tiers`);
+        const validated = TierListResponseSchema.parse(response);
+        return {
+            items: validated.items,
+            total: {
+                all: typeof validated.total.all === 'number' ? validated.total.all : undefined,
+                filtered: typeof validated.total.filtered === 'number' ? validated.total.filtered : undefined,
+            },
+        };
+    }
+    catch (error) {
+        throw formatApiError(error, "openloyalty_tierset_get_tiers");
+    }
+}
+export const tiersetToolDefinitions = [
+    {
+        name: "openloyalty_tierset_list",
+        description: "List all tier sets. Use tierset_get to fetch conditions needed for defining tiers. Returns tierSetId, name, active status, and tier count for each tier set.",
+        inputSchema: TierSetListInputSchema,
+        handler: tiersetList,
+    },
+    {
+        name: "openloyalty_tierset_create",
+        description: "Create a new tier set (loyalty program structure). After creation, call tierset_get to obtain conditionId values, then tierset_update_tiers to define tier thresholds. Conditions define what metrics are used for tier progression (e.g., activeUnits for points balance).",
+        inputSchema: TierSetCreateInputSchema,
+        handler: tiersetCreate,
+    },
+    {
+        name: "openloyalty_tierset_get",
+        description: "Get tier set details including conditionId values needed for tierset_update_tiers. Returns the full tier set with conditions array containing conditionId for each condition.",
+        inputSchema: TierSetGetInputSchema,
+        handler: tiersetGet,
+    },
+    {
+        name: "openloyalty_tierset_update",
+        description: "Update tier set metadata (name, description, active status, downgrade settings). Does not modify tiers - use tierset_update_tiers for that.",
+        inputSchema: TierSetUpdateInputSchema,
+        handler: tiersetUpdate,
+    },
+    {
+        name: "openloyalty_tierset_update_tiers",
+        description: `Define tier thresholds for a tier set. PREREQUISITE: Call tierset_get first to obtain conditionId values. Each tier's conditions array uses conditionId from the parent tier set plus a threshold value.
+
+Example for a 3-tier program with points-based progression:
+- Bronze tier: conditions: [{ conditionId: "xxx", value: 400 }]
+- Silver tier: conditions: [{ conditionId: "xxx", value: 800 }]
+- Gold tier: conditions: [{ conditionId: "xxx", value: 1200 }]
+
+The conditionId must match one from tierset_get response.`,
+        inputSchema: TierSetUpdateTiersInputSchema,
+        handler: tiersetUpdateTiers,
+    },
+    {
+        name: "openloyalty_tierset_get_tiers",
+        description: "Get all tiers in a tier set. Returns levelId values that can be used for campaign targeting. Includes each tier's name and condition thresholds.",
+        inputSchema: TierSetGetTiersInputSchema,
+        handler: tiersetGetTiers,
+    },
+];