# 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.
- 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.