@open-loyalty/mcp-server 1.1.0 → 1.3.3

package/dist/instructions.js

@@ -0,0 +1,440 @@
+/**
+ * MCP Server Instructions - provides context and guidance for AI agents
+ * using the Open Loyalty MCP server.
+ */
+export const SERVER_INSTRUCTIONS = `
+Open Loyalty MCP Server - Complete Loyalty Program Management
+
+## Domain Model
+
+Member (loyalty program participant)
+  └── Points (wallet balance, transfers)
+  └── Tier (current level: Bronze, Silver, Gold)
+  └── Transactions (purchase history)
+  └── Rewards (redeemed coupons)
+  └── Achievements (gamification progress)
+  └── Badges (visual rewards from achievements)
+
+TierSet (loyalty program structure)
+  └── Conditions (criteria: activeUnits, totalSpending)
+  └── Tiers (levels with thresholds)
+
+WalletType (points currency configuration)
+
+Reward (redeemable items)
+  └── Categories (reward groupings)
+
+Campaign (automated points/rewards rules)
+  └── Type (earning, spending, custom, instant_reward)
+  └── Trigger (transaction, custom_event, points_transfer)
+  └── Rules (SKU, category, transaction amount conditions)
+  └── Effects (give_points, multiply_points, percentage_discount)
+  └── Targeting (segments, tiers for audience)
+
+Segment (member audience grouping)
+  └── Parts (groups of criteria - OR logic between parts)
+      └── Criteria (conditions - AND logic within part)
+          Types: transaction_count (working; requires min+max). Other types may be rejected by the API.
+
+Achievement (gamification goals)
+  └── Trigger (transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update)
+  └── CompleteRule (periodGoal, period type, unique counting)
+  └── Badge (visual reward when completed)
+
+Badge (visual recognition)
+  └── Linked to achievements via badgeTypeId
+  └── Auto-created when referenced by achievement
+
+## Key Workflows
+
+### 1. Create 3-tier Loyalty Program:
+RECOMMENDED WORKFLOW:
+1. wallet_type_list → Get wallet code (usually "default")
+2. tierset_list → Check if tier set already exists
+3. IF EXISTS: tierset_get → Get conditionId from existing tier set
+   ELSE: tierset_create → Create new, then tierset_get to get conditionId
+4. tierset_update_tiers → Define tier thresholds using conditionId
+5. tierset_get_tiers → Verify tiers created correctly
+
+GOTCHA - Valid tier condition attributes:
+- activeUnits (current spendable balance)
+- totalEarnedUnits (lifetime points - NOT 'earnedUnits'!)
+- totalSpending (lifetime spend amount)
+- monthsSinceJoiningProgram (tenure in months)
+- cumulatedEarnedUnits (similar to totalEarnedUnits)
+
+COMMON MISTAKE: Using 'earnedUnits' will fail - use 'totalEarnedUnits' for lifetime points.
+
+### 2. Register and Reward Member:
+member_create → points_add (welcome bonus) → member_get (verify)
+
+### 3. Record Purchase and Earn Points:
+transaction_create (with customerData) → triggers campaigns → points auto-added
+
+### 4. Redeem Reward:
+reward_list → reward_buy (deducts points) → reward_redeem (mark coupon used)
+
+### 5. Assign Unmatched Transaction:
+transaction_list (matched=false) → transaction_assign_member → points earned
+
+### 6. Check Member Tier Progress:
+member_get_tier_progress → shows current tier, next tier, progress %
+
+### 7. Double Points for VIP Members:
+segment_create (with transaction_count criteria) → campaign_create (targeting that segment with give_points effect and pointsRule: "transaction.grossValue * 2")
+
+### 8. Purchase Achievement with Badge:
+badge_list (find or note badgeTypeId) → achievement_create (type+trigger+aggregation+period required, badgeTypeId)
+
+### 9. Create Targeted Promotion:
+segment_create (define audience) → campaign_create (type: earning, target: segment, segmentIds: [segmentId])
+
+### 10. Track Member Gamification:
+achievement_list_member_achievements → badge_get_member_badges → achievement_get_member_progress
+
+## Discovery Paths:
+- Members: member_list → member_get → points_get_balance
+- Tiers: tierset_list → tierset_get → tierset_get_tiers
+- Rewards: reward_category_list → reward_list → reward_get
+- Transactions: transaction_list → transaction_get
+- Campaigns: campaign_list → campaign_get → campaign_simulate
+- Segments: segment_list → segment_get → segment_get_members → campaign_create (audience targeting)
+- Achievements: achievement_list → badge_list → achievement_create (with badge)
+- Member Gamification: achievement_list_member_achievements → badge_get_member_badges
+
+## Important Patterns:
+- TIER SETUP: conditionId REQUIRED for tier thresholds
+  1. tierset_create returns conditions but you need the id from tierset_get
+  2. The conditionId is in tierset_get response: conditions[].id (this IS the conditionId)
+  3. Use this conditionId in tierset_update_tiers for each tier's threshold
+- TIER ATTRIBUTES: Use 'totalEarnedUnits' (NOT 'earnedUnits') for lifetime points
+- walletType uses CODE (e.g., 'default'), not UUID
+- Points operations: check balance with points_get_balance before spending
+- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used
+- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)
+
+### Pagination:
+- Traditional pagination: use page + perPage params
+- Cursor pagination: provide cursor from previous response for efficient deep pagination
+- Cursor-enabled tools: member_list, transaction_list, points_get_history
+- First scroll request: cursor="" (empty string)
+- Subsequent requests: use cursor value from previous response
+- When cursor provided, page param is ignored
+
+### Campaign Patterns:
+- Campaign types: direct (standard), referral (referral programs)
+- Triggers: transaction (purchase), custom_event, time, achievement, etc.
+- Effects: give_points, give_reward, deduct_unit
+- Target campaigns to segments or tiers using audience.target: "segment" and audience.segments array
+- campaign_create requires activity.startsAt, rules[].name, and effects[].effect (use key effect, not type). pointsRule is a STRING expression.
+
+### Points Expression (pointsRule):
+pointsRule is a STRING expression, not an object. Examples:
+- Fixed: "100"
+- Per dollar: "transaction.grossValue * 10"
+- Category-based: "transaction.category('electronics').grossValue * 5"
+- Capped: "(transaction.grossValue * 2 >= 100) ? 100 : transaction.grossValue * 2"
+- Rounded: "round_up(0.1 * transaction.grossValue)"
+
+### Segment Patterns:
+- Parts use OR logic (member matches ANY part)
+- Criteria within a part use AND logic (member must match ALL criteria in that part)
+- Common criteria: transaction_count (working; requires min+max). Other criteria may be rejected by the API.
+
+### Achievement Patterns:
+- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update
+- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)
+- period.type defines timeframe: day, week, month, year, last_day, calendarDays, calendarWeeks, calendarMonths, calendarYears
+- aggregation.type defines counting method: quantity (count events only)
+- Link to badge via badgeTypeId - badge auto-created if doesn't exist
+- uniqueAttribute for counting distinct values (e.g., unique products)
+
+### Achievement Period Types:
+- "day": Count all-time when consecutive=1
+- "week": Count per week (use consecutive=1 for all-time weekly tracking)
+- "month": Count per month
+- "year": Count per year
+- "last_day": Rolling window of N days (e.g., value: 7 for last 7 days)
+- "calendarDays": Reset daily at midnight
+- "calendarWeeks": Reset weekly (Monday)
+- "calendarMonths": Reset monthly (1st of month)
+- "calendarYears": Reset yearly (January 1st)
+
+### Streak Achievement Example (7-day login streak):
+{
+  "rules": [{
+    "trigger": "custom_event",
+    "event": "app_login",
+    "type": "direct",
+    "aggregation": {"type": "quantity"},
+    "completeRule": {
+      "periodGoal": 1,
+      "period": {"type": "last_day", "value": 7, "consecutive": 1}
+    },
+    "limit": {
+      "interval": {"type": "calendarDays", "value": 1},
+      "value": 1
+    }
+  }]
+}
+
+### Custom Event Workflows:
+
+#### Create Custom Event Campaign:
+1. custom_event_schema_list → Check if event type exists
+2. custom_event_schema_create (if needed) → Define event type and fields
+3. campaign_create with trigger: "custom_event", event: "{event_type}"
+4. Send events via custom_event_send to trigger campaign
+
+#### Create Achievement with Custom Event:
+1. custom_event_schema_create → Define event (e.g., "location_visit")
+2. achievement_create with:
+   - rules[].trigger: "custom_event"
+   - rules[].event: "{event_type}"
+   - rules[].type: "direct"
+   - rules[].aggregation.type: "quantity"
+   - rules[].completeRule.periodGoal: {count}
+   - rules[].completeRule.period: { type: "day", consecutive: 1 } (all-time)
+
+#### Create Campaign Triggered by Achievement:
+1. achievement_create → Get achievementId from response
+2. campaign_create with:
+   - trigger: "achievement"
+   - achievementId: "{achievement_id}"
+   - rules with effects (give_points, give_reward)
+
+### Condition Operators (for campaigns/achievements):
+- is_equal, is_not_equal
+- gte, gt, lte, lt
+- is_between, is_not_between
+- is_time_between
+- is_day_of_week, is_day_of_month
+- contains, not_contains
+- starts_with, ends_with
+- one_of, not_one_of
+- expression (for custom logic)
+
+## Common Campaign Patterns (Industry-Agnostic)
+
+These patterns work for any loyalty program - retail, QSR, aviation, fan engagement, hospitality, etc.
+
+### Pattern 1: Count Events Toward Goal (Achievements)
+Use case: Track member actions (visits, purchases, logins, check-ins) toward a milestone.
+1. custom_event_schema_create → Define your action type (e.g., "store_visit", "app_login")
+2. achievement_create with:
+   - trigger: "custom_event"
+   - event: "{your_event_code}"
+   - aggregation: { type: "quantity" }
+   - completeRule: { periodGoal: {count}, period: { type: "day", consecutive: 1 } }
+3. custom_event_send to log each action
+
+### Pattern 2: Points Per Action (Instant Rewards)
+Use case: Award instant points for each qualifying action.
+1. custom_event_schema_create (if not using transaction)
+2. campaign_create with:
+   - trigger: "custom_event" (or "transaction")
+   - event: "{event_code}" (for custom events)
+   - rules: [{ effects: [{ effect: "give_points", pointsRule: "50" }] }]
+
+### Pattern 3: Conditional Rewards (Bonus Conditions)
+Use case: Award points only when a condition is met (e.g., early arrival, large purchase).
+Use ternary expressions in pointsRule instead of conditions array:
+- pointsRule: "event.body.minutes_before >= 60 ? 25 : 0"
+- pointsRule: "transaction.grossValue >= 100 ? 50 : 0"
+
+### Pattern 4: Execution Limits (Anti-Fraud)
+Use case: Limit rewards to prevent abuse (once per day, once per week).
+Campaign limits structure:
+{
+  "limits": {
+    "executionsPerMember": {
+      "value": 1,
+      "interval": { "type": "calendarDays", "value": 1 }
+    }
+  }
+}
+Note: Use "calendarDays" (not "days"), "calendarWeeks", "calendarMonths", "calendarYears".
+Omit interval entirely for lifetime/forever limit.
+
+### Pattern 5: Achievement-Triggered Bonus
+Use case: Award bonus points/rewards when member completes an achievement.
+1. achievement_create → Get achievementId from response
+2. campaign_create with:
+   - trigger: "achievement"
+   - achievementId: "{achievement_id}"
+   - rules with give_points or give_reward effect
+
+### Pattern 6: Tiered Milestones
+Use case: Multiple achievement levels (bronze/silver/gold, 5/10/25 visits).
+Create multiple achievements with increasing periodGoal values,
+each linked to a different bonus campaign with increasing rewards.
+
+### Pattern 7: Time-Limited Promotion
+Use case: Seasonal or promotional campaigns.
+{
+  "activity": {
+    "startsAt": "2026-01-01 00:00+00:00",
+    "endsAt": "2026-03-31 23:59+00:00"
+  }
+}
+
+### Pattern 8: Streak Tracking
+Use case: Reward consecutive daily/weekly actions (login streaks, workout streaks).
+Achievement with:
+- completeRule.period: { type: "last_day", value: 7 } (rolling 7-day window)
+- limit: { value: 1, interval: { type: "calendarDays", value: 1 } } (max 1 per day)
+
+## Phase 3: Analytics, Admin, Roles & Stores
+
+### Domain Model (Extended)
+
+Admin (system user)
+  └── Roles (permission sets)
+      └── Permissions (resource + access level)
+  └── API Keys (programmatic access)
+
+Store (multi-tenant container)
+  └── Members, Campaigns, Rewards (isolated per store)
+
+Audit Log (compliance tracking)
+  └── eventType, entityType, entityId, username, timestamp
+
+### Analytics Workflows:
+
+#### 11. Get Program Overview:
+analytics_dashboard → analytics_tiers → analytics_members
+
+#### 12. Analyze Points Economy:
+analytics_points → analytics_units (per wallet) → points_get_histogram
+
+#### 13. Measure Campaign Performance:
+analytics_campaigns → analytics_campaign_detail (specific campaign)
+
+#### 14. Track Transactions:
+analytics_transactions → transaction_list (details)
+
+### Aggregation Queries (Top Spenders, Purchase Analysis):
+
+IMPORTANT: For queries like "top 5 spenders in July 2025", use this approach:
+
+#### 15. Find Top Spenders by Date Range:
+1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction
+2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions
+3. Aggregate grossValue by customerId in your code
+4. Sort by total spent, take top N
+5. member_get for each top spender to get names/details
+
+CRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:
+- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach
+- DO NOT skip pages or try to sample data - you will get inaccurate results
+- DO NOT use transaction_get individually - transaction_list already includes customerId
+- DO NOT try to find "smarter" analytics endpoints - they don't exist for per-customer aggregation
+- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty
+- Start with cursor='' (empty string), use returned cursor for next request, repeat until done
+
+Example: Top 5 spenders July 2025
+- First request: transaction_list(purchasedAtFrom: "2025-07-01", purchasedAtTo: "2025-07-31", perPage: 50, cursor: "")
+- Each result includes: transactionId, grossValue, customerId, purchasedAt
+- Keep fetching with returned cursor until response has no cursor or empty transactions
+- Even if there are 1500 transactions (30 pages), iterate through ALL of them
+- Group by customerId, sum grossValue, sort descending, take 5
+
+### Admin & Security Workflows:
+
+#### 15. Create Admin with Limited Role:
+acl_get_resources → role_create → admin_create (with roleId)
+
+#### 16. Generate API Key for Integration:
+admin_get → apikey_create → SAVE TOKEN IMMEDIATELY (shown once!)
+
+#### 17. Audit User Actions:
+audit_list (filter by username/entity) → audit_export (compliance report)
+
+### Store Multi-Tenancy:
+
+#### 18. Create New Store:
+store_create → configure campaigns/tiers → member_create (with storeCode)
+
+### Analytics Query Patterns:
+- All analytics tools support dateFrom/dateTo ISO date filters
+- analytics_dashboard: high-level program metrics
+- analytics_units: wallet-specific metrics (requires walletTypeCode)
+- analytics_campaign_detail: detailed metrics for single campaign
+
+### Admin → Role → Permission Model:
+┌─────────┐     ┌──────┐     ┌────────────┐
+│  Admin  │────▶│ Role │────▶│ Permission │
+└─────────┘     └──────┘     └────────────┘
+     │                            │
+     │                       resource + access
+     │                       (VIEW, MODIFY, etc.)
+     ▼
+┌─────────┐
+│ API Key │
+└─────────┘
+
+### Store Multi-Tenancy:
+- Each store is isolated: members, campaigns, rewards, transactions
+- storeCode parameter routes requests to correct tenant
+- Default store used when storeCode omitted
+- IMPORTANT: Do NOT pass storeCode parameter unless the user explicitly asks to work with a different store. The configured default store should always be used unless the user requests otherwise.
+
+## Phase 4: Webhooks, Import & Export
+
+### Domain Model (Extended)
+
+Webhook Subscription (event notification)
+  └── eventName (event to subscribe to)
+  └── url (callback endpoint)
+  └── headers (custom HTTP headers)
+
+Import (bulk data upload)
+  └── type: member, groupValue, segmentMembers, unitTransferAdding, etc.
+  └── status: pending, processing, succeed, failed
+  └── items (individual row results)
+
+Export (bulk data download)
+  └── type: campaignCode, member, memberTier, memberSegment, rewardFulfillment
+  └── status: pending, done, failed, error
+  └── CSV file (when status='done')
+
+### Webhook Workflows:
+
+#### 19. Subscribe to Member Events for CRM Sync:
+webhook_events → webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')
+
+#### 20. List and Manage Subscriptions:
+webhook_list → webhook_get → webhook_update or webhook_delete
+
+### Import Workflows:
+
+#### 21. Bulk Import Members from CSV:
+import_create (type: 'member', fileContent: CSV data) → import_list → import_get (check status)
+
+#### 22. Bulk Add Points to Members:
+import_create (type: 'unitTransferAdding', fileContent: CSV) → poll import_get until complete
+
+### Export Workflows:
+
+#### 23. Export Campaign Codes:
+export_create (type: 'campaignCode', filters: { campaignId }) → poll export_get (until status='done') → export_download
+
+#### 24. Export Member Data:
+export_create (type: 'member') → export_get → export_download (returns CSV)
+
+### Webhook Patterns:
+- Use webhook_events to discover available event types before subscribing
+- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }
+- Common events: member.created, member.updated, transaction.created, reward.purchased
+
+### Import Patterns:
+- Import is async: create returns importId, poll status with import_get
+- CSV format required - provide plain text, not base64
+- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon
+
+### Export Patterns:
+- Export is async: create returns exportId, poll status until 'done'
+- API body wrapper varies by type: { campaignCode: { filters... } }
+- Only call export_download when status='done'
+- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment
+`;

package/dist/prompts/fan-engagement-setup.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Fan Engagement Setup Prompts
+ *
+ * MCP prompt templates for guided campaign setup.
+ * These define conversational flows and default values for AI agents
+ * to help program admins create fan engagement campaigns.
+ */
+export interface WorkflowQuestion {
+    id: string;
+    question: string;
+    type: "number" | "boolean" | "string" | "select";
+    default?: unknown;
+    options?: string[];
+    validation?: (value: unknown) => boolean;
+    hint?: string;
+}
+export interface WorkflowStep {
+    id: string;
+    action: string;
+    tool: string;
+    description: string;
+}
+export interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description: string;
+    triggerPhrases: string[];
+    questions: WorkflowQuestion[];
+    steps: WorkflowStep[];
+}
+export declare const DEFAULTS: {
+    readonly matchAttendance: {
+        readonly coinsPerMatch: 50;
+        readonly milestones: number[];
+        readonly milestoneBonuses: Record<string | number, number>;
+        readonly limitPerDay: 1;
+        readonly badges: Record<string | number, string>;
+    };
+    readonly earlyArrival: {
+        readonly minutesBefore: 60;
+        readonly coinsPerArrival: 25;
+        readonly limitPerMatch: 1;
+    };
+    readonly sportsbarVisit: {
+        readonly coinsPerVisit: 50;
+        readonly visitMilestone: 5;
+        readonly milestoneBonus: 500;
+        readonly limitPerDay: 1;
+    };
+    readonly vodWatching: {
+        readonly trackBy: "views" | "minutes";
+        readonly coinsPerUnit: 10;
+        readonly unitSize: 10;
+        readonly achievementMinutes: 300;
+        readonly achievementBonus: 200;
+    };
+    readonly appLoginStreak: {
+        readonly coinsPerLogin: 5;
+        readonly streakDays: 7;
+        readonly streakBonus: 50;
+        readonly limitPerDay: 1;
+    };
+    readonly seasonDates: {
+        readonly start: string;
+        readonly end: string;
+    };
+};
+export declare const MATCH_ATTENDANCE_WORKFLOW: WorkflowDefinition;
+export declare const EARLY_ARRIVAL_WORKFLOW: WorkflowDefinition;
+export declare const SPORTSBAR_VISIT_WORKFLOW: WorkflowDefinition;
+export declare const VOD_WATCHING_WORKFLOW: WorkflowDefinition;
+export declare const APP_LOGIN_STREAK_WORKFLOW: WorkflowDefinition;
+export declare const ALL_WORKFLOWS: WorkflowDefinition[];
+/**
+ * Find matching workflow based on user input
+ */
+export declare function findMatchingWorkflow(userInput: string): WorkflowDefinition | undefined;
+/**
+ * Get workflow by ID
+ */
+export declare function getWorkflowById(id: string): WorkflowDefinition | undefined;
+/**
+ * Parse comma-separated values to array
+ */
+export declare function parseCommaSeparated(value: string): string[];
+/**
+ * Parse milestones (handles both numbers and percentages like "80%")
+ */
+export declare function parseMilestones(value: string): (number | string)[];
+/**
+ * Format ISO date for Open Loyalty (YYYY-MM-DD HH:mm+TZ)
+ */
+export declare function formatOLDate(date: string | Date): string;
+export declare const AGENT_PROMPTS: {
+    /**
+     * System prompt for fan engagement setup
+     */
+    systemPrompt: string;
+    /**
+     * Workflow completion template
+     */
+    completionTemplate: (results: {
+        campaignIds: string[];
+        achievementIds: string[];
+        summary: string;
+    }) => string;
+};