ابنِ مع AI

# Building a Lia app

This is a web app that runs inside the Lia app (lialabs.org), like a Telegram mini app. Docs: https://docs.lialabs.org (every page as Markdown: add .md; everything: https://docs.lialabs.org/llms-full.txt).

## The SDK
- In a page without a build step: <script src="https://api.lialabs.org/sdk/lia-apps-v1.js"></script> gives window.Lia. Never copy or bundle that file.
- With a bundler: npm install @lia-labs/sdk (or @lia-labs/sdk-react, -preact, -vue, -svelte, -solid, -angular, @lia-labs/elements). Use one or the other on a page, never both.
- Call init() first, then ready() once the first screen is drawn. Outside Lia every call fails with code "not_in_lia"; for local development call mockLia() when isLia() is false.
- Every failure is an Error with a code. "cancelled" from pay() is a normal no, not an error to report.

## Trust
- Never trust the page. Your server verifies a session token (from init() or session(), 15 minutes) with POST https://api.lialabs.org/api/apps/v1/session/verify and takes the player id from Lia's answer, never from the page.
- Secret keys (lia_test_..., lia_live_...) and the webhook secret (whsec_...) live on the server only. The app id is the only public identifier.
- Prices come from Lia's records: the page passes a product id to pay(), never an amount.

## Payments
- pay(productId) opens Lia's pay sheet and answers { chargeId, productId }. The server then checks GET /charges/:id (its player, product and status), gives the item once per charge id, and calls POST /charges/:id/deliver. If it can't deliver, POST /charges/:id/refund.
- On opening, call charges() and deliver any paid, undelivered charges; listen with onCharge() too. Webhooks (charge.paid) are a nudge: check with the API, and verify the Lia-Signature header (HMAC SHA-256 of "<t>.<raw body>" with the whsec_ secret).

## Rewards, ads, notifications
- Pay players in $LIA only from the server: POST /rewards with a key that names the reason (a key pays once, ever). At most 10,000 LIA a reward; handle pool_empty and daily_limit.
- A rewarded video answers { watched, adId }: give the reward only after the server checks POST /ads/verify (watched, and the same player), once per adId.
- Between rounds and games, call Lia.showInterstitialAd() (Lia paces it: about one every 90 seconds and every 2nd round; "too_soon" means carry on). Rewarded videos only behind a button the player chooses (a hint, a second chance), never by themselves between rounds. Test keys always get Google's test ads.
- Banners and native ads (SDK 1.7): Lia.showBanner({ position: "bottom" | "top" }) and Lia.showNativeAd({ placement: "card" | "sheet" }). Lia draws them natively beside the page (the page gets shorter), never inside it: don't build an ad slot in your own HTML for them, just let the layout follow the viewport height. Show the card at pauses (a results screen) and hideNativeAd() when play resumes; both answer { shown: false, reason } when there's nothing to show, so carry on. For an ad inside the page's own content, use the developer's own AdSense or Google Ad Manager tags: Lia lets only Google's ad frames load and opens ad taps in Safari; that revenue is the developer's own, not counted by Lia. For games: pin Lia.showBanner({ position: "top" }) before Lia.ready() and keep it for the visit; put in-page ad rows only on calm screens (home, lobby), never over or under the board; don't use the native card or sheet over gameplay.
- Notifications are opt-in (requestNotifications()), sent by the server with POST /notifications, at most 3 a day per person from one app, an hour apart, 180 characters, no links. Use a startParam to open the right screen.

## Feel like Lia
- Use Lia's theme (CSS variables --lia-bg-color, --lia-text-color, --lia-hint-color...), the safe areas (--lia-safe-area-inset-bottom), Lia.language (13 languages) and Lia.rtl for dir.
- Use Lia's mainButton for the main action, backButton for your own screens, Lia's dialogs and toasts, and play sound only while soundOn.
- Only your own pages load in the frame: open other sites with openLink(url).

## Conventions
- In text people read: "$LIA" for the token, "LIA" next to numbers (5 LIA).
- Retry server POSTs with the same Idempotency-Key header.