@makefully/adaptfully 5.1.2 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.2.0 — 2026-11-11
+
+### Added
+
+- **`device-auth`** — PIN/QR limited-input auth plugin; TV starts/polls, companion completes on the web deploy. See [`docs/device-auth.md`](docs/device-auth.md).
+- **`tv-host`** — lean-back host with Back key + `onDeviceAuth` for PIN/QR chrome.
+- **Web packager** — default platforms include `webos` / `lgtv`; builder family resolves `webos` even with `packager: "web"`.
+
 ## 5.1.2 — 2026-11-10
 
 ### Fixed

package/docs/device-auth.md

@@ -0,0 +1,67 @@
+# Device auth (PIN / QR)
+
+`device-auth` is an Adaptfully auth plugin for limited-input shells (LG webOS TV, etc.). The TV build only **starts** and **polls** a short-lived session. Companion Google (or other) sign-in happens on the game’s **existing web deploy**, not inside the TV package.
+
+## Registration
+
+```json
+"lgtv": {
+  "packager": "web",
+  "builder": "webos",
+  "registrations": {
+    "auth": "device-auth",
+    "host": "tv-host",
+    "config": "javascript/adaptfully-bridge.js"
+  }
+}
+```
+
+## Config keys
+
+| Key | Purpose |
+|-----|---------|
+| `deviceAuthStartUrl` | `POST` mint session |
+| `deviceAuthPollUrl` | `GET` poll (`?device_code=`) |
+| `deviceAuthCompanionBase` | Fallback QR/base URL if start omits `verificationUrl` |
+
+## HTTP protocol
+
+### `POST start`
+
+Response:
+
+```json
+{
+  "deviceCode": "opaque-poll-token",
+  "userCode": "AB12CD",
+  "expiresIn": 600,
+  "interval": 2000,
+  "verificationUrl": "https://game.example/tv-login.html?code=AB12CD"
+}
+```
+
+### `GET poll?device_code=…`
+
+```json
+{ "status": "pending" }
+```
+
+```json
+{ "status": "approved", "user": { "id": "provider-subject", "email": "a@b.co" } }
+```
+
+Also: `expired`, `denied`.
+
+### `POST complete`
+
+Body: `user_code` or `device_code`, plus `plusId`, `email`, optional `user_id`.
+
+## Companion helpers
+
+Optional page script: `lib/runtime/auth/device-auth-companion.js`  
+(`adaptfully.auth.deviceCompanion.readCodeFromLocation()` / `.complete(...)`).
+
+## Events
+
+`window` CustomEvent `adaptfully:device-auth` with `detail.phase` of `pending` | `approved` | `expired` | `denied` | `error`.  
+`tv-host` forwards these via `onDeviceAuth(cb)`.

package/lib/node/packagers/web.js

@@ -5,11 +5,11 @@ export class WebPackager extends Packager {
     static id = 'web';
 
     /** @type {string[]} */
-    static defaultPlatforms = ['web', 'uwp', 'pwa'];
+    static defaultPlatforms = ['web', 'uwp', 'pwa', 'webos', 'lgtv'];
 
     needsGameConfig() {
-        // Stamp version/platform for all web-family routes (web, uwp, pwa) so
-        // analytics resolveAppVersion() matches electron/capacitor builds.
+        // Stamp version/platform for all web-family routes (web, uwp, pwa, webos)
+        // so analytics resolveAppVersion() matches electron/capacitor builds.
         return true;
     }
 }

package/lib/node/registrations.js

@@ -30,6 +30,10 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'platform.js', 'auth/_helpers.js', 'auth/dev-auth.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.auth.Dev);`,
     },
+    'device-auth': {
+        scripts: ['core.js', 'platform.js', 'auth/_helpers.js', 'auth/device-auth.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.auth.Device);`,
+    },
     localStorage: {
         scripts: ['core.js', 'storage/_helpers.js', 'storage/local-storage.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.storage.LocalStorage());`,
@@ -58,6 +62,10 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'host/_helpers.js', 'host/noop-host.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.host.Noop());`,
     },
+    'tv-host': {
+        scripts: ['core.js', 'host/_helpers.js', 'host/tv-host.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.host.Tv());`,
+    },
 };
 
 /** Default Wrapfully builder → config.platforms key */
@@ -77,6 +85,8 @@ export const DEFAULT_BUILDER_PLATFORMS = {
     'ios-sim': 'ios',
     webapp: 'web',
     uwp: 'uwp',
+    webos: 'lgtv',
+    'webos-dev': 'lgtv',
 };
 
 const ADAPTFULLY_MARKER = '<!-- adaptfully -->';
@@ -402,6 +412,9 @@ export function resolveFamilyFromTarget(target) {
     if (target === 'pwa') {
         return 'pwa';
     }
+    if (target === 'webos' || target === 'webos-dev') {
+        return 'webos';
+    }
     if (target === 'webapp' || target === 'web') {
         return 'webapp';
     }
@@ -419,6 +432,9 @@ export function resolveFamily(targets, packager) {
     if (targets.length === 1 && targets[0] === 'pwa') {
         return 'pwa';
     }
+    if (targets.length === 1 && (targets[0] === 'webos' || targets[0] === 'webos-dev')) {
+        return 'webos';
+    }
 
     if (packager === 'electron') {
         return 'electron';

package/lib/runtime/auth/device-auth-companion.js

@@ -0,0 +1,69 @@
+/* global fetch, window */
+
+/**
+ * Optional helpers for a web companion page that completes device-auth sessions.
+ * Not registered as an Adaptfully plugin — include on the companion page only.
+ *
+ * Usage:
+ *   const code = adaptfully.auth.deviceCompanion.readCodeFromLocation();
+ *   await adaptfully.auth.deviceCompanion.complete({
+ *     completeUrl, deviceCode or userCode, plusId, email, userId?
+ *   });
+ */
+(function registerDeviceAuthCompanion(ns) {
+    ns.auth = ns.auth || {};
+
+    /**
+     * @returns {string}
+     */
+    function readCodeFromLocation() {
+        try {
+            const params = new URLSearchParams(window.location.search || '');
+            return String(params.get('code') || params.get('user_code') || params.get('pin') || '').trim();
+        } catch {
+            return '';
+        }
+    }
+
+    /**
+     * @param {{
+     *   completeUrl: string,
+     *   deviceCode?: string,
+     *   userCode?: string,
+     *   plusId: string,
+     *   email: string,
+     *   userId?: string,
+     * }} options
+     */
+    async function complete(options) {
+        const completeUrl = String(options?.completeUrl || '').trim();
+        if (!completeUrl) {
+            throw new Error('deviceCompanion.complete requires completeUrl');
+        }
+        const body = {
+            device_code: options.deviceCode || undefined,
+            user_code: options.userCode || undefined,
+            plusId: options.plusId,
+            email: options.email,
+            user_id: options.userId || undefined,
+        };
+        const response = await fetch(completeUrl, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(`device-login complete failed (${response.status}): ${text}`);
+        }
+        return response.json().catch(() => ({ ok: true }));
+    }
+
+    ns.auth.deviceCompanion = {
+        readCodeFromLocation,
+        complete,
+    };
+}(window.adaptfully || (window.adaptfully = {})));

package/lib/runtime/auth/device-auth.js

@@ -0,0 +1,335 @@
+/* global fetch, window */
+
+/**
+ * Device / PIN / QR auth for limited-input shells (LG webOS TV, etc.).
+ *
+ * TV build starts a short-lived session and polls. Companion sign-in happens on
+ * the game's existing web deploy (not in the TV package).
+ *
+ * Config (adaptfully config / game-config):
+ *   deviceAuthStartUrl      POST → { deviceCode, userCode, expiresIn, interval?, verificationUrl }
+ *   deviceAuthPollUrl       GET  → { status, user? }  (append ?device_code=)
+ *   deviceAuthCompanionBase optional base for QR if start omits verificationUrl
+ *
+ * Events: window 'adaptfully:device-auth' CustomEvent with detail
+ *   { phase: 'pending'|'approved'|'expired'|'denied'|'error', userCode?, verificationUrl?, qrUrl?, expiresIn?, error? }
+ *
+ *   adaptfully.register('auth', adaptfully.auth.Device);
+ */
+(function registerDeviceAuth(ns) {
+    const { configValue, getStorage } = ns.auth.helpers;
+
+    const DEFAULT_AUTO_LOGIN_KEY = 'lastLoggedIn';
+    const DEFAULT_USER_KEY = 'adaptfully_device_auth_user';
+    const DEFAULT_INTERVAL_MS = 2000;
+
+    class DeviceAuthPlugin {
+        constructor() {
+            this.name = 'device';
+            this.user = null;
+            this.authenticated = false;
+            this._pending = null;
+            this._pollTimer = null;
+            this._loginInFlight = false;
+        }
+
+        supportsAutoLogin() {
+            return true;
+        }
+
+        supportsLogout() {
+            return true;
+        }
+
+        requiresEmail() {
+            return true;
+        }
+
+        #autoLoginStorageKey() {
+            return configValue('autoLoginStorageKey', DEFAULT_AUTO_LOGIN_KEY);
+        }
+
+        #userStorageKey() {
+            return configValue('deviceAuthUserKey', DEFAULT_USER_KEY);
+        }
+
+        #startUrl() {
+            return String(configValue('deviceAuthStartUrl', '') || '').trim();
+        }
+
+        #pollUrl() {
+            return String(configValue('deviceAuthPollUrl', '') || '').trim();
+        }
+
+        #companionBase() {
+            return String(configValue('deviceAuthCompanionBase', '') || '').trim();
+        }
+
+        #emit(detail) {
+            try {
+                window.dispatchEvent(new CustomEvent('adaptfully:device-auth', { detail }));
+            } catch {
+                // ignore
+            }
+        }
+
+        #persistUser(user) {
+            const storage = getStorage();
+            if (!storage || !user?.id) {
+                return;
+            }
+            storage.set(this.#autoLoginStorageKey(), user.id);
+            try {
+                storage.set(this.#userStorageKey(), JSON.stringify({
+                    id: user.id,
+                    email: user.email || '',
+                }));
+            } catch {
+                // ignore
+            }
+        }
+
+        #clearPersisted() {
+            const storage = getStorage();
+            storage?.remove(this.#autoLoginStorageKey());
+            storage?.remove(this.#userStorageKey());
+        }
+
+        #readPersistedUser() {
+            const storage = getStorage();
+            const raw = storage?.get?.(this.#userStorageKey());
+            if (!raw || typeof raw !== 'string') {
+                return null;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed?.id) {
+                    return {
+                        id: String(parsed.id),
+                        email: String(parsed.email || ''),
+                    };
+                }
+            } catch {
+                // ignore
+            }
+            return null;
+        }
+
+        #stopPoll() {
+            if (this._pollTimer != null) {
+                window.clearTimeout(this._pollTimer);
+                this._pollTimer = null;
+            }
+            this._pending = null;
+        }
+
+        #buildVerificationUrl(deviceCode, userCode, fromServer) {
+            if (fromServer) {
+                return String(fromServer);
+            }
+            const base = this.#companionBase();
+            if (!base) {
+                return '';
+            }
+            const join = base.includes('?') ? '&' : '?';
+            const code = encodeURIComponent(deviceCode || userCode || '');
+            return `${base}${join}code=${code}`;
+        }
+
+        whenReady(done) {
+            if (!this.#startUrl() || !this.#pollUrl()) {
+                done({
+                    error: 'device-auth: deviceAuthStartUrl and deviceAuthPollUrl are required',
+                });
+                return;
+            }
+            done();
+        }
+
+        login(callback) {
+            if (this.authenticated && this.user?.id) {
+                callback({ authenticated: true, user: this.getUser() });
+                return;
+            }
+            if (this._loginInFlight) {
+                return;
+            }
+            this.#stopPoll();
+            this._loginInFlight = true;
+
+            fetch(this.#startUrl(), {
+                method: 'POST',
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+                body: '{}',
+            })
+                .then((response) => {
+                    if (!response.ok) {
+                        throw new Error(`device-login start failed (${response.status})`);
+                    }
+                    return response.json();
+                })
+                .then((data) => {
+                    const deviceCode = data.deviceCode || data.device_code;
+                    const userCode = data.userCode || data.user_code;
+                    const expiresIn = Number(data.expiresIn || data.expires_in || 600);
+                    const intervalMs = Math.max(
+                        1000,
+                        Number(data.interval || data.intervalMs || DEFAULT_INTERVAL_MS),
+                    );
+                    const verificationUrl = this.#buildVerificationUrl(
+                        deviceCode,
+                        userCode,
+                        data.verificationUrl || data.verification_url,
+                    );
+
+                    if (!deviceCode || !userCode) {
+                        throw new Error('device-login start missing deviceCode/userCode');
+                    }
+
+                    this._pending = {
+                        deviceCode,
+                        userCode,
+                        verificationUrl,
+                        expiresAt: Date.now() + (expiresIn * 1000),
+                        intervalMs,
+                        callback,
+                    };
+
+                    this.#emit({
+                        phase: 'pending',
+                        userCode,
+                        verificationUrl,
+                        qrUrl: verificationUrl,
+                        expiresIn,
+                        deviceCode,
+                    });
+
+                    this.#schedulePoll();
+                })
+                .catch((err) => {
+                    this._loginInFlight = false;
+                    this.#emit({
+                        phase: 'error',
+                        error: err?.message || String(err),
+                    });
+                    callback({ authenticated: false, user: null });
+                });
+        }
+
+        #schedulePoll() {
+            const pending = this._pending;
+            if (!pending) {
+                return;
+            }
+            this._pollTimer = window.setTimeout(() => this.#pollOnce(), pending.intervalMs);
+        }
+
+        #pollOnce() {
+            const pending = this._pending;
+            if (!pending) {
+                return;
+            }
+
+            if (Date.now() > pending.expiresAt) {
+                this.#stopPoll();
+                this._loginInFlight = false;
+                this.#emit({ phase: 'expired', userCode: pending.userCode });
+                pending.callback({ authenticated: false, user: null });
+                return;
+            }
+
+            const url = new URL(this.#pollUrl(), window.location.href);
+            url.searchParams.set('device_code', pending.deviceCode);
+
+            fetch(url.toString(), { headers: { Accept: 'application/json' } })
+                .then((response) => {
+                    if (!response.ok) {
+                        throw new Error(`device-login poll failed (${response.status})`);
+                    }
+                    return response.json();
+                })
+                .then((data) => {
+                    const status = String(data.status || '').toLowerCase();
+                    if (status === 'approved' && data.user?.id) {
+                        const user = {
+                            id: String(data.user.id),
+                            email: String(data.user.email || ''),
+                        };
+                        this.user = user;
+                        this.authenticated = true;
+                        this.#persistUser(user);
+                        this.#emit({
+                            phase: 'approved',
+                            userCode: pending.userCode,
+                            user,
+                        });
+                        const cb = pending.callback;
+                        this.#stopPoll();
+                        this._loginInFlight = false;
+                        cb({ authenticated: true, user: this.getUser() });
+                        return;
+                    }
+                    if (status === 'expired' || status === 'denied') {
+                        this.#emit({
+                            phase: status,
+                            userCode: pending.userCode,
+                        });
+                        const cb = pending.callback;
+                        this.#stopPoll();
+                        this._loginInFlight = false;
+                        cb({ authenticated: false, user: null });
+                        return;
+                    }
+                    this.#schedulePoll();
+                })
+                .catch((err) => {
+                    console.warn('[adaptfully device-auth] poll error', err);
+                    this.#schedulePoll();
+                });
+        }
+
+        autoLogin(callback) {
+            const stored = this.#readPersistedUser();
+            if (stored?.id) {
+                this.user = stored;
+                this.authenticated = true;
+                callback({ authenticated: true, user: this.getUser() });
+                return;
+            }
+            callback({ authenticated: false, user: null });
+        }
+
+        logout(callback) {
+            this.#stopPoll();
+            this._loginInFlight = false;
+            this.authenticated = false;
+            this.user = null;
+            this.#clearPersisted();
+            callback();
+        }
+
+        getUser() {
+            if (!this.authenticated || !this.user) {
+                return null;
+            }
+            return { id: this.user.id, email: this.user.email };
+        }
+
+        isAuthenticated() {
+            return !!this.authenticated;
+        }
+
+        /** Cancel an in-progress PIN/QR login without logging out a restored session. */
+        cancelLogin() {
+            const pending = this._pending;
+            this.#stopPoll();
+            this._loginInFlight = false;
+            if (pending?.callback) {
+                this.#emit({ phase: 'denied', userCode: pending.userCode });
+                pending.callback({ authenticated: false, user: null });
+            }
+        }
+    }
+
+    ns.auth.Device = () => new DeviceAuthPlugin();
+}(window.adaptfully));

package/lib/runtime/host/tv-host.js

@@ -0,0 +1,123 @@
+/* global window */
+
+/**
+ * Lean-back TV host (LG webOS and similar).
+ * Handles Back key → history/back listeners and exposes environment "tv".
+ * Listen for adaptfully:device-auth to render PIN/QR chrome in the game UI.
+ *
+ *   adaptfully.register('host', adaptfully.host.Tv);
+ */
+(function registerTvHost(ns) {
+    const { helpers } = ns.host;
+
+    ns.host.Tv = function tvHostFactory() {
+        const pauseListeners = [];
+        const captionsListeners = [];
+        const volumeListeners = {
+            sound: [],
+            music: [],
+            vo: [],
+            sfx: [],
+        };
+        const backListeners = [];
+        const deviceAuthListeners = [];
+        let features = null;
+        /** @type {Array<() => void>} */
+        const cleanups = [];
+
+        function onKeyDown(event) {
+            const key = event.key || '';
+            const keyCode = event.keyCode || event.which;
+            // webOS Back / Escape / browser Back
+            const isBack = key === 'Backspace'
+                || key === 'Escape'
+                || key === 'XF86Back'
+                || keyCode === 461
+                || keyCode === 27
+                || keyCode === 8;
+            if (!isBack) {
+                return;
+            }
+            if (backListeners.length === 0) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            helpers.emit(backListeners, { key, keyCode });
+        }
+
+        function onDeviceAuth(event) {
+            helpers.emit(deviceAuthListeners, event?.detail || null);
+        }
+
+        window.addEventListener('keydown', onKeyDown, true);
+        window.addEventListener('adaptfully:device-auth', onDeviceAuth);
+        cleanups.push(() => window.removeEventListener('keydown', onKeyDown, true));
+        cleanups.push(() => window.removeEventListener('adaptfully:device-auth', onDeviceAuth));
+
+        return {
+            kind: 'tv',
+
+            getEnvironment() {
+                return Promise.resolve('tv');
+            },
+
+            onPause(cb) {
+                return helpers.subscribe(pauseListeners, cb);
+            },
+
+            onCaptionsMuted(cb) {
+                return helpers.subscribe(captionsListeners, cb);
+            },
+
+            onVolume(channel, cb) {
+                const list = volumeListeners[channel];
+                if (!list) {
+                    return () => {};
+                }
+                return helpers.subscribe(list, cb);
+            },
+
+            /** Magix Remote / webOS Back */
+            onBack(cb) {
+                return helpers.subscribe(backListeners, cb);
+            },
+
+            /** Forwarded adaptfully:device-auth detail for PIN/QR UI */
+            onDeviceAuth(cb) {
+                return helpers.subscribe(deviceAuthListeners, cb);
+            },
+
+            setFeatures(next) {
+                features = next && typeof next === 'object' ? { ...next } : next;
+            },
+
+            notifyLoaded() {},
+
+            notifyProgress(_progress, _detail) {},
+
+            notifyEndGame(_payload) {},
+
+            send(_event, _data) {},
+
+            dispose() {
+                while (cleanups.length) {
+                    try {
+                        cleanups.pop()();
+                    } catch {
+                        // ignore
+                    }
+                }
+            },
+
+            /** @internal */
+            _getState() {
+                return {
+                    features,
+                    backListeners: backListeners.length,
+                    deviceAuthListeners: deviceAuthListeners.length,
+                };
+            },
+        };
+    };
+}(window.adaptfully));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/adaptfully",
-    "version": "5.1.2",
+    "version": "5.2.0",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",