d-sports-engage-native

​

Overview

d-sports-engage-native (package name: engage-native) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, profile, plus binder, market, quests, and a team-admin hub.

• App version: 1.25.9
• Run: infisical login once, then bun start — press a for Android or i for iOS.

​

Tech stack

​

Features

• Wallet — Custodial token balances, send/receive, PIN-gated server-side signing, pack opening
• Shop — Collectibles, cart, coin bundles, RevenueCat IAP + Thirdweb crypto checkout
• Digital binder — Card inventory viewer and transfer flows (app/binder)
• Market — Pack store and trading stay on separate screens (app/market/packs, app/market/trading)
• Leaderboard — Multi-board rankings powered by the quest/points system
• Locker room — Social feed, posts, comments with @handle mentions, likes, stars, sport-driven lineups, live/game surfaces
• Game Engine — Shared shell for Pick’em, Trivia, prize wheel, guess-the-player, daily lineup, card trivia, login-streak scratcher, six hockey playfields, air hockey, and locker-singularity (/(tabs)/locker-room/games/[gameKey])
• Quests — Team-aware quests, daily quiz sessions, arena check-in, Fan Rep
• Profile — Stats, achievements, featured collectibles, settings, account deletion
• Admin hub — Team-manager surfaces for packs, collectibles, coins, games, moderation, users (app/(admin))
• Theme — Dark/light mode (default dark), plus high-contrast and color-blindness palettes
• Push — OneSignal (not a second notification backend)

​

What changed since last docs sync

• App version is 1.25.9. iOS and Android runtimeVersion are both 1.25.9.
• Auth package is @clerk/expo 4.6.1 (Clerk Core 3 rename from @clerk/clerk-expo). The source README may still mention the old package name.
• HQ starred clubs sync through /api/me/starred-teams. A star is a bookmark, not a follow.
• The Game Engine registers air-hockey and locker-singularity alongside Pick’em, Trivia, prize-wheel-spin, guess-the-player, daily-lineup, card-trivia, login-streak-scratcher, and six hockey games. Locker Singularity uses the idle ledger, not session verbs. How-to-Play walkthroughs are local-only and must not spend a daily attempt.
• Deep links claim app.d-sports.org (iOS Universal Links plus Android App Links for locker-room, profile, market, quests, binder, leaderboard, rate). api.d-sports.org mobile callbacks are unchanged.
• About → Settings includes a manual EAS OTA update check.
• Locker room can attach sport-driven lineups. The API persists lineup on POST /api/locker-room and serves real rosters from GET /api/teams/{id}/roster.
• Native safety actions call /api/user/mutes and /api/user/blocks (distinct from Game Center thread mute).
• Secrets are injected with Infisical. bun start wraps Metro in infisical run --env=dev.
• Mobile OAuth can land a 128-char hex token in the URL fragment (#token=). Native stashes it in memory and redeems it at POST /api/mobile/exchange for a Clerk ticket, then signIn.create({ strategy: 'ticket' }).
• Custodial wallets no longer sign on-device. Sends call POST /api/wallets/{address}/sign-transaction after a PIN gate.
• New route groups: app/binder, app/market, app/quests, and a full app/(admin) ops hub.
• Android App Links now cover api.d-sports.org mobile callbacks.
• Official Android sideload APKs live in the public engage-android repo.

​

Backend integration surfaces

• Primary API source: d-sports-api under /api/* and /api/v1/engage/*.
• Native consumes team, league, quest, Fan Rep, reward, wallet, commerce, social, games, and mobile-auth endpoints.
• Retry/caching logic and auth token injection live in lib/api/*. API responses can fall back to MMKV cache.

​

Quest, Fan Rep, and pass UX

• Quest UI reflects team-scoped eligibility and pass-gated progression.
• Daily quests use the /api/v1/engage/quests/* session API (start, submit, forfeit).
• Fan Rep screens read /api/v1/engage/rep/breakdown and /api/v1/engage/rep/ledger.
• Reward presentation differentiates free/unpaid states and claimability.
• Native progression state must mirror backend eligibility and completion semantics.

​

Team-aware experiences

• Team discovery, favorite-team interactions, and leaderboard context are integrated across locker room and profile surfaces.
• Team and league metadata is sourced from backend sync pipelines fed by the leagues repository.
• The games tab joins GET /api/games/catalog with GET /api/v1/engage/games/catalog. Engine rows stay visible when the legacy catalog omits them. Unknown engine keys show Update required, they are not ignored. locker-singularity progress uses the idle ledger routes.

​

Compliance and legal: pack opening odds

• Native odds disclosure behavior is documented with policy-aligned copy and evidence requirements.
• Disclosure values must come from backend payloads and remain visible/accessible near open actions.

​

Getting started

1. Clone the repository and run bun install.
2. Run infisical login once.
3. Install or build an Expo dev client, then bun start.
4. For EAS profiles and store submission, see the repo docs/EAS-BUILDS.md.

The app targets native first and also builds for web. It talks to the deployed D-Sports API; you do not need a local backend for day-to-day client work.

​

Deep dives

• Architecture
• Feature mapping
• Integration contracts
• Game Engine
• Compliance and legal docs