Returns the account's effective premium entitlement. Resolution order: the entitlement cached from RevenueCat (re-read from RevenueCat when older than the configured TTL, when it has lapsed, or when `refresh=1` is sent), then the legacy App Store record, then the user's Stripe subscription (active, trialing, or cancelled but still inside its paid period). RevenueCat or Stripe being unreachable never fails the request; the cached value is used. The subscription object is the unified premium entitlement, the same whichever store it was bought in. `isActive` is true when access is currently granted; admins receive active access automatically even without a paid subscription. `status` is one of `none`, `active`, `trial`, `cancelled` (will not renew but still active until `expiresAt`), `billing_issue`, `expired`, `refunded`. `store` is `app_store`, `play_store`, `stripe`, `promotional` or null. `source` says where the answer came from: `revenuecat` (synced from RevenueCat), `legacy_mobile` (App Store record validated through `POST /iap/ios/validate` before RevenueCat), `legacy_stripe` (looked up directly in Stripe), or `admin` (role-based access without a paid entitlement). `appUserId` is the RevenueCat App User ID for this account (the user id) and `entitlementId` the entitlement the mobile SDK should check. `managementUrl` is the store's subscription management page when known.

Called by the mobile app right after a purchase, restore or sign-in so the backend (and therefore the website and OCR credits) reflects the new state immediately instead of when RevenueCat's webhook arrives. Reads the subscriber from RevenueCat, stores the normalised entitlement on the user, opens or closes the OCR usage record for store-backed subscriptions, and returns the effective entitlement in the same shape as `GET /iap/subscription`. Idempotent; safe to call repeatedly. When RevenueCat is not configured on the server the current entitlement is returned with `synced: false` and nothing is changed. The subscription object is the unified premium entitlement, the same whichever store it was bought in. `isActive` is true when access is currently granted; admins receive active access automatically even without a paid subscription. `status` is one of `none`, `active`, `trial`, `cancelled` (will not renew but still active until `expiresAt`), `billing_issue`, `expired`, `refunded`. `store` is `app_store`, `play_store`, `stripe`, `promotional` or null. `source` says where the answer came from: `revenuecat` (synced from RevenueCat), `legacy_mobile` (App Store record validated through `POST /iap/ios/validate` before RevenueCat), `legacy_stripe` (looked up directly in Stripe), or `admin` (role-based access without a paid entitlement). `appUserId` is the RevenueCat App User ID for this account (the user id) and `entitlementId` the entitlement the mobile SDK should check. `managementUrl` is the store's subscription management page when known.

Returns the one-time OCR page packs sold as consumable in-app purchases in the mobile app (App Store / Google Play, tracked through RevenueCat). Each entry gives the store product id to fetch, the pages it grants and the list price in USD; the store's localized price should be shown to the user. Purchased pages are added to the account's balance (never expire) and are spent on uploads only after the plan's monthly credits are used up. Public.

Pre-RevenueCat flow, kept for older app builds. Validates proof of an App Store subscription purchase with Apple and saves the result as the account's legacy App Store record. At least one of `transactionReceipt`, `transactionId` or `originalTransactionId` must be sent. When the server is configured for the App Store Server API and a transaction id is supplied, the transaction and its subscription status are fetched from Apple (Production first, then Sandbox); otherwise the `transactionReceipt` is verified through Apple's receipt verification endpoint. The purchase must belong to the Sharh app bundle and to a recognised subscription product (by default `sharh.monthly.subscription` or `sharh.yearly.subscription`). The latest transaction for a recognised product determines the result. An App Store subscription can be linked to only one Sharh account: if another user already holds the same `originalTransactionId`, the request fails with 409. On success the response is the account's effective entitlement in the same shape as `GET /iap/subscription` (a RevenueCat-synced entitlement, when present, takes precedence over the record just validated). A validation that finds an inactive or expired subscription still returns 200 with `isActive: false`. The subscription object is the unified premium entitlement, the same whichever store it was bought in. `isActive` is true when access is currently granted; admins receive active access automatically even without a paid subscription. `status` is one of `none`, `active`, `trial`, `cancelled` (will not renew but still active until `expiresAt`), `billing_issue`, `expired`, `refunded`. `store` is `app_store`, `play_store`, `stripe`, `promotional` or null. `source` says where the answer came from: `revenuecat` (synced from RevenueCat), `legacy_mobile` (App Store record validated through `POST /iap/ios/validate` before RevenueCat), `legacy_stripe` (looked up directly in Stripe), or `admin` (role-based access without a paid entitlement). `appUserId` is the RevenueCat App User ID for this account (the user id) and `entitlementId` the entitlement the mobile SDK should check. `managementUrl` is the store's subscription management page when known.