docs: mark upgradeBadgeSubscription's badgeRequest as to be dropped; trim store purchase comments

apps/simplex-badge-service/src/BadgeService/Catalog.hs

@@ -136,16 +136,14 @@ defaultCatalog seededAt = (prices, offers)
           createdAt = seededAt
         }
 
--- | What one unit of a store product grants.
 data StoreProduct = StoreProduct
   { badgeType :: BadgeType,
     months :: Int
   }
   deriving (Eq, Show)
 
--- | A receipt proves only which product was paid for, so the badge comes from here and never from
--- the client. Mirrors the one-time products of BadgeStore.swift and BadgeStore.kt, whose ids differ
--- by store; their subscriptions are refused, since nothing adds a renewal's months to a badge yet.
+-- | A receipt proves only the product paid for, so the badge comes from here, never from the client.
+-- Mirrors the one-time SKUs of BadgeStore.swift and .kt; subscriptions wait until renewals add months.
 storeProduct :: PaymentProvider -> Text -> Maybe StoreProduct
 storeProduct provider productId = case (provider, productId) of
   (PPApple, "BADGE_SUPPORTER_01") -> Just $ StoreProduct BTSupporter 1

apps/simplex-badge-service/src/BadgeService/Service.hs

@@ -464,8 +464,6 @@ storeRefusalResponse = \case
   SRPending -> pure $ errorResponse BSEPaymentPending
   SRUnreachable reason -> logWarn ("store unreachable: " <> reason) $> errorResponse BSEProviderUnavailable
 
--- | A funding already spent answers as the purchase it funded: that purchase again for its own key,
--- and usedCode for any other.
 claimedResponse :: DB.Connection -> BadgeServiceErrorCode -> C.PublicKeyEd25519 -> FundingClaim -> IO (Either BadgeServiceResponse ())
 claimedResponse db usedCode purchaseKey = \case
   Unclaimed -> pure $ Right ()
@@ -476,7 +474,6 @@ claimedResponse db usedCode purchaseKey = \case
         maybe (Left $ errorResponse BSEInternal) (Left . credentialResponse (Just credential) Nothing)
           <$> getLedgerEntries db badgePurchaseId 0
 
--- | The grant of a new purchase and the first month issued from it, signed; nothing is written.
 signFirstMonth :: BadgeIssuerKey -> ChatController -> BadgeMasterKey -> BadgeType -> Int -> StatementCreditType -> UTCTime -> IO (Either BadgeServiceResponse (StatementEntry, (StatementEntry, BadgeCredential)))
 signFirstMonth key cc masterKey badgeType months credit now = do
   (grantUuid, issueUuid) <- (,) <$> randomId cc <*> randomId cc
@@ -491,7 +488,6 @@ signFirstMonth key cc masterKey badgeType months credit now = do
         Left e -> logError ("badge service signing failed: " <> T.pack e) $> Left (errorResponse BSEInternal)
         Right signed -> pure $ Right (granted, signed)
 
--- | Writes what signFirstMonth signed onto the purchase just claimed for it.
 firstMonthResponse :: DB.Connection -> Int64 -> Maybe T.Text -> (StatementEntry, (StatementEntry, BadgeCredential)) -> IO BadgeServiceResponse
 firstMonthResponse db purchaseId creditPaymentId_ (granted, signed) = do
   appendLedgerPlan db purchaseId creditPaymentId_ [granted] $ Just $ issuanceAfter granted signed

apps/simplex-badge-service/src/BadgeService/Store.hs

@@ -66,7 +66,6 @@ data IssuedCode = IssuedCode
     redemption :: FundingClaim
   }
 
--- | Whether a code or a store payment has already funded a purchase, and which.
 data FundingClaim
   = Unclaimed
   | Claimed ClaimedPurchase
@@ -121,7 +120,6 @@ getBadgeCode db codeHash =
     toCode (badgeCodeId, badgeType, months, paymentStatus, revokedAt, expiresAt, purchaseId_, purchaseKey_, credential_) =
       IssuedCode {badgeCodeId, badgeType, months, paymentStatus, revokedAt, expiresAt, redemption = fundingClaim purchaseId_ purchaseKey_ credential_}
 
--- | The purchase a store transaction's payment funds, read the same way as a code's.
 getStorePaymentClaim :: DB.Connection -> PaymentProvider -> Text -> IO FundingClaim
 getStorePaymentClaim db provider providerRef =
   maybeFirstRow' Unclaimed (\(purchaseId, purchaseKey, credential_) -> fundingClaim (Just purchaseId) (Just purchaseKey) credential_) $
@@ -287,9 +285,8 @@ createCodePurchase db NewCodePurchase {badgeCodeId, purchaseKey, masterKey = Bad
         (purchaseKey, Binary mk, badgeType, badgeType, PSIssued, badgeCodeId, now, now)
       Just <$> insertedRowId db
 
--- | Must run in the same transaction as the credential rows. The payment is inserted before the
--- purchase, and its (provider, provider_ref) is unique: a transaction presented twice at once, or
--- under another key, inserts nothing the second time and fails.
+-- | In the transaction of the credential rows. The payment's unique (provider, provider_ref) is the
+-- claim: a transaction presented twice at once, or under another key, inserts nothing the second time.
 createStorePurchase :: DB.Connection -> NewStorePurchase -> UTCTime -> IO (Maybe Int64)
 createStorePurchase db NewStorePurchase {paymentId, provider, providerRef, paid, purchaseKey, masterKey = BadgeMasterKey mk, badgeType} now = do
   claimed <-