@mywallpaper/addon-sdk 2.6.1 → 2.8.0

package/src/runtime/addon-client.js

@@ -0,0 +1,627 @@
+/* eslint-disable no-var, curly, object-shorthand */
+/**
+ * MyWallpaper Addon SDK v2.0
+ *
+ * API disponible pour les addons:
+ * - window.MyWallpaper.config          → Configuration actuelle
+ * - window.MyWallpaper.layerId         → ID du layer
+ * - window.MyWallpaper.onSettingsChange(fn) → Callback hot-reload
+ * - window.MyWallpaper.onEvent(type, fn)    → Événements système
+ * - window.MyWallpaper.ready(options)       → Signal prêt
+ * - window.MyWallpaper.renderComplete()     → Signal rendu visuel terminé
+ *
+ * Note: Uses 'var' intentionally for maximum iframe/browser compatibility
+ */
+; (function () {
+  'use strict'
+
+  var layerId = window.__MYWALLPAPER_LAYER_ID__ || ''
+  var config = window.__MYWALLPAPER_INITIAL_CONFIG__ || {}
+  var isReady = false
+  var isRenderComplete = false
+
+  var settingsCallbacks = []
+  var eventCallbacks = new Map()
+  var lifecycleCallbacks = { mount: [], unmount: [], pause: [], resume: [] }
+  var pendingStorage = new Map()
+  var pendingPermissions = new Map()
+  var pendingNetwork = new Map()
+  var pendingOAuth = new Map()
+  var pendingOAuthScopes = new Map()
+  var pendingFileAccess = new Map()
+  var grantedBlobUrls = new Map() // settingKey -> blobUrl
+
+  // Audio state (synced from host)
+  var audioState = {
+    status: 'none',
+    currentTime: 0,
+    duration: 0,
+    volume: 1,
+    loop: false,
+    playbackRate: 1
+  }
+  var audioCallbacks = new Set()
+
+  // Get the original fetch saved by network-sandbox.js (before it was blocked)
+  var originalFetch = window.__MYWALLPAPER_ORIGINAL_FETCH__ || null
+
+  // Message handler
+  function onMessage(e) {
+    if (e.source !== window.parent) return
+    var d = e.data
+    if (!d || d.source !== 'MyWallpaperHost') return
+
+    switch (d.type) {
+      case 'SETTINGS_UPDATE':
+        var p = d.payload || d
+        config = p.settings || p
+        var keys = p.changedKeys || Object.keys(config)
+        settingsCallbacks.forEach(function (cb) {
+          try { cb(config, keys) } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'SYSTEM_EVENT':
+        var cbs = eventCallbacks.get(d.payload.event)
+        if (cbs) cbs.forEach(function (cb) {
+          try { cb(d.payload.data) } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'LIFECYCLE':
+        var lcbs = lifecycleCallbacks[d.payload.event]
+        if (lcbs) lcbs.forEach(function (cb) {
+          try { cb() } catch (err) { console.error('[MyWallpaper]', err) }
+        })
+        break
+
+      case 'STORAGE_RESPONSE':
+        var op = pendingStorage.get(d.payload.requestId)
+        if (op) {
+          pendingStorage.delete(d.payload.requestId)
+          d.payload.success ? op.resolve(d.payload.value) : op.reject(new Error(d.payload.error))
+        }
+        break
+
+      case 'PERMISSION_GRANT':
+        var permOp = pendingPermissions.get(d.payload.requestId)
+        if (permOp) {
+          pendingPermissions.delete(d.payload.requestId)
+          permOp(d.payload.granted === true)
+        }
+        break
+
+      case 'NETWORK_RESPONSE':
+        var netOp = pendingNetwork.get(d.payload.requestId)
+        if (netOp) {
+          pendingNetwork.delete(d.payload.requestId)
+          if (d.payload.success) {
+            netOp.resolve({
+              ok: d.payload.status >= 200 && d.payload.status < 300,
+              status: d.payload.status || 200,
+              statusText: d.payload.statusText || 'OK',
+              headers: d.payload.headers || {},
+              data: d.payload.data
+            })
+          } else {
+            netOp.reject(new Error(d.payload.error || 'Network request failed'))
+          }
+        }
+        break
+
+      case 'OAUTH_RESPONSE':
+        var oauthOp = pendingOAuth.get(d.payload.requestId)
+        if (oauthOp) {
+          pendingOAuth.delete(d.payload.requestId)
+          if (d.payload.success) {
+            // Check if it's a scopes error
+            if (d.payload.error === 'insufficient_scopes') {
+              oauthOp.resolve({
+                error: 'insufficient_scopes',
+                message: d.payload.message,
+                provider: d.payload.provider,
+                missingScopes: d.payload.missing_scopes || d.payload.missingScopes || [],
+                requiredScopes: d.payload.required_scopes || d.payload.requiredScopes || []
+              })
+            } else {
+              oauthOp.resolve({
+                ok: d.payload.status >= 200 && d.payload.status < 300,
+                status: d.payload.status || 200,
+                headers: d.payload.headers || {},
+                data: d.payload.data
+              })
+            }
+          } else {
+            // Check if it's a scopes error from failed request
+            if (d.payload.error === 'insufficient_scopes' ||
+              (d.payload.data && d.payload.data.error === 'insufficient_scopes')) {
+              var scopesData = d.payload.data || d.payload
+              oauthOp.resolve({
+                error: 'insufficient_scopes',
+                message: scopesData.message || 'Insufficient OAuth scopes',
+                provider: scopesData.provider,
+                missingScopes: scopesData.missing_scopes || scopesData.missingScopes || [],
+                requiredScopes: scopesData.required_scopes || scopesData.requiredScopes || []
+              })
+            } else {
+              oauthOp.reject(new Error(d.payload.error || 'OAuth request failed'))
+            }
+          }
+        }
+        break
+
+      case 'OAUTH_SCOPES_GRANT':
+        var scopeResolver = pendingOAuthScopes.get(d.payload.requestId)
+        if (scopeResolver) {
+          pendingOAuthScopes.delete(d.payload.requestId)
+          scopeResolver(d.payload.granted === true)
+        }
+        break
+
+      case 'FILE_ACCESS_RESPONSE':
+        // Handle file access response from host
+        // Host sends us a Blob object (cloned via structured clone)
+        // We create our own blob URL from it
+        var fileOp = pendingFileAccess.get(d.requestId)
+        if (fileOp) {
+          pendingFileAccess.delete(d.requestId)
+          if (d.granted && d.blob instanceof Blob) {
+            // Create our own blob URL from the received Blob
+            var blobUrl = URL.createObjectURL(d.blob)
+            grantedBlobUrls.set(d.settingKey, blobUrl)
+            fileOp.resolve({ granted: true, blobUrl: blobUrl })
+          } else {
+            fileOp.resolve({ granted: false, error: d.error || 'Access denied' })
+          }
+        }
+        break
+
+      case 'AUDIO_STATE':
+        // Sync audio state from host
+        audioState = d.payload || d
+        audioCallbacks.forEach(function (cb) {
+          try { cb(audioState) } catch (err) { console.error('[MyWallpaper] Audio callback error:', err) }
+        })
+        break
+    }
+  }
+
+  function send(type, payload) {
+    window.parent.postMessage({ type: type, layerId: layerId, timestamp: Date.now(), payload: payload }, '*')
+  }
+
+  function storageOp(op, key, value) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingStorage.set(id, { resolve: resolve, reject: reject })
+      setTimeout(function () {
+        if (pendingStorage.has(id)) {
+          pendingStorage.delete(id)
+          reject(new Error('Storage timeout'))
+        }
+      }, 5000)
+      send('STORAGE_OPERATION', { operation: op, key: key, value: value, requestId: id })
+    })
+  }
+
+  /**
+   * Network fetch via secure host proxy
+   * This is the ONLY way addons can make network requests
+   * Domain must be declared in manifest.json permissions.network.domains
+   */
+  function networkFetch(url, options) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingNetwork.set(id, { resolve: resolve, reject: reject })
+      // 30s timeout for network requests
+      setTimeout(function () {
+        if (pendingNetwork.has(id)) {
+          pendingNetwork.delete(id)
+          reject(new Error('Network request timeout (30s)'))
+        }
+      }, 30000)
+      options = options || {}
+      send('NETWORK_REQUEST', {
+        url: url,
+        method: options.method || 'GET',
+        headers: options.headers,
+        body: options.body,
+        requestId: id
+      })
+    })
+  }
+
+  /**
+   * OAuth API request via secure host proxy
+   * Makes authenticated API calls to OAuth providers (GitHub, Google, etc.)
+   * Tokens are stored securely on the server - never exposed to addons
+   *
+   * @param {string} provider - OAuth provider ('github', 'google', 'discord', 'spotify', 'twitch')
+   * @param {string} endpoint - API endpoint path (e.g., '/user', '/user/repos')
+   * @param {object} options - Request options (method, body, headers, requiredScopes)
+   */
+  function oauthRequest(provider, endpoint, options) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingOAuth.set(id, { resolve: resolve, reject: reject })
+      // 30s timeout for OAuth requests
+      setTimeout(function () {
+        if (pendingOAuth.has(id)) {
+          pendingOAuth.delete(id)
+          reject(new Error('OAuth request timeout (30s)'))
+        }
+      }, 30000)
+      options = options || {}
+      send('OAUTH_REQUEST', {
+        provider: provider,
+        endpoint: endpoint,
+        method: options.method || 'GET',
+        body: options.body,
+        headers: options.headers,
+        requiredScopes: options.requiredScopes || [],
+        requestId: id
+      })
+    })
+  }
+
+  /**
+   * Get the scopes granted for a connected OAuth provider
+   * Returns an empty array if not connected
+   *
+   * @param {string} provider - OAuth provider
+   * @returns {Promise<string[]>} Array of granted scopes
+   */
+  function oauthGetScopes(provider) {
+    return new Promise(function (resolve, reject) {
+      var id = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      var handler = function (e) {
+        if (e.source !== window.parent) return
+        var d = e.data
+        if (!d || d.source !== 'MyWallpaperHost') return
+        if (d.type === 'OAUTH_SCOPES_RESPONSE' && d.payload.requestId === id) {
+          window.removeEventListener('message', handler)
+          if (d.payload.success) {
+            resolve(d.payload.scopes || [])
+          } else {
+            reject(new Error(d.payload.error || 'Failed to get scopes'))
+          }
+        }
+      }
+      window.addEventListener('message', handler)
+      // 10s timeout
+      setTimeout(function () {
+        window.removeEventListener('message', handler)
+        resolve([]) // Return empty array on timeout (not connected)
+      }, 10000)
+      send('OAUTH_GET_SCOPES', { provider: provider, requestId: id })
+    })
+  }
+
+  /**
+   * Request re-authorization with additional scopes
+   * Opens the OAuth flow with new scopes while preserving existing ones
+   *
+   * @param {string} provider - OAuth provider
+   * @param {string[]} scopes - Additional scopes to request
+   * @param {string} reason - Reason shown to user
+   * @returns {Promise<boolean>} True if re-auth was successful
+   */
+  function oauthRequestScopes(provider, scopes, reason) {
+    return new Promise(function (resolve) {
+      var requestId = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+      pendingOAuthScopes.set(requestId, resolve)
+      // 60s timeout - user needs time to complete OAuth flow
+      setTimeout(function () {
+        if (pendingOAuthScopes.has(requestId)) {
+          pendingOAuthScopes.delete(requestId)
+          resolve(false)
+        }
+      }, 60000)
+      send('OAUTH_REQUEST_SCOPES', { provider: provider, scopes: scopes, reason: reason, requestId: requestId })
+    })
+  }
+
+  window.addEventListener('message', onMessage)
+
+  window.MyWallpaper = {
+    get config() { return config },
+    layerId: layerId,
+    version: '2.5',
+
+    onSettingsChange: function (fn) { if (typeof fn === 'function') settingsCallbacks.push(fn) },
+
+    onEvent: function (event, fn) {
+      if (typeof fn !== 'function') return
+      if (!eventCallbacks.has(event)) eventCallbacks.set(event, new Set())
+      eventCallbacks.get(event).add(fn)
+    },
+
+    offEvent: function (event, fn) {
+      var cbs = eventCallbacks.get(event)
+      if (cbs) cbs.delete(fn)
+    },
+
+    onMount: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.mount.push(fn) },
+    onUnmount: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.unmount.push(fn) },
+    onPause: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.pause.push(fn) },
+    onResume: function (fn) { if (typeof fn === 'function') lifecycleCallbacks.resume.push(fn) },
+
+    ready: function (opts) {
+      if (isReady) return
+      isReady = true
+      opts = opts || {}
+      send('ADDON_READY', {
+        version: '2.5',
+        capabilities: opts.capabilities || [],
+        subscribedEvents: opts.subscribedEvents || []
+      })
+    },
+
+    requestPermission: function (perm, reason) {
+      return new Promise(function (resolve) {
+        var requestId = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+        pendingPermissions.set(requestId, resolve)
+        // 30s timeout - user needs time to see and respond to permission modal
+        setTimeout(function () {
+          if (pendingPermissions.has(requestId)) {
+            pendingPermissions.delete(requestId)
+            resolve(false) // Timeout = denied
+          }
+        }, 30000)
+        send('REQUEST_PERMISSION', { permission: perm, reason: reason, requestId: requestId })
+      })
+    },
+
+    renderComplete: function () {
+      if (isRenderComplete) return
+      isRenderComplete = true
+      var renderTimeMs = Math.round(performance.now())
+      send('RENDER_COMPLETE', { renderTimeMs: renderTimeMs })
+    },
+
+    storage: {
+      get: function (k) { return storageOp('get', k) },
+      set: function (k, v) { return storageOp('set', k, v) },
+      delete: function (k) { return storageOp('delete', k) },
+      clear: function () { return storageOp('clear') },
+      keys: function () { return storageOp('keys') },
+      size: function () { return storageOp('size') }
+    },
+
+    /**
+     * Network API - Secure proxy for HTTP requests
+     * All requests go through the host which validates domain whitelist
+     *
+     * @example
+     * // manifest.json: "permissions": { "network": { "domains": ["api.weather.com"] } }
+     * const response = await MyWallpaper.network.fetch('https://api.weather.com/current')
+     * if (response.ok) console.log(response.data)
+     */
+    network: {
+      fetch: networkFetch
+    },
+
+    /**
+     * OAuth API - Secure authenticated API calls to OAuth providers
+     * Tokens are stored securely on the server - never exposed to addons
+     *
+     * Supported providers: github, google, discord, spotify, twitch
+     *
+     * @example
+     * // First request permission
+     * const granted = await MyWallpaper.requestPermission('oauth:github', 'To display your GitHub profile')
+     * if (granted) {
+     *   // Make authenticated API request
+     *   const response = await MyWallpaper.oauth.request('github', '/user')
+     *   if (response.ok) console.log('GitHub user:', response.data)
+     *
+     *   // List repositories (with required scopes)
+     *   const repos = await MyWallpaper.oauth.request('github', '/user/repos', {
+     *     requiredScopes: ['repo']  // Will return scope error if missing
+     *   })
+     *   if (repos.error === 'insufficient_scopes') {
+     *     // Request additional scopes
+     *     const granted = await MyWallpaper.oauth.requestScopes('github', repos.missingScopes, 'Access private repos')
+     *     if (granted) {
+     *       // Retry request
+     *       const repos = await MyWallpaper.oauth.request('github', '/user/repos', { requiredScopes: ['repo'] })
+     *     }
+     *   }
+     * }
+     */
+    oauth: {
+      request: oauthRequest,
+      getScopes: oauthGetScopes,
+      requestScopes: oauthRequestScopes,
+      isConnected: function (provider) {
+        // Check connection by getting scopes - if scopes array is returned, provider is connected
+        return oauthGetScopes(provider)
+          .then(function (scopes) { return scopes.length > 0 })
+          .catch(function () { return false })
+      }
+    },
+
+    /**
+     * File Access API - Request access to user-uploaded files
+     * Files are not sent automatically - the addon must request access
+     * A modal is shown to the user EVERY TIME (not persisted)
+     *
+     * @example
+     * const videoRef = MyWallpaper.config.backgroundVideo
+     * if (MyWallpaper.files.isFileReference(videoRef)) {
+     *   const result = await MyWallpaper.files.request('backgroundVideo')
+     *   if (result.granted) {
+     *     video.src = result.blobUrl
+     *   }
+     * }
+     */
+    files: {
+      /**
+       * Check if a value is a file reference placeholder
+       * @param {unknown} value - Any value from config
+       * @returns {boolean} true if this is a FileReference
+       */
+      isFileReference: function (value) {
+        return value !== null &&
+          typeof value === 'object' &&
+          value.__type === 'file-reference' &&
+          typeof value.settingKey === 'string'
+      },
+
+      /**
+       * Request access to a file from the user
+       * Shows a modal asking for permission (every time)
+       * @param {string} settingKey - The setting key containing the file reference
+       * @returns {Promise<{granted: boolean, blobUrl?: string, error?: string}>}
+       */
+      request: function (settingKey) {
+        return new Promise(function (resolve) {
+          var requestId = Date.now() + '-' + Math.random().toString(36).slice(2)
+          pendingFileAccess.set(requestId, { resolve: resolve })
+          // 60s timeout - user needs time to respond to modal
+          setTimeout(function () {
+            if (pendingFileAccess.has(requestId)) {
+              pendingFileAccess.delete(requestId)
+              resolve({ granted: false, error: 'Request timeout' })
+            }
+          }, 60000)
+          send('FILE_ACCESS_REQUEST', { settingKey: settingKey, requestId: requestId })
+        })
+      },
+
+      /**
+       * Revoke access to a previously granted file
+       * The blob URL will be invalidated
+       * @param {string} settingKey - The setting key to revoke access for
+       */
+      revoke: function (settingKey) {
+        var blobUrl = grantedBlobUrls.get(settingKey)
+        if (blobUrl) {
+          URL.revokeObjectURL(blobUrl)
+          grantedBlobUrls.delete(settingKey)
+        }
+      }
+    },
+
+    /**
+     * Audio API - Parent-managed audio playback
+     * Audio is played by the host (parent window) to bypass iframe sandbox restrictions
+     * The addon controls playback via commands, host syncs state back
+     *
+     * @example
+     * // Play audio from a URL
+     * MyWallpaper.audio.play('https://example.com/sound.mp3', { volume: 0.8 })
+     *
+     * // Play audio from a file setting
+     * MyWallpaper.audio.play('audioFile')  // settingKey
+     *
+     * // Listen to state changes
+     * MyWallpaper.audio.onStateChange(function(state) {
+     *   console.log('Audio status:', state.status, 'Time:', state.currentTime)
+     * })
+     */
+    audio: {
+      /**
+       * Play audio from a source
+       * @param {string|object} source - URL, settingKey, or FileReference
+       * @param {object} options - { volume, loop, playbackRate, startTime }
+       */
+      play: function (source, options) {
+        var payload = { command: 'play', options: options || {} }
+
+        if (typeof source === 'string') {
+          if (source.startsWith('http') || source.startsWith('data:') || source.startsWith('blob:')) {
+            payload.url = source
+          } else {
+            // Assume it's a settingKey
+            payload.settingKey = source
+          }
+        } else if (source && source.__type === 'file-reference') {
+          payload.fileRef = source
+        } else if (source && source.settingKey) {
+          payload.settingKey = source.settingKey
+        }
+
+        send('AUDIO_COMMAND', payload)
+      },
+
+      /** Pause audio playback */
+      pause: function () {
+        send('AUDIO_COMMAND', { command: 'pause' })
+      },
+
+      /** Resume audio playback */
+      resume: function () {
+        send('AUDIO_COMMAND', { command: 'resume' })
+      },
+
+      /** Stop and reset audio */
+      stop: function () {
+        send('AUDIO_COMMAND', { command: 'stop' })
+      },
+
+      /**
+       * Seek to position
+       * @param {number} seconds - Position in seconds
+       */
+      seek: function (seconds) {
+        send('AUDIO_COMMAND', { command: 'seek', value: seconds })
+      },
+
+      /**
+       * Set volume
+       * @param {number} volume - Volume from 0.0 to 1.0
+       */
+      setVolume: function (volume) {
+        send('AUDIO_COMMAND', { command: 'setVolume', value: Math.max(0, Math.min(1, volume)) })
+      },
+
+      /**
+       * Enable or disable loop
+       * @param {boolean} loop - Whether to loop
+       */
+      setLoop: function (loop) {
+        send('AUDIO_COMMAND', { command: 'setLoop', value: !!loop })
+      },
+
+      /**
+       * Set playback rate
+       * @param {number} rate - Playback rate (0.25 to 4.0)
+       */
+      setPlaybackRate: function (rate) {
+        send('AUDIO_COMMAND', { command: 'setPlaybackRate', value: rate })
+      },
+
+      /**
+       * Get current audio state
+       * @returns {object} { status, currentTime, duration, volume, loop, playbackRate, error? }
+       */
+      getState: function () {
+        return {
+          status: audioState.status,
+          currentTime: audioState.currentTime,
+          duration: audioState.duration,
+          volume: audioState.volume,
+          loop: audioState.loop,
+          playbackRate: audioState.playbackRate,
+          error: audioState.error
+        }
+      },
+
+      /**
+       * Listen to audio state changes
+       * @param {function} callback - Called with AudioState on each change
+       * @returns {function} Unsubscribe function
+       */
+      onStateChange: function (callback) {
+        if (typeof callback !== 'function') return function () { }
+        audioCallbacks.add(callback)
+        // Call immediately with current state
+        callback(audioState)
+        return function () { audioCallbacks.delete(callback) }
+      }
+    }
+  }
+
+  console.warn('[MyWallpaper] SDK v2.5 ready:', layerId)
+})()