revenuecat-entitlements-gate

revenuecat-entitlements-gate: check a RevenueCat entitlement

Use this skill when the user wants to decide whether to show or hide a feature based on an active RevenueCat entitlement. The skill covers the one shot check and the reactive listener; it does not cover purchasing (see revenuecat-purchase-flow) or auth (revenuecat-identify-user).

1. Detect the platform

Inspect the working directory and pick the first match, from top to bottom:

1. React Native: package.json has a react-native-purchases entry, or react-native as a dependency → read platforms/react-native.md. If expo is also a dependency, note it as an Expo project.
2. Flutter: pubspec.yaml exists at the project root → read platforms/flutter.md.
3. Kotlin Multiplatform: build.gradle.kts contains a kotlin { … } multiplatform source sets block, or depends on com.revenuecat.purchases:purchases-kmp* → read platforms/kmp.md.
4. Android (native): build.gradle(.kts) applies com.android.application (and is not KMP) → read platforms/android.md.
5. iOS (native): Package.swift, *.xcodeproj, *.xcworkspace, or Podfile at the project root → read platforms/ios.md.

If several match (e.g. an ios/ folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.

2. Shared concepts (all platforms)

• Check the entitlement identifier, not the product ID. The identifier (for example "premium") is configured in the RevenueCat dashboard and mapped to one or more products. Using the entitlement lets you change products, prices, and stores without touching app code.
• customerInfo.entitlements.active is the source of truth. It is a Map<String, EntitlementInfo> keyed by entitlement identifier. Presence in active means the user currently has access. Absence means they do not, regardless of past purchases.
• Do not gate on purchase history. Expired subscriptions still appear in customerInfo.entitlements.all but drop out of active. Use active only.
• Fetch once, then subscribe. The first customerInfo call returns a cached value quickly, and the SDK refreshes in the background. Every SDK exposes a listener or stream that fires when entitlements change (after a purchase, restore, renewal, or expiration). Subscribe to that instead of polling.
• The SDK must be configured first. If Purchases.configure(…) has not run, the entitlement call will fail. Set up the SDK via integrate-revenuecat before using this skill.

3. Implementation

Read the platform file that matches detection:

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

Each platform file shows the one shot check, the reactive subscription, and where to place each in a typical app.

4. Verify

Do not claim the gate works until:

1. A user with an active entitlement sees the gated feature, and a user without it does not.
2. When the entitlement state changes (test with a sandbox purchase or a manual grant in the dashboard), the UI updates without a manual restart, confirming the listener is wired.
3. The entitlement identifier in the code matches an identifier that exists in the RevenueCat dashboard. A typo here silently gates everyone out.