ppackage

TELEGRAM_USERAUTH_BACKEND.md

@@ -29,6 +29,12 @@ There are two supported flows.
 4. Backend sets `userauth_session` cookie and redirects back to the storefront.
 5. Frontend calls `GET /userauth/session` and becomes authenticated.
 
+Package note:
+
+- The published `telegram-userauth` package does not require this direct flow by default.
+- If the host app provides `telegram-login-url`, the package button can use this flow.
+- If `telegram-login-url` is omitted, the package button opens the `url` returned by `POST /userauth/qr/create`.
+
 ### 2. QR login from desktop
 
 1. Frontend opens dialog.
@@ -36,7 +42,7 @@ There are two supported flows.
 3. Backend returns `{ token, url }` where `url` is a Telegram deep link.
 4. Frontend renders a QR from that URL.
 5. User scans QR and bot calls `POST /userauth/qr/confirm`.
-6. Frontend polls `GET /userauth/qr/poll?token=...` every 3 seconds.
+6. Frontend polls `GET /userauth/qr/poll?token=...` every 5 seconds by default.
 7. When status becomes `confirmed`, backend returns session payload and sets the cookie.
 8. Frontend syncs local cart using `POST /usersession/{sessionId}`.
 
@@ -99,7 +105,12 @@ Requirements:
 
 ### `GET /userauth/qr/poll?token={token}`
 
-Called every 3 seconds until confirmation or expiration.
+Called every 5 seconds by default until confirmation or expiration.
+
+Package note:
+
+- The reusable package exposes `poll-interval-ms` and defaults it to `5000`.
+- Backend should not assume a stricter cadence than 5 seconds.
 
 Possible responses:
 
@@ -184,6 +195,8 @@ Frontend behavior depends on this endpoint in two places:
 - initial auth check on app startup
 - fallback polling if QR token creation fails
 
+This endpoint is also used by the package after successful direct-login redirects and during fallback retries.
+
 Response `200`:
 
 ```json
@@ -302,12 +315,30 @@ Do not use `*` for `Access-Control-Allow-Origin` together with credentials.
 
 ## Frontend Runtime Expectations
 
-The current dialog behavior is fixed and should be preserved by backend responses.
+The reusable package behavior should be preserved by backend responses.
 
-- QR polling interval: every 3 seconds
+- QR polling interval: every 5 seconds by default
 - QR expiration on frontend: after 100 checks
-- If QR creation fails, frontend falls back to direct login URL and session polling
-- After login, frontend closes the dialog and re-checks session
+- If QR creation fails, frontend falls back to session polling
+- Primary button opens `telegram-login-url` when the host app provides one
+- Otherwise, primary button opens the deep link returned by `POST /userauth/qr/create`
+- After login, frontend emits an authenticated event to the host app
+
+## Package Integration Notes
+
+The published package is a custom element named `telegram-userauth`.
+
+Expected host configuration:
+
+- `api-base-url` for separate backend origins, or empty for same-origin deployments
+- optional `telegram-login-url` for dedicated direct-button flows
+- optional `poll-interval-ms`, default `5000`
+
+Expected package events:
+
+- `userauth-authenticated` with `{ session }`
+- `userauth-statechange` with `{ state }`
+- `userauth-error` with `{ message }`
 
 ## Minimal Backend Checklist