Extension Development Guide

my-extension.spotiflac-ext (ZIP)
├── manifest.json      # Required: Metadata and configuration
├── main.js           # Required: Main JavaScript code
└── icon.png          # Optional: Extension icon (PNG, 128x128 recommended)

{
  "name": "my-music-provider",
  "displayName": "My Music Provider",
  "version": "1.0.0",
  "description": "Extension for downloading from MyMusic service",
  "author": "Your Name",
  "homepage": "https://github.com/username/my-extension",
  "icon": "icon.png",

  "permissions": {
    "network": ["api.mymusic.com", "cdn.mymusic.com"],
    "storage": true,
    "file": true
  },

  "type": ["metadata_provider", "download_provider"],
  
  "skipMetadataEnrichment": false,
  "skipBuiltInFallback": false,

  "qualityOptions": [
    {
      "id": "LOSSLESS",
      "label": "FLAC Lossless",
      "description": "16-bit / 44.1kHz"
    },
    {
      "id": "MP3_320",
      "label": "MP3 320kbps",
      "description": "High quality MP3"
    },
    {
      "id": "OPUS_128",
      "label": "Opus 128kbps",
      "description": "Efficient audio codec"
    }
  ],

  "settings": [
    {
      "key": "apiKey",
      "label": "API Key",
      "type": "string",
      "description": "API key from MyMusic",
      "required": true
    },
    {
      "key": "quality",
      "label": "Audio Quality",
      "type": "select",
      "options": ["LOSSLESS", "HIGH", "NORMAL"],
      "default": "LOSSLESS"
    },
    {
      "key": "enableCache",
      "label": "Enable Cache",
      "type": "boolean",
      "default": true
    }
  ]
}

"qualityOptions": [
  {
    "id": "MP3_320",
    "label": "MP3 320kbps",
    "description": "High quality MP3"
  },
  {
    "id": "OPUS_128",
    "label": "Opus 128kbps",
    "description": "Efficient audio codec"
  },
  {
    "id": "AAC_256",
    "label": "AAC 256kbps",
    "description": "Apple audio format"
  }
]

"qualityOptions": [
  {
    "id": "PREMIUM_FLAC",
    "label": "Premium FLAC",
    "description": "24-bit Hi-Res (requires premium)",
    "settings": [
      {
        "key": "premium_api_key",
        "type": "string",
        "label": "Premium API Key",
        "description": "API key for premium tier access",
        "required": true,
        "secret": true
      },
      {
        "key": "premium_endpoint",
        "type": "string",
        "label": "Premium Endpoint",
        "default": "https://api.example.com/premium/stream"
      }
    ]
  },
  {
    "id": "FREE_MP3",
    "label": "Free MP3",
    "description": "128kbps (free tier)",
    "settings": [
      {
        "key": "free_endpoint",
        "type": "string",
        "label": "Free Endpoint",
        "default": "https://api.example.com/free/stream"
      }
    ]
  }
]

function download(trackId, quality, outputPath, progressCallback) {
  // Get quality-specific settings
  const qualitySettings = settings.qualitySettings?.[quality] || {};
  
  let endpoint;
  let apiKey;
  
  if (quality === 'PREMIUM_FLAC') {
    endpoint = qualitySettings.premium_endpoint || 'https://api.example.com/premium/stream';
    apiKey = qualitySettings.premium_api_key;
    if (!apiKey) {
      return { success: false, error: 'Premium API key required', error_type: 'auth_error' };
    }
  } else {
    endpoint = qualitySettings.free_endpoint || 'https://api.example.com/free/stream';
    apiKey = settings.api_key; // Use global API key for free tier
  }
  
  // ... download logic using endpoint and apiKey
}

"permissions": {
  "network": [
    "api.example.com",    // HTTP access to specific domain
    "*.example.com"       // Wildcard subdomain
  ],
  "storage": true,        // Storage API access (for caching, settings)
  "file": true            // File API access (for downloads, file operations)
}

"type": [
  "metadata_provider",   // Provides search/metadata
  "download_provider"    // Provides downloads
]

"settings": [
  {
    "key": "username",
    "label": "Username",
    "type": "string",
    "description": "Your account username",
    "required": true
  },
  {
    "key": "region",
    "label": "Region",
    "type": "select",
    "options": ["ID", "US", "JP", "UK"],
    "default": "ID"
  },
  {
    "key": "debug",
    "label": "Debug Mode",
    "type": "boolean",
    "default": false
  },
  {
    "key": "maxRetries",
    "label": "Max Retries",
    "type": "number",
    "default": 3
  }
]

"settings": [
  {
    "key": "login_button",
    "label": "Login to Service",
    "type": "button",
    "description": "Click to authenticate with your account",
    "action": "startLogin"
  },
  {
    "key": "clear_cache",
    "label": "Clear Cache",
    "type": "button",
    "description": "Remove all cached data",
    "action": "clearCache"
  }
]

// In your extension's index.js
function startLogin() {
  // Start OAuth flow
  auth.startOAuthWithPKCE({
    authUrl: "https://accounts.example.com/authorize",
    tokenUrl: "https://accounts.example.com/token",
    clientId: settings.clientId,
    scopes: ["streaming", "user-read-private"],
    redirectUri: "spotiflac://auth/callback"
  });
  
  return { success: true, message: "Opening login page..." };
}

function clearCache() {
  storage.clear();
  return { success: true, message: "Cache cleared!" };
}

// Register the action functions
registerExtension({
  initialize: initialize,
  cleanup: cleanup,
  startLogin: startLogin,     // Button action
  clearCache: clearCache,     // Button action
  // ... other functions
});

// Success
{ success: true, message: "Optional success message" }

// Error
{ success: false, error: "Error description" }

"settings": [
  {
    "key": "api_key",
    "label": "API Key",
    "type": "string",
    "description": "Your API key from the service",
    "required": true,
    "secret": true
  }
]

"searchBehavior": {
  "enabled": true,
  "placeholder": "Search YouTube...",
  "primary": false,
  "icon": "youtube.png",
  "thumbnailRatio": "wide",
  "thumbnailWidth": 100,
  "thumbnailHeight": 56
}

"searchBehavior": {
  "enabled": true,
  "placeholder": "Search YouTube...",
  "thumbnailRatio": "wide"
}

"searchBehavior": {
  "enabled": true,
  "thumbnailWidth": 120,
  "thumbnailHeight": 68
}

function customSearch(query, options) {
  // Search your platform
  const results = http.get(`https://api.example.com/search?q=${encodeURIComponent(query)}`);
  // Return array of track objects
  return JSON.parse(results.body).tracks.map(t => ({
    id: t.id,
    name: t.title,
    artists: t.artist,
    album_name: t.album,
    duration_ms: t.duration * 1000,
    images: t.thumbnail  // Thumbnail URL (will use thumbnailRatio for display)
  }));
}

"urlHandler": {
  "enabled": true,
  "patterns": [
    "music.youtube.com",
    "youtube.com/watch",
    "youtu.be"
  ]
}

// YouTube Music
"patterns": ["music.youtube.com", "youtube.com/watch", "youtu.be"]

// SoundCloud
"patterns": ["soundcloud.com"]

// Bandcamp
"patterns": ["bandcamp.com"]

/**
 * Handle a URL from the user
 * @param {string} url - The full URL to handle
 * @returns {Object} Track, Album, or Artist metadata
 */
function handleURL(url) {
  // Parse the URL to determine content type
  const urlType = detectUrlType(url);
  
  if (urlType === 'track') {
    return handleTrackUrl(url);
  } else if (urlType === 'album') {
    return handleAlbumUrl(url);
  } else if (urlType === 'artist') {
    return handleArtistUrl(url);
  }
  
  return {
    success: false,
    error: "Unsupported URL type"
  };
}

// Return a single track
function handleTrackUrl(url) {
  const trackId = extractTrackId(url);
  const data = fetchTrackData(trackId);
  
  return {
    success: true,
    type: "track",  // Optional, defaults to "track"
    track: {
      id: data.id,
      name: data.title,
      artists: data.artist,
      album_name: data.album || "Unknown Album",
      duration_ms: data.duration * 1000,
      images: data.thumbnail
    }
  };
}

// Return an album with tracks
function handleAlbumUrl(url) {
  const albumId = extractAlbumId(url);
  const data = fetchAlbumData(albumId);
  
  return {
    success: true,
    type: "album",
    album: {
      id: data.id,
      name: data.title,
      artists: data.artist,
      release_date: data.releaseDate,
      total_tracks: data.tracks.length,
      images: data.cover,
      album_type: data.type,  // "album", "single", "compilation"
      tracks: data.tracks.map(t => ({
        id: t.id,
        name: t.title,
        artists: t.artist,
        album_name: data.title,
        duration_ms: t.duration * 1000,
        track_number: t.trackNumber,
        disc_number: t.discNumber || 1,
        isrc: t.isrc
      }))
    }
  };
}

// Return an artist with albums
function handleArtistUrl(url) {
  const artistId = extractArtistId(url);
  const data = fetchArtistData(artistId);
  
  return {
    success: true,
    type: "artist",
    artist: {
      id: data.id,
      name: data.name,
      image_url: data.picture,
      albums: data.albums.map(a => ({
        id: a.id,
        name: a.title,
        artists: data.name,
        release_date: a.releaseDate,
        total_tracks: a.trackCount,
        images: a.cover,
        album_type: a.type  // "album", "single", "compilation"
      }))
    }
  };
}

registerExtension({
  initialize: initialize,
  cleanup: cleanup,
  handleURL: handleURL,  // Add this!
  // ... other functions
});

{
  "minAppVersion": "3.0.1",
  "type": ["metadata_provider"]
}

function customSearch(query, options) {
  const results = searchAPI(query);
  
  return results.map(item => {
    if (item.type === 'track') {
      return {
        id: item.id,
        name: item.title,
        artists: item.artist,
        album_name: item.album,
        duration_ms: item.duration * 1000,
        cover_url: item.thumbnail,
        item_type: "track"  // Optional, default
      };
    } else if (item.type === 'album' || item.type === 'ep' || item.type === 'single') {
      return {
        id: item.id,              // Album/browse ID
        name: item.title,
        artists: item.artist,
        album_name: item.title,   // Same as name for albums
        album_type: item.type,    // "album", "ep", "single", "playlist"
        release_date: item.year,
        cover_url: item.thumbnail,
        item_type: "album"        // REQUIRED for albums
      };
    } else if (item.type === 'playlist') {
      return {
        id: item.id,              // Playlist ID
        name: item.title,
        artists: item.owner,      // Playlist owner
        album_name: item.title,
        album_type: "playlist",
        cover_url: item.thumbnail,
        item_type: "playlist"     // REQUIRED for playlists
      };
    }
  });
}

/**
 * Fetch album tracks by ID
 * @param {string} albumId - Album ID from search result
 * @returns {Object} Album with tracks array
 */
function getAlbum(albumId) {
  const data = fetchAlbumData(albumId);
  
  return {
    id: albumId,
    name: data.title,
    artists: data.artist,
    cover_url: data.thumbnail,
    release_date: data.year,
    total_tracks: data.tracks.length,
    album_type: data.type,  // "album", "ep", "single"
    tracks: data.tracks.map(t => ({
      id: t.id,
      name: t.title,
      artists: t.artist,
      album_name: data.title,
      duration_ms: t.duration * 1000,
      cover_url: t.thumbnail || data.thumbnail,
      track_number: t.trackNumber,
      provider_id: "your-extension-id"
    })),
    provider_id: "your-extension-id"
  };
}

/**
 * Fetch playlist tracks by ID
 * @param {string} playlistId - Playlist ID from search result
 * @returns {Object} Playlist with tracks array
 */
function getPlaylist(playlistId) {
  const data = fetchPlaylistData(playlistId);
  
  return {
    id: playlistId,
    name: data.title,
    owner: data.owner,
    cover_url: data.thumbnail,
    total_tracks: data.tracks.length,
    tracks: data.tracks.map(t => ({
      id: t.id,
      name: t.title,
      artists: t.artist,
      album_name: t.album || data.title,
      duration_ms: t.duration * 1000,
      cover_url: t.thumbnail,
      provider_id: "your-extension-id"
    })),
    provider_id: "your-extension-id"
  };
}

// Register functions
registerExtension({
  initialize: initialize,
  customSearch: customSearch,
  getAlbum: getAlbum,       // Required for album support
  getPlaylist: getPlaylist, // Required for playlist support
  // ... other functions
});

function customSearch(query) {
  const results = searchAPI(query);
  
  return results.map(item => {
    if (item.type === "artist") {
      return {
        id: item.id,
        name: item.name,
        artists: item.name,      // Artist name in artists field for consistency
        cover_url: item.thumbnail,
        item_type: "artist"      // REQUIRED for artist items
      };
    }
    // ... handle tracks, albums, playlists
  });
}

/**
 * Fetch artist info and albums by ID
 * @param {string} artistId - Artist ID from search result
 * @returns {Object} Artist info with albums array
 */
function getArtist(artistId) {
  const data = fetchArtistData(artistId);
  
  return {
    id: artistId,
    name: data.name,
    image_url: data.thumbnail,
    albums: data.albums.map(album => ({
      id: album.id,
      name: album.title,
      artists: data.name,
      cover_url: album.thumbnail,
      release_date: album.year,
      total_tracks: album.trackCount || 0,
      album_type: album.type || "album",  // "album", "ep", "single"
      provider_id: "your-extension-id"
    })),
    provider_id: "your-extension-id"
  };
}

// Register function
registerExtension({
  // ... other functions
  getArtist: getArtist,  // Required for artist support
});

/**
 * Enrich track metadata before download
 * @param {Object} track - Track object from search/album/playlist
 * @returns {Object} Enriched track object
 */
function enrichTrack(track) {
  if (!track || !track.id) {
    return track;
  }
  
  // Example: Use Odesli API to get ISRC and external links
  const ytUrl = "https://music.youtube.com/watch?v=" + encodeURIComponent(track.id);
  const odesliUrl = "https://api.song.link/v1-alpha.1/links?url=" + encodeURIComponent(ytUrl);
  
  try {
    const res = fetch(odesliUrl, { method: "GET" });
    if (!res || !res.ok) {
      return track;
    }
    
    const data = res.json();
    const enrichment = {};
    
    // Extract ISRC from entities
    if (data.entitiesByUniqueId) {
      for (const key of Object.keys(data.entitiesByUniqueId)) {
        const entity = data.entitiesByUniqueId[key];
        if (entity && entity.isrc) {
          enrichment.isrc = entity.isrc;
          break;
        }
      }
    }
    
    // Extract external links for fallback downloads
    if (data.linksByPlatform) {
      enrichment.external_links = {};
      
      if (data.linksByPlatform.deezer) {
        enrichment.external_links.deezer = data.linksByPlatform.deezer.url;
        // Extract Deezer track ID
        const match = data.linksByPlatform.deezer.url.match(/\/track\/(\d+)/);
        if (match) enrichment.deezer_id = match[1];
      }
      if (data.linksByPlatform.tidal) {
        enrichment.external_links.tidal = data.linksByPlatform.tidal.url;
      }
      if (data.linksByPlatform.spotify) {
        enrichment.external_links.spotify = data.linksByPlatform.spotify.url;
      }
    }
    
    return Object.assign({}, track, enrichment);
  } catch (e) {
    log.error("enrichTrack failed", e);
    return track;
  }
}

// Register function
registerExtension({
  // ... other functions
  enrichTrack: enrichTrack,  // Optional: enrich tracks before download
});

Extension Search (YouTube Music, SoundCloud, etc.)
       │
       ▼
   enrichTrack() called before download
       │
       ▼
   Odesli API returns: tidal_id, qobuz_id, isrc
       │
       ▼
   SpotiFLAC downloads from Tidal/Qobuz using direct ID
       │
       ▼
   High-quality FLAC/MQA audio (no search needed!)

"trackMatching": {
  "customMatching": true,
  "strategy": "custom",
  "durationTolerance": 5
}

function matchTrack(sourceTrack, candidates) {
  // sourceTrack: { name, artists, duration_ms, isrc, ... }
  // candidates: array of tracks from your search
  
  // Use built-in matching helpers
  const normalizedSource = matching.normalizeString(sourceTrack.name);
  
  for (const candidate of candidates) {
    const normalizedCandidate = matching.normalizeString(candidate.name);
    const similarity = matching.compareStrings(normalizedSource, normalizedCandidate);
    const durationMatch = matching.compareDuration(sourceTrack.duration_ms, candidate.duration_ms, 3000);
    
    if (similarity > 0.8 && durationMatch) {
      return {
        matched: true,
        track_id: candidate.id,
        confidence: similarity
      };
    }
  }
  
  return { matched: false, reason: "No match found" };
}

"postProcessing": {
  "enabled": true,
  "hooks": [
    {
      "id": "convert_mp3",
      "name": "Convert to MP3",
      "description": "Convert FLAC to MP3 320kbps",
      "defaultEnabled": false,
      "supportedFormats": ["flac"]
    },
    {
      "id": "normalize",
      "name": "Normalize Audio",
      "description": "Apply ReplayGain normalization",
      "defaultEnabled": true,
      "supportedFormats": ["flac", "mp3"]
    }
  ]
}

function postProcess(filePath, metadata, hookId) {
  if (hookId === 'convert_mp3') {
    const outputPath = filePath.replace('.flac', '.mp3');
    
    // Use FFmpeg API
    const result = ffmpeg.convert(filePath, outputPath, {
      codec: 'libmp3lame',
      bitrate: '320k'
    });
    
    if (result.success) {
      // Delete original file
      file.delete(filePath);
      return { success: true, new_file_path: outputPath };
    }
    return { success: false, error: result.error };
  }
  
  if (hookId === 'normalize') {
    // Apply ReplayGain
    const result = ffmpeg.execute(`-i "${filePath}" -af "loudnorm" -y "${filePath}.tmp"`);
    if (result.success) {
      file.move(filePath + '.tmp', filePath);
      return { success: true, new_file_path: filePath };
    }
    return { success: false, error: result.error };
  }
  
  return { success: true, new_file_path: filePath };
}

// ============================================
// Extension: My Music Provider
// Version: 1.0.0
// ============================================

// Global variable to store settings
let settings = {};

// ============================================
// LIFECYCLE HOOKS (Required)
// ============================================

/**
 * Called when extension is loaded
 * @param {Object} config - User settings
 */
function initialize(config) {
  settings = config || {};
  log.info("Extension initialized with settings:", settings);

  // Validate required settings
  if (!settings.apiKey) {
    throw new Error("API Key is required");
  }

  return true;
}

/**
 * Called when extension is unloaded
 */
function cleanup() {
  log.info("Extension cleanup");
  // Clean up resources if any
}

// ============================================
// METADATA PROVIDER (Optional)
// ============================================

/**
 * Search tracks by query
 * @param {string} query - Search query
 * @param {number} limit - Max results
 * @returns {Array} Array of track objects
 */
function searchTracks(query, limit) {
  log.debug("Searching:", query);

  const response = http.get("https://api.mymusic.com/search", {
    params: {
      q: query,
      type: "track",
      limit: limit
    },
    headers: {
      "Authorization": "Bearer " + settings.apiKey
    }
  });

  if (!response.ok) {
    log.error("Search failed:", response.status);
    return [];
  }

  const data = JSON.parse(response.body);

  // Transform to SpotiFLAC format
  return data.tracks.map(track => ({
    id: track.id,
    name: track.title,
    artists: track.artist.name,
    album_name: track.album.title,
    album_artist: track.album.artist.name,
    isrc: track.isrc,
    duration_ms: track.duration * 1000,
    track_number: track.trackNumber,
    disc_number: track.discNumber || 1,
    release_date: track.album.releaseDate,
    images: track.album.cover
  }));
}


/**
 * Get track detail by ID
 * @param {string} trackId - Track ID
 * @returns {Object} Track object
 */
function getTrack(trackId) {
  const response = http.get("https://api.mymusic.com/tracks/" + trackId, {
    headers: {
      "Authorization": "Bearer " + settings.apiKey
    }
  });

  if (!response.ok) {
    return null;
  }

  const track = JSON.parse(response.body);

  return {
    id: track.id,
    name: track.title,
    artists: track.artist.name,
    album_name: track.album.title,
    album_artist: track.album.artist.name,
    isrc: track.isrc,
    duration_ms: track.duration * 1000,
    track_number: track.trackNumber,
    disc_number: track.discNumber || 1,
    release_date: track.album.releaseDate,
    images: track.album.cover
  };
}

/**
 * Get album detail by ID
 * @param {string} albumId - Album ID
 * @returns {Object} Album object with tracks
 */
function getAlbum(albumId) {
  const response = http.get("https://api.mymusic.com/albums/" + albumId, {
    headers: {
      "Authorization": "Bearer " + settings.apiKey
    }
  });

  if (!response.ok) {
    return null;
  }

  const album = JSON.parse(response.body);

  return {
    id: album.id,
    name: album.title,
    artists: album.artist.name,
    release_date: album.releaseDate,
    total_tracks: album.trackCount,
    images: album.cover,
    tracks: album.tracks.map(track => ({
      id: track.id,
      name: track.title,
      artists: track.artist.name,
      album_name: album.title,
      isrc: track.isrc,
      duration_ms: track.duration * 1000,
      track_number: track.trackNumber,
      disc_number: track.discNumber || 1
    }))
  };
}

/**
 * Get artist detail by ID
 * @param {string} artistId - Artist ID
 * @returns {Object} Artist object
 */
function getArtist(artistId) {
  const response = http.get("https://api.mymusic.com/artists/" + artistId, {
    headers: {
      "Authorization": "Bearer " + settings.apiKey
    }
  });

  if (!response.ok) {
    return null;
  }

  const artist = JSON.parse(response.body);

  return {
    id: artist.id,
    name: artist.name,
    images: artist.picture,
    albums: artist.albums.map(album => ({
      id: album.id,
      name: album.title,
      release_date: album.releaseDate,
      total_tracks: album.trackCount,
      images: album.cover,
      album_type: album.type
    }))
  };
}

/**
 * Enrich track metadata before download (lazy enrichment hook)
 * 
 * This function is called by the runtime just before download starts.
 * Use this to fetch expensive metadata (like real ISRC) that you don't
 * want to fetch upfront when loading playlists/albums.
 * 
 * Benefits:
 * - Playlists/albums load instantly without waiting for enrichment
 * - Only tracks that are actually downloaded get enriched
 * - Reduces API calls for tracks that are never downloaded
 * 
 * @param {Object} track - Track metadata object
 * @param {string} track.id - Track ID
 * @param {string} track.name - Track name
 * @param {string} track.artists - Artist name(s)
 * @param {string} track.isrc - Current ISRC (may be placeholder)
 * @param {number} track.duration_ms - Duration in milliseconds
 * @returns {Object} Enriched track metadata (or original if no enrichment needed)
 * 
 * @example
 * function enrichTrack(track) {
 *   // Only enrich if ISRC looks like a placeholder (e.g., Spotify ID)
 *   if (track.isrc && track.isrc.length === 22) {
 *     // Fetch real ISRC from external API
 *     const realISRC = fetchRealISRC(track.id);
 *     if (realISRC) {
 *       track.isrc = realISRC;
 *     }
 *   }
 *   return track;
 * }
 */
function enrichTrack(track) {
  // Example: Fetch real ISRC via SongLink -> Deezer
  if (track.isrc && track.isrc.length === 22) {
    // This looks like a Spotify ID, not a real ISRC
    const deezerUrl = getDeezerUrlFromSongLink(track.id);
    if (deezerUrl) {
      const realISRC = getISRCFromDeezer(deezerUrl);
      if (realISRC) {
        log.info("Enriched ISRC:", track.isrc, "->", realISRC);
        track.isrc = realISRC;
      }
    }
  }
  return track;
}

// ============================================
// ODESLI (SONG.LINK) INTEGRATION EXAMPLE
// ============================================
// The Odesli API is useful for:
// - Converting YouTube/SoundCloud tracks to ISRC
// - Finding the same track on Deezer/Tidal/Spotify
// - Enabling built-in service fallback for extensions that don't have ISRCs

/**
 * Example: Enrich YouTube Music tracks with ISRC via Odesli
 * @param {Object} track - Track metadata from extension
 * @returns {Object} Enriched track with ISRC and external links
 */
function enrichTrackWithOdesli(track) {
  if (!track || !track.id) return track;
  
  // Build YouTube Music URL for Odesli lookup
  var ytUrl = "https://music.youtube.com/watch?v=" + encodeURIComponent(track.id);
  var odesliUrl = "https://api.song.link/v1-alpha.1/links?url=" + encodeURIComponent(ytUrl);
  
  try {
    var res = fetch(odesliUrl, {
      method: "GET",
      headers: {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      }
    });
    
    if (!res || !res.ok) return track;
    
    var data = res.json();
    if (!data) return track;
    
    // Extract ISRC from entitiesByUniqueId
    if (data.entitiesByUniqueId) {
      var entities = data.entitiesByUniqueId;
      var entityKeys = Object.keys(entities);
      
      for (var i = 0; i < entityKeys.length; i++) {
        var entity = entities[entityKeys[i]];
        if (entity && entity.isrc) {
          track.isrc = entity.isrc;
          log.info("enrichTrack: found ISRC", track.isrc);
          break;
        }
      }
    }
    
    // Extract links to other services (optional)
    if (data.linksByPlatform) {
      var links = data.linksByPlatform;
      track.external_links = {};
      
      if (links.deezer && links.deezer.url) {
        track.external_links.deezer = links.deezer.url;
        // Extract Deezer track ID
        var deezerMatch = links.deezer.url.match(/\/track\/(\d+)/);
        if (deezerMatch) track.deezer_id = deezerMatch[1];
      }
      if (links.tidal && links.tidal.url) {
        track.external_links.tidal = links.tidal.url;
      }
      if (links.spotify && links.spotify.url) {
        track.external_links.spotify = links.spotify.url;
      }
    }
    
    return track;
  } catch (e) {
    log.error("enrichTrack: Odesli API error", String(e));
    return track;
  }
}

// Don't forget to add odesli.io/api.song.link to manifest permissions:
// "permissions": {
//   "network": ["api.song.link", "odesli.io", ...]
// }


// ============================================
// DOWNLOAD PROVIDER (Optional)
// ============================================

/**
 * Check if track is available for download
 * @param {string} isrc - ISRC code
 * @param {string} trackName - Track name (fallback)
 * @param {string} artistName - Artist name (fallback)
 * @returns {Object} Availability info
 */
function checkAvailability(isrc, trackName, artistName) {
  // Search track by ISRC
  let trackId = null;

  if (isrc) {
    const response = http.get("https://api.mymusic.com/search", {
      params: { isrc: isrc },
      headers: { "Authorization": "Bearer " + settings.apiKey }
    });

    if (response.ok) {
      const data = JSON.parse(response.body);
      if (data.tracks && data.tracks.length > 0) {
        trackId = data.tracks[0].id;
      }
    }
  }

  // Fallback: search by name
  if (!trackId) {
    const query = trackName + " " + artistName;
    const response = http.get("https://api.mymusic.com/search", {
      params: { q: query, type: "track", limit: 1 },
      headers: { "Authorization": "Bearer " + settings.apiKey }
    });

    if (response.ok) {
      const data = JSON.parse(response.body);
      if (data.tracks && data.tracks.length > 0) {
        trackId = data.tracks[0].id;
      }
    }
  }

  return {
    available: trackId !== null,
    track_id: trackId,
    quality: settings.quality || "LOSSLESS"
  };
}

/**
 * Get download URL for track
 * @param {string} trackId - Track ID from checkAvailability
 * @param {string} quality - Requested quality
 * @returns {Object} Download info
 */
function getDownloadUrl(trackId, quality) {
  const response = http.get("https://api.mymusic.com/tracks/" + trackId + "/stream", {
    params: { quality: quality },
    headers: { "Authorization": "Bearer " + settings.apiKey }
  });

  if (!response.ok) {
    return { success: false, error: "Failed to get stream URL" };
  }

  const data = JSON.parse(response.body);

  return {
    success: true,
    url: data.url,
    format: data.format,        // "flac", "mp3", "m4a"
    quality: data.quality,
    bit_depth: data.bitDepth,   // 16, 24
    sample_rate: data.sampleRate // 44100, 96000, etc
  };
}


/**
 * Download track to file
 * @param {Object} request - Download request
 * @param {Function} progressCallback - Progress callback
 * @returns {Object} Download result
 */
function download(request, progressCallback) {
  log.info("Downloading:", request.track_name);

  // 1. Check availability
  const availability = checkAvailability(
    request.isrc,
    request.track_name,
    request.artist_name
  );

  if (!availability.available) {
    return {
      success: false,
      error: "Track not available",
      error_type: "not_found"
    };
  }

  // 2. Get download URL
  const downloadInfo = getDownloadUrl(
    availability.track_id,
    request.quality || "LOSSLESS"
  );

  if (!downloadInfo.success) {
    return {
      success: false,
      error: downloadInfo.error,
      error_type: "stream_error"
    };
  }

  // 3. Build output filename
  const extension = downloadInfo.format === "flac" ? ".flac" : ".m4a";
  const filename = gobackend.sanitizeFilename(
    request.track_name + " - " + request.artist_name
  ) + extension;
  const outputPath = request.output_dir + "/" + filename;

  // 4. Download file with progress
  const result = file.download(downloadInfo.url, outputPath, {
    headers: {
      "Authorization": "Bearer " + settings.apiKey
    },
    onProgress: function(received, total) {
      const percent = total > 0 ? received / total : 0;
      progressCallback(percent);
    }
  });

  if (!result.success) {
    return {
      success: false,
      error: "Download failed: " + result.error,
      error_type: "download_error"
    };
  }

  // 5. Return success
  return {
    success: true,
    file_path: outputPath,
    format: downloadInfo.format,
    actual_bit_depth: downloadInfo.bit_depth,
    actual_sample_rate: downloadInfo.sample_rate
  };
}

// Export functions (required at end of file)
// SpotiFLAC will call these functions

// ============================================
// REGISTER EXTENSION (REQUIRED!)
// ============================================
// You MUST call registerExtension() at the end of your script
// to register your extension with SpotiFLAC.
// Pass an object containing all your provider functions.

registerExtension({
  // Lifecycle (required)
  initialize: initialize,
  cleanup: cleanup,
  
  // Metadata Provider functions (if type includes "metadata_provider")
  searchTracks: searchTracks,
  getTrack: getTrack,
  getAlbum: getAlbum,
  getArtist: getArtist,
  
  // Lazy enrichment hook (optional, called before download)
  enrichTrack: enrichTrack,
  
  // Download Provider functions (if type includes "download_provider")
  checkAvailability: checkAvailability,
  getDownloadUrl: getDownloadUrl,
  download: download
});

console.log("My Music Provider loaded!");

// Minimal example
registerExtension({
  initialize: function(config) { return true; },
  cleanup: function() {},
  searchTracks: function(query, limit) { return []; }
});

// GET request
const response = http.get(url, headers);

// POST request - body can be string or object (auto-stringified to JSON)
const response = http.post(url, body, headers);

// PUT request - same signature as POST
const response = http.put(url, body, headers);

// DELETE request - no body
const response = http.delete(url, headers);

// PATCH request - same signature as POST
const response = http.patch(url, body, headers);

// Generic request (supports any HTTP method)
const response = http.request(url, {
  method: "POST",           // HTTP method (default: "GET")
  body: { key: "value" },   // Request body (string or object)
  headers: {                // Request headers
    "Authorization": "Bearer token",
    "Content-Type": "application/json"
  }
});

// Clear all cookies for this extension
http.clearCookies();

// Custom User-Agent is respected
const response = http.get(url, {
  "User-Agent": "MyExtension/1.0",
  "Authorization": "Bearer token"
});

{
  statusCode: 200,    // HTTP status code
  status: 200,        // Alias for statusCode
  ok: true,           // true if status code is 2xx
  body: "...",        // Response body as string
  headers: {          // Response headers
    "Content-Type": "application/json",
    "Set-Cookie": ["cookie1=value1", "cookie2=value2"]  // Arrays for multi-value headers
  }
}

// Example: Parse JSON response
const data = JSON.parse(response.body);
// Or use utils helper
const data = utils.parseJSON(response.body);

// Method 1: Manual string building
const formBody = "grant_type=authorization_code" +
  "&client_id=" + encodeURIComponent(clientId) +
  "&code=" + encodeURIComponent(authCode) +
  "&redirect_uri=" + encodeURIComponent(redirectUri);

const response = http.post("https://api.example.com/oauth/token", formBody, {
  "Content-Type": "application/x-www-form-urlencoded"
});

// Method 2: Using URLSearchParams (browser-compatible)
const params = new URLSearchParams();
params.set("grant_type", "authorization_code");
params.set("client_id", clientId);
params.set("code", authCode);
params.set("redirect_uri", redirectUri);

const response = http.post("https://api.example.com/oauth/token", params.toString(), {
  "Content-Type": "application/x-www-form-urlencoded"
});

// Method 3: Helper function
function formEncode(obj) {
  return Object.keys(obj)
    .map(key => encodeURIComponent(key) + "=" + encodeURIComponent(obj[key]))
    .join("&");
}

const response = http.post("https://api.example.com/oauth/token", formEncode({
  grant_type: "authorization_code",
  client_id: clientId,
  code: authCode,
  redirect_uri: redirectUri
}), {
  "Content-Type": "application/x-www-form-urlencoded"
});

// First request - server sets cookies
http.get("https://api.example.com/login");

// Second request - cookies are automatically included
http.get("https://api.example.com/data");

// Clear cookies if needed (e.g., for logout)
http.clearCookies();

{
  "permissions": {
    "network": [
      "music.youtube.com",
      "www.youtube.com",
      "youtube.com",
      "youtubei.googleapis.com",
      "*.googlevideo.com",
      "*.youtube.com",
      "*.ytimg.com"
    ],
    "storage": true
  }
}

async function searchYouTubeMusic(query) {
  const visitorId = storage.get("visitorId") || "";
  
  const response = http.post("https://youtubei.googleapis.com/youtubei/v1/search", {
    query: query,
    context: {
      client: {
        clientName: "WEB_REMIX",
        clientVersion: "1.20240101.01.00"
      }
    }
  }, {
    "Content-Type": "application/json",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "X-Goog-Visitor-Id": visitorId,
    "X-Youtube-Client-Version": "1.20240101.01.00",
    "X-Youtube-Client-Name": "67"
  });
  
  // Save visitor ID from response headers for future requests
  const newVisitorId = response.headers["X-Goog-Visitor-Id"];
  if (newVisitorId) {
    storage.set("visitorId", newVisitorId);
  }
  
  if (!response.ok) {
    log.error("YouTube Music search failed:", response.statusCode);
    return [];
  }
  
  return JSON.parse(response.body);
}

// Basic GET request
const response = fetch("https://api.example.com/data");
const data = response.json();

// POST request with options
const response = fetch("https://api.example.com/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer token"
  },
  body: JSON.stringify({ query: "search term" })
});

if (response.ok) {
  const data = response.json();
  console.log(data);
} else {
  console.log("Error:", response.status, response.statusText);
}

{
  ok: true,              // true if status is 2xx
  status: 200,           // HTTP status code
  statusText: "OK",      // HTTP status text
  url: "...",            // Request URL
  headers: {},           // Response headers
  
  // Methods
  text(),                // Returns body as string
  json(),                // Parses body as JSON
  arrayBuffer()          // Returns body as byte array
}

// Encode string to Base64
const encoded = btoa("Hello, World!");  // "SGVsbG8sIFdvcmxkIQ=="

// Decode Base64 to string
const decoded = atob("SGVsbG8sIFdvcmxkIQ==");  // "Hello, World!"

// Encode string to bytes (UTF-8)
const encoder = new TextEncoder();
const bytes = encoder.encode("Hello");  // [72, 101, 108, 108, 111]

// Decode bytes to string
const decoder = new TextDecoder("utf-8");
const text = decoder.decode([72, 101, 108, 108, 111]);  // "Hello"

// Parse URL
const url = new URL("https://example.com/path?foo=bar&baz=qux");
console.log(url.hostname);    // "example.com"
console.log(url.pathname);    // "/path"
console.log(url.search);      // "?foo=bar&baz=qux"
console.log(url.searchParams.get("foo"));  // "bar"

// Build URL with query params
const params = new URLSearchParams();
params.set("query", "search term");
params.set("limit", "10");
const queryString = params.toString();  // "query=search+term&limit=10"

// Relative URL resolution
const base = new URL("https://example.com/api/");
const full = new URL("users/123", base);
console.log(full.href);  // "https://example.com/api/users/123"

// rollup.config.js
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/index.js',
    format: 'iife',  // Immediately Invoked Function Expression
    name: 'MyExtension'
  }
};

// Save data (persisted across app restarts)
storage.set("key", "value");
storage.set("config", { foo: "bar" });

// Get data
const value = storage.get("key");
const config = storage.get("config");

// Remove data
storage.remove("key");

// Download file
const result = file.download(url, outputPath, {
  headers: {},
  onProgress: function (received, total) {
    // Progress callback
  },
});

// Check if file exists
const exists = file.exists(path);

// Read file content
const content = file.read(path);

// Write file
file.write(path, content);

// Delete file
file.delete(path);

log.debug("Debug message", data);
log.info("Info message", data);
log.warn("Warning message", data);
log.error("Error message", data);

// JSON
const obj = utils.parseJSON(jsonString);
const str = utils.stringifyJSON(obj);

// Encoding
const encoded = utils.base64Encode(string);
const decoded = utils.base64Decode(encoded);

// Hashing
const md5Hash = utils.md5(string);
const sha256Hash = utils.sha256(string);

// HMAC (for API signatures and TOTP)
const signature = utils.hmacSHA256(message, secretKey);      // Returns hex string
const signatureB64 = utils.hmacSHA256Base64(message, secretKey);  // Returns base64 string
const hmacResult = utils.hmacSHA1(keyBytes, messageBytes);   // Returns array of bytes (for TOTP)

function generateTOTP(secret, counter) {
  // Decode base32 secret to bytes
  const key = base32Decode(secret);
  
  // Convert counter to 8 bytes (big-endian)
  const counterBytes = [];
  let c = counter;
  for (let i = 7; i >= 0; i--) {
    counterBytes[i] = c & 0xff;
    c = Math.floor(c / 256);
  }
  
  // HMAC-SHA1 - key and message can be arrays of bytes
  const hmac = utils.hmacSHA1(key, counterBytes);
  
  // Dynamic truncation
  const offset = hmac[hmac.length - 1] & 0x0f;
  const code = ((hmac[offset] & 0x7f) << 24) |
               ((hmac[offset + 1] & 0xff) << 16) |
               ((hmac[offset + 2] & 0xff) << 8) |
               (hmac[offset + 3] & 0xff);
  
  return (code % 1000000).toString().padStart(6, "0");
}

// Usage
const counter = Math.floor(Date.now() / 1000 / 30);
const totpCode = generateTOTP(base32Secret, counter);

function signRequest(method, path, timestamp, body, secretKey) {
  // Build string to sign (format varies by API)
  const stringToSign = [method, path, timestamp, body].join("\n");
  
  // Generate HMAC-SHA256 signature
  const signature = utils.hmacSHA256Base64(stringToSign, secretKey);
  
  return signature;
}

// Example: Signed API request
function makeSignedRequest(endpoint, data) {
  const timestamp = Date.now().toString();
  const body = JSON.stringify(data);
  const signature = signRequest("POST", endpoint, timestamp, body, settings.api_secret);
  
  return http.post("https://api.example.com" + endpoint, body, {
    "Content-Type": "application/json",
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "X-API-Key": settings.api_key
  });
}

// Sanitize filename
const safe = gobackend.sanitizeFilename(filename);

// Get audio quality info from file
const quality = gobackend.getAudioQuality(filePath);
// returns object { bitDepth: 16, sampleRate: 44100, totalSamples: 12345 }
// or { error: "..." }

// Build filename from template
const filename = gobackend.buildFilename(template, metadata);
// metadata is object: { title, artist, album, track_number, ... }

// Store sensitive data (encrypted on disk)
credentials.store("key", "value");
credentials.store("config", { apiKey: "...", secret: "..." });

// Get sensitive data (decrypted)
const value = credentials.get("key");
const config = credentials.get("config");

// Check if credential exists
const exists = credentials.has("key");

// Remove credential
credentials.remove("key");

// Request app to open OAuth URL
auth.openAuthUrl(authUrl, callbackUrl);

// Get auth code (set by app after OAuth callback)
const code = auth.getAuthCode();

// Set auth tokens
auth.setAuthCode({
  code: "...",
  access_token: "...",
  refresh_token: "...",
  expires_in: 3600
});

// Check if authenticated
const isAuth = auth.isAuthenticated();

// Get current tokens
const tokens = auth.getTokens();
// { access_token, refresh_token, is_authenticated, expires_at, is_expired }

// Clear auth state (logout)
auth.clearAuth();

// 1. Start OAuth with PKCE (generates verifier/challenge automatically)
const result = auth.startOAuthWithPKCE({
  authUrl: "https://accounts.spotify.com/authorize",
  clientId: "your_client_id",
  redirectUri: "spotiflac://callback",
  scope: "user-read-private playlist-read-private",
  extraParams: {
    show_dialog: "true"
  }
});

if (result.success) {
  log.info("OAuth URL opened:", result.authUrl);
  log.info("PKCE verifier stored for later use");
}

// 2. After user authorizes, get the auth code
const code = auth.getAuthCode();

// 3. Exchange code for tokens (uses stored PKCE verifier automatically)
const tokens = auth.exchangeCodeWithPKCE({
  tokenUrl: "https://accounts.spotify.com/api/token",
  clientId: "your_client_id",
  redirectUri: "spotiflac://callback",
  code: code
});

if (tokens.success) {
  log.info("Access token:", tokens.access_token);
  log.info("Refresh token:", tokens.refresh_token);
  // Tokens are automatically stored in auth state
}

// Generate PKCE pair manually
const pkce = auth.generatePKCE(64);  // Optional length (43-128, default: 64)
// { verifier: "...", challenge: "...", method: "S256" }

// Get stored PKCE (if previously generated)
const storedPKCE = auth.getPKCE();
// { verifier: "...", challenge: "...", method: "S256" } or {}

// Build your own OAuth URL with PKCE
const authUrl = `https://accounts.spotify.com/authorize?` +
  `client_id=${CLIENT_ID}` +
  `&response_type=code` +
  `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
  `&code_challenge=${pkce.challenge}` +
  `&code_challenge_method=S256` +
  `&scope=${encodeURIComponent(SCOPE)}`;

// Open the URL
auth.openAuthUrl(authUrl, REDIRECT_URI);

// After callback, exchange manually using http.post
const response = http.post("https://accounts.spotify.com/api/token",
  `grant_type=authorization_code` +
  `&client_id=${CLIENT_ID}` +
  `&code=${authCode}` +
  `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
  `&code_verifier=${pkce.verifier}`,
  { "Content-Type": "application/x-www-form-urlencoded" }
);

{
  authUrl: string,      // Required: OAuth authorization endpoint
  clientId: string,     // Required: Your OAuth client ID
  redirectUri: string,  // Required: Callback URL
  scope: string,        // Optional: OAuth scopes
  extraParams: object   // Optional: Additional URL parameters
}

{
  tokenUrl: string,     // Required: OAuth token endpoint
  clientId: string,     // Required: Your OAuth client ID
  code: string,         // Required: Authorization code from callback
  redirectUri: string,  // Optional: Must match authorization request
  extraParams: object   // Optional: Additional form parameters
}

// Encrypt string with key
const encrypted = utils.encrypt("data", "key");
// { success: true, data: "base64-encrypted" }

// Decrypt string
const decrypted = utils.decrypt(encrypted.data, "key");
// { success: true, data: "data" }

// Generate random key
const key = utils.generateKey(32);
// { success: true, key: "base64", hex: "hex" }

// Execute raw FFmpeg command
const result = ffmpeg.execute('-i "input.flac" -c:a libmp3lame -b:a 320k "output.mp3"');
// { success: true, output: "..." } or { success: false, error: "..." }

// Get audio file info
const info = ffmpeg.getInfo("file.flac");
// { success: true, bit_depth: 16, sample_rate: 44100, duration: 180.5 }

// Convert with options (helper function)
const result = ffmpeg.convert("input.flac", "output.mp3", {
  codec: "libmp3lame",    // Audio codec
  bitrate: "320k",        // Bitrate
  sample_rate: 44100,     // Sample rate
  channels: 2             // Number of channels
});

// Compare two strings with fuzzy matching (returns 0-1 similarity)
const similarity = matching.compareStrings("Track Name", "track name (remastered)");
// 0.85

// Compare durations with tolerance (in milliseconds)
const match = matching.compareDuration(180000, 182000, 3000);
// true (within 3 second tolerance)

// Normalize string for comparison (removes suffixes, special chars)
const normalized = matching.normalizeString("Track Name (Remastered) [Explicit]");
// "track name"

{
  "name": "free-music-api",
  "displayName": "Free Music API",
  "version": "1.0.0",
  "description": "Search from Free Music API",
  "author": "Developer",
  "permissions": {
    "network": ["api.freemusic.com"]
  },
  "type": ["metadata_provider"],
  "settings": []
}

let settings = {};

function initialize(config) {
  settings = config || {};
  log.info("Free Music API initialized");
  return true;
}

function cleanup() {
  log.info("Cleanup");
}

function searchTracks(query, limit) {
  const url = "https://api.freemusic.com/search?q=" + encodeURIComponent(query) + "&limit=" + limit;
  const response = http.get(url, {});

  if (!response.ok) return [];

  const data = JSON.parse(response.body);
  return data.results.map((t) => ({
    id: t.id,
    name: t.title,
    artists: t.artist,
    album_name: t.album,
    isrc: t.isrc,
    duration_ms: t.duration_ms,
    images: t.artwork,
  }));
}

// REQUIRED: Register the extension
registerExtension({
  initialize: initialize,
  cleanup: cleanup,
  searchTracks: searchTracks
});

{
  "name": "premium-music",
  "displayName": "Premium Music",
  "version": "1.0.0",
  "description": "Download from Premium Music service",
  "author": "Developer",
  "permissions": {
    "network": [
      "api.premiummusic.com",
      "cdn.premiummusic.com"
    ],
    "storage": true
  },
  "type": ["download_provider"],
  "settings": [
    {
      "key": "email",
      "label": "Email",
      "type": "string",
      "required": true
    },
    {
      "key": "password",
      "label": "Password",
      "type": "string",
      "required": true
    }
  ]
}

let settings = {};
let accessToken = null;

function initialize(config) {
  settings = config || {};

  if (!settings.email || !settings.password) {
    throw new Error("Email and password required");
  }

  // Login and save token
  const body = JSON.stringify({
    email: settings.email,
    password: settings.password
  });

  const response = http.post("https://api.premiummusic.com/auth/login", body, {
    "Content-Type": "application/json"
  });

  if (!response.ok) {
    throw new Error("Login failed");
  }

  const data = JSON.parse(response.body);
  accessToken = data.access_token;

  // Save token for next session
  storage.set("access_token", accessToken);

  log.info("Logged in successfully");
  return true;
}

function cleanup() {
  accessToken = null;
}

function checkAvailability(isrc, trackName, artistName) {
  const url = "https://api.premiummusic.com/search?isrc=" + isrc;
  const response = http.get(url, {
    Authorization: "Bearer " + accessToken
  });

  if (!response.ok) {
    return { available: false };
  }

  const data = JSON.parse(response.body);
  if (data.tracks && data.tracks.length > 0) {
    return {
      available: true,
      track_id: data.tracks[0].id,
      quality: "LOSSLESS",
    };
  }

  return { available: false };
}

function getDownloadUrl(trackId, quality) {
  const url = "https://api.premiummusic.com/tracks/" + trackId + "/download?quality=" + quality;
  const response = http.get(url, {
    Authorization: "Bearer " + accessToken
  });

  if (!response.ok) {
    return { success: false, error: "Failed to get URL" };
  }

  const data = JSON.parse(response.body);
  return {
    success: true,
    url: data.url,
    format: "flac",
    bit_depth: 24,
    sample_rate: 96000,
  };
}

function download(trackId, quality, outputPath, progressCallback) {
  // 1. Get download URL directly (availability checked by app)
  const downloadInfo = getDownloadUrl(trackId, quality);

  if (!downloadInfo.success) {
    return {
      success: false,
      error: downloadInfo.error,
      error_type: "stream_error",
    };
  }

  // 2. Download to outputPath provided by app
  const result = file.download(downloadInfo.url, outputPath, {
    headers: { Authorization: "Bearer " + accessToken },
    onProgress: function(received, total) {
      const percent = total > 0 ? (received / total) * 100 : 0;
      progressCallback(percent);
    }
  });

  if (!result.success) {
    return {
      success: false,
      error: result.error,
      error_type: "download_error",
    };
  }

  return {
    success: true,
    file_path: outputPath,
    format: "flac",
    actual_bit_depth: downloadInfo.bit_depth,
    actual_sample_rate: downloadInfo.sample_rate,
  };
}

// REQUIRED: Register the extension
registerExtension({
  initialize: initialize,
  cleanup: cleanup,
  checkAvailability: checkAvailability,
  getDownloadUrl: getDownloadUrl,
  download: download
});

console.log("Premium Music extension loaded!");

# Windows (PowerShell)
Compress-Archive -Path manifest.json, main.js -DestinationPath my-extension.zip
Rename-Item my-extension.zip my-extension.spotiflac-ext

# Linux/Mac
zip my-extension.zip manifest.json main.js
mv my-extension.zip my-extension.spotiflac-ext

"permissions": {
  "network": [
    "music.youtube.com",
    "www.youtube.com", 
    "youtube.com",
    "youtubei.googleapis.com",
    "*.googlevideo.com",
    "*.youtube.com",
    "*.ytimg.com"
  ]
}

// Old way (still works)
http.post(url, JSON.stringify(body), headers);

// New way (v3.0.0-alpha.2+)
http.post(url, body, headers);  // Objects auto-stringified

"permissions": {
  "network": ["api.example.com"],
  "storage": true,
  "file": true
}

// ❌ Wrong - absolute path
file.write("/sdcard/Music/song.flac", data);

// ✅ Correct - relative path (within extension sandbox)
file.write("cache/temp.flac", data);

// ✅ Correct - use outputPath provided by download function
function download(trackId, quality, outputPath, progressCallback) {
  // outputPath is already the correct absolute path managed by the app
  return file.download(streamUrl, outputPath, { headers: headers });
}

function ensureValidToken() {
  const tokens = auth.getTokens();
  
  // Check if token exists and is not expired
  if (tokens.access_token && !tokens.is_expired) {
    return true;
  }
  
  // Token expired or missing - try to refresh
  const refreshToken = credentials.get("refresh_token");
  if (!refreshToken) {
    return false; // Need full re-authentication
  }
  
  // Call your OAuth provider's refresh endpoint
  const response = http.post("https://api.example.com/oauth/token", {
    grant_type: "refresh_token",
    refresh_token: refreshToken,
    client_id: settings.client_id
  }, { "Content-Type": "application/json" });
  
  if (!response.ok) {
    auth.clearAuth();
    return false;
  }
  
  const newTokens = JSON.parse(response.body);
  
  // Update stored tokens
  credentials.store("access_token", newTokens.access_token);
  if (newTokens.refresh_token) {
    credentials.store("refresh_token", newTokens.refresh_token);
  }
  
  // Update auth state
  auth.setAuthCode({
    access_token: newTokens.access_token,
    refresh_token: newTokens.refresh_token || refreshToken,
    expires_in: newTokens.expires_in
  });
  
  return true;
}

// Use before any authenticated API call
function makeAuthenticatedRequest(url) {
  if (!ensureValidToken()) {
    return { error: "Authentication required" };
  }
  
  const tokens = auth.getTokens();
  return http.get(url, {
    "Authorization": "Bearer " + tokens.access_token
  });
}

// Relative paths (recommended)
file.write("cache/data.json", data);     // → {ext_dir}/cache/data.json
file.read("config.txt");                  // → {ext_dir}/config.txt
file.exists("downloads/track.flac");      // → {ext_dir}/downloads/track.flac

// Absolute paths (allowed for download queue integration)
file.write("/storage/emulated/0/Music/track.flac", data);  // Allowed
file.read("/sdcard/Download/file.txt");                     // Allowed

{extension-id}/
├── storage.json          # storage API data
├── .credentials.enc      # encrypted credentials
├── cache/                # your cache files
└── downloads/            # your download files

// Redirects are followed automatically
const response = http.get("https://example.com/redirect");
// response.url will be the final URL after redirects
// response.statusCode will be the final response status

// The HTTP client follows up to 10 redirects by default
// If more redirects occur, the request will fail

// Most cases: just use the response directly
const response = http.get(url);
if (response.ok) {
  // Final response after any redirects
}

function download(request, progressCallback) {
  // Check availability
  const availability = checkAvailability(request.isrc, request.track_name, request.artist_name);
  
  if (!availability.available) {
    return {
      success: false,
      error: "Track not found on this service",
      error_type: "not_found"
    };
  }
  
  // Check authentication
  if (!auth.isAuthenticated()) {
    return {
      success: false,
      error: "Please authenticate first",
      error_type: "auth_error"
    };
  }
  
  // Get stream URL
  const streamInfo = getDownloadUrl(availability.track_id, request.quality);
  
  if (!streamInfo.success) {
    // Determine error type from response
    if (streamInfo.status === 429) {
      return {
        success: false,
        error: "Rate limited, please wait",
        error_type: "rate_limit"
      };
    }
    if (streamInfo.status === 451 || streamInfo.status === 403) {
      return {
        success: false,
        error: "Content not available in your region",
        error_type: "geo_blocked"
      };
    }
    return {
      success: false,
      error: streamInfo.error || "Failed to get stream",
      error_type: "stream_error"
    };
  }
  
  // Download file
  const result = file.download(streamInfo.url, request.output_path, {
    headers: { "Authorization": "Bearer " + auth.getTokens().access_token },
    onProgress: progressCallback
  });
  
  if (!result.success) {
    return {
      success: false,
      error: "Download failed: " + result.error,
      error_type: "download_error"
    };
  }
  
  return {
    success: true,
    file_path: request.output_path,
    format: streamInfo.format
  };
}

// Requests that take longer than 30 seconds will fail
const response = http.get("https://slow-api.example.com/data");
if (response.error) {
  // Could be timeout: "context deadline exceeded" or similar
  log.error("Request failed:", response.error);
}

// Request the app to open an OAuth URL
// The app will open this URL in a browser and wait for callback
auth.openAuthUrl(authUrl, callbackUrl);

// Get the auth code (set by app after OAuth callback)
const code = auth.getAuthCode();

// Set auth tokens after exchanging code for tokens
auth.setAuthCode({
  code: "auth_code",
  access_token: "access_token",
  refresh_token: "refresh_token",
  expires_in: 3600  // seconds
});

// Check if extension is authenticated
const isAuth = auth.isAuthenticated();

// Get current tokens
const tokens = auth.getTokens();
// Returns: { access_token, refresh_token, is_authenticated, expires_at, is_expired }

// Clear all auth state (logout)
auth.clearAuth();

// Store a credential (encrypted on disk)
credentials.store("api_key", "my-secret-key");
credentials.store("user_data", { email: "user@example.com", token: "..." });

// Get a credential
const apiKey = credentials.get("api_key");
const userData = credentials.get("user_data");

// Check if credential exists
const hasKey = credentials.has("api_key");

// Remove a credential
credentials.remove("api_key");

// Encrypt data with a key
const result = utils.encrypt("sensitive data", "encryption-key");
// Returns: { success: true, data: "base64-encrypted-string" }

// Decrypt data
const decrypted = utils.decrypt(result.data, "encryption-key");
// Returns: { success: true, data: "sensitive data" }

// Generate a random encryption key
const key = utils.generateKey(32);  // 32 bytes = 256 bits
// Returns: { success: true, key: "base64-key", hex: "hex-key" }

let settings = {};
const CLIENT_ID = "your_spotify_client_id";
const REDIRECT_URI = "spotiflac://spotify-callback";
const SCOPES = "user-read-private user-library-read playlist-read-private";

function initialize(config) {
  settings = config || {};
  
  // Check if already authenticated
  if (auth.isAuthenticated()) {
    const tokens = auth.getTokens();
    if (!tokens.is_expired) {
      log.info("Already authenticated");
      return true;
    }
    // Token expired, need to refresh or re-auth
    log.info("Token expired, need to re-authenticate");
  }
  
  return true;
}

function startLogin() {
  const result = auth.startOAuthWithPKCE({
    authUrl: "https://accounts.spotify.com/authorize",
    clientId: CLIENT_ID,
    redirectUri: REDIRECT_URI,
    scope: SCOPES
  });
  
  if (!result.success) {
    log.error("Failed to start OAuth:", result.error);
    return false;
  }
  
  log.info("Please authorize in the browser...");
  return true;
}

function handleCallback() {
  const code = auth.getAuthCode();
  if (!code) {
    log.error("No auth code received");
    return false;
  }
  
  const tokens = auth.exchangeCodeWithPKCE({
    tokenUrl: "https://accounts.spotify.com/api/token",
    clientId: CLIENT_ID,
    redirectUri: REDIRECT_URI,
    code: code
  });
  
  if (!tokens.success) {
    log.error("Token exchange failed:", tokens.error);
    return false;
  }
  
  log.info("Authentication successful!");
  // Tokens are now stored and accessible via auth.getTokens()
  return true;
}

function makeAuthenticatedRequest(url) {
  const tokens = auth.getTokens();
  if (!tokens.access_token) {
    throw new Error("Not authenticated");
  }
  
  return http.get(url, {
    "Authorization": "Bearer " + tokens.access_token
  });
}

// Register extension
registerExtension({
  initialize: initialize,
  startLogin: startLogin,
  handleCallback: handleCallback,
  // ... other functions
});

let settings = {};
let accessToken = null;

function initialize(config) {
  settings = config || {};
  
  // Check if we have stored tokens
  const storedToken = credentials.get("access_token");
  if (storedToken) {
    accessToken = storedToken;
    // Verify token is still valid
    if (auth.isAuthenticated()) {
      log.info("Using stored authentication");
      return true;
    }
  }
  
  // Need to authenticate
  log.info("Authentication required");
  return true;
}

// Call this to start OAuth flow
function startAuth() {
  const clientId = settings.client_id;
  const redirectUri = "spotiflac://oauth/callback";
  
  const authUrl = `https://api.example.com/oauth/authorize?` +
    `client_id=${clientId}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `response_type=code&` +
    `scope=read,download`;
  
  // Request app to open auth URL
  auth.openAuthUrl(authUrl, redirectUri);
  
  return { success: true, message: "Please complete authentication in browser" };
}

// Call this after user completes OAuth (app will set the code)
function completeAuth() {
  const code = auth.getAuthCode();
  if (!code) {
    return { success: false, error: "No auth code received" };
  }
  
  // Exchange code for tokens
  const response = http.post("https://api.example.com/oauth/token", JSON.stringify({
    grant_type: "authorization_code",
    code: code,
    client_id: settings.client_id,
    client_secret: settings.client_secret
  }), {
    "Content-Type": "application/json"
  });
  
  if (response.statusCode !== 200) {
    return { success: false, error: "Token exchange failed" };
  }
  
  const tokens = JSON.parse(response.body);
  
  // Store tokens securely
  credentials.store("access_token", tokens.access_token);
  credentials.store("refresh_token", tokens.refresh_token);
  
  // Update auth state
  auth.setAuthCode({
    access_token: tokens.access_token,
    refresh_token: tokens.refresh_token,
    expires_in: tokens.expires_in
  });
  
  accessToken = tokens.access_token;
  
  return { success: true };
}

// Use in download function
function download(trackId, quality, outputPath, progressCallback) {
  if (!auth.isAuthenticated()) {
    return { success: false, error: "Not authenticated", error_type: "auth_error" };
  }
  
  const tokens = auth.getTokens();
  if (tokens.is_expired) {
    // Refresh token
    const refreshed = refreshAccessToken();
    if (!refreshed.success) {
      return { success: false, error: "Token refresh failed", error_type: "auth_error" };
    }
  }
  
  // Use accessToken for API calls
  const response = http.get(`https://api.example.com/tracks/${trackId}/stream`, {
    "Authorization": "Bearer " + accessToken
  });
  
  // ... rest of download logic
}

function refreshAccessToken() {
  const refreshToken = credentials.get("refresh_token");
  if (!refreshToken) {
    return { success: false };
  }
  
  const response = http.post("https://api.example.com/oauth/token", JSON.stringify({
    grant_type: "refresh_token",
    refresh_token: refreshToken,
    client_id: settings.client_id
  }), {
    "Content-Type": "application/json"
  });
  
  if (response.statusCode !== 200) {
    return { success: false };
  }
  
  const tokens = JSON.parse(response.body);
  credentials.store("access_token", tokens.access_token);
  accessToken = tokens.access_token;
  
  auth.setAuthCode({
    access_token: tokens.access_token,
    expires_in: tokens.expires_in
  });
  
  return { success: true };
}

// Register extension
registerExtension({
  initialize: initialize,
  cleanup: function() { accessToken = null; },
  startAuth: startAuth,
  completeAuth: completeAuth,
  download: download
});

{
  id: "track123",           // Unique ID (required)
  name: "Track Name",       // Track title (required)
  artists: "Artist Name",   // Artist(s) (required)
  album_name: "Album",      // Album name (optional)
  album_artist: "Artist",   // Album artist (optional)
  isrc: "USRC12345678",     // ISRC code (optional but recommended for matching)
  duration_ms: 240000,      // Duration in milliseconds (required)
  track_number: 1,          // Track number (optional)
  disc_number: 1,           // Disc number (optional)
  release_date: "2024-01-01", // Release date (optional)
  images: "https://..."     // Cover art/thumbnail URL (optional)
}

{
  id: "album123",
  name: "Album Name",
  artists: "Artist Name",
  release_date: "2024-01-01",
  total_tracks: 12,
  images: "https://...",
  album_type: "album",      // "album", "single", "compilation"
  tracks: [/* array of Track objects */]
}

{
  id: "artist123",
  name: "Artist Name",
  images: "https://...",
  albums: [/* array of Album objects */]
}

// Success
{
  success: true,
  file_path: "/path/to/file.flac",
  format: "flac",
  actual_bit_depth: 24,
  actual_sample_rate: 96000,
  // Optional metadata (used when skipMetadataEnrichment is true)
  title: "Track Name",
  artist: "Artist Name",
  album: "Album Name",
  album_artist: "Album Artist",
  track_number: 1,
  disc_number: 1,
  release_date: "2024-01-01",
  cover_url: "https://...",
  isrc: "USRC12345678"
}

// Error
{
  success: false,
  error: "Error message",
  error_type: "not_found" | "stream_error" | "download_error" | "auth_error"
}

function download(trackId, quality, outputPath, progressCallback) {
  // ... download logic ...
  
  return {
    success: true,
    file_path: outputPath,
    // Include metadata from your source
    title: videoInfo.title,
    artist: videoInfo.artist,
    album: videoInfo.album || videoInfo.title,
    cover_url: videoInfo.thumbnail
  };
}