@open-loyalty/mcp-server 1.3.7 → 1.5.3

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

@@ -0,0 +1,26 @@
+import { TierSet, TierSetListItem, Tier } from "../../types/schemas/tierset.js";
+import type { TierSetListInput, TierSetCreateInput, TierSetGetInput, TierSetUpdateInput, TierSetUpdateTiersInput } from "./schemas.js";
+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;
+    };
+}>;

package/dist/tools/tierset/handlers.js

@@ -0,0 +1,196 @@
+import { apiGet, apiPost, apiPut } from "../../client/http.js";
+import { TierSetSchema, TierSetListResponseSchema, TierListResponseSchema, } from "../../types/schemas/tierset.js";
+import { formatApiError, OpenLoyaltyError } from "../../utils/errors.js";
+import { getStoreCode } from "../../config.js";
+import { buildPaginationQuery } from "../../utils/pagination.js";
+export async function tiersetList(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    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, "ol_tierset_list");
+    }
+}
+export async function tiersetCreate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // API QUIRK: Only accepts specific fields at creation time.
+    // Fields NOT supported at creation: tiers, active, downgrade
+    // These must be set via tierset_update or tierset_update_tiers after creation.
+    //
+    // REQUIRED fields:
+    // - translations.en.name (string)
+    // - conditions (array with attribute, optionally walletType)
+    //
+    // IMPORTANT: Only include description if actually provided - API rejects empty string as "extra field"
+    const enTranslation = {
+        name: input.name,
+    };
+    if (input.description) {
+        enTranslation.description = input.description;
+    }
+    // Explicitly map conditions to only include known fields (attribute + walletType)
+    // This strips any extra fields that might slip through Zod validation
+    const mappedConditions = input.conditions.map((c) => {
+        const condition = {
+            attribute: c.attribute,
+        };
+        if (c.walletType) {
+            condition.walletType = c.walletType;
+        }
+        return condition;
+    });
+    const tierSetPayload = {
+        translations: {
+            en: enTranslation,
+        },
+        conditions: mappedConditions,
+    };
+    const payload = { tierSet: tierSetPayload };
+    try {
+        const response = await apiPost(`/${storeCode}/tierSet`, payload);
+        // API QUIRK: Create endpoint only returns { tierSetId: string }
+        // We need to fetch the full tier set to get the conditionId values
+        const createResponse = response;
+        if (!createResponse.tierSetId) {
+            throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
+        }
+        // Fetch the created tier set to get condition IDs
+        const tierSetResponse = await apiGet(`/${storeCode}/tierSet/${createResponse.tierSetId}`);
+        const validated = TierSetSchema.parse(tierSetResponse);
+        return {
+            tierSetId: validated.tierSetId,
+            conditions: validated.conditions.map((c) => ({
+                conditionId: c.id,
+                attribute: c.attribute,
+            })),
+        };
+    }
+    catch (error) {
+        // Detect "maximum 3 active tier sets" limit error
+        const axiosError = error;
+        const allMessages = [
+            axiosError.response?.data?.message || "",
+            ...(axiosError.response?.data?.errors || []).map(e => e.message)
+        ].join(" ").toLowerCase();
+        if (allMessages.includes("maximum") || allMessages.includes("limit") || (allMessages.includes("tier") && allMessages.includes("3"))) {
+            throw new OpenLoyaltyError({
+                code: "TIER_SET_LIMIT",
+                message: "Maximum 3 active tier sets per store",
+                hint: "Use ol_tierset_list() to see existing tier sets. Reuse an existing tier set or deactivate one before creating a new one.",
+                relatedTool: "ol_tierset_create",
+            });
+        }
+        throw formatApiError(error, "ol_tierset_create");
+    }
+}
+export async function tiersetGet(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    try {
+        const response = await apiGet(`/${storeCode}/tierSet/${input.tierSetId}`);
+        const validated = TierSetSchema.parse(response);
+        return validated;
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_tierset_get");
+    }
+}
+export async function tiersetUpdate(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // API requires conditions to be present in PUT requests, even for metadata-only updates.
+    // Fetch existing tier set to preserve conditions.
+    let existingTierSet;
+    try {
+        const response = await apiGet(`/${storeCode}/tierSet/${input.tierSetId}`);
+        existingTierSet = TierSetSchema.parse(response);
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_tierset_update");
+    }
+    // Build payload using existing values as defaults
+    const tierSetPayload = {
+        // Always include conditions - API requires this even for metadata updates
+        conditions: existingTierSet.conditions.map((c) => ({
+            attribute: c.attribute,
+            walletType: c.walletType,
+        })),
+        // Always include translations
+        translations: {
+            en: {
+                name: input.name ?? existingTierSet.name,
+                description: input.description ?? existingTierSet.description ?? "",
+            },
+        },
+        // Preserve active status unless explicitly changed
+        active: input.active ?? existingTierSet.active,
+    };
+    if (input.downgrade !== undefined) {
+        tierSetPayload.downgrade = input.downgrade;
+    }
+    try {
+        await apiPut(`/${storeCode}/tierSet/${input.tierSetId}`, { tierSet: tierSetPayload });
+    }
+    catch (error) {
+        throw formatApiError(error, "ol_tierset_update");
+    }
+}
+export async function tiersetUpdateTiers(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    // 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, "ol_tierset_update_tiers");
+    }
+}
+export async function tiersetGetTiers(input) {
+    const storeCode = getStoreCode(input.storeCode);
+    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, "ol_tierset_get_tiers");
+    }
+}

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

@@ -0,0 +1,124 @@
+export { TierSetListInputSchema, TierSetCreateInputSchema, TierSetGetInputSchema, TierSetUpdateInputSchema, TierSetUpdateTiersInputSchema, TierSetGetTiersInputSchema, } from "./schemas.js";
+export type { TierSetListInput, TierSetCreateInput, TierSetGetInput, TierSetUpdateInput, TierSetUpdateTiersInput, } from "./schemas.js";
+export { tiersetList, tiersetCreate, tiersetGet, tiersetUpdate, tiersetUpdateTiers, tiersetGetTiers, } from "./handlers.js";
+import { tiersetList, tiersetCreate, tiersetGet, tiersetUpdate, tiersetUpdateTiers, tiersetGetTiers } from "./handlers.js";
+export declare const tiersetToolDefinitions: readonly [{
+    readonly name: "ol_tierset_list";
+    readonly title: "List Loyalty Programs";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        page: import("zod").ZodOptional<import("zod").ZodNumber>;
+        perPage: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    readonly handler: typeof tiersetList;
+}, {
+    readonly name: "ol_tierset_create";
+    readonly title: "Create Loyalty Program";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        name: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        conditions: import("zod").ZodArray<import("zod").ZodObject<{
+            attribute: import("zod").ZodEnum<["activeUnits", "totalEarnedUnits", "totalSpending", "monthsSinceJoiningProgram", "cumulatedEarnedUnits"]>;
+            walletType: import("zod").ZodOptional<import("zod").ZodString>;
+        }, "strip", import("zod").ZodTypeAny, {
+            attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+            walletType?: string | undefined;
+        }, {
+            attribute: "activeUnits" | "totalEarnedUnits" | "totalSpending" | "monthsSinceJoiningProgram" | "cumulatedEarnedUnits";
+            walletType?: string | undefined;
+        }>, "many">;
+    };
+    readonly handler: typeof tiersetCreate;
+}, {
+    readonly name: "ol_tierset_get";
+    readonly title: "Get Loyalty Program Details";
+    readonly description: string;
+    readonly readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        tierSetId: import("zod").ZodString;
+    };
+    readonly handler: typeof tiersetGet;
+}, {
+    readonly name: "ol_tierset_update";
+    readonly title: "Update Loyalty Program";
+    readonly description: string;
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        tierSetId: import("zod").ZodString;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        downgrade: import("zod").ZodOptional<import("zod").ZodObject<{
+            mode: import("zod").ZodEnum<["none", "automatic", "x_days"]>;
+            days: import("zod").ZodOptional<import("zod").ZodNumber>;
+        }, "strip", import("zod").ZodTypeAny, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }, {
+            mode: "none" | "automatic" | "x_days";
+            days?: number | undefined;
+        }>>;
+    };
+    readonly handler: typeof tiersetUpdate;
+}, {
+    readonly name: "ol_tierset_update_tiers";
+    readonly title: "Configure Tier Thresholds";
+    readonly description: "Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.\n\n⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.\n\n⚠️ INPUT FORMAT: Pass 'name' and 'description' as TOP-LEVEL fields on each tier object.\n❌ WRONG: { translations: { en: { name: \"Bronze\" } } }\n✅ CORRECT: { name: \"Bronze\", description: \"Entry tier\" }\n\nExample - Creating 4 tiers in ONE call:\ntiers: [\n  { name: \"Bronze\", description: \"Entry tier\", conditions: [{ conditionId: \"xxx\", value: 0 }] },\n  { name: \"Silver\", description: \"500+ points\", conditions: [{ conditionId: \"xxx\", value: 500 }] },\n  { name: \"Gold\", description: \"1000+ points\", conditions: [{ conditionId: \"xxx\", value: 1000 }] },\n  { name: \"Platinum\", description: \"Top tier\", conditions: [{ conditionId: \"xxx\", value: 2000 }] }\n]\n\nThe conditionId must match the one from tierset_get response - use the SAME conditionId for all tiers.";
+    readonly readOnly: false;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        tierSetId: import("zod").ZodString;
+        tiers: import("zod").ZodArray<import("zod").ZodObject<{
+            levelId: import("zod").ZodOptional<import("zod").ZodString>;
+            name: import("zod").ZodString;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+            active: import("zod").ZodOptional<import("zod").ZodBoolean>;
+            conditions: import("zod").ZodArray<import("zod").ZodObject<{
+                conditionId: import("zod").ZodString;
+                value: import("zod").ZodNumber;
+            }, "strip", import("zod").ZodTypeAny, {
+                value: number;
+                conditionId: string;
+            }, {
+                value: number;
+                conditionId: string;
+            }>, "many">;
+        }, "strip", import("zod").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: "ol_tierset_get_tiers";
+    readonly title: "Get Tier Configuration";
+    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 readOnly: true;
+    readonly inputSchema: {
+        storeCode: import("zod").ZodOptional<import("zod").ZodString>;
+        tierSetId: import("zod").ZodString;
+    };
+    readonly handler: typeof tiersetGetTiers;
+}];

package/dist/tools/tierset/index.js

@@ -0,0 +1,88 @@
+// Re-export schemas
+export { TierSetListInputSchema, TierSetCreateInputSchema, TierSetGetInputSchema, TierSetUpdateInputSchema, TierSetUpdateTiersInputSchema, TierSetGetTiersInputSchema, } from "./schemas.js";
+// Re-export handlers
+export { tiersetList, tiersetCreate, tiersetGet, tiersetUpdate, tiersetUpdateTiers, tiersetGetTiers, } from "./handlers.js";
+// Imports for tool definitions
+import { TierSetListInputSchema, TierSetCreateInputSchema, TierSetGetInputSchema, TierSetUpdateInputSchema, TierSetUpdateTiersInputSchema, TierSetGetTiersInputSchema, } from "./schemas.js";
+import { tiersetList, tiersetCreate, tiersetGet, tiersetUpdate, tiersetUpdateTiers, tiersetGetTiers, } from "./handlers.js";
+// Tool definitions
+export const tiersetToolDefinitions = [
+    {
+        name: "ol_tierset_list",
+        title: "List Loyalty Programs",
+        description: "List all tier sets. A tier set is a CONTAINER that holds MULTIPLE tiers (e.g., Bronze/Silver/Gold). " +
+            "⚠️ ALWAYS check existing tier sets FIRST before creating - reuse if one exists. " +
+            "Returns tierSetId, name, active status, and tier count for each tier set.",
+        readOnly: true,
+        inputSchema: TierSetListInputSchema,
+        handler: tiersetList,
+    },
+    {
+        name: "ol_tierset_create",
+        title: "Create Loyalty Program",
+        description: "Create a tier set -- a container for all tiers (e.g., Bronze/Silver/Gold/Platinum). " +
+            "KEY DECISIONS (confirm with user if not specified): " +
+            "1. Progression metric -- what drives tier advancement? totalEarnedUnits (lifetime loyalty), totalSpending (revenue-focused), activeUnits (balance-based, penalizes redemptions) " +
+            "2. Tier structure -- how many tiers and what names? (design tiers before creating) " +
+            "WORKFLOW: tierset_list (check existing, max 3 active) -> tierset_create (ONE set) -> tierset_get (get conditionId) -> tierset_update_tiers (add ALL tiers). " +
+            "REQUIRED: name, conditions array. Only name/description/conditions accepted at creation. " +
+            "NOTE: Use 'attribute' NOT 'type' in conditions. For unit-based attributes, set walletType to 'default'.",
+        readOnly: false,
+        inputSchema: TierSetCreateInputSchema,
+        handler: tiersetCreate,
+    },
+    {
+        name: "ol_tierset_get",
+        title: "Get Loyalty Program Details",
+        description: "Get tier set details including conditionId values needed for tierset_update_tiers. " +
+            "CRITICAL: After tierset_create, call this to get the conditionId from conditions[].id. " +
+            "Use this SAME conditionId for ALL tiers when calling tierset_update_tiers.",
+        readOnly: true,
+        inputSchema: TierSetGetInputSchema,
+        handler: tiersetGet,
+    },
+    {
+        name: "ol_tierset_update",
+        title: "Update Loyalty Program",
+        description: "Update tier set metadata (name, description, active status, downgrade settings). " +
+            "KEY DECISIONS (confirm with user if not specified): " +
+            "1. Downgrade policy -- 'none' (members never lose tier), 'automatic' (instant downgrade), 'x_days' (grace period) " +
+            "2. Active toggle -- activating affects ALL members' tier placement immediately " +
+            "Automatically preserves existing conditions. Does not modify tiers -- use tierset_update_tiers for that.",
+        readOnly: false,
+        inputSchema: TierSetUpdateInputSchema,
+        handler: tiersetUpdate,
+    },
+    {
+        name: "ol_tierset_update_tiers",
+        title: "Configure Tier Thresholds",
+        description: `Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.
+
+⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.
+
+⚠️ INPUT FORMAT: Pass 'name' and 'description' as TOP-LEVEL fields on each tier object.
+❌ WRONG: { translations: { en: { name: "Bronze" } } }
+✅ CORRECT: { name: "Bronze", description: "Entry tier" }
+
+Example - Creating 4 tiers in ONE call:
+tiers: [
+  { name: "Bronze", description: "Entry tier", conditions: [{ conditionId: "xxx", value: 0 }] },
+  { name: "Silver", description: "500+ points", conditions: [{ conditionId: "xxx", value: 500 }] },
+  { name: "Gold", description: "1000+ points", conditions: [{ conditionId: "xxx", value: 1000 }] },
+  { name: "Platinum", description: "Top tier", conditions: [{ conditionId: "xxx", value: 2000 }] }
+]
+
+The conditionId must match the one from tierset_get response - use the SAME conditionId for all tiers.`,
+        readOnly: false,
+        inputSchema: TierSetUpdateTiersInputSchema,
+        handler: tiersetUpdateTiers,
+    },
+    {
+        name: "ol_tierset_get_tiers",
+        title: "Get Tier Configuration",
+        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: true,
+        inputSchema: TierSetGetTiersInputSchema,
+        handler: tiersetGetTiers,
+    },
+];

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

@@ -0,0 +1,127 @@
+import { z } from "zod";
+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">;
+};
+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;
+};
+export type TierSetListInput = {
+    storeCode?: string;
+    page?: number;
+    perPage?: number;
+};
+export type TierSetCreateInput = {
+    storeCode?: string;
+    name: string;
+    description?: string;
+    conditions: {
+        attribute: string;
+        walletType?: string;
+    }[];
+};
+export type TierSetGetInput = {
+    storeCode?: string;
+    tierSetId: string;
+};
+export type TierSetUpdateInput = {
+    storeCode?: string;
+    tierSetId: string;
+    name?: string;
+    description?: string;
+    active?: boolean;
+    downgrade?: {
+        mode: string;
+        days?: number;
+    };
+};
+export type TierSetUpdateTiersInput = {
+    storeCode?: string;
+    tierSetId: string;
+    tiers: {
+        levelId?: string;
+        name: string;
+        description?: string;
+        active?: boolean;
+        conditions: {
+            conditionId: string;
+            value: number;
+        }[];
+    }[];
+};

package/dist/tools/tierset/schemas.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { TierSetAttributeEnum, DowngradeModeEnum, } from "../../types/schemas/tierset.js";
+export const TierSetListInputSchema = {
+    storeCode: 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."),
+    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("INTERNAL: Auto-configured from server settings. NEVER ask the user for this value. Only set if the user explicitly requests a different store."),
+    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 condition field name. IMPORTANT: Use 'attribute' NOT 'type'. " +
+            "BUSINESS DECISION: Determines what drives tier progression. " +
+            "totalEarnedUnits = lifetime loyalty rewards engagement. totalSpending = revenue-focused. " +
+            "activeUnits = balance-based (penalizes redemptions). " +
+            "NOTE: 'earnedUnits' is NOT valid -- use 'totalEarnedUnits'."),
+        walletType: z.string().optional().describe("Wallet type CODE (not UUID). Required for unit-based attributes (activeUnits, totalEarnedUnits, cumulatedEarnedUnits). " +
+            "Use wallet_type_list to find walletType.code (e.g., 'default')."),
+    })).describe("Array of conditions that define tier progression criteria. " +
+        "EXACT FORMAT: [{ \"attribute\": \"totalEarnedUnits\", \"walletType\": \"default\" }]. " +
+        "Use 'attribute' NOT 'type' for the condition field name."),
+    // NOTE: downgrade and active are NOT supported at creation time - use tierset_update after creation
+};
+export const TierSetGetInputSchema = {
+    storeCode: 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."),
+    tierSetId: z.string().describe("The tier set ID to retrieve."),
+};
+export const TierSetUpdateInputSchema = {
+    storeCode: 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."),
+    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. " +
+        "BUSINESS IMPACT: Activating affects ALL members' tier placement immediately."),
+    downgrade: z.object({
+        mode: DowngradeModeEnum.describe("BUSINESS DECISION: 'none' = members never lose tier (generous but expensive). " +
+            "'automatic' = instant downgrade when conditions not met (strict, controls costs). " +
+            "'x_days' = grace period before downgrade (balanced approach)."),
+        days: z.number().optional().describe("Grace period in days (required when mode='x_days'). Typical values: 30-90 days."),
+    }).optional().describe("Downgrade configuration. Determines if and when members lose tier status."),
+};
+export const TierSetUpdateTiersInputSchema = {
+    storeCode: 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."),
+    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("Tier name as a TOP-LEVEL string (e.g., 'Bronze'). NOT in translations wrapper."),
+        description: z.string().optional().describe("Tier description as a TOP-LEVEL string. NOT in translations wrapper."),
+        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 tier. " +
+                "BUSINESS IMPACT: Tier thresholds define program difficulty. Too low = everyone at top tier (budget bloat). " +
+                "Too high = empty tiers (member frustration). Industry guideline: ~50% at base, ~5% at top."),
+        })).describe("Array of condition thresholds. Each uses conditionId from tierset_get."),
+    })).describe("Array of tier definitions. Each tier needs 'name' as a direct string field, NOT wrapped in translations."),
+};
+export const TierSetGetTiersInputSchema = {
+    storeCode: 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."),
+    tierSetId: z.string().describe("The tier set ID to get tiers for."),
+};