@learnorama/mozaik-sdk 0.14.1-staging.51.1 → 0.15.0-staging.53.1

package/CUSTOMER-ADMIN.md

@@ -0,0 +1,101 @@
+# Customer administrator integration
+
+Use the release containing the `admin-customer` SDK module. Customer permissions
+are separate from Mozaik staff permissions. No customer gets the internal desk
+DTOs or unrestricted tenant selectors.
+
+## Sign in
+
+Use `createMozaikAuth` from `@learnorama/mozaik-sdk/auth`, with the normal
+`prepareSso` / `completeSso` PKCE flow and a callback at `/auth/callback`.
+The initial integration shares the `mozaik-web` public Keycloak client. The
+operator must allow the exact frontend origin in API redirects, Keycloak and
+CORS: local port 5175, `https://admin.stg.mozaik.co` for staging, and the production
+origin in production only. Configure `CUSTOMER_ADMIN_ORIGIN` consistently.
+
+Passwords and password setup stay in Keycloak. This change does not implement
+the mockup's separate six-digit email MFA or trusted device for 30 days. The
+realm password policy applies to all newly set/changed passwords, not just
+customer administrators; existing passwords are not reset.
+
+An invitation email may first complete Keycloak required actions. A callback
+with `kc_action_status=success` **and no OAuth authorization code** is not a
+session: start the normal PKCE login. Do not pass that status as a login code.
+After an authenticated verified callback from the configured admin origin, the
+backend accepts the matching pending invitation. The explicit
+`acceptCustomerAdminInvitation()` operation also supports accepting after login.
+
+## Read the organization and capabilities
+
+```ts
+import {
+  readCustomerOrganization, readCustomerDashboard,
+  listCustomerBeneficiaries, listCustomerAdministrators,
+} from '@learnorama/mozaik-sdk/api/admin-customer';
+
+const organization = await readCustomerOrganization({ client });
+if (organization.statsOpen) {
+  const dashboard = await readCustomerDashboard({ days: 90 }, { client });
+}
+if (organization.enrolledVisible) {
+  const page = await listCustomerBeneficiaries({ page: 1, limit: 24 }, { client });
+}
+```
+
+Use `organization.role` (also projected in auth principal roles):
+
+| Role | Access in this first integration |
+| --- | --- |
+| `customer_admin_principal` | Enabled reads; invite/revoke administrators |
+| `customer_admin_manager` | Enabled reads; no administrator or subscription management |
+| `customer_admin_readonly` | Enabled reads; no mutations |
+
+Beneficiary management/communication mutations are future rubrics; their absence
+is not permission to reuse internal staff routes. All requests recheck native
+grants, so revocation does not wait for access-token expiration. Users without
+a customer grant receive 403. Support impersonation and child profiles cannot
+act as customer administrators.
+
+The home organization controls scope. A CSE cannot read descendants. A library
+consortium may include its permitted library sites. `statsOpen` and
+`enrolledVisible` are settings controlled by Mozaik, false until enabled;
+administrators cannot enable their own access to personal data. The beneficiary
+directory never exposes individual reading, tutoring or consumption history.
+
+Use `readCustomerOrganizationOverview()` for totals and
+`readCustomerContractUsage(contractId)` for organization-contract usage. A
+personal contract or another customer's contract is refused. Usage units are
+not an activation-code stock count. Missing branding/access/account-manager
+metadata remains null. Connection metrics state their definition and tracking
+coverage; a null previous value means no reliable comparison, not zero.
+
+## Invite and revoke
+
+```ts
+import {
+  inviteCustomerAdministrator, revokeCustomerAdministrator,
+} from '@learnorama/mozaik-sdk/api/admin-customer';
+
+const invitation = await inviteCustomerAdministrator({
+  email: 'colleague@example.org', firstName: 'Camille', lastName: 'Martin',
+  role: 'customer_admin_readonly',
+}, { client });
+```
+
+An invitation lasts seven days and acceptance consumes it once. Existing
+verified accounts keep their password; new accounts complete Keycloak email
+verification/password setup. The local pending account grants no patron or
+administrative rights before acceptance. A person already attached to another
+organization requires staff reconciliation; email matching never moves them.
+
+Only an existing principal can invite from the customer app. Mozaik staff use
+`inviteFirstCustomerAdministrator(tenantId, body)` under their existing scope
+and high-assurance authentication; the first role must be principal.
+`listCustomerAdministrators` includes active and pending/expired invitations.
+Use `revokeCustomerAdministrator(userId)` for active grants and
+`revokeCustomerAdministratorInvitation(invitationId)` for pending invitations.
+The last active principal is protected. Revocation removes the administrative
+grant, not an existing beneficiary's personal account.
+
+No existing legacy customer administrators are automatically granted access.
+A release still needs explicit organization settings and first invitations.

package/CVS-PLAYBACK.md

@@ -0,0 +1,135 @@
+# Cinema integration with the SDK
+
+This guide targets the frontend-request update prepared on 27 October 2026.
+Use the SDK from the release containing these operations; this document does
+not mean the pending backend changes have already reached staging.
+
+## Browse and quote
+
+Reuse the authenticated SDK client and active profile headers. Show Cinema
+when `readCapabilities().cinema.catalogueAllowed` is true. Its `homeUrl`,
+`catalogueUrl` and `accessUrl` correspond to these typed operations:
+
+```ts
+import {
+  readCinemaHome, listCinemaFilms, readCinemaAccess,
+} from '@learnorama/mozaik-sdk/api/cvs-documents';
+
+const home = await readCinemaHome({ limit: 8 }, { client });
+const films = await listCinemaFilms({ page: 1, limit: 24, sort: 'newest' }, { client });
+const film = films.data[0];
+const quote = film && await readCinemaAccess({ docId: film.id }, { client });
+```
+
+Cards include `genres`, `durationSeconds`, `directors`, and `coverUrl` when known.
+Null metadata is unknown. Follow each home row's `documentsUrl` for subsequent
+pages; keep its filters. `listCvsSelectionDocuments` retrieves an owned CVS
+list in recorded order. Search remains available separately; do not fetch the
+whole inventory to classify it on the frontend.
+
+`readCinemaAccess()` without `docId` is an overview. Several allowances must
+**not be added together**: they can apply to different films. An overview with
+more than 100 allowances sets `balancesComplete=false`. A film-specific quote
+resolves the actual act, cost and allowance:
+
+- `credits.left`, `total`, `until`, `grantedBy`, `contractId`, `contractReference`
+  describe the selected grant. `unlimited=true` has null amounts, not zero.
+- `scope` says whether the allowance belongs to a profile, household or tenant.
+- `allowed` and `reason` describe the current decision; this is not a reservation.
+- `unitCost` is the actual consumption policy, currently one unit for a new act,
+  zero when starting playback under an existing valid loan. It is not the
+  document's catalogue price or legacy `unitCount`.
+- `act`, `loanHours`, `validUntil`, and `actionUrl` distinguish direct viewing
+  from borrowing and from an already-held loan.
+
+After borrowing or starting playback, invalidate/refetch `/me/cinema` for the
+film and the overview. Never decrement a simulated balance. The mutation checks
+rights and quota again, so a concurrent household spend may still return 409.
+
+## Explicit Play action
+
+```ts
+import { borrow } from '@learnorama/mozaik-sdk/api/cvs-loans';
+import { startSession, readDashManifest } from '@learnorama/mozaik-sdk/api/cvs-streaming';
+import { renewLease, closeLease } from '@learnorama/mozaik-sdk/api/consumption';
+
+// Run only after the user presses Play, with a fresh quote for this docId.
+if (!quote?.allowed) throw new Error('This film is not currently available');
+if (quote.actionUrl === '/cvs/loans') {
+  if (quote.act !== 'loan_view' && quote.act !== 'loan_download') {
+    throw new Error('Unexpected loan contract');
+  }
+  await borrow({ workId: film.id, act: quote.act, requestKey: crypto.randomUUID() }, { client });
+}
+const playback = await startSession({ docId: film.id }, {
+  client,
+  headers: {
+    'Idempotency-Key': crypto.randomUUID(),
+    'X-Client-Platform': 'web',
+  },
+});
+await readCinemaAccess({ docId: film.id }, { client });
+```
+
+Retain each request key for an intentional retry of that same action. Borrow
+and playback need different keys. Do not prefetch these mutations or blindly
+retry them: opening DRM is an external operation. `streamingDetails(docId)` is
+a read-only readiness check and returns no licence or lease.
+
+Use `web` for Tizen/webOS, `android` for Android TV, `ios` for tvOS. These are
+DRM/OS families; there is no fourth DRM family named `tv`.
+
+## Player and DRM
+
+| Response field | Meaning |
+| --- | --- |
+| `streamUrl` / `drm.hls` | HLS manifest |
+| `drm.dash` | Direct CDN MPEG-DASH manifest |
+| `drm.normalizedDashUrl` | Optional authenticated backend MPD normalization route |
+| `drm.widevine`, `drm.fairplay` | Licence acquisition URLs |
+| `drm.certificate` | URL of public DER FairPlay application-certificate bytes |
+| `drm.token` | Provider licence token; not the Mozaik bearer |
+| `drm.kid` | Content key identifier; not a raw decryption key |
+| `drm.contentId` | Provider media identity; not the CVS document ID |
+| `lease.eventId`, `lease.expiresAt` | Playback heartbeat handle and deadline |
+
+The SDK does not implement a player/CDM. Configure the player with its supported
+provider protocol; its licence challenge returns the protected key material.
+Fetch the public FairPlay certificate as bytes, not as a JSON or base64 field.
+The configured legacy certificate is reachable but actual Safari/iOS playback
+still needs device validation. Its embedded X.509 expiration alone was not used
+to claim successful or failed FairPlay decryption.
+
+For a DASH player affected by self-referencing `dependencyId`, fetch the
+normalized MPD with the SDK, then pass a Blob URL to the player:
+
+```ts
+const xml = await readDashManifest(film.id, { client });
+const manifestUrl = URL.createObjectURL(new Blob([xml], { type: 'application/dash+xml' }));
+// await player.load(manifestUrl);
+// Revoke after player unload: URL.revokeObjectURL(manifestUrl);
+```
+
+The backend removes only a representation's dependency on itself. Other
+dependencies remain; segment BaseURL resolves to the original CDN. The endpoint
+is bounded and read-only, and does not grant playback rights by itself. Do not
+send API bearer/profile headers to CDN, certificate or licence hosts.
+
+## Heartbeat and stop
+
+Call `renewLease(playback.lease.eventId, { client })` while playing, typically
+every 30 seconds. Honor its returned deadline; a 404 means the lease is gone.
+Call `closeLease` on stop/unmount/player failure. JSON carries the handle; no
+`Location` header is needed. The durable database expiry survives Redis loss
+and is the same deadline used by the reaper.
+
+Playback has its own event, linked to a fixed-term loan where applicable.
+Closing playback does not return the loan; renewing playback cannot extend the
+loan's contractual deadline. Returning a loan releases a seat without refunding
+spent units. Never substitute a loan ID, docId, or key ID for the playback event.
+
+Handle 401 through SSO, 403 as a profile restriction, 404 as unavailable/unready,
+409 as exhausted quota or no seat, 429 using Retry-After, and 503 as provider
+unavailability. Verify video **and audio**, licence challenge, several heartbeats,
+and stop on each target platform after release. Provider-stubbed tests prove the
+backend contract, not device/CDM interoperability.

package/PRESS.md

@@ -0,0 +1,208 @@
+# Press integration
+
+Use the SDK generated from the release containing these routes. Publications,
+dated editions and articles have distinct identities:
+
+| Object | Identity | Listing |
+| --- | --- | --- |
+| Publication / newspaper | `contentId`, plus provider `publicationId` when applicable | `listPressTitles` |
+| Dated PressReader edition | publication + `issueDate` | `readIssues(contentId)` |
+| Article | native `articleId`; separate `providerArticleId` | `listPressArticles`, `readPressReview` |
+| Newspaper voucher offer | `lemonde`, `lequipe`, `lefigaro` | `listPressPartnerAccess` |
+
+`readCapabilities()` supplies `biblio.pressArticlesUrl`, `pressReviewUrl` and
+`pressPartnersUrl`. Provider cards identify their catalogue and reader action.
+Use the same authenticated effective profile throughout. The backend filters
+rights and age restrictions before counts, deduplication and pagination.
+
+## Article review
+
+```ts
+import { request } from '@learnorama/mozaik-sdk';
+import {
+  readPressReview, listPressArticles, openPressArticleReader,
+} from '@learnorama/mozaik-sdk/api/biblio-press';
+import type { PressArticlePage } from '@learnorama/mozaik-sdk/models';
+import { renewLease, closeLease } from '@learnorama/mozaik-sdk/api/consumption';
+
+const review = await readPressReview({ limit: 6 }, { client });
+const first = review.sections[0];
+if (first && first.articles.meta.totalPages > 1) {
+  // Keep the server's selection, date window and page-size filters intact.
+  const url = new URL(first.articlesUrl, client.baseUrl);
+  url.searchParams.set('page', '2');
+  const next = await request<PressArticlePage>(url.pathname + url.search, { client });
+}
+
+const page = await listPressArticles({
+  publicationId: '2526', page: 1, limit: 24,
+}, { client });
+
+// Only after the reader presses Open. Do not prefetch this mutation.
+const article = page.data[0];
+if (article) {
+  const opened = await openPressArticleReader(article.articleId, {
+    client, headers: { 'Idempotency-Key': crypto.randomUUID() },
+  });
+  // Open opened.url in the licensed reader. Never log its token-bearing URL.
+  // Renew while actually reading, and close when the reader exits:
+  await renewLease(opened.lease.eventId, { client });
+  await closeLease(opened.lease.eventId, { client });
+}
+```
+
+`/press-feed` remains a feed of publication cards. `/press-review` contains real
+article cards and uses publication favourites already saved with
+`mode=press_title`. It offers selected headlines and related themes; each
+section includes its own page and continuation URL. Review selection applies
+the editorial rules and a maximum of four articles per publication before
+pagination. Monthly and other long-period editions remain eligible for their
+recorded editorial lifetime. An ordinary article query defaults to seven days;
+explicit `since`/`until` queries can cover up to 366 days.
+
+Article metadata is local: GET requests do not contact PressReader or grant
+reader access. `publishedAt` can be null because an issue date is not an article
+publication timestamp. There is no full-text body endpoint; the licensed reader
+opens the stored provider article ID and issue date. Empty review sections are
+omitted. Invalidate the review after changing publication favourites and clear
+profile-scoped caches when switching profiles.
+
+## Publisher codes
+
+```ts
+import {
+  readPressPartnerAccess, claimPressPartnerCode,
+} from '@learnorama/mozaik-sdk/api/biblio-press';
+
+const state = await readPressPartnerAccess('lemonde', { client });
+// Explicit user action only; GET/capabilities/onboarding never claim a code.
+if (state.canRequestCode) {
+  const access = await claimPressPartnerCode('lemonde', { client });
+  // Show access.code and access.activationUrl privately to this household.
+  // Never log, persist in analytics, or automatically visit the activation URL.
+}
+```
+
+The same household reuses its existing eligible code across devices and adult
+profiles. Concurrent requests cannot spend two codes for that household. Support
+impersonation cannot reveal or allocate codes. A generic press category does
+not override provider exclusions; contracts can permit each newspaper separately.
+
+Allocation is not activation. `activatedOn`, `benefitEndsOn` and
+`renewalAvailableOn` stay null until a publisher report confirms the date.
+The legacy policies are Le Monde three calendar months; L’Équipe thirty days
+with renewal after twenty-eight (older banks used three months); Le Figaro one
+calendar month. Actual bank policy is explicit in the response.
+
+Handle 404 as unavailable to this profile, 409 as no currently usable stock,
+and 503 as unavailable configuration. Refetch status after a claim. A code claim
+records an allocation audit, not a newspaper-reading session.
+
+## Operator setup
+
+Global catalogue administrators with high-assurance authentication use the
+generated `admin-catalogue` functions for offer/title bindings, bank policies,
+code import, disablement and publisher activation reports. Imports are bounded
+to 500 codes/report entries and are atomic. Same-bank retries are idempotent;
+conflicting activation dates need an explicit correction reason. Lists and audit
+records never contain code values.
+
+Article refresh requires `PRESSREADER_DISCOVERY_ENABLED`,
+`PRESSREADER_DISCOVERY_URL` and the private `PRESSREADER_DISCOVERY_KEY`.
+The worker and minute dispatcher process one bounded page per task, retaining
+previous article data on failures. Global administrators can enqueue a refresh
+with a unique request key and inspect progress through
+`/admin/press/article-refreshes`.
+
+Voucher encryption uses the existing `COMMERCE_SECRET_KEY`; keep it stable.
+Stock and confirmed-activation reports must be supplied separately. Importing
+legacy records does not enable an offer or allocate any new code. Staging exports
+omit real voucher stock; create synthetic test banks explicitly for frontend work.
+
+## Article enrichment and profile preferences
+
+The frontend-request update adds `language`, `wordCount`, `readingMinutes`,
+`topics`, catalogue `themes`, `read` and `lastOpenedAt` to article cards.
+`read` means this profile opened the licensed reader, not that it finished the
+article. `readingMinutes` is estimated at 200 words/minute **only when a full
+article word count is known**. The sampled Discovery response has no such count;
+null must remain absent in the UI. A short summary is not the full article.
+
+`topics` are PressReader-supplied named entities, with stable native `topicId`
+and counts over the accessible cached articles. They are distinct from the
+publication's catalogue `themeId`; they are not an inferred editorial grouping
+such as “pension reform.” `listPressTopics` defaults to issues since yesterday.
+Counts describe imported, accessible articles, not the entire provider archive.
+
+```ts
+import {
+  listPressTopics, followPressTopic, unfollowPressTopic,
+  readPressFacets, updateReadingPreferences, acknowledgePressReview,
+} from '@learnorama/mozaik-sdk/api/biblio-press';
+
+const topics = await listPressTopics({ limit: 20 }, { client });
+// On the user's explicit Follow action:
+if (topics.data[0]) await followPressTopic(topics.data[0].topicId, { client });
+const filtered = await listPressArticles({ topicId: 21, lang: 'en', page: 1 }, { client });
+const facets = await readPressFacets({ client });
+await updateReadingPreferences({ language: 'fr', regionCode: 'FR-ARA' }, { client });
+// Only once this review was actually displayed, never on prefetch:
+await acknowledgePressReview({ through: review.generatedAt }, { client });
+```
+
+Use actual IDs/codes from topics/facets in production. Regional facets require
+explicitly mapped publications; a country or IP address does not establish a
+publication's region. No mappings are fabricated. Language filters preserve
+original-language headlines. GETs never advance the visit cursor or follow a
+subject.
+
+The section `key` is now a generated enum:
+
+| Key | Selection |
+| --- | --- |
+| `headlines` | Selected headlines |
+| `favoritesHeadlines` | Headlines from followed publications, unopened first |
+| `basedOnFavorites` | Themes related to followed publications |
+| `theme` | Explicit catalogue theme |
+| `focus` | Most-covered supplied subject since yesterday, with counts |
+| `followedTopics` | Subjects followed by this profile |
+| `shortReads` | Known full word count from 1 to 200 |
+| `longReads` | Known full word count of at least 1,600, recent month |
+| `regional` | Explicit publication mapping and profile's selected region |
+| `international` | Available articles outside the selected profile language |
+
+Render existing nonempty sections; use `features[].available` and `reason` to
+explain unavailable functionality. There is no integrated press-video source:
+`video` is unavailable and no video section is invented. A long article is not
+necessarily evergreen; the backend does not claim that classification.
+
+`updatedAt` describes cached metadata updates. `generatedAt` is the display
+snapshot for the explicit visit acknowledgment. `newCount` counts newly ingested
+accessible articles after the stored visit; `newSince=null` on the first visit
+means no prior baseline. It is not a count of articles the person finished.
+Refetch article/review queries after opening, following, changing preferences,
+or acknowledging a displayed review. Clear caches on profile switches.
+
+Le Monde, L’Équipe and Le Figaro voucher offers stay outside publication/edition
+kiosk lists. Use their explicit partner access operations; do not try to open
+PressReader issues for a voucher offer.
+
+## Clear Biblio reading history
+
+```ts
+import { clearReadingHistory } from '@learnorama/mozaik-sdk/api/biblio-library';
+await clearReadingHistory({ state: 'finished' }, { client });
+// state: 'in_progress', or omit the query for all Biblio profile history.
+```
+
+The mutation is idempotent (204) and uses the active authenticated profile.
+`listHistory` accepts the same state filter and returns its page total.
+After clearing, refetch history and home-feed. Finished means progress >= 100;
+other previously opened entries are in progress. New reading after the clearing
+cutoff can reappear. Progress, favourites, downloads, loans, credits and the
+accounting ledger stay intact. Support impersonation cannot clear it.
+
+This is profile-visible Biblio history clearing. It is not a claim that all
+provider, cinema, search or legally retained accounting records are erased.
+The broader privacy-screen wording must match that scope until its separate
+retention/erasure policy is implemented.

package/README.md

@@ -131,17 +131,23 @@ articles or trending topics that the upstream catalogue does not contain.
 `reason: "license_required"`; a configured activation can be requested when the
 eligible adult explicitly opens the reader.
 
-- `POST /partners/youscribe/user/auth` opens that profile's reader. It provisions
-  its subscription on first use and returns `{licenseNumber, token}`.
-- `POST /partners/youscribe/media/{mediaId}/reader-auth` additionally validates
-  the chosen title and returns its consumption lease. Prefer it when a title
-  has already been selected.
-- `GET /partners/youscribe/user/auth` and `GET /media/{mediaId}/package` require
-  an existing licence and never create one. For the hosted reader, activate on
-  the explicit user action before fetching its package URL.
-
-Call the generated `openNativeAuth`/`openNativeReader` functions, or invoke their
-TanStack **mutations** from the reader-opening event. Never invoke them on mount,
+- `POST /biblio/me/youscribe/license` takes the seat. Call it on the patron's
+  Read click and nowhere else — not on entering the books section, prefetch,
+  bootstrap or onboarding: a seat is a paid subscription. It is idempotent and
+  the only call that allocates one, and it answers `409` with counters when the
+  household's four are taken. `DELETE` on the same path gives a seat back.
+- `GET /partners/youscribe/user/auth` returns `{licenseNumber, token}` for the
+  native SDK. It requires an existing seat and never creates one. There is no
+  per-title variant: a YouScribe token is issued per patron, not per title.
+- For the hosted (web) reader, read `reader.url` from
+  `GET /partners/youscribe/media/{mediaId}`. A `null` url carries
+  `unavailable: "forbidden"` (allowed to browse, not to read) or
+  `"unreachable"` (our side failed) — they are different answers.
+
+Call the generated `createYouscribeLicense` function, or invoke its TanStack
+**mutation**, from the reader-opening event. `openNativeAuth` and
+`openNativeReader` still work as in 0.13.0 but are deprecated. Never invoke
+any of them on mount,
 prefetch, login, onboarding, catalogue navigation, or for every household profile.
 One activated profile keeps the same provider identity across retries and releases;
 staging and production use different identities. No token should be persisted.
@@ -564,3 +570,11 @@ import { apiVersion, backendRevision, schemaSha256 } from '@learnorama/mozaik-sd
 Generated HTTP TypeScript types describe the API contract; they do not validate
 response bodies at runtime. The package contains the client and type declarations, not application
 credentials or backend implementation code.
+
+### Frontend integration guides
+
+The published package includes [cinema browsing, quotes and playback](CVS-PLAYBACK.md),
+[press articles, topics and publisher codes](PRESS.md),
+[customer administrator sign-in and permissions](CUSTOMER-ADMIN.md), and
+[TV pairing](TV-LOGIN.md). Use the guide and generated operations from the same
+published release; an uncommitted local guide does not establish staging availability.

package/TV-LOGIN.md

@@ -0,0 +1,137 @@
+# Connexion de l’application TV
+
+La TV affiche un QR code et un code court. L’utilisateur ouvre la page web
+d’activation sur son téléphone ou ordinateur, se connecte puis **confirme dans
+Keycloak**. La TV reçoit ensuite une session utilisable par le SDK.
+
+Ce document concerne les nouvelles routes et le SDK publiés avec cette modification.
+Ils seront disponibles après la release habituelle ; aucun déploiement manuel n’est requis.
+
+## Côté TV
+
+```ts
+import { startTvLogin } from '@learnorama/mozaik-sdk/auth';
+import { createClient } from '@learnorama/mozaik-sdk';
+import type { SessionRead } from '@learnorama/mozaik-sdk/models';
+
+const login = await startTvLogin({
+  baseUrl: 'https://api.stg.mozaik.co',
+  onStatus: status => console.log(status), // pending ou slow_down, sans jeton
+});
+
+// Afficher :
+// <img src={login.qrCodeDataUrl} alt="Connecter cette TV" />
+// login.userCode, login.verificationUri et un compte à rebours vers login.expiresAt.
+
+let session: SessionRead;
+try {
+  session = await login.waitForSession();
+} finally {
+  login.cancel(); // aussi à appeler si l’utilisateur quitte l’écran
+}
+const api = createClient({
+  baseUrl: 'https://api.stg.mozaik.co',
+  getAccessToken: () => session.access_token,
+});
+// session.account est le compte connecté ; api appelle les routes métier.
+```
+
+Le helper génère le PKCE S256, garde le vérificateur et le code privé en mémoire,
+attend avant le premier appel et respecte les intervalles. Un `slow_down`
+augmente durablement le délai. Les erreurs transitoires et `Retry-After` entraînent
+un recul borné par l’expiration du code. Refus et expiration arrêtent la boucle.
+Plusieurs appels à `waitForSession()` partagent une seule boucle.
+
+Un nouveau QR nécessite un nouvel appel à `startTvLogin()`. Annuler l’ancien
+avant de remplacer l’écran. `cancel()` arrête l’appairage ; il ne déconnecte pas
+une session déjà remise à l’application.
+
+Pour renouveler ou fermer la session, utiliser **le clientId renvoyé**, normalement
+`mozaik-tv`, avec les méthodes existantes :
+
+```ts
+import { refreshSession, deleteSession } from '@learnorama/mozaik-sdk/api/auth';
+
+session = await refreshSession({
+  clientId: login.clientId,
+  refresh_token: session.refresh_token!,
+}, { client: api });
+
+await deleteSession({
+  clientId: login.clientId,
+  refresh_token: session.refresh_token!,
+}, { client: api });
+```
+
+Le store d’authentification TV doit sérialiser les renouvellements, appliquer les
+durées `expires_in`/`refresh_expires_in`, et oublier ses jetons à la déconnexion.
+S’il persiste des credentials, utiliser le stockage sécurisé de la plateforme.
+Les règles de durée et de révocation SSO restent celles du realm Keycloak.
+
+## Page web à ajouter : `/activate`
+
+Le QR mène à `FRONTEND_HOST/activate?user_code=ABCD-EFGH`.
+La même page sans paramètre propose la saisie manuelle du code affiché sur la TV.
+
+1. Lire `user_code` ou laisser l’utilisateur le saisir.
+2. S’il n’est pas connecté dans ce navigateur, utiliser **le parcours de connexion
+   déjà présent dans l’application**. Conserver `/activate?user_code=...` comme
+   `returnTo`. Cela permet aussi aux utilisateurs SSO de choisir leur connexion
+   habituelle ; ne pas les envoyer directement sur un formulaire de mot de passe.
+3. Avec le client authentifié, appeler :
+
+```ts
+import { prepareDeviceVerification } from '@learnorama/mozaik-sdk/api/auth-device';
+
+const { verificationUrl } = await prepareDeviceVerification({
+  userCode: userCode.trim().toUpperCase(),
+}, { client: auth.client });
+
+window.location.assign(verificationUrl);
+```
+
+Keycloak affiche la TV demandant l’accès et exige une confirmation, y compris
+si le navigateur est déjà connecté ou a déjà approuvé une autre TV. L’utilisateur
+peut refuser. Après confirmation, la page indique que l’on peut la fermer ; le
+polling débloque la TV. Le front n’a pas d’endpoint d’« approbation automatique ».
+
+Pour une connexion interne, le helper SSO existant est `prepareInternalSso` ;
+pour un partenaire, `prepareProviderSso(alias)` ; pour un compte natif,
+`prepareProviderSso('native')`. Réutiliser la sélection déjà faite par le front.
+Un jeton mobile seul ne crée pas de cookie SSO dans le navigateur : le QR doit
+passer par la page web d’activation et son parcours de connexion.
+
+## Contrat HTTP, également utilisable hors JavaScript
+
+| Appel | Entrée | Résultat |
+| --- | --- | --- |
+| `POST /auth/device-authorizations` | `codeChallenge` : SHA-256/base64url du vérificateur | QR PNG en data URL, `userCode`, liens d’activation, `deviceCode` privé, `clientId`, `expiresIn`, `interval` |
+| `POST /auth/device-authorizations/verification` | `userCode`, bearer du compte connecté | URL de confirmation Keycloak ; cet appel n’approuve pas la TV |
+| `POST /auth/sessions/device` | `deviceCode`, `codeVerifier` | `pending`, `slow_down`, `denied`, `expired`, ou `authorized` avec `session` |
+| `PUT /auth/sessions` | `clientId`, `refresh_token` | Session renouvelée |
+| `DELETE /auth/sessions` | `clientId`, `refresh_token` | Déconnexion suivant les règles SSO existantes |
+
+Le code dure cinq minutes. `deviceCode` et `codeVerifier` ne doivent jamais
+apparaître dans un QR, une URL, une capture de diagnostic ou un log. Le code
+court `userCode` ne permet pas d’obtenir les jetons. Sur `slow_down`, augmenter
+le délai courant d’au moins cinq secondes ; sur `401`, démarrer un nouvel
+appairage ; sur `429`/`503`, respecter `Retry-After` sans dépasser l’expiration.
+
+## Profils et sécurité
+
+Le navigateur et les TV peuvent partager un `sid` de SSO Keycloak. Un nonce
+signé par Keycloak et conservé au renouvellement distingue chaque appairage TV
+dans le mécanisme existant des profils. Changer de profil sur une TV ne change
+pas celui du téléphone ou d’une autre TV. Cela n’altère pas les règles globales
+de révocation de la session SSO du broker.
+
+Une session de support ou un profil dépendant ne peut pas lancer la vérification.
+Le backend vérifie aussi le verrou enfant du navigateur avant d’enregistrer la
+TV : appeler directement le broker ne donne pas accès à l’API avec un jeton TV
+non enregistré. Toujours terminer via `POST /auth/sessions/device`.
+
+La release inclut le client public `mozaik-tv`, le PKCE et son mapper de nonce
+dans la configuration Keycloak/Helm. Aucun nouveau secret fournisseur n’est
+nécessaire. Si `KEYCLOAK_ALLOWED_CLIENT_IDS` est surchargé explicitement dans un
+environnement, y inclure `mozaik-tv`. `FRONTEND_HOST` doit désigner le front qui
+sert `/activate`.

package/dist/api/account.d.ts

@@ -1,5 +1,5 @@
 
-import { Q as ServiceListRead, Vr as OnboardingRead, cg as AccountUpdateWrite, ll as FrontendCapabilitiesRead, ug as AccountDetailRead } from "../chunks/index.js";
+import { Il as FrontendCapabilitiesRead, Q as ServiceListRead, si as OnboardingRead, x_ as AccountDetailRead, y_ as AccountUpdateWrite } from "../chunks/index.js";
 import { c as request } from "../chunks/client.js";
 //#region src/api/account/account.d.ts
 export declare const getDeleteAccountUrl: () => string;