update-card-benefits

name: update-card-benefits description: Update, add, or remove benefits from existing credit cards in Perks Reminder. Use when the user asks to update card benefits, add a new benefit to a card, remove a benefit, change benefit values, or mentions annual fee updates for cards like Amex Platinum, Chase Sapphire Reserve.

Update Card Benefits in Perks Reminder

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:

{
  name: 'American Express Platinum Card',
  issuer: 'American Express',
  annualFee: 895, // Update annual fee if changed
  benefits: [
    // Add new benefits
    {
      description: '$100 Quarterly Resy Dining Credit',
      category: 'Dining',
      maxAmount: 100,
      frequency: BenefitFrequency.QUARTERLY,
      percentage: 0,
      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
      occurrencesInCycle: 1,
    },
    // Keep existing benefits...
  ],
}

Step 2: Update the Template

npx prisma db seed

This updates the predefined card template for new users.

Step 3: Run the Unified Update Script

# Preview changes (safe - no data modified)
node scripts/update-card-benefits.js --card "Card Name" --dry-run

# Execute the update (migrates all existing users)
node 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

# Update Amex Platinum
node scripts/update-card-benefits.js \
  --card "American Express Platinum Card" \
  --dry-run

# Update Chase Sapphire Reserve
node scripts/update-card-benefits.js \
  --card "Chase Sapphire Reserve" \
  --force

# Update Amex Business Platinum
node scripts/update-card-benefits.js \
  --card "American Express Business Platinum Card" \
  --force

Alternative: Advanced Migration Framework

For complex migrations involving multiple cards or custom logic:

# 1. Create migration definition in scripts/migrate-benefits.js

# 2. Validate migration
node scripts/validate-migration.js --migration-id=your-migration

# 3. Preview changes
node scripts/migrate-benefits.js --migration-id=your-migration --dry-run

# 4. Execute migration
node scripts/migrate-benefits.js --migration-id=your-migration --force

Common Mistakes to Avoid

Mistake 1: Only Running Seed

npx 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

npx prisma db seed  # Update template
node 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:

// First half: January - June
{
  description: '$300 Hotel Credit (Jan-Jun)',
  frequency: BenefitFrequency.YEARLY,
  cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
  fixedCycleStartMonth: 1,
  fixedCycleDurationMonths: 6,
},
// Second half: July - December
{
  description: '$300 Hotel Credit (Jul-Dec)',
  frequency: BenefitFrequency.YEARLY,
  cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
  fixedCycleStartMonth: 7,
  fixedCycleDurationMonths: 6,
},

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