@akinon/pz-masterpass-rest 2.0.16 → 2.0.17-rc.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @akinon/pz-masterpass-rest
 
+## 2.0.17-rc.0
+
+### Patch Changes
+
+- 823a4449: ZERO-4193: Upgrade TypeScript to version 5.2.2 across multiple packages
+- 5da13fff: ZERO-4358: fix masterpass-rest guest checkout flow
+- fb4aa9b4: ZERO-4333: update maxLength for cardNumber input and enhance button styling in installment list
+- d51fa68e: ZERO-4399: add card rewards to pz-masterpass-rest
+- 63a72000: ZERO-3895: enhance payment processing with additional fields support
+
 ## 2.0.16
 
 ## 2.0.15

package/docs/USAGE.md

@@ -15,6 +15,7 @@
   - [LinkModal](#5-linkmodal)
   - [OTPModal](#6-otpmodal)
   - [ConfirmationModal](#7-confirmationmodal)
+  - [RewardSelectionModal](#7b-rewardselectionmodal)
   - [ErrorDisplay](#8-errordisplay)
   - [LoadingState](#9-loadingstate)
   - [EmptyState](#10-emptystate)
@@ -76,6 +77,7 @@ export default MasterpassRest
 | `environment` | `'production' \| 'development'` | `undefined` | SDK environment |
 | `texts` | `MasterpassRestOptionTexts` | `defaultTexts` | UI text overrides for localization |
 | `customRender` | `MasterpassRestOptionCustomRender` | `undefined` | Custom render functions |
+| `enableRewards` | `boolean` | `false` | Opt in to the card rewards (FBB/BNS) feature. Requires backend support for `MasterpassRestRewardListPage` and `MasterpassRestRewardSelectionPage`. |
 
 ```tsx
 <PluginModule
@@ -90,6 +92,28 @@ export default MasterpassRest
 />
 ```
 
+### Enabling the Rewards feature
+
+The card rewards feature (FBB / BNS query + selection) is **disabled by default** to keep existing integrations unaffected. To opt in:
+
+```tsx
+<MasterpassRestOption
+  locale="tr"
+  currency="try"
+  enableRewards
+/>
+```
+
+When `enableRewards` is `true`:
+- After a saved card is selected, the package automatically calls `MasterpassRestRewardListPage` to fetch available rewards.
+- A "Use Rewards" CTA appears inline on the selected card (default `CardList`).
+- A modal is mounted at the bottom of the view for selection (`RewardSelectionModal`).
+- On confirm, the selection is sent to `MasterpassRestRewardSelectionPage`. The chosen rewards are then forwarded to Masterpass via `additional_fields.rewardList` server-side during `prepareMasterpassOrder` — no frontend wiring needed.
+
+Both backend pages must exist on your environment. If they don't, the package silently falls back (no rewards shown, no UI errors), but you'll see failed network requests in devtools.
+
+See [RewardSelectionModal](#7b-rewardselectionmodal) for custom render options including a no-modal inline pattern.
+
 ---
 
 ## Custom Rendering
@@ -107,6 +131,7 @@ type MasterpassRestOptionCustomRender = {
   linkModal?: (props: LinkModalProps) => ReactElement
   otpModal?: (props: OTPModalProps) => ReactElement
   confirmationModal?: (props: ConfirmationModalProps) => ReactElement
+  rewardSelectionModal?: (props: RewardSelectionModalProps) => ReactElement
   errorDisplay?: (props: ErrorDisplayProps) => ReactElement
   loadingState?: (props: LoadingStateProps) => ReactElement
   emptyState?: (props: EmptyStateProps) => ReactElement
@@ -171,35 +196,58 @@ Displays the user's saved cards with selection, CVC input, and remove functional
 
 ```typescript
 type CardListProps = {
-  cards: any[]                               // Array of CardModel objects
-  onCardSelect: (card: any) => void          // Called when a card is selected
-  selectedCard?: any | null                  // Currently selected card
-  onRemove?: (card: any) => void             // Called to initiate card removal
-  removingCardId?: string | null             // Card being removed (shows loader)
-  cvc?: string                               // Current CVC input value
-  onCvcChange?: (cvc: string) => void        // CVC input change handler
-  cvcRequired?: boolean                      // Whether CVC field is shown
+  cards: any[]
+  onCardSelect: (card: any) => void
+  selectedCard?: any | null
+  onRemove?: (card: any) => void
+  removingCardId?: string | null
+  cvc?: string
+  onCvcChange?: (cvc: string) => void
+  cvcRequired?: boolean
+
+  availableRewards?: RewardItem[]
+  selectedRewards?: RewardItem[]
+  isLoadingRewards?: boolean
+  isConfirmingRewards?: boolean
+  onOpenRewardModal?: () => void
+  onConfirmRewards?: (selected: RewardItem[]) => Promise<void> | void
+  rewardCurrency?: string
+  rewardPayableAmount?: string | number | null
+
   texts: MasterpassRestOptionTexts
 }
 ```
 
+`cards`, `onCardSelect`, `selectedCard`, `onRemove`, `removingCardId`, `cvc`, `onCvcChange`, `cvcRequired` are the standard card props. The reward props are only populated when `enableRewards` is set on `MasterpassRestOption`; when disabled they are `undefined` and existing card-list themes keep working unchanged.
+
+Reward prop behavior:
+- `availableRewards` — list returned by `MasterpassRestRewardListPage` for the currently selected card.
+- `selectedRewards` — what the user has confirmed so far (persisted in Redux).
+- `isLoadingRewards` — true while the list is being fetched.
+- `isConfirmingRewards` — true while the selection is being posted.
+- `onOpenRewardModal` — opens the default `RewardSelectionModal`.
+- `onConfirmRewards` — bypasses the modal entirely; posts a selection directly. The cumulative cap (special → general) is applied inside before the network call.
+- `rewardCurrency` — display-only ISO code, e.g. `'TRY'`.
+- `rewardPayableAmount` — the order's unpaid amount as a string. Pass this to `getCappedRewardTotal(selected, rewardPayableAmount)` if you render the redeemable total in your inline picker.
+
 **CardModel structure (each item in `cards` array):**
 
 ```typescript
 interface CardModel {
-  cardAlias: string               // 'My Visa Card'
-  maskedCardNumber: string        // '534261******1234'
-  uniqueCardNumber: string        // Unique identifier
+  cardAlias: string
+  maskedCardNumber: string
+  uniqueCardNumber: string
   cardType: 'Credit' | 'Debit' | 'Unknown' | ''
-  cardBin: string                 // First 6 digits
+  cardBin: string
   isDefaultCard: boolean
   expireSoon: boolean
   isExpired: boolean
   cardValidationType: 'OTP' | 'RTA' | '_3D' | 'Unknown' | ''
-  // ...more fields
 }
 ```
 
+`cardAlias` is the user-friendly name (e.g. `"My Visa Card"`); `cardBin` is the first 6 digits; `uniqueCardNumber` is the stable identifier. More fields are available — see `account.types.ts`.
+
 **Example:**
 
 ```tsx
@@ -234,7 +282,6 @@ customRender: {
             </button>
           </div>
 
-          {/* CVC input for selected card */}
           {selectedCard?.uniqueCardNumber === card.uniqueCardNumber && (
             <input
               type="text"
@@ -597,6 +644,105 @@ customRender: {
 
 ---
 
+### 7b. RewardSelectionModal
+
+Modal that lets the customer pick which card rewards (FBB / BNS) to apply. Only mounted when `enableRewards={true}` is passed to `MasterpassRestOption`. Requires backend support for `MasterpassRestRewardListPage` and `MasterpassRestRewardSelectionPage`.
+
+**Props:**
+
+```typescript
+type RewardSelectionModalProps = {
+  open: boolean
+  onClose: () => void
+  onConfirm: (selected: RewardItem[]) => Promise<void> | void
+  rewards: RewardItem[]
+  selectedRewards: RewardItem[]
+  isLoading?: boolean
+  currency?: string
+  payableAmount?: string | number | null
+  texts: MasterpassRestOptionTexts
+}
+
+type RewardItem = {
+  type: 'special' | 'general'
+  amount: number | string
+  name?: 'FBB' | 'BNS'
+}
+```
+
+`RewardItem.type` is the category — `'special'` maps to `FBB`, `'general'` maps to `BNS`. `amount` is what the backend currently returns (string like `"180.00"`); both `string` and `number` are accepted. `name` is the optional raw code.
+
+#### Cumulative cap behavior
+
+When `payableAmount` is provided, the modal shows the **actual amount that will be redeemed**, not the full reward value. The cap is cumulative across both categories with a fixed priority — `special` first, then `general`:
+
+```
+payable = 100.00
+special reward = 180.00  →  100.00 used   (capped, remaining = 0)
+general reward =  50.00  →    0.00 used   (no budget left)
+```
+
+When a reward is selected and capped, the modal:
+- Shows the full reward amount struck through.
+- Displays a green note below it using `texts.rewardCappedNoticeText` with `{amount}` replaced by the actual redeemed value.
+
+`confirmRewards` applies the same cap before sending the selection to `MasterpassRestRewardSelectionPage`, so the backend payload is always `special + general ≤ payable`.
+
+**Example — override with your own modal:**
+
+```tsx
+{
+  customRender: {
+    rewardSelectionModal: ({ open, onClose, onConfirm, rewards, ...props }) => (
+      <MyRewardModal
+        isOpen={open}
+        onDismiss={onClose}
+        onApply={onConfirm}
+        items={rewards}
+        {...props}
+      />
+    )
+  }
+}
+```
+
+**Example — render rewards inline (no modal at all) via CardList:**
+
+Brands that prefer an inline picker instead of a modal can use the new reward props on `CardListProps`:
+
+```tsx
+{
+  customRender: {
+    cardList: (props) => (
+      <MyCardList
+        cards={props.cards}
+        onCardSelect={props.onCardSelect}
+        selectedCard={props.selectedCard}
+        renderRewards={(card) =>
+          props.availableRewards?.length ? (
+            <InlineRewardPicker
+              rewards={props.availableRewards}
+              selected={props.selectedRewards ?? []}
+              loading={props.isLoadingRewards}
+              confirming={props.isConfirmingRewards}
+              payableAmount={props.rewardPayableAmount}
+              onConfirm={props.onConfirmRewards}
+            />
+          ) : null
+        }
+        {...props}
+      />
+    )
+  }
+}
+```
+
+`onConfirmRewards` bypasses the default modal entirely — your inline picker calls it directly with the user's selection, the package applies the cumulative cap and posts to `MasterpassRestRewardSelectionPage`. For showing the capped redeemable total in your inline picker, use `getCappedRewardTotal(selected, props.rewardPayableAmount)` from `'@akinon/pz-masterpass-rest'`.
+
+When you go this route, leave `customRender.rewardSelectionModal` unset — the default modal still won't show because your CardList handles selection via `onConfirmRewards` directly.
+
+---
+
 ### 8. ErrorDisplay
 
 Shown at the bottom of the payment area when an error occurs.
@@ -733,16 +879,21 @@ type MasterpassRestOptionRenderProps = {
   handleOTPSubmit: (otp: string) => Promise<{ success: boolean; message?: string }>
   onCloseError: () => void
 
-  // Loading States
   isCheckoutLoading: boolean
   isInstallmentLoading: boolean
   isPrepareLoading: boolean
   isFinalizeLoading: boolean
+  isProcessingPayment: boolean
+  isRewardsQueryLoading: boolean
+  isRewardsSelectLoading: boolean
+
+  openRewardModal: () => void
+  closeRewardModal: () => void
+  handleConfirmRewards: (selected: RewardItem[]) => Promise<void>
+  payableAmount: string | null
 
-  // Texts
   texts: MasterpassRestOptionTexts
 
-  // Default Components (use these to avoid reimplementing everything)
   components: {
     PaymentMethodSelector: React.ComponentType<PaymentMethodSelectorProps>
     CardList: React.ComponentType<CardListProps>
@@ -751,10 +902,75 @@ type MasterpassRestOptionRenderProps = {
     LinkModal: React.ComponentType<LinkModalProps>
     OTPModal: React.ComponentType<OTPModalProps>
     ConfirmationModal: React.ComponentType<ConfirmationModalProps>
+    RewardSelectionModal: React.ComponentType<RewardSelectionModalProps>
   }
 }
 ```
 
+`isProcessingPayment` is the orchestration-level flag that stays `true` for the entire payment flow (refresh → prepare → Masterpass SDK → finalize). If your `fullRender` exposes a "Proceed to Payment" button, OR it together with `isPrepareLoading` and `isFinalizeLoading` and pass that to your `InstallmentList.paymentLoading` — otherwise the button briefly re-enables between the prepare and finalize steps and double-clicks slip through.
+
+#### Opting in to rewards from `fullRender`
+
+If your `fullRender` replaces the package's default view, it also bypasses the default `RewardSelectionModal` mount and the inline reward CTA on the default `CardList`. To enable rewards in a `fullRender` integration:
+
+1. Pass `enableRewards={true}` on `MasterpassRestOption` so the package auto-fetches rewards on card selection and exposes the modal helpers via render props.
+2. Mount `components.RewardSelectionModal` alongside your other modals, wired to `modalState.showRewardModal`, `closeRewardModal`, `handleConfirmRewards`, `paymentState.availableRewards`, `paymentState.selectedRewards`, `isRewardsSelectLoading`, and `payableAmount`.
+3. In whichever component renders the saved-card list, expose an "Use Rewards" trigger that calls `openRewardModal` once `paymentState.availableRewards.length > 0`. If you use `components.CardList`, pass the reward props through (`availableRewards`, `selectedRewards`, `isLoadingRewards`, `onOpenRewardModal`, `rewardCurrency`, `rewardPayableAmount`) and it will render the inline CTA for you.
+
+Minimal sketch:
+
+```tsx
+<MasterpassRestOption
+  enableRewards
+  customRender={{
+    fullRender: (props) => {
+      const {
+        paymentState,
+        modalState,
+        components: { CardList, RewardSelectionModal },
+        openRewardModal,
+        closeRewardModal,
+        handleConfirmRewards,
+        isRewardsQueryLoading,
+        isRewardsSelectLoading,
+        payableAmount,
+        texts
+      } = props
+
+      return (
+        <>
+          <CardList
+            {...cardListProps}
+            availableRewards={paymentState.availableRewards}
+            selectedRewards={paymentState.selectedRewards}
+            isLoadingRewards={paymentState.isLoadingRewards || isRewardsQueryLoading}
+            isConfirmingRewards={isRewardsSelectLoading}
+            onOpenRewardModal={openRewardModal}
+            rewardCurrency="TRY"
+            rewardPayableAmount={payableAmount}
+            texts={texts}
+          />
+
+          <RewardSelectionModal
+            open={modalState.showRewardModal}
+            onClose={closeRewardModal}
+            onConfirm={handleConfirmRewards}
+            rewards={paymentState.availableRewards}
+            selectedRewards={paymentState.selectedRewards}
+            isLoading={isRewardsSelectLoading}
+            currency="TRY"
+            payableAmount={payableAmount}
+            texts={texts}
+          />
+        </>
+      )
+    }
+  }}
+/>
+```
+
+Without `enableRewards`, the package does not call `MasterpassRestRewardListPage`, no reward state is populated, and the helpers stay no-ops — existing `fullRender` brands keep behaving identically until they explicitly opt in.
+
 **Example - Custom layout with default components:**
 
 ```tsx
@@ -784,6 +1000,7 @@ customRender: {
       isInstallmentLoading,
       isPrepareLoading,
       isFinalizeLoading,
+      isProcessingPayment,
       texts,
       components
     } = props
@@ -840,14 +1057,13 @@ customRender: {
                 selectedInstallment={paymentState.selectedInstallment}
                 isLoading={isInstallmentLoading || isPrepareLoading}
                 onProceedToPayment={handleProceedToPayment}
-                paymentLoading={isFinalizeLoading}
+                paymentLoading={isProcessingPayment || isPrepareLoading || isFinalizeLoading}
                 texts={texts}
               />
             )}
           </div>
         </div>
 
-        {/* Modals - use default components */}
         <LinkModal
           open={modalState?.showLinkModal ?? false}
           onClose={() => updateModalState({ showLinkModal: false })}
@@ -880,14 +1096,12 @@ All user-facing strings can be overridden via the `texts` prop. Pass only the ke
     locale: 'tr',
     currency: 'try',
     texts: {
-      // Titles
       title: 'Masterpass ile Ode',
       selectCardTitle: 'Kart Secin',
       newCardTitle: 'Yeni Kart ile Ode',
       installmentOptionsTitle: 'Taksit Secenekleri',
       enterCardDetailsTitle: 'Kart Bilgilerini Girin',
 
-      // Form labels
       cardNumberLabel: 'Kart Numarasi',
       cardholderNameLabel: 'Kart Uzerindeki Isim',
       expiryDateLabel: 'Son Kullanma Tarihi',
@@ -895,43 +1109,50 @@ All user-facing strings can be overridden via the `texts` prop. Pass only the ke
       saveCardLabel: 'Bu karti gelecek odemeler icin kaydet',
       addCardButton: 'Kart Ekle',
 
-      // Payment method
       savedCardsText: 'Kayitli Kartlar',
       newCardText: 'Yeni Kart',
 
-      // Installments
       singlePaymentText: 'Tek Cekim',
-      installmentsText: '{count} Taksit',    // {count} is replaced dynamically
+      installmentsText: '{count} Taksit',
       noInterestText: 'Faizsiz',
       proceedToPaymentText: 'Odemeye Devam Et',
       processingPaymentText: 'Odeme Isleniyor...',
 
-      // Card list
       defaultCardText: 'Varsayilan',
       expiresSoonText: 'Suresi Yakinda Dolacak',
 
-      // Modals
       linkModalDescription: '<PHONE_NUMBER> numarasi ile Masterpass hesabinizdaki kartlari gormek ister misiniz?',
       linkAccountButton: 'Evet, istiyorum',
       linkModalCancelButton: 'Hayir, istemiyorum',
       removeCardMessage: '<{cardAlias}> kartini Masterpass altyapisindan silmek istediginize emin misiniz?',
 
-      // Verification
+      rewardOpenButtonText: 'Puanlari Kullan',
+      rewardModalTitle: 'Kart Puanlarini Kullan',
+      rewardModalDescription: 'Bu siparise uygulamak istediginiz puanlari secin.',
+      rewardModalEmptyMessage: 'Bu kart icin uygun puan yok.',
+      rewardModalConfirmText: 'Uygula',
+      rewardModalCancelText: 'Vazgec',
+      rewardModalLoadingText: 'Uygulaniyor...',
+      rewardSelectedSummaryText: '{count} puan uygulandi',
+      rewardAvailableSummaryText: '{count} puan mevcut',
+      rewardCategorySpecialText: 'Ozel Puanlar',
+      rewardCategoryGeneralText: 'Genel Puanlar',
+      rewardCappedNoticeText: '{amount} kullanilacak',
+      rewardFailedToLoadText: 'Puanlar yuklenemedi',
+      rewardFailedToSelectText: 'Puanlar uygulanamadi',
+
       rtaVerificationTitle: 'Guvenlik Dogrulamasi',
       bankOtpVerificationTitle: 'Banka Dogrulamasi',
       cvvVerificationTitle: 'CVV Dogrulamasi',
       verifyButton: 'Dogrula',
 
-      // Errors
       paymentErrorTitle: 'Odeme Hatasi',
       cardNumberRequiredText: 'Kart numarasi zorunludur',
       cardNumberInvalidText: 'Gecerli bir kart numarasi girin',
 
-      // Loading
       loadingMessage: 'Odeme sistemi hazirlaniyor...',
       scriptLoadingMessage: 'Odeme altyapisi yukleniyor...',
 
-      // Session
       sessionExpiredTitle: 'Oturum Suresi Doldu',
       sessionExpiredMessage: 'Oturumunuz zaman asimina ugradi. Devam etmek icin islemi yeniden baslatin.',
       sessionExpiredButton: 'Yeniden Basla'
@@ -951,6 +1172,9 @@ Some text keys support placeholders:
 | `removeCardMessage` | `{cardAlias}` | Name of the card being removed |
 | `cvcHelpText` | `{length}`, `{side}` | CVC digit count and card side |
 | `linkModalDescription` | `<PHONE_NUMBER>` | User's phone number (auto-replaced by SDK) |
+| `rewardSelectedSummaryText` | `{count}` | Number of selected rewards |
+| `rewardAvailableSummaryText` | `{count}` | Number of available rewards for the selected card |
+| `rewardCappedNoticeText` | `{amount}` | Capped redeemable amount (e.g. `"100.00 TRY"`) |
 
 ---
 
@@ -1012,53 +1236,101 @@ const {
 
 ### `useMasterpassPayment`
 
-Handles the payment processing flow.
+Handles the payment processing flow, including the rewards opt-in.
 
 ```typescript
 import { useMasterpassPayment } from '@akinon/pz-masterpass-rest'
 
 const {
-  paymentState,          // selectedCard, selectedInstallment, installments, etc.
+  paymentState,
   isCheckoutLoading,
   isInstallmentLoading,
   isPrepareLoading,
   isFinalizeLoading,
-  handleCardSelect,      // Select a saved card (triggers BIN check)
+  isRewardsQueryLoading,
+  isRewardsSelectLoading,
+  payableAmount,
+  handleCardSelect,
   handleInstallmentSelect,
-  processPayment,        // Stored card payment
-  processDirectPayment   // New card payment
-} = useMasterpassPayment()
+  processPayment,
+  processDirectPayment,
+  fetchRewardsForCard,
+  openRewardModal,
+  closeRewardModal,
+  confirmRewards
+} = useMasterpassPayment({ enableRewards: true })
 ```
 
+`paymentState` carries the live selection state (`selectedCard`, `selectedInstallment`, `installments`, plus `availableRewards`, `selectedRewards`, `isLoadingRewards` when rewards are enabled).
+
+`useMasterpassPayment` accepts a single options arg `{ enableRewards?: boolean }` — default `false`. When `false`, `handleCardSelect` skips the reward fetch, and the reward state stays empty. Pass `true` only when you are also using `<MasterpassRestOption enableRewards />` (or rendering the rewards UI yourself); otherwise the package never hits `MasterpassRestRewardListPage`.
+
+`payableAmount` is read from `state.checkout.preOrder.unpaid_amount` (falling back to `total_amount_with_interest`). Pass it to `getCappedRewardTotal` / `getCappedRewardAmounts` if you are building a custom rewards UI.
+
+`confirmRewards(selected)` applies the cumulative cap (`special` first, then `general`) and posts to `MasterpassRestRewardSelectionPage`. It returns `{ success: true }` on success or `{ success: false, message }` on failure.
+
 ---
 
 ## Exported Utilities
 
 ```typescript
 import {
-  // Card utilities
-  formatCardNumber,    // '5342610000001234' -> '5342 6100 0000 1234'
-  formatExpiryDate,    // '1227' -> '12/27'
-  formatCVV,           // Strips non-digits, max 4 chars
-  detectCardType,      // Returns 'visa' | 'mastercard' | 'amex' | 'troy' | 'discover' | 'unknown'
-  getCvcLength,        // Returns 3 (or 4 for Amex)
-  maskCardNumber,      // '5342610000001234' -> '****1234'
-  validateCardNumber,  // Luhn algorithm validation
-  getCardBIN,          // Returns first 6 digits
-  getCardIcon,         // Returns logo image object by BIN
-
-  // Payment utilities
-  isTokenExpired,             // Check JWT token expiration
-  getTransactionType,         // Returns 'PURCHASE' or 'PURCHASE_3D'
-  formatAmountForPayment,     // '1500.00' -> '150000'
-  createPaymentRequest,       // Builds stored card payment request
-  createDirectPaymentRequest, // Builds new card payment request
-
-  // Validation
-  createCreditCardFormSchema  // Returns Yup validation schema
+  formatCardNumber,
+  formatExpiryDate,
+  formatCVV,
+  detectCardType,
+  getCvcLength,
+  maskCardNumber,
+  validateCardNumber,
+  getCardBIN,
+  getCardIcon,
+
+  isTokenExpired,
+  getTransactionType,
+  formatAmountForPayment,
+  createPaymentRequest,
+  createDirectPaymentRequest,
+
+  parseRewardAmount,
+  getCappedRewardAmounts,
+  getCappedRewardTotal,
+  REWARD_PRIORITY,
+
+  createCreditCardFormSchema
 } from '@akinon/pz-masterpass-rest'
 ```
 
+**Card utilities** — `formatCardNumber` (`'5342610000001234'` → `'5342 6100 0000 1234'`), `formatExpiryDate` (`'1227'` → `'12/27'`), `formatCVV` (strips non-digits, max 4 chars), `detectCardType` (returns `'visa' | 'mastercard' | 'amex' | 'troy' | 'discover' | 'unknown'`), `getCvcLength` (returns `3`, or `4` for Amex), `maskCardNumber` (`'5342610000001234'` → `'****1234'`), `validateCardNumber` (Luhn), `getCardBIN` (first 6 digits), `getCardIcon` (logo image object by BIN).
+
+**Payment utilities** — `isTokenExpired` checks the JWT expiry, `getTransactionType` returns `'PURCHASE'` / `'PURCHASE_3D'`, `formatAmountForPayment` (`'1500.00'` → `'150000'`), `createPaymentRequest` / `createDirectPaymentRequest` build the SDK request body.
+
+**Reward utilities** — used internally and exported for custom UIs:
+
+```typescript
+parseRewardAmount(amount: number | string): number
+
+getCappedRewardAmounts(
+  selected: RewardItem[],
+  payableAmount?: string | number | null
+): Record<'special' | 'general', number>
+
+getCappedRewardTotal(
+  selected: RewardItem[],
+  payableAmount?: string | number | null
+): number
+
+REWARD_PRIORITY: ['special', 'general']
+```
+
+- `parseRewardAmount` safely parses backend string amounts (e.g. `"180.00"`) to a number; returns `0` for invalid input.
+- `getCappedRewardAmounts` applies the cumulative cap (`special` first, then `general`) and returns the actual amounts that will be redeemed per category.
+- `getCappedRewardTotal` is the sum of the capped amounts — use this when rendering a "X TRY will be applied" total.
+- `REWARD_PRIORITY` is the fixed order in which the cap is applied. Exported so custom UIs can iterate in the same order.
+
+`payableAmount` is the order's unpaid amount. If `null` / `undefined` / unparseable, no cap is applied (returns the full reward amounts) — this matches the behavior in the package and is safe as a fallback.
+
+**Validation** — `createCreditCardFormSchema` returns the Yup schema used by the default `CreditCardForm`.
+
 ---
 
 ## Type Definitions
@@ -1067,7 +1339,6 @@ All types are exported and can be imported for use in custom components:
 
 ```typescript
 import type {
-  // Component props
   PaymentMethodSelectorProps,
   CardListProps,
   CreditCardFormProps,
@@ -1075,6 +1346,7 @@ import type {
   LinkModalProps,
   OTPModalProps,
   ConfirmationModalProps,
+  RewardSelectionModalProps,
   ErrorDisplayProps,
   LoadingStateProps,
   EmptyStateProps,
@@ -1082,7 +1354,6 @@ import type {
   MasterpassRestOptionCustomRender,
   MasterpassRestOptionTexts,
 
-  // Data types
   CardModel,
   CardType,
   Installment,
@@ -1092,21 +1363,21 @@ import type {
   OTPType,
   TransactionType,
   InformationModalData,
+  RewardItem,
+  RewardName,
+  RewardCategory,
 
-  // Account types
   AccountAccessRequest,
   AccountAccessResponse,
   AccountAccessSuccessResponse,
   AccountAccessErrorResponse,
   CardResponse,
 
-  // Payment types
   PaymentProcessRequest,
   DirectPaymentRequest,
   DirectPaymentResponse,
   MPResponse,
 
-  // Environment
   MasterpassEnvironment
 } from '@akinon/pz-masterpass-rest'
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/pz-masterpass-rest",
-  "version": "2.0.16",
+  "version": "2.0.17-rc.0",
   "main": "src/index.ts",
   "types": "src/index.d.ts",
   "description": "Modern React-based Masterpass REST API integration package for ProjectZero e-commerce platform",
@@ -31,6 +31,6 @@
   "devDependencies": {
     "@types/react": "18.2.27",
     "@types/react-dom": "18.2.12",
-    "typescript": "5.2.2"
+    "typescript": "^5.2.2"
   }
 }