[Ramiz69]

What

hasEntitlement(for:) says whether the customer may use a product. currentEntitlement(for:) returns the
transaction behind that answer, with its dates, so an app can work out things like when a trial ends without
importing StoreKit:

if let trial = await purchases.currentEntitlement(for: "app.trial") {
    let trialEnds = trial.purchaseDate.addingTimeInterval(14 * 86_400)
}

The case that prompted it: App Review requires the free trial of a one-time purchase to be a free
non-consumable (guideline 3.1.1), and the app has to compute the trial's end from when it was "bought". That
date comes from the App Store, so it survives a reinstall and is the same on every device in a Family Sharing
group.

Behaviour

• It reads Transaction.currentEntitlements(for:), the same source as hasEntitlement(for:), so it returns a
  transaction exactly when that returns true. It updates the cached flag and the purchasedProducts event
  the same way; the shared code moved into syncCachedFlag.

• When several transactions qualify, the rule is fixed and documented:

  • revoked transactions are skipped;
  • the customer's own purchase wins over a family-shared grant;
  • then the earliest purchaseDate wins, then the lowest id.

  The answer therefore does not depend on StoreKit's order and does not change when a second grant appears
  later.

• The new requirement has a default implementation that returns nil, so 4.0 conformers (including the mocks
  apps keep for tests and previews) still compile. That makes this a minor release, 4.1.0.

• README asks for 4.1.0. GettingStarted, MigratingTo4 and the symbol pages cover the new method and say when a
  mock should implement it.

Tests

CurrentEntitlementTests checks the selection rule using transactions built by hand:

• no entitlement gives nil;
• a purchased non-consumable is returned with its purchase date;
• a revoked transaction gives nil;
• an own purchase beats an older family-shared one;
• the earliest purchase wins whatever the input order, and a tie is broken by id;
• a 4.0 conformer gets the nil default;
• a stand-in's own implementation is called through any PurchasesProtocol.

The Transaction.currentEntitlements(for:) call itself is not tested, like every other live StoreKit path in
the kit, because it needs a host app.

Verified locally (Xcode 27.2 / Swift 6.4.2)

• swift test: 106 tests in 12 suites pass, with 0 warnings.
• xcodebuild build succeeds for iOS, Mac Catalyst, watchOS, tvOS and visionOS with 0 warnings, and the tests
  build for visionOS.
• Builds with all six upcoming Swift 7 features and -warnings-as-errors.
• DocC from a fresh derived-data path: 0 warnings.
• Examples/PaywallDemo builds unchanged.