Update Card Benefits in CouponCycle

This skill guides you through updating benefits for existing credit cards. This is a 3-step process to ensure all users (new and existing) see the changes.

The Problem

When you update benefits in prisma/seed.ts:

• New users who add the card will see the changes
• Existing users still have the old benefit structure

This skill ensures ALL users get the updates.

Recommended Workflow

Step 1: Edit the Seed File

Edit prisma/seed.ts to add, remove, or modify benefits:

typescript
1{
2  name: 'American Express Platinum Card',
3  issuer: 'American Express',
4  annualFee: 895, // Update annual fee if changed
5  benefits: [
6    // Add new benefits
7    {
8      description: '$100 Quarterly Resy Dining Credit',
9      category: 'Dining',
10      maxAmount: 100,
11      frequency: BenefitFrequency.QUARTERLY,
12      percentage: 0,
13      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
14      occurrencesInCycle: 1,
15    },
16    // Keep existing benefits...
17  ],
18}

Step 2: Update the Template

bash
1npx prisma db seed

This updates the predefined card template for new users.

Step 3: Run the Unified Update Script

bash
1# Preview changes (safe - no data modified)
2node scripts/update-card-benefits.js --card "Card Name" --dry-run
3
4# Execute the update (migrates all existing users)
5node scripts/update-card-benefits.js --card "Card Name" --force

What the Script Does

The unified script automatically:

1. Verifies the predefined card exists
2. Finds all existing user cards for that card type
3. Smart diff-based migration:
   • Adds new benefits (preserves existing statuses)
   • Updates changed benefits (keeps benefit IDs)
   • Removes deprecated benefits
4. Creates benefit status records (makes benefits visible)
5. Uses transactions (rollback on failure)

Example Commands

bash
1# Update Amex Platinum
2node scripts/update-card-benefits.js \
3  --card "American Express Platinum Card" \
4  --dry-run
5
6# Update Chase Sapphire Reserve
7node scripts/update-card-benefits.js \
8  --card "Chase Sapphire Reserve" \
9  --force
10
11# Update Amex Business Platinum
12node scripts/update-card-benefits.js \
13  --card "American Express Business Platinum Card" \
14  --force

Alternative: Advanced Migration Framework

For complex migrations involving multiple cards or custom logic:

bash
1# 1. Create migration definition in scripts/migrate-benefits.js
2
3# 2. Validate migration
4node scripts/validate-migration.js --migration-id=your-migration
5
6# 3. Preview changes
7node scripts/migrate-benefits.js --migration-id=your-migration --dry-run
8
9# 4. Execute migration
10node scripts/migrate-benefits.js --migration-id=your-migration --force

Common Mistakes to Avoid

Mistake 1: Only Running Seed

bash
1npx prisma db seed  # Only helps NEW users

Mistake 2: Forgetting to Run Update Script

Without the update script, existing users won't see the changes.

Correct Process

bash
1npx prisma db seed  # Update template
2node scripts/update-card-benefits.js --card "Card Name" --force

Benefit Frequency Reference

Cycle Alignment Reference

Semi-Annual Benefits Pattern

For benefits that reset twice a year (Jan-Jun, Jul-Dec), create TWO separate benefits:

typescript
1// First half: January - June
2{
3  description: '$300 Hotel Credit (Jan-Jun)',
4  frequency: BenefitFrequency.YEARLY,
5  cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
6  fixedCycleStartMonth: 1,
7  fixedCycleDurationMonths: 6,
8},
9// Second half: July - December
10{
11  description: '$300 Hotel Credit (Jul-Dec)',
12  frequency: BenefitFrequency.YEARLY,
13  cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
14  fixedCycleStartMonth: 7,
15  fixedCycleDurationMonths: 6,
16},

Troubleshooting

"Card not found" Error

• Check the exact card name in the database
• Card names are case-sensitive

Users Not Seeing Benefits

• Ensure benefit statuses were created
• Users may need to refresh their browser

Migration Failed for Some Users

• Check error messages in output
• Re-run the script to retry failed users
• Individual failures don't affect other users

Safety Features

• Dry Run Mode: Always test with --dry-run first
• Transaction Safety: Changes rollback on failure
• Progress Tracking: See which users were migrated
• Preserves Completed Status: Existing completions are kept