@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/types/schemas/wallet-type.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 export declare const WalletTypeSchema: z.ZodObject<{
     walletTypeId: z.ZodString;
     code: z.ZodString;
-    name: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
     unitSingularName: z.ZodOptional<z.ZodString>;
     unitPluralName: z.ZodOptional<z.ZodString>;
     active: z.ZodBoolean;
@@ -13,9 +13,9 @@ export declare const WalletTypeSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     code: string;
     walletTypeId: string;
-    name: string;
     active: boolean;
     isDefault: boolean;
+    name?: string | undefined;
     unitSingularName?: string | undefined;
     unitPluralName?: string | undefined;
     createdAt?: string | undefined;
@@ -24,9 +24,9 @@ export declare const WalletTypeSchema: z.ZodObject<{
 }, {
     code: string;
     walletTypeId: string;
-    name: string;
     active: boolean;
     isDefault: boolean;
+    name?: string | undefined;
     unitSingularName?: string | undefined;
     unitPluralName?: string | undefined;
     createdAt?: string | undefined;
@@ -37,7 +37,7 @@ export declare const WalletTypeListResponseSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         walletTypeId: z.ZodString;
         code: z.ZodString;
-        name: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
         unitSingularName: z.ZodOptional<z.ZodString>;
         unitPluralName: z.ZodOptional<z.ZodString>;
         active: z.ZodBoolean;
@@ -48,9 +48,9 @@ export declare const WalletTypeListResponseSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         code: string;
         walletTypeId: string;
-        name: string;
         active: boolean;
         isDefault: boolean;
+        name?: string | undefined;
         unitSingularName?: string | undefined;
         unitPluralName?: string | undefined;
         createdAt?: string | undefined;
@@ -59,9 +59,9 @@ export declare const WalletTypeListResponseSchema: z.ZodObject<{
     }, {
         code: string;
         walletTypeId: string;
-        name: string;
         active: boolean;
         isDefault: boolean;
+        name?: string | undefined;
         unitSingularName?: string | undefined;
         unitPluralName?: string | undefined;
         createdAt?: string | undefined;
@@ -72,9 +72,9 @@ export declare const WalletTypeListResponseSchema: z.ZodObject<{
     items: {
         code: string;
         walletTypeId: string;
-        name: string;
         active: boolean;
         isDefault: boolean;
+        name?: string | undefined;
         unitSingularName?: string | undefined;
         unitPluralName?: string | undefined;
         createdAt?: string | undefined;
@@ -85,9 +85,9 @@ export declare const WalletTypeListResponseSchema: z.ZodObject<{
     items: {
         code: string;
         walletTypeId: string;
-        name: string;
         active: boolean;
         isDefault: boolean;
+        name?: string | undefined;
         unitSingularName?: string | undefined;
         unitPluralName?: string | undefined;
         createdAt?: string | undefined;

package/dist/types/schemas/wallet-type.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 export const WalletTypeSchema = z.object({
     walletTypeId: z.string(),
     code: z.string(),
-    name: z.string(),
+    name: z.string().optional(), // Optional: single wallet type endpoint may not return name
     unitSingularName: z.string().optional(),
     unitPluralName: z.string().optional(),
     active: z.boolean(),

package/dist/types/schemas/webhook.d.ts

@@ -45,64 +45,6 @@ export declare const WebhookSubscriptionSchema: z.ZodObject<{
     createdAt?: string | undefined;
 }>;
 export type WebhookSubscription = z.infer<typeof WebhookSubscriptionSchema>;
-export declare const WebhookSubscriptionCreateInputSchema: z.ZodObject<{
-    eventName: z.ZodString;
-    url: z.ZodString;
-    headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        headerName: z.ZodString;
-        headerValue: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        headerName: string;
-        headerValue: string;
-    }, {
-        headerName: string;
-        headerValue: string;
-    }>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-    eventName: string;
-    headers?: {
-        headerName: string;
-        headerValue: string;
-    }[] | undefined;
-}, {
-    url: string;
-    eventName: string;
-    headers?: {
-        headerName: string;
-        headerValue: string;
-    }[] | undefined;
-}>;
-export type WebhookSubscriptionCreateInput = z.infer<typeof WebhookSubscriptionCreateInputSchema>;
-export declare const WebhookSubscriptionUpdateInputSchema: z.ZodObject<{
-    eventName: z.ZodOptional<z.ZodString>;
-    url: z.ZodOptional<z.ZodString>;
-    headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        headerName: z.ZodString;
-        headerValue: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        headerName: string;
-        headerValue: string;
-    }, {
-        headerName: string;
-        headerValue: string;
-    }>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    headers?: {
-        headerName: string;
-        headerValue: string;
-    }[] | undefined;
-    url?: string | undefined;
-    eventName?: string | undefined;
-}, {
-    headers?: {
-        headerName: string;
-        headerValue: string;
-    }[] | undefined;
-    url?: string | undefined;
-    eventName?: string | undefined;
-}>;
-export type WebhookSubscriptionUpdateInput = z.infer<typeof WebhookSubscriptionUpdateInputSchema>;
 export declare const WebhookEventTypesSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {

package/dist/types/schemas/webhook.js

@@ -12,18 +12,6 @@ export const WebhookSubscriptionSchema = z.object({
     headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
     createdAt: z.string().optional().describe("Creation timestamp (ISO format)."),
 });
-// Input schema for creating a webhook subscription
-export const WebhookSubscriptionCreateInputSchema = z.object({
-    eventName: z.string().describe("Event name to subscribe to. Use webhook_events to discover available events."),
-    url: z.string().describe("URL to receive webhook events."),
-    headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
-});
-// Input schema for updating a webhook subscription
-export const WebhookSubscriptionUpdateInputSchema = z.object({
-    eventName: z.string().optional().describe("Event name to subscribe to."),
-    url: z.string().optional().describe("URL to receive webhook events."),
-    headers: z.array(WebhookHeaderSchema).optional().describe("Custom headers to include in webhook requests."),
-});
 // Response schema for webhook event types list
 export const WebhookEventTypesSchema = z.object({
     items: z.array(z.string()).describe("List of available webhook event type names."),

package/dist/utils/errors.js

@@ -31,6 +31,35 @@ export function formatApiError(error, relatedTool) {
         if (status === 400) {
             const errors = data?.errors;
             const errorDetails = errors?.map(e => `${e.path || ''}: ${e.message}`).join('; ') || '';
+            const fullMessage = data?.message
+                ? `${String(data.message)}${errorDetails ? ` (${errorDetails})` : ''}`
+                : "Invalid request data";
+            // Parse "extra fields" errors - usually means a field shouldn't be at top level
+            if (fullMessage.includes("extra fields") || fullMessage.includes("should not contain extra fields")) {
+                return new OpenLoyaltyError({
+                    code: "VALIDATION_ERROR",
+                    message: fullMessage,
+                    hint: "The API rejected unexpected fields in your request. Common causes: " +
+                        "1. A field name is misspelled, " +
+                        "2. A field should be nested differently (e.g., badgeTypeId may not be supported at creation time), " +
+                        "3. The field isn't supported for this endpoint. " +
+                        "Try removing optional fields and adding them back one at a time to identify the problematic field.",
+                    relatedTool,
+                });
+            }
+            // Parse "selected choice is invalid" errors - enum value mismatch
+            if (fullMessage.includes("selected choice is invalid") || fullMessage.includes("The selected choice is invalid")) {
+                return new OpenLoyaltyError({
+                    code: "VALIDATION_ERROR",
+                    message: fullMessage,
+                    hint: "An enum value is invalid. Common fixes: " +
+                        "1. For interval types, use 'calendarDays' (not 'days'), 'calendarWeeks', 'calendarMonths', 'calendarYears'. " +
+                        "2. For period types, use 'day' (not 'days'), 'week', 'month', 'year'. " +
+                        "3. For trigger types, check the tool description for valid options. " +
+                        "4. Omit interval entirely for lifetime/forever limits.",
+                    relatedTool,
+                });
+            }
             // If API returns "Validation failed" with no details, it's likely an MCP implementation bug
             const hasNoDetails = !errorDetails && data?.message === "Validation failed";
             const hint = hasNoDetails
@@ -38,9 +67,7 @@ export function formatApiError(error, relatedTool) {
                 : "Check the input parameters match the expected format";
             return new OpenLoyaltyError({
                 code: "VALIDATION_ERROR",
-                message: data?.message
-                    ? `${String(data.message)}${errorDetails ? ` (${errorDetails})` : ''}`
-                    : "Invalid request data",
+                message: fullMessage,
                 hint,
                 relatedTool,
             });

package/dist/utils/payload.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Removes undefined values from an object.
+ * Useful for building API payloads where undefined fields should be omitted.
+ *
+ * Note: Only filters top-level undefined values. Nested objects are passed through as-is.
+ * Falsy values (false, 0, '', null) are preserved - only undefined is removed.
+ *
+ * @example
+ * omitUndefined({ a: 1, b: undefined, c: false, d: '' })
+ * // Returns: { a: 1, c: false, d: '' }
+ */
+export declare function omitUndefined<T extends Record<string, unknown>>(obj: T): Partial<T>;

package/dist/utils/payload.js

@@ -0,0 +1,14 @@
+/**
+ * Removes undefined values from an object.
+ * Useful for building API payloads where undefined fields should be omitted.
+ *
+ * Note: Only filters top-level undefined values. Nested objects are passed through as-is.
+ * Falsy values (false, 0, '', null) are preserved - only undefined is removed.
+ *
+ * @example
+ * omitUndefined({ a: 1, b: undefined, c: false, d: '' })
+ * // Returns: { a: 1, c: false, d: '' }
+ */
+export function omitUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}

package/dist/workflows/app-login-streak.d.ts

@@ -0,0 +1,39 @@
+/**
+ * App Login Streak Workflow
+ *
+ * Creates a campaign to reward fans for daily app logins,
+ * with achievements for consecutive login streaks.
+ */
+export interface AppLoginStreakConfig {
+    /** Coins awarded per daily login */
+    coinsPerLogin: number;
+    /** Whether to create streak bonus achievement */
+    createStreakBonus: boolean;
+    /** Number of consecutive days for streak achievement */
+    streakDays: number;
+    /** Bonus coins for completing the streak */
+    streakBonus: number;
+    /** Badge name for streak achievement (optional) */
+    badgeName?: string;
+    /** Season start date (ISO format) */
+    seasonStart: string;
+    /** Season end date (ISO format) */
+    seasonEnd: string;
+}
+export interface AppLoginStreakResult {
+    success: boolean;
+    loginCampaignId?: string;
+    streakAchievementId?: string;
+    streakBonusCampaignId?: string;
+    errors: string[];
+    summary: string;
+}
+/**
+ * Execute the app login streak workflow
+ */
+export declare function executeAppLoginStreakWorkflow(config?: Partial<AppLoginStreakConfig>): Promise<AppLoginStreakResult>;
+export declare const appLoginStreakWorkflow: {
+    id: string;
+    name: string;
+    execute: typeof executeAppLoginStreakWorkflow;
+};

package/dist/workflows/app-login-streak.js

@@ -0,0 +1,298 @@
+/**
+ * App Login Streak Workflow
+ *
+ * Creates a campaign to reward fans for daily app logins,
+ * with achievements for consecutive login streaks.
+ */
+import { campaignCreate, campaignList } from "../tools/campaign/handlers.js";
+import { achievementCreate, achievementList } from "../tools/achievement.js";
+import { badgeList } from "../tools/badge.js";
+import { formatOLDate, DEFAULTS } from "../prompts/fan-engagement-setup.js";
+// ============================================================================
+// Workflow Implementation
+// ============================================================================
+/**
+ * Execute the app login streak workflow
+ */
+export async function executeAppLoginStreakWorkflow(config = {}) {
+    const result = {
+        success: false,
+        errors: [],
+        summary: "",
+    };
+    // Merge with defaults
+    const cfg = {
+        coinsPerLogin: config.coinsPerLogin ?? DEFAULTS.appLoginStreak.coinsPerLogin,
+        createStreakBonus: config.createStreakBonus ?? true,
+        streakDays: config.streakDays ?? DEFAULTS.appLoginStreak.streakDays,
+        streakBonus: config.streakBonus ?? DEFAULTS.appLoginStreak.streakBonus,
+        badgeName: config.badgeName ?? "Dedicated Fan",
+        seasonStart: config.seasonStart ?? DEFAULTS.seasonDates.start,
+        seasonEnd: config.seasonEnd ?? DEFAULTS.seasonDates.end,
+    };
+    try {
+        // Step 1: Create daily login campaign (limited to 1 per day)
+        const loginCampaignResult = await createLoginCampaign(cfg);
+        if (loginCampaignResult.error) {
+            result.errors.push(loginCampaignResult.error);
+        }
+        else {
+            result.loginCampaignId = loginCampaignResult.campaignId;
+        }
+        // Step 2: Create streak achievement and bonus campaign if enabled
+        if (cfg.createStreakBonus) {
+            const badges = await getAvailableBadges();
+            const achievementResult = await createStreakAchievement(cfg, badges);
+            if (achievementResult.error) {
+                result.errors.push(achievementResult.error);
+            }
+            else {
+                result.streakAchievementId = achievementResult.achievementId;
+                // Create bonus campaign for streak achievement
+                if (achievementResult.achievementId) {
+                    const bonusCampaignResult = await createStreakBonusCampaign(achievementResult.achievementId, cfg);
+                    if (bonusCampaignResult.error) {
+                        result.errors.push(bonusCampaignResult.error);
+                    }
+                    else {
+                        result.streakBonusCampaignId = bonusCampaignResult.campaignId;
+                    }
+                }
+            }
+        }
+        // Step 3: Verify setup
+        const verification = await verifySetup(result);
+        if (verification.warnings.length > 0) {
+            result.errors.push(...verification.warnings);
+        }
+        // Determine success
+        result.success = result.loginCampaignId !== undefined && result.errors.length === 0;
+        // Build summary
+        result.summary = buildSummary(cfg, result);
+    }
+    catch (error) {
+        result.errors.push(`Workflow error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+async function createLoginCampaign(cfg) {
+    try {
+        const response = await campaignCreate({
+            type: "direct",
+            trigger: "custom_event",
+            event: "app_login",
+            translations: {
+                en: {
+                    name: "Daily App Login Reward",
+                    description: `Earn ${cfg.coinsPerLogin} coins for logging into the app daily`,
+                },
+            },
+            activity: {
+                startsAt: formatOLDate(cfg.seasonStart),
+                endsAt: formatOLDate(cfg.seasonEnd),
+            },
+            rules: [
+                {
+                    name: "Award coins for daily login",
+                    effects: [
+                        {
+                            effect: "give_points",
+                            pointsRule: { fixedValue: cfg.coinsPerLogin },
+                        },
+                    ],
+                },
+            ],
+            limits: {
+                // Strictly one login reward per day
+                executionsPerMember: {
+                    value: 1,
+                    interval: { type: "days", value: 1 },
+                },
+            },
+            active: true,
+        });
+        return { campaignId: response.campaignId };
+    }
+    catch (error) {
+        return {
+            error: `Failed to create login campaign: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function getAvailableBadges() {
+    try {
+        const response = await badgeList({});
+        const badgeMap = new Map();
+        for (const badge of response.badges) {
+            if (badge.name && badge.badgeTypeId) {
+                badgeMap.set(badge.name.toLowerCase(), badge.badgeTypeId);
+            }
+        }
+        return badgeMap;
+    }
+    catch {
+        return new Map();
+    }
+}
+async function createStreakAchievement(cfg, badges) {
+    try {
+        const badgeTypeId = cfg.badgeName
+            ? badges.get(cfg.badgeName.toLowerCase())
+            : undefined;
+        /**
+         * Streak achievements in Open Loyalty use:
+         * - periodGoal: 1 (one login per period)
+         * - period: { consecutive: X, value: 1 } where X is streak days
+         *
+         * This tracks consecutive periods (days) where the goal is met.
+         */
+        const achievementPayload = {
+            translations: {
+                en: {
+                    name: `${cfg.streakDays}-Day Login Streak`,
+                    description: `Log in ${cfg.streakDays} consecutive days to complete this achievement`,
+                },
+            },
+            active: true,
+            activity: {
+                startsAt: formatOLDate(cfg.seasonStart),
+                endsAt: formatOLDate(cfg.seasonEnd),
+            },
+            rules: [
+                {
+                    trigger: "custom_event",
+                    event: "app_login",
+                    completeRule: {
+                        periodGoal: 1,
+                        period: {
+                            consecutive: cfg.streakDays,
+                            value: 1, // 1 day period
+                        },
+                    },
+                },
+            ],
+        };
+        if (badgeTypeId) {
+            achievementPayload.badgeTypeId = badgeTypeId;
+        }
+        const response = await achievementCreate(achievementPayload);
+        return { achievementId: response.achievementId };
+    }
+    catch (error) {
+        return {
+            error: `Failed to create streak achievement: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function createStreakBonusCampaign(achievementId, cfg) {
+    try {
+        const response = await campaignCreate({
+            type: "direct",
+            trigger: "achievement",
+            translations: {
+                en: {
+                    name: `${cfg.streakDays}-Day Login Streak Bonus`,
+                    description: `Bonus ${cfg.streakBonus} coins for maintaining a ${cfg.streakDays}-day login streak`,
+                },
+            },
+            activity: {
+                startsAt: formatOLDate(cfg.seasonStart),
+                endsAt: formatOLDate(cfg.seasonEnd),
+            },
+            rules: [
+                {
+                    name: `Bonus for ${cfg.streakDays}-day streak`,
+                    effects: [
+                        {
+                            effect: "give_points",
+                            pointsRule: { fixedValue: cfg.streakBonus },
+                        },
+                    ],
+                    conditions: [
+                        {
+                            operator: "is_equal",
+                            attribute: "achievement.achievementId",
+                            data: { value: achievementId },
+                        },
+                    ],
+                },
+            ],
+            active: true,
+        });
+        return { campaignId: response.campaignId };
+    }
+    catch (error) {
+        return {
+            error: `Failed to create streak bonus campaign: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function verifySetup(result) {
+    const warnings = [];
+    try {
+        if (result.loginCampaignId) {
+            const campaigns = await campaignList({ active: true });
+            const found = campaigns.campaigns.some((c) => c.campaignId === result.loginCampaignId);
+            if (!found) {
+                warnings.push("Login campaign created but not found in active campaigns list");
+            }
+        }
+        if (result.streakAchievementId) {
+            const achievements = await achievementList({ active: true });
+            const found = achievements.achievements.some((a) => a.achievementId === result.streakAchievementId);
+            if (!found) {
+                warnings.push("Streak achievement created but not found in active achievements list");
+            }
+        }
+    }
+    catch (error) {
+        warnings.push(`Verification error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { warnings };
+}
+function buildSummary(cfg, result) {
+    const lines = [];
+    if (result.loginCampaignId) {
+        lines.push(`Daily login campaign created!`);
+        lines.push(`\nDaily reward: ${cfg.coinsPerLogin} coins`);
+        lines.push(`Limit: 1 reward per day (prevents multiple login scans)`);
+    }
+    if (result.streakAchievementId) {
+        lines.push(`\nStreak Achievement: ${cfg.streakDays} consecutive days`);
+        if (cfg.badgeName) {
+            lines.push(`Badge: ${cfg.badgeName}`);
+        }
+        if (result.streakBonusCampaignId) {
+            lines.push(`Streak bonus: ${cfg.streakBonus} coins`);
+        }
+    }
+    lines.push(`\nSeason: ${cfg.seasonStart} to ${cfg.seasonEnd}`);
+    lines.push(`\nCustom event to trigger reward:`);
+    lines.push(`  Event: app_login`);
+    lines.push(`\nExample event payload:`);
+    lines.push(`{`);
+    lines.push(`  "event": "app_login"`);
+    lines.push(`}`);
+    lines.push(`\nStreak mechanics:`);
+    lines.push(`- Fan must log in at least once each day`);
+    lines.push(`- Missing a day resets the streak counter`);
+    lines.push(`- Achievement completes when ${cfg.streakDays} consecutive days are reached`);
+    if (result.errors.length > 0) {
+        lines.push(`\nWarnings/Errors:`);
+        for (const error of result.errors) {
+            lines.push(`- ${error}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export const appLoginStreakWorkflow = {
+    id: "app-login-streak",
+    name: "App Login Streak Campaign",
+    execute: executeAppLoginStreakWorkflow,
+};

package/dist/workflows/early-arrival.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Early Arrival Workflow
+ *
+ * Creates a campaign to reward fans who arrive early to matches.
+ * Uses a custom event with minutes_before attribute for conditional rewards.
+ */
+export interface EarlyArrivalConfig {
+    /** How early (in minutes) counts as "early arrival" */
+    minutesBefore: number;
+    /** Coins awarded for early arrival */
+    coinsPerArrival: number;
+    /** Maximum early arrival bonuses per match (typically 1) */
+    limitPerMatch: number;
+    /** Season start date (ISO format) */
+    seasonStart: string;
+    /** Season end date (ISO format) */
+    seasonEnd: string;
+}
+export interface EarlyArrivalResult {
+    success: boolean;
+    campaignId?: string;
+    errors: string[];
+    summary: string;
+}
+/**
+ * Execute the early arrival workflow
+ */
+export declare function executeEarlyArrivalWorkflow(config?: Partial<EarlyArrivalConfig>): Promise<EarlyArrivalResult>;
+export declare const earlyArrivalWorkflow: {
+    id: string;
+    name: string;
+    execute: typeof executeEarlyArrivalWorkflow;
+};