@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/workflows/early-arrival.js

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ */
+import { campaignCreate } from "../tools/campaign/handlers.js";
+import { formatOLDate, DEFAULTS } from "../prompts/fan-engagement-setup.js";
+// ============================================================================
+// Workflow Implementation
+// ============================================================================
+/**
+ * Execute the early arrival workflow
+ */
+export async function executeEarlyArrivalWorkflow(config = {}) {
+    const result = {
+        success: false,
+        errors: [],
+        summary: "",
+    };
+    // Merge with defaults
+    const cfg = {
+        minutesBefore: config.minutesBefore ?? DEFAULTS.earlyArrival.minutesBefore,
+        coinsPerArrival: config.coinsPerArrival ?? DEFAULTS.earlyArrival.coinsPerArrival,
+        limitPerMatch: config.limitPerMatch ?? DEFAULTS.earlyArrival.limitPerMatch,
+        seasonStart: config.seasonStart ?? DEFAULTS.seasonDates.start,
+        seasonEnd: config.seasonEnd ?? DEFAULTS.seasonDates.end,
+    };
+    try {
+        // Create the early arrival campaign with condition
+        const campaignResult = await createEarlyArrivalCampaign(cfg);
+        if (campaignResult.error) {
+            result.errors.push(campaignResult.error);
+        }
+        else {
+            result.campaignId = campaignResult.campaignId;
+            result.success = true;
+        }
+        // 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 createEarlyArrivalCampaign(cfg) {
+    try {
+        /**
+         * The early_arrival custom event expects:
+         * {
+         *   "event": "early_arrival",
+         *   "attributes": {
+         *     "minutes_before": 75  // how many minutes before kickoff they arrived
+         *   }
+         * }
+         *
+         * The campaign condition checks if minutes_before >= threshold
+         */
+        const response = await campaignCreate({
+            type: "direct",
+            trigger: "custom_event",
+            event: "early_arrival",
+            translations: {
+                en: {
+                    name: "Early Arrival Bonus",
+                    description: `Earn ${cfg.coinsPerArrival} bonus coins for arriving at least ${cfg.minutesBefore} minutes before kickoff`,
+                },
+            },
+            activity: {
+                startsAt: formatOLDate(cfg.seasonStart),
+                endsAt: formatOLDate(cfg.seasonEnd),
+            },
+            rules: [
+                {
+                    name: "Award coins for early arrival",
+                    effects: [
+                        {
+                            effect: "give_points",
+                            pointsRule: { fixedValue: cfg.coinsPerArrival },
+                        },
+                    ],
+                    conditions: [
+                        {
+                            operator: "gte",
+                            attribute: "event.minutes_before",
+                            data: { value: cfg.minutesBefore },
+                        },
+                    ],
+                },
+            ],
+            limits: {
+                executionsPerMember: {
+                    value: cfg.limitPerMatch,
+                    interval: { type: "days", value: 1 },
+                },
+            },
+            active: true,
+        });
+        return { campaignId: response.campaignId };
+    }
+    catch (error) {
+        return {
+            error: `Failed to create early arrival campaign: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function buildSummary(cfg, result) {
+    const lines = [];
+    if (result.success && result.campaignId) {
+        lines.push(`Early arrival campaign created successfully!`);
+        lines.push(`\nReward: ${cfg.coinsPerArrival} coins`);
+        lines.push(`Requirement: Arrive at least ${cfg.minutesBefore} minutes before kickoff`);
+        lines.push(`Limit: ${cfg.limitPerMatch} bonus per match day`);
+        lines.push(`\nSeason: ${cfg.seasonStart} to ${cfg.seasonEnd}`);
+        lines.push(`\nCustom event to trigger reward:`);
+        lines.push(`  Event: early_arrival`);
+        lines.push(`  Required attribute: minutes_before (number)`);
+        lines.push(`\nExample event payload:`);
+        lines.push(`{`);
+        lines.push(`  "event": "early_arrival",`);
+        lines.push(`  "attributes": {`);
+        lines.push(`    "minutes_before": 75`);
+        lines.push(`  }`);
+        lines.push(`}`);
+    }
+    else {
+        lines.push(`Early arrival campaign setup failed.`);
+    }
+    if (result.errors.length > 0) {
+        lines.push(`\nErrors:`);
+        for (const error of result.errors) {
+            lines.push(`- ${error}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export const earlyArrivalWorkflow = {
+    id: "early-arrival",
+    name: "Early Arrival Campaign",
+    execute: executeEarlyArrivalWorkflow,
+};

package/dist/workflows/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Fan Engagement Workflows
+ *
+ * Orchestrated workflows for setting up complete fan engagement campaigns.
+ * These combine multiple Open Loyalty tools into guided, step-by-step flows.
+ */
+import { matchAttendanceWorkflow, executeMatchAttendanceWorkflow, type MatchAttendanceConfig, type MatchAttendanceResult } from "./match-attendance.js";
+import { earlyArrivalWorkflow, executeEarlyArrivalWorkflow, type EarlyArrivalConfig, type EarlyArrivalResult } from "./early-arrival.js";
+import { sportsbarVisitWorkflow, executeSportsbarVisitWorkflow, type SportsbarVisitConfig, type SportsbarVisitResult } from "./sportsbar-visit.js";
+import { vodWatchingWorkflow, executeVodWatchingWorkflow, type VodWatchingConfig, type VodWatchingResult } from "./vod-watching.js";
+import { appLoginStreakWorkflow, executeAppLoginStreakWorkflow, type AppLoginStreakConfig, type AppLoginStreakResult } from "./app-login-streak.js";
+export { matchAttendanceWorkflow, executeMatchAttendanceWorkflow, type MatchAttendanceConfig, type MatchAttendanceResult, };
+export { earlyArrivalWorkflow, executeEarlyArrivalWorkflow, type EarlyArrivalConfig, type EarlyArrivalResult, };
+export { sportsbarVisitWorkflow, executeSportsbarVisitWorkflow, type SportsbarVisitConfig, type SportsbarVisitResult, };
+export { vodWatchingWorkflow, executeVodWatchingWorkflow, type VodWatchingConfig, type VodWatchingResult, };
+export { appLoginStreakWorkflow, executeAppLoginStreakWorkflow, type AppLoginStreakConfig, type AppLoginStreakResult, };
+export { DEFAULTS, ALL_WORKFLOWS, findMatchingWorkflow, getWorkflowById, parseCommaSeparated, parseMilestones, formatOLDate, AGENT_PROMPTS, type WorkflowDefinition, type WorkflowQuestion, type WorkflowStep, } from "../prompts/fan-engagement-setup.js";
+export interface FanEngagementConfig {
+    /** Match attendance configuration */
+    matchAttendance?: Partial<MatchAttendanceConfig>;
+    /** Early arrival configuration */
+    earlyArrival?: Partial<EarlyArrivalConfig>;
+    /** Sports bar visit configuration */
+    sportsbarVisit?: Partial<SportsbarVisitConfig>;
+    /** VOD watching configuration */
+    vodWatching?: Partial<VodWatchingConfig>;
+    /** App login streak configuration */
+    appLoginStreak?: Partial<AppLoginStreakConfig>;
+    /** Which workflows to execute (default: all) */
+    enabledWorkflows?: ("match-attendance" | "early-arrival" | "sportsbar-visit" | "vod-watching" | "app-login-streak")[];
+}
+export interface FanEngagementResult {
+    success: boolean;
+    results: {
+        matchAttendance?: MatchAttendanceResult;
+        earlyArrival?: EarlyArrivalResult;
+        sportsbarVisit?: SportsbarVisitResult;
+        vodWatching?: VodWatchingResult;
+        appLoginStreak?: AppLoginStreakResult;
+    };
+    summary: string;
+    totalCampaigns: number;
+    totalAchievements: number;
+    errors: string[];
+}
+/**
+ * Execute all fan engagement workflows
+ *
+ * This is the master workflow that orchestrates all individual workflows
+ * based on the provided configuration.
+ */
+export declare function executeAllFanEngagementWorkflows(config?: FanEngagementConfig): Promise<FanEngagementResult>;
+export declare const allWorkflows: readonly [{
+    id: string;
+    name: string;
+    execute: typeof executeMatchAttendanceWorkflow;
+}, {
+    id: string;
+    name: string;
+    execute: typeof executeEarlyArrivalWorkflow;
+}, {
+    id: string;
+    name: string;
+    execute: typeof executeSportsbarVisitWorkflow;
+}, {
+    id: string;
+    name: string;
+    execute: typeof executeVodWatchingWorkflow;
+}, {
+    id: string;
+    name: string;
+    execute: typeof executeAppLoginStreakWorkflow;
+}];
+/**
+ * Get workflow by ID
+ */
+export declare function getWorkflow(id: string): {
+    id: string;
+    name: string;
+    execute: typeof executeAppLoginStreakWorkflow;
+} | {
+    id: string;
+    name: string;
+    execute: typeof executeEarlyArrivalWorkflow;
+} | {
+    id: string;
+    name: string;
+    execute: typeof executeMatchAttendanceWorkflow;
+} | {
+    id: string;
+    name: string;
+    execute: typeof executeSportsbarVisitWorkflow;
+} | {
+    id: string;
+    name: string;
+    execute: typeof executeVodWatchingWorkflow;
+} | undefined;
+/**
+ * Execute a workflow by ID with given config
+ */
+export declare function executeWorkflowById(id: string, config?: Record<string, unknown>): Promise<unknown>;

package/dist/workflows/index.js

@@ -0,0 +1,208 @@
+/**
+ * Fan Engagement Workflows
+ *
+ * Orchestrated workflows for setting up complete fan engagement campaigns.
+ * These combine multiple Open Loyalty tools into guided, step-by-step flows.
+ */
+// Import execute functions for internal use
+import { matchAttendanceWorkflow, executeMatchAttendanceWorkflow, } from "./match-attendance.js";
+import { earlyArrivalWorkflow, executeEarlyArrivalWorkflow, } from "./early-arrival.js";
+import { sportsbarVisitWorkflow, executeSportsbarVisitWorkflow, } from "./sportsbar-visit.js";
+import { vodWatchingWorkflow, executeVodWatchingWorkflow, } from "./vod-watching.js";
+import { appLoginStreakWorkflow, executeAppLoginStreakWorkflow, } from "./app-login-streak.js";
+// Re-export all workflow components
+export { matchAttendanceWorkflow, executeMatchAttendanceWorkflow, };
+export { earlyArrivalWorkflow, executeEarlyArrivalWorkflow, };
+export { sportsbarVisitWorkflow, executeSportsbarVisitWorkflow, };
+export { vodWatchingWorkflow, executeVodWatchingWorkflow, };
+export { appLoginStreakWorkflow, executeAppLoginStreakWorkflow, };
+// Re-export prompt utilities
+export { DEFAULTS, ALL_WORKFLOWS, findMatchingWorkflow, getWorkflowById, parseCommaSeparated, parseMilestones, formatOLDate, AGENT_PROMPTS, } from "../prompts/fan-engagement-setup.js";
+// ============================================================================
+// Master Workflow
+// ============================================================================
+/**
+ * Execute all fan engagement workflows
+ *
+ * This is the master workflow that orchestrates all individual workflows
+ * based on the provided configuration.
+ */
+export async function executeAllFanEngagementWorkflows(config = {}) {
+    const enabledWorkflows = config.enabledWorkflows || [
+        "match-attendance",
+        "early-arrival",
+        "sportsbar-visit",
+        "vod-watching",
+        "app-login-streak",
+    ];
+    const result = {
+        success: false,
+        results: {},
+        summary: "",
+        totalCampaigns: 0,
+        totalAchievements: 0,
+        errors: [],
+    };
+    try {
+        // Execute each enabled workflow
+        for (const workflowId of enabledWorkflows) {
+            switch (workflowId) {
+                case "match-attendance": {
+                    const maResult = await executeMatchAttendanceWorkflow(config.matchAttendance);
+                    result.results.matchAttendance = maResult;
+                    if (maResult.baseCampaignId)
+                        result.totalCampaigns++;
+                    result.totalCampaigns += maResult.achievements.filter((a) => a.bonusCampaignId).length;
+                    result.totalAchievements += maResult.achievements.length;
+                    result.errors.push(...maResult.errors);
+                    break;
+                }
+                case "early-arrival": {
+                    const eaResult = await executeEarlyArrivalWorkflow(config.earlyArrival);
+                    result.results.earlyArrival = eaResult;
+                    if (eaResult.campaignId)
+                        result.totalCampaigns++;
+                    result.errors.push(...eaResult.errors);
+                    break;
+                }
+                case "sportsbar-visit": {
+                    const sbResult = await executeSportsbarVisitWorkflow(config.sportsbarVisit);
+                    result.results.sportsbarVisit = sbResult;
+                    if (sbResult.visitCampaignId)
+                        result.totalCampaigns++;
+                    if (sbResult.bonusCampaignId)
+                        result.totalCampaigns++;
+                    if (sbResult.achievementId)
+                        result.totalAchievements++;
+                    result.errors.push(...sbResult.errors);
+                    break;
+                }
+                case "vod-watching": {
+                    const vodResult = await executeVodWatchingWorkflow(config.vodWatching);
+                    result.results.vodWatching = vodResult;
+                    if (vodResult.watchCampaignId)
+                        result.totalCampaigns++;
+                    if (vodResult.bonusCampaignId)
+                        result.totalCampaigns++;
+                    if (vodResult.achievementId)
+                        result.totalAchievements++;
+                    result.errors.push(...vodResult.errors);
+                    break;
+                }
+                case "app-login-streak": {
+                    const loginResult = await executeAppLoginStreakWorkflow(config.appLoginStreak);
+                    result.results.appLoginStreak = loginResult;
+                    if (loginResult.loginCampaignId)
+                        result.totalCampaigns++;
+                    if (loginResult.streakBonusCampaignId)
+                        result.totalCampaigns++;
+                    if (loginResult.streakAchievementId)
+                        result.totalAchievements++;
+                    result.errors.push(...loginResult.errors);
+                    break;
+                }
+            }
+        }
+        // Determine overall success
+        result.success = result.errors.length === 0 && result.totalCampaigns > 0;
+        // Build summary
+        result.summary = buildMasterSummary(result);
+    }
+    catch (error) {
+        result.errors.push(`Master workflow error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function buildMasterSummary(result) {
+    const lines = [];
+    lines.push(`Fan Engagement Program Setup Complete!`);
+    lines.push(`========================================`);
+    lines.push(`\nCreated: ${result.totalCampaigns} campaigns, ${result.totalAchievements} achievements`);
+    // Match Attendance
+    if (result.results.matchAttendance) {
+        const ma = result.results.matchAttendance;
+        if (ma.baseCampaignId) {
+            lines.push(`\nMatch Attendance:`);
+            lines.push(`  - Base campaign: ${ma.baseCampaignId}`);
+            if (ma.achievements.length > 0) {
+                lines.push(`  - Achievements: ${ma.achievements.map((a) => a.milestone).join(", ")} matches`);
+            }
+        }
+    }
+    // Early Arrival
+    if (result.results.earlyArrival?.campaignId) {
+        lines.push(`\nEarly Arrival:`);
+        lines.push(`  - Campaign: ${result.results.earlyArrival.campaignId}`);
+    }
+    // Sports Bar
+    if (result.results.sportsbarVisit?.visitCampaignId) {
+        lines.push(`\nSports Bar Visits:`);
+        lines.push(`  - Visit campaign: ${result.results.sportsbarVisit.visitCampaignId}`);
+        if (result.results.sportsbarVisit.achievementId) {
+            lines.push(`  - Achievement: ${result.results.sportsbarVisit.achievementId}`);
+        }
+    }
+    // VOD Watching
+    if (result.results.vodWatching?.watchCampaignId) {
+        lines.push(`\nVOD Watching:`);
+        lines.push(`  - Watch campaign: ${result.results.vodWatching.watchCampaignId}`);
+        if (result.results.vodWatching.achievementId) {
+            lines.push(`  - Achievement: ${result.results.vodWatching.achievementId}`);
+        }
+    }
+    // App Login
+    if (result.results.appLoginStreak?.loginCampaignId) {
+        lines.push(`\nApp Login Streak:`);
+        lines.push(`  - Login campaign: ${result.results.appLoginStreak.loginCampaignId}`);
+        if (result.results.appLoginStreak.streakAchievementId) {
+            lines.push(`  - Streak achievement: ${result.results.appLoginStreak.streakAchievementId}`);
+        }
+    }
+    // Custom events reference
+    lines.push(`\nCustom Events Reference:`);
+    lines.push(`  - match_attendance: Triggered when fan scans at stadium entry`);
+    lines.push(`  - early_arrival: Triggered when fan arrives early (needs minutes_before attribute)`);
+    lines.push(`  - sportsbar_visit: Triggered when fan visits the sports bar`);
+    lines.push(`  - vod_watch: Triggered when fan watches video (needs minutes_watched attribute)`);
+    lines.push(`  - app_login: Triggered on daily app login`);
+    // Errors
+    if (result.errors.length > 0) {
+        lines.push(`\nWarnings/Errors (${result.errors.length}):`);
+        for (const error of result.errors.slice(0, 5)) {
+            lines.push(`  - ${error}`);
+        }
+        if (result.errors.length > 5) {
+            lines.push(`  ... and ${result.errors.length - 5} more`);
+        }
+    }
+    return lines.join("\n");
+}
+// ============================================================================
+// All Workflows Registry
+// ============================================================================
+export const allWorkflows = [
+    matchAttendanceWorkflow,
+    earlyArrivalWorkflow,
+    sportsbarVisitWorkflow,
+    vodWatchingWorkflow,
+    appLoginStreakWorkflow,
+];
+/**
+ * Get workflow by ID
+ */
+export function getWorkflow(id) {
+    return allWorkflows.find((w) => w.id === id);
+}
+/**
+ * Execute a workflow by ID with given config
+ */
+export async function executeWorkflowById(id, config) {
+    const workflow = getWorkflow(id);
+    if (!workflow) {
+        throw new Error(`Workflow not found: ${id}`);
+    }
+    return workflow.execute(config);
+}

package/dist/workflows/match-attendance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Match Attendance Workflow
+ *
+ * Creates a complete match attendance reward program including:
+ * - Base campaign for per-match coin rewards
+ * - Achievements for attendance milestones (6, 12 matches, etc.)
+ * - Bonus campaigns triggered by achievement completion
+ */
+export interface MatchAttendanceConfig {
+    /** Coins awarded per match attendance */
+    coinsPerMatch: number;
+    /** Attendance milestones for achievements (e.g., [6, 12] or [6, 12, "80%"]) */
+    milestones: (number | string)[];
+    /** Badge names for each milestone */
+    badgeNames: string[];
+    /** Bonus coins for each milestone */
+    milestoneBonuses: number[];
+    /** Maximum attendances counted per day (anti-fraud) */
+    limitPerDay: number;
+    /** Season start date (ISO format) */
+    seasonStart: string;
+    /** Season end date (ISO format) */
+    seasonEnd: string;
+}
+export interface MatchAttendanceResult {
+    success: boolean;
+    baseCampaignId?: string;
+    achievements: Array<{
+        achievementId: string;
+        milestone: number | string;
+        badgeName: string;
+        bonusCampaignId?: string;
+    }>;
+    errors: string[];
+    summary: string;
+}
+/**
+ * Execute the match attendance workflow
+ */
+export declare function executeMatchAttendanceWorkflow(config?: Partial<MatchAttendanceConfig>): Promise<MatchAttendanceResult>;
+export declare const matchAttendanceWorkflow: {
+    id: string;
+    name: string;
+    execute: typeof executeMatchAttendanceWorkflow;
+};