@open-loyalty/mcp-server 1.3.7 → 1.4.1

package/dist/tools/achievement.js

@@ -1,354 +0,0 @@
-import { z } from "zod";
-import { apiGet, apiPost, apiPut, apiPatch } from "../client/http.js";
-import { formatApiError } from "../utils/errors.js";
-import { getStoreCode } from "../config.js";
-// Input Schemas
-export const AchievementListInputSchema = {
-    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."),
-    name: z.string().optional().describe("Filter by achievement name."),
-};
-// Period type enum for achievements
-// NOTE: "forever" is NOT valid - use "day" with consecutive=1 for all-time tracking
-const AchievementPeriodTypeEnum = z.enum([
-    "day",
-    "week",
-    "month",
-    "year",
-    "last_day",
-    "calendarDays",
-    "calendarWeeks",
-    "calendarMonths",
-    "calendarYears",
-]);
-// Aggregation type enum for achievements
-const AchievementAggregationTypeEnum = z.enum([
-    "quantity",
-    "sum",
-    "average",
-    "min",
-    "max",
-]);
-// Rule input schema
-const AchievementRuleInputSchema = z.object({
-    achievementRuleId: z.string().optional().describe("Rule ID (for updates)."),
-    translations: z.record(z.string(), z.object({
-        name: z.string(),
-        description: z.string().optional(),
-    })).optional().describe("Rule name and description translations."),
-    trigger: z.enum([
-        "transaction",
-        "custom_event",
-        "points_transfer",
-        "reward_redemption",
-        "referral",
-        "achievement",
-        "tier_change",
-        "registration",
-        "profile_update",
-    ]).optional().describe("Event type that triggers rule progress. For login tracking, use custom_event with a custom 'app_login' event schema."),
-    type: z.enum(["direct", "referral"]).optional().describe("Rule type: direct (default) or referral."),
-    event: z.string().optional().describe("Custom event code (required for trigger='custom_event'). Must match an existing custom event schema."),
-    completeRule: z.object({
-        periodGoal: z.union([z.number(), z.string()]).describe("Goal value to reach (e.g., 5 for 5 purchases, 100 for 100 points)."),
-        period: z.object({
-            type: AchievementPeriodTypeEnum.describe("Period type: 'day' (all-time when consecutive=1), 'last_day' (rolling N days), " +
-                "'calendarDays' (reset daily), 'calendarWeeks' (reset weekly), 'calendarMonths' (reset monthly)."),
-            consecutive: z.number().min(1).describe("Required consecutive periods. Use 1 for all-time tracking, 7 for weekly streaks, etc."),
-        }).describe("Period configuration. REQUIRED: both type and consecutive must be provided."),
-        uniqueAttribute: z.string().optional().describe("Attribute for unique counting (e.g., 'sku' to count unique products)."),
-    }).describe("Completion goal configuration."),
-    aggregation: z.object({
-        type: AchievementAggregationTypeEnum.describe("How to aggregate: 'quantity' (count events), 'sum' (add values), etc."),
-        rule: z.string().optional().describe("Expression for value extraction (e.g., 'transaction.grossValue' for sum of transaction values)."),
-    }).optional().describe("Value aggregation. Use type='quantity' for event counting, type='sum' with rule for value-based goals."),
-    conditions: z.array(z.record(z.unknown())).optional().describe("Conditions that must be met."),
-    limit: z.object({
-        value: z.number().optional().describe("Max events per interval (e.g., 1 for once-per-day limit)."),
-        interval: z.object({
-            type: z.string().describe("Interval type: 'calendarDays', 'calendarWeeks', etc."),
-            value: z.number().optional().describe("Interval value."),
-        }).optional().describe("Time interval for the limit."),
-    }).optional().describe("Per-rule execution limit (use for streak patterns: limit 1 per day)."),
-    uniqueReferee: z.boolean().optional().describe("Whether referee must be unique (for referral achievements)."),
-});
-export const AchievementCreateInputSchema = {
-    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: z.record(z.string(), z.object({
-        name: z.string(),
-        description: z.string().optional(),
-    })).describe("Achievement name and description. At least 'en' key required."),
-    active: z.boolean().optional().describe("Whether achievement is active (default: false)."),
-    activity: z.object({
-        startsAt: z.string().optional().describe("ISO datetime when achievement becomes active."),
-        endsAt: z.string().optional().describe("ISO datetime when achievement ends."),
-        operator: z.string().optional().describe("Activity condition operator."),
-    }).optional().describe("Time period configuration."),
-    limit: z.object({
-        value: z.number().optional().describe("Maximum completions."),
-        interval: z.object({
-            type: z.string(),
-            value: z.number().optional(),
-        }).optional(),
-    }).optional().describe("Overall limit configuration."),
-    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules defining completion criteria."),
-    badgeTypeId: z.string().optional().describe("Badge type ID to award upon completion."),
-};
-export const AchievementGetInputSchema = {
-    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."),
-    achievementId: z.string().describe("The achievement ID (UUID) to retrieve."),
-};
-export const AchievementUpdateInputSchema = {
-    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."),
-    achievementId: z.string().describe("The achievement ID (UUID) to update."),
-    translations: z.record(z.string(), z.object({
-        name: z.string(),
-        description: z.string().optional(),
-    })).describe("Achievement name and description."),
-    active: z.boolean().optional().describe("Whether achievement is active."),
-    activity: z.object({
-        startsAt: z.string().optional(),
-        endsAt: z.string().optional(),
-        operator: z.string().optional(),
-    }).optional().describe("Time period configuration."),
-    limit: z.object({
-        value: z.number().optional(),
-        interval: z.object({
-            type: z.string(),
-            value: z.number().optional(),
-        }).optional(),
-    }).optional().describe("Limit configuration."),
-    rules: z.array(AchievementRuleInputSchema).describe("Achievement rules."),
-    badgeTypeId: z.string().optional().describe("Badge type ID to award."),
-};
-export const AchievementPatchInputSchema = {
-    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."),
-    achievementId: z.string().describe("The achievement ID (UUID) to patch."),
-    active: z.boolean().optional().describe("Whether achievement is active."),
-    translations: z.record(z.string(), z.object({
-        name: z.string().optional(),
-        description: z.string().optional(),
-    })).optional().describe("Partial translation updates."),
-};
-export const AchievementGetMemberProgressInputSchema = {
-    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)."),
-    achievementId: z.string().describe("The achievement ID (UUID)."),
-};
-export const AchievementListMemberAchievementsInputSchema = {
-    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)."),
-    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 achievement name."),
-    achievementId: z.string().optional().describe("Filter by specific achievement ID."),
-};
-// Handler functions
-export async function achievementList(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}/achievement${queryString ? `?${queryString}` : ""}`;
-    try {
-        const response = await apiGet(url);
-        const achievements = (response.items || []).map((item) => ({
-            achievementId: item.achievementId,
-            name: item.name,
-            active: item.active,
-            createdAt: item.createdAt,
-            badgeTypeId: item.badgeTypeId,
-        }));
-        const total = response.total || {};
-        return {
-            achievements,
-            total: {
-                all: typeof total.all === "number" ? total.all : undefined,
-                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
-            },
-        };
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_list");
-    }
-}
-export async function achievementCreate(input) {
-    const storeCode = getStoreCode(input.storeCode);
-    const achievementPayload = {
-        translations: input.translations,
-        rules: input.rules,
-    };
-    if (input.active !== undefined)
-        achievementPayload.active = input.active;
-    if (input.activity)
-        achievementPayload.activity = input.activity;
-    if (input.limit)
-        achievementPayload.limit = input.limit;
-    if (input.badgeTypeId)
-        achievementPayload.badgeTypeId = input.badgeTypeId;
-    try {
-        // CRITICAL: Wrap body as { achievement: {...} }
-        const response = await apiPost(`/${storeCode}/achievement`, { achievement: achievementPayload });
-        return { achievementId: response.achievementId };
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_create");
-    }
-}
-export async function achievementGet(input) {
-    const storeCode = getStoreCode(input.storeCode);
-    try {
-        const response = await apiGet(`/${storeCode}/achievement/${input.achievementId}`);
-        return response;
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_get");
-    }
-}
-export async function achievementUpdate(input) {
-    const storeCode = getStoreCode(input.storeCode);
-    const achievementPayload = {
-        translations: input.translations,
-        rules: input.rules,
-    };
-    if (input.active !== undefined)
-        achievementPayload.active = input.active;
-    if (input.activity)
-        achievementPayload.activity = input.activity;
-    if (input.limit)
-        achievementPayload.limit = input.limit;
-    if (input.badgeTypeId !== undefined)
-        achievementPayload.badgeTypeId = input.badgeTypeId;
-    try {
-        // CRITICAL: Wrap body as { achievement: {...} }
-        await apiPut(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_update");
-    }
-}
-export async function achievementPatch(input) {
-    const storeCode = getStoreCode(input.storeCode);
-    const achievementPayload = {};
-    if (input.active !== undefined)
-        achievementPayload.active = input.active;
-    if (input.translations)
-        achievementPayload.translations = input.translations;
-    try {
-        // CRITICAL: Wrap body as { achievement: {...} }
-        await apiPatch(`/${storeCode}/achievement/${input.achievementId}`, { achievement: achievementPayload });
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_patch");
-    }
-}
-export async function achievementGetMemberProgress(input) {
-    const storeCode = getStoreCode(input.storeCode);
-    try {
-        const response = await apiGet(`/${storeCode}/member/${input.memberId}/achievement/${input.achievementId}`);
-        return response;
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_get_member_progress");
-    }
-}
-export async function achievementListMemberAchievements(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.achievementId)
-        params.append("achievementId", input.achievementId);
-    const queryString = params.toString();
-    const url = `/${storeCode}/member/${input.memberId}/achievement${queryString ? `?${queryString}` : ""}`;
-    try {
-        const response = await apiGet(url);
-        const achievements = response.items || [];
-        const total = response.total || {};
-        return {
-            achievements,
-            total: {
-                all: typeof total.all === "number" ? total.all : undefined,
-                filtered: typeof total.filtered === "number" ? total.filtered : undefined,
-            },
-        };
-    }
-    catch (error) {
-        throw formatApiError(error, "openloyalty_achievement_list_member_achievements");
-    }
-}
-// Tool definitions
-export const achievementToolDefinitions = [
-    {
-        name: "openloyalty_achievement_list",
-        title: "List Achievements",
-        description: "List achievements. Achievements gamify member behavior by setting goals (e.g., 'Make 5 purchases this month'). Returns achievementId, name, active status, and associated badge. Use achievement_get for full rules and configuration.",
-        readOnly: true,
-        inputSchema: AchievementListInputSchema,
-        handler: achievementList,
-    },
-    {
-        name: "openloyalty_achievement_create",
-        title: "Create Achievement",
-        description: "Create achievement with rules that track member progress. Triggers: transaction, custom_event, points_transfer, referral, etc. " +
-            "REQUIRED in each rule: type='direct', completeRule with periodGoal and period (type + consecutive). " +
-            "Example - '5 purchases all-time': rules: [{ type: 'direct', trigger: 'transaction', aggregation: { type: 'quantity' }, completeRule: { periodGoal: 5, period: { type: 'day', consecutive: 1 } } }]. " +
-            "For streaks, use consecutive > 1 with limit: { value: 1, interval: { type: 'calendarDays', value: 1 } }.",
-        readOnly: false,
-        inputSchema: AchievementCreateInputSchema,
-        handler: achievementCreate,
-    },
-    {
-        name: "openloyalty_achievement_get",
-        title: "Get Achievement Details",
-        description: "Get achievement details including all rules, conditions, activity period, limits, and completions count.",
-        readOnly: true,
-        inputSchema: AchievementGetInputSchema,
-        handler: achievementGet,
-    },
-    {
-        name: "openloyalty_achievement_update",
-        title: "Update Achievement",
-        description: "Update achievement configuration. Requires full achievement object (translations, rules). Use achievement_get first to retrieve current configuration.",
-        readOnly: false,
-        inputSchema: AchievementUpdateInputSchema,
-        handler: achievementUpdate,
-    },
-    {
-        name: "openloyalty_achievement_patch",
-        title: "Patch Achievement",
-        description: "Partial update of achievement. Use for simple changes like activating/deactivating or updating translations without providing full rules.",
-        readOnly: false,
-        inputSchema: AchievementPatchInputSchema,
-        handler: achievementPatch,
-    },
-    {
-        name: "openloyalty_achievement_get_member_progress",
-        title: "Get Member Achievement Progress",
-        description: "Get member's progress on a specific achievement. Returns completedCount, and for each rule: periodGoal, currentPeriodValue, and consecutive period tracking.",
-        readOnly: true,
-        inputSchema: AchievementGetMemberProgressInputSchema,
-        handler: achievementGetMemberProgress,
-    },
-    {
-        name: "openloyalty_achievement_list_member_achievements",
-        title: "List Member Achievements",
-        description: "List all achievements with member's progress. Returns each achievement's status, completion count, and per-rule progress. Use for displaying gamification dashboard.",
-        readOnly: true,
-        inputSchema: AchievementListMemberAchievementsInputSchema,
-        handler: achievementListMemberAchievements,
-    },
-];