Perks Feature

Perk browsing, search, categories, redemption, and code-based perks.

Location

Feature module: src/features/perks/
Routes: src/app/(tabs)/promotions/(tabs)/perks.tsx, src/app/(tabs)/promotions/(perks)/, src/app/perk-info/[id].tsx

API Functions

Defined in src/features/perks/api/index.ts:

Function	Method	Endpoint	Description
`getScreens(screen, city?)`	GET	`screens/{screen}`	Server-driven UI screen data
`getPerkList(category, limit, page, city, logic?)`	GET	`perks`	Paginated perk listing
`searchPerks(query, city?)`	GET	`perks/search`	Search perks
`getViewedPerks(sortBy?)`	GET	`perks/viewed`	User’s viewed perks
`getSearchHistory()`	GET	`perks/search/history`	Search history
`saveSearchHistory(query)`	POST	`perks/search/history`	Save search term
`redeemPerk(perkId)`	POST	`perks/{id}/redeem`	Redeem a perk (returns code)
`savePerkViewed(perkId)`	POST	`perks/{id}/viewed`	Mark perk as viewed
`redeemCodePerk(code)`	POST	`perks/redeem/{code}`	Redeem a code-based perk

All use apiV2.

Server-Driven UI

The perks screen uses the server-driven UI engine (src/features/screens/). The API returns a screen configuration via getScreens('perks'), and the rendering engine displays widgets defined in the response. This allows the backend to control the perks home layout without app updates.

Components

Perk Cards (`components/perk-cards/`)

Component	Description
`PerkCard`	Standard perk card
`PerkFeaturedCard`	Featured/highlighted perk
`PerkHeroCard`	Hero-sized perk card
`PerkMiniCard`	Compact perk card
`PerkSpotlightCard`	Spotlight perk
`PerkSpotlightMiniCard`	Mini spotlight perk

All cards have Storybook stories for visual testing.

Perk Info (`components/perk-info/`)

Component	Description
`PerkInfoContent`	Perk detail content
`PerkInfoHeader`	Perk detail header
`PerkInfoImageContent`	Image content section
`PerkRedemptionContent`	Redemption instructions
`PerkExpiry`	Expiry date display
`PerkRibbon`	Promotional ribbon
`OtherPerks`	Related perks section

Perk Redeem (`components/perk-redeem/`)

Component	Description
`PerkRedeemSuccess`	Redemption success state

Search (`components/search/`)

Component	Description
`PerkSearch`	Search interface
`PerkSearchResults`	Results display
`PerkResultCard`	Search result card
`RecentPerkSearches`	Recent searches list
`PerkHistoryTerm`	Single history item
`EmptySearchResults`	No results state
`SearchTitle`	Search section title

Widgets (`components/widgets/`)

Component	Description
`PerkHero`	Hero section widget
`PerkSpotlight`	Spotlight section
`PerkSpotlightMini`	Mini spotlight
`PerkStack`	Stacked cards widget
`PerkCluster`	Clustered cards widget

Other Components

Component	Description
`Perks`	Main perks screen
`ScreenRenderer`	Renders server-driven UI screens
`PerkList`	Perk list by category
`PerksHeader`	Perks section header
`PerkLabel`	Category/type label
`PerkCode`	Redemption code display
`PerkCardButton`	Card action button
`QrCode`	QR code display for redemption
`Tabs`	Category tabs
`TabButton`	Individual tab button
`PlusButton`	Add/redeem code button
`EmptyPerks`	No perks state

Placeholders

Comprehensive loading skeletons for every card/widget variant in components/placeholders/.

Routes

Route	Description
`(tabs)/promotions/(tabs)/perks.tsx`	Perks home (server-driven)
`(tabs)/promotions/(perks)/perk-search.tsx`	Perk search screen
`(tabs)/promotions/(perks)/perk-redeem.tsx`	Perk redemption screen
`perk-info/[id].tsx`	Perk detail page (outside tabs)

Utilities

utils/constants.ts — Perk category constants
utils/colors.ts — Perk-specific color utilities
utils/helpers.ts — General perk helpers