If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/RevenueCat/purchases-ios shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 14 active contributors
• Distributed ownership (top contributor 28% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live RevenueCat/purchases-ios repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/RevenueCat/purchases-ios.

What it runs against: a local clone of RevenueCat/purchases-ios — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in RevenueCat/purchases-ios | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of RevenueCat/purchases-ios. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/RevenueCat/purchases-ios.git
#   cd purchases-ios
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of RevenueCat/purchases-ios and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "RevenueCat/purchases-ios(\\.git)?\\b" \\
  && ok "origin remote is RevenueCat/purchases-ios" \\
  || miss "origin remote is not RevenueCat/purchases-ios (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".circleci/config.yml" \\
  && ok ".circleci/config.yml" \\
  || miss "missing critical file: .circleci/config.yml"
test -f ".swiftpm/xcode/xcshareddata/xcschemes/RevenueCatUI.xcscheme" \\
  && ok ".swiftpm/xcode/xcshareddata/xcschemes/RevenueCatUI.xcscheme" \\
  || miss "missing critical file: .swiftpm/xcode/xcshareddata/xcschemes/RevenueCatUI.xcscheme"
test -f ".swiftlint.yml" \\
  && ok ".swiftlint.yml" \\
  || miss "missing critical file: .swiftlint.yml"
test -f "AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Tracker.swift" \\
  && ok "AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Tracker.swift" \\
  || miss "missing critical file: AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Tracker.swift"
test -f "AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/RewardVerification.swift" \\
  && ok "AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/RewardVerification.swift" \\
  || miss "missing critical file: AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/RewardVerification.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/RevenueCat/purchases-ios"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RevenueCat is a production-grade in-app purchase and subscription management SDK for iOS/watchOS/tvOS/macOS/visionOS that wraps StoreKit with server-side receipt validation, entitlement tracking, and analytics integration. It provides a unified API to fetch products, process purchases, validate receipts on RevenueCat's backend, and track subscription status across platforms—eliminating the complexity of direct StoreKit integration. Modular Swift Package Manager structure: RevenueCat core SDK in the root (Purchases framework) with ~10M lines of Swift/Objective-C; AdapterSDKs/ contains companion integrations (RevenueCatAdMob); .circleci/ and .github/workflows/ manage CI/CD. SwiftPM workspace at .swiftpm/xcode with schemes for both RevenueCat and RevenueCatUI (paywall UI component). Testing and examples inline with source.

iOS/multiplatform app developers building subscription or in-app purchase features who want server-side receipt validation, remote product configuration, and unified subscription analytics without building their own backend validation infrastructure. Also for teams needing cross-platform purchase consistency across iOS, watchOS, tvOS, and macOS.

Highly mature and production-ready. The codebase shows 10M+ lines of Swift, structured CI/CD via CircleCI and GitHub Actions, version management (.version file), and migration guides spanning v3→v4→v5 releases indicating steady long-term maintenance. Clear evidence of active development with dependency management (dependabot.yml) and code quality tooling (.swiftlint.yml).

Low risk for production use. No obvious single-point-of-failure in the visible file structure; the repo includes comprehensive CI configuration suggesting robust testing practices. Main risk is dependency on RevenueCat's cloud backend for receipt validation and product configuration—network outages or service issues directly impact functionality. Requires API key management and active RevenueCat account.

Active maintenance evident from Dependabot configuration, CircleCI/GitHub Actions workflows, and the migration guide references suggesting recent major version work. The presence of RevenueCatUI schemes alongside RevenueCat indicates ongoing feature expansion into UI components. Adapter SDK directory (AdMob example) shows ecosystem integration work.

git clone https://github.com/RevenueCat/purchases-ios.git
cd purchases-ios
# Swift Package Manager projects don't require 'pod install'
# Open in Xcode: open .swiftpm/xcode/package.xcworkspace
# Or integrate via SPM: .package(url: "https://github.com/RevenueCat/purchases-ios", from: "5.0.0")

Daily commands: This is a library/SDK, not an executable app. To develop locally: open .swiftpm/xcode/package.xcworkspace in Xcode, then build the RevenueCat or RevenueCatUI schemes. To test: run the built-in test targets from the schemes. For example projects: open AdapterSDKs/RevenueCatAdMob/Examples/AdMobIntegrationSample/AdMobIntegrationSample.xcodeproj.

• .circleci/config.yml — Primary CI/CD pipeline configuration defining build, test, and deployment workflows for all platforms (iOS, watchOS, tvOS, macOS, visionOS).
• .swiftpm/xcode/xcshareddata/xcschemes/RevenueCatUI.xcscheme — Swift Package Manager scheme configuration for RevenueCatUI, essential for local development and distribution of the primary UI framework.
• .swiftlint.yml — SwiftLint configuration enforcing code style and quality standards across the entire codebase; must-read for maintaining contribution consistency.
• AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Tracker.swift — Core tracking abstraction for the AdMob adapter; central hub for revenue event instrumentation and ad integration.
• AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/RewardVerification.swift — Primary reward verification orchestrator for secure ad reward validation; critical to revenue integrity and anti-fraud logic.
• .github/CODEOWNERS — Defines code ownership and review requirements for different modules; necessary to understand approval workflows and contributor responsibilities.
• .spi.yml — Swift Package Index configuration controlling how the package is indexed and distributed; defines public API surface.

Add a new ad network adapter (e.g., for Facebook Audience Network)

1. Create a new folder: AdapterSDKs/RevenueCatFAN matching the structure of RevenueCatAdMob (AdapterSDKs/RevenueCatAdMob)
2. Implement Tracking adapter following the pattern in AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Adapter.swift (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/Adapter.swift)
3. Add RewardVerification orchestration (Setup.swift, State.swift, RewardVerification.swift) (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification)
4. Create delegate forwarding classes (FullScreenContentDelegate.swift pattern) (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Tracking/FullScreenContentDelegate.swift)
5. Add comprehensive test suite in Tests/RevenueCatFANTests matching AdMob test structure (AdapterSDKs/RevenueCatAdMob/Tests/RevenueCatAdMobTests)
6. Create example integration app under AdapterSDKs/RevenueCatFAN/Examples/ (AdapterSDKs/RevenueCatAdMob/Examples/AdMobIntegrationSample)

Add a new reward verification state transition or validation rule

1. Update the State machine enum in AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/State.swift (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/State.swift)
2. Implement new validation logic in RewardVerification.swift orchestrator (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/RewardVerification.swift)
3. Add Outcome.swift enum case for the new validation result type (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/RewardVerification/Outcome.swift)
4. Create or extend StateTests.swift with test cases covering the new transition (AdapterSDKs/RevenueCatAdMob/Tests/RevenueCatAdMobTests/StateTests.swift)
5. Update RewardVerificationStrings.swift with new logging messages (AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Logging/Strings/RewardVerificationStrings.swift)

Add support for a new iOS/tvOS/watchOS platform variant

1. Update .circleci/config.yml to add platform-specific build and test jobs (.circleci/config.yml)
2. Create a new test plan (e.g., BackendIntegrationTests-WatchOS.xctestplan) for platform-specific integration tests (BackendIntegrationTests/BackendIntegrationTests-All.xctestplan)
3. Update .swiftpm/xcode/xcshareddata/xcschemes/ with platform-specific build schemes (.swiftpm/xcode/xcshareddata/xcschemes/RevenueCatUI.xcscheme)
4. Add platform-specific test doubles or mocks in AdapterSDKs/RevenueCatAdMob/Tests/ (AdapterSDKs/RevenueCatAdMob/Tests/RevenueCatAdMobTests/PollerTestDoubles.swift)

Enhance SwiftLint rule coverage or add new code style rules

1. Review and modify .swiftlint.yml configuration file with new or adjusted rules (.swiftlint.yml)
2. Run linter against AdapterSDKs/RevenueCatAdMob/Sources to validate coverage (AdapterSDKs/RevenueCatAdMob/Sources)
3. Update CircleCI linting job in .circleci/config.yml to enforce new rules (.circleci/config.yml)
4. Document rule rationale in AGENTS.md for contributor guidance (AGENTS.md)

RevenueCat API Key Required: The SDK is useless without a valid API key from RevenueCat dashboard; network calls will fail or return 401s. StoreKit Entitlements: Must have proper entitlements configured in your Xcode project (com.apple.developer.storekit / In-App Purchase capability). Receipt Validation Dependency: All receipt validation happens server-side on RevenueCat's backend—offline receipt checking is not supported. Objective-C Interop: Legacy Objective-C support is maintained but newer features may be Swift-only; check migration guides when upgrading. Multiple StoreKit Versions: Code likely contains branching for StoreKit v1 vs v2; behavior differs between iOS 15.x and earlier.

• Server-Side Receipt Validation — RevenueCat's core value proposition—the SDK sends receipts to RevenueCat's backend instead of validating locally, preventing fraud and decoupling app logic from Apple's validation API changes
• StoreKit Integration Layer — The SDK abstracts StoreKit v1 and v2 differences behind a unified API, allowing the same app code to run on iOS 15- and iOS 15+
• Entitlements as Remote Configuration — RevenueCat decouples product definitions and feature gates from the app binary—products and entitlements can be updated server-side without redeploying the app
• Cross-Platform Purchase Synchronization — A single RevenueCat user account can own subscriptions across iOS, macOS, tvOS, watchOS—the SDK handles identity and sync so a purchase on iPhone unlocks the app on Apple Watch
• Subscription State Machine — Subscriptions have complex states (grace period, billing issue, cancelled, expired); RevenueCat tracks these server-side and exposes them as simple enums in the SDK to avoid app-side state bugs
• Webhook Events — RevenueCat pushes real-time purchase, renewal, and cancellation events to your backend via webhooks—critical for server-side business logic that can't rely on the app being open
• Objective-C/Swift Interop in Package Distribution — The SDK ships both Swift and Objective-C APIs from a single SPM package; understanding this hybrid approach matters for maintaining backward compatibility across major versions

• apple/swift-package-manager — Underlying package manager and distribution system for RevenueCat SDK
• realm/realm-swift — Alternative persistence layer for local caching; RevenueCat likely uses UserDefaults/Keychain but Realm is a common choice for SDK storage
• RevenueCat/purchases-android — Sister SDK for Android; same RevenueCat backend but Android-specific StoreKit equivalent (Google Play Billing)
• RevenueCat/purchases-unity — Cross-platform adapter wrapping RevenueCat for Unity game developers; part of RevenueCat ecosystem
• firebase/firebase-ios-sdk — Common companion integration for analytics; RevenueCat users often feed purchase events to Firebase for cohort analysis

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for RevenueCatAdMob RewardVerification module

The RevenueCatAdMob adapter has a complex RewardVerification system (Dispatcher.swift, Poller.swift, State.swift, VerifiedReward.swift) that lacks visible test coverage. This is critical for production ad reward integrity. A new contributor could add unit tests for state transitions, polling logic, and reward verification outcomes.

• [ ] Create Tests/RevenueCatAdMob/RewardVerification/ directory structure
• [ ] Add unit tests for Poller.swift covering poll timing and retry logic
• [ ] Add unit tests for State.swift covering state machine transitions
• [ ] Add unit tests for Dispatcher.swift covering async dispatch behavior
• [ ] Add integration tests for RewardVerification.swift end-to-end flow
• [ ] Ensure tests cover RewardVerificationResult.swift success/failure cases

Add GitHub Actions workflow for SwiftLint validation in CI/CD pipeline

The repo has .swiftlint.yml configuration file and actionlint.yml workflow, but no dedicated SwiftLint GitHub Action workflow visible in .github/workflows/. This would catch style violations before merge and maintain code consistency across the large codebase (iOS, watchOS, tvOS, macOS, visionOS).

• [ ] Create .github/workflows/swiftlint.yml workflow file
• [ ] Configure job to run SwiftLint against Sources/ directory
• [ ] Add separate lint checks for main RevenueCat framework and RevenueCatUI
• [ ] Configure SwiftLint to also check AdapterSDKs/RevenueCatAdMob/Sources/
• [ ] Set workflow to run on pull_request and push to main branch
• [ ] Add workflow status badge to README.md

Add missing unit tests for RevenueCatAdMob Tracking delegates (BannerViewDelegate, DelegateStores)

The Tracking subdirectory contains delegate wrappers (BannerViewDelegate.swift, DelegateStores.swift, AdLoader+Tracking.swift) that handle lifecycle events for ads. These are critical for proper tracking but lack visible test coverage. Tests would verify delegate forwarding and state management.

• [ ] Create Tests/RevenueCatAdMob/Tracking/ directory
• [ ] Add unit tests for BannerViewDelegate.swift covering delegate method forwarding
• [ ] Add unit tests for DelegateStores.swift covering storage and retrieval of delegate references
• [ ] Add tests for AdLoader+Tracking.swift verifying impression tracking calls
• [ ] Add tests for FullScreenAd+Tracking.swift covering show/dismiss lifecycle
• [ ] Verify tests mock RevenueCat SDK calls and validate tracking events are fired correctly

• Add comprehensive Swift documentation comments (///) to public APIs in the core Purchases framework that lack them—improves IDE autocomplete and generated docs.
• Expand the AdMob adapter example in AdapterSDKs/RevenueCatAdMob/Examples/ with a complete working demo app that shows purchase flow end-to-end, since currently only skeleton files exist.
• Create unit test stubs for missing coverage in the Objective-C bridge layer, particularly around legacy API compatibility, to ensure v3/v4 migration compatibility isn't accidentally broken.

The RevenueCat purchases-ios codebase shows generally good security practices with proper GitHub organization (CODEOWNERS, templates, workflows). However, there are moderate concerns around secrets management in CI/CD pipelines, dependency version pinning, and data handling in associated object storage. The absence of a security policy and potential verbose logging in production are minor issues. The library's focus on in-app purchases and subscriptions means any vulnerabilities could directly impact payment security. Recommendations include implementing stricter CI/CD secret management, pinning dependency versions, and establishing a formal vulnerability disclosure policy.

• Medium · Potential Secrets in CircleCI Configuration — .circleci/config.yml, .circleci/default_config.yml. CircleCI configuration files (.circleci/config.yml, .circleci/default_config.yml) may contain environment variables, API keys, or other sensitive credentials. These files should be carefully reviewed to ensure no secrets are hardcoded. Fix: Use CircleCI's secure environment variables feature instead of hardcoding secrets. Rotate any exposed credentials immediately. Implement pre-commit hooks to prevent secret commits.
• Medium · GitHub Actions Workflow Security — .github/workflows/rcgitbot_please_test.yml, .github/workflows/rerun_danger_on_label.yml. Multiple GitHub Actions workflows (.github/workflows/) could be vulnerable to privilege escalation if they run untrusted code or use overly permissive permissions. The rcgitbot_please_test.yml and rerun_danger_on_label.yml workflows are particularly sensitive. Fix: Apply principle of least privilege to workflow permissions. Use pinned action versions instead of @latest or @main. Review and validate any user-triggered workflows. Implement CODEOWNERS review requirements.
• Medium · Dependency Management Gaps — AdapterSDKs/RevenueCatAdMob/Package.swift, Root Package.swift (not provided). The codebase structure indicates a Swift package with multiple dependencies (AdapterSDKs, RevenueCatAdMob), but no Package.lock file or dependency version pinning information was provided. This could allow for supply chain attacks through dependency version manipulation. Fix: Ensure Package.resolved files are committed to version control. Use exact versions or narrow version ranges for critical dependencies. Regularly audit and update dependencies using tools like SwiftPM audit and GitHub Dependabot.
• Low · AssociatedObjectStore Implementation — AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/AssociatedObjectStore.swift. The AssociatedObjectStore.swift file uses associated objects which could potentially store sensitive data without proper protection. If used to cache credentials or personal information, this could expose data to memory dumps or debugging. Fix: Review what data is stored in AssociatedObjectStore. Implement proper data protection for sensitive information. Consider using Keychain for credential storage instead of memory caches.
• Low · Information Disclosure via Logging — AdapterSDKs/RevenueCatAdMob/Sources/RevenueCatAdMob/Logging/. Multiple logging files are present (RewardVerificationStrings.swift, Logging directory) which may output sensitive debug information. In production, verbose logging could expose transaction IDs, user identifiers, or reward verification details. Fix: Ensure logging is disabled or minimal in production builds. Implement log level configuration. Never log sensitive data like user IDs, payment information, or verification tokens.
• Low · No Security.md File — Repository root. There is no SECURITY.md file visible in the repository root. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with vulnerability disclosure guidelines, preferred contact methods, and responsible disclosure timeframe. Link it from README.md.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.