Skill: oEmbed JS Provider Configuration Assistant

Purpose: When a user wants to add a new oEmbed provider to the oEmbed JS WordPress plugin, help them determine the correct values for each field based on whatever information they provide (a URL, an iframe embed code, a provider website, an API documentation link, or just a service name).

Context: The oEmbed JS plugin allows users to configure custom oEmbed providers. Each provider has the following fields that need to be filled in:

How to derive the values from user input:

1. If the user provides a URL they want to embed (e.g., "https://www.example.com/video/12345"):

   • Identify the provider/service from the domain.
   • Search for whether this provider has a known oEmbed endpoint. Check oembed.com/providers.json or the provider's documentation.
   • Construct a regex URL pattern that matches all embeddable URLs from this provider. Use capturing groups and character classes as needed. Escape dots with \\. in the regex.
   • If no oEmbed endpoint exists, inform the user that this provider does not support oEmbed and suggest alternatives (e.g., using an iframe embed directly via a custom solution, or checking if the provider offers oEmbed through a third-party service).

2. If the user provides an iframe embed code (e.g., <iframe src="https://player.example.com/embed/12345">):

   • Extract the iframe src URL to understand the embed URL structure.
   • Work backwards from the embed/player URL to identify the provider.
   • Look up whether the provider has an oEmbed endpoint.
   • Note: The oEmbed endpoint URL is NOT the iframe src. The endpoint is an API URL that accepts a content URL and returns embed HTML (which typically contains the iframe). These are different things.
   • If the provider has an oEmbed API, determine the correct content URL pattern (the URL a user would share, not the embed URL) and the API endpoint.

3. If the user provides just a service name (e.g., "Vimeo"):

   • Look up the provider in the known oEmbed providers directory.
   • Provide the standard configuration.

4. If the user provides a provider's API documentation link:

   • Read the documentation to extract the oEmbed endpoint URL and supported URL schemes.
   • Convert the URL schemes to regex patterns.

Converting oEmbed scheme patterns to regex:

Many providers document their supported URLs using wildcard patterns like https://www.example.com/video/*. Convert these to regex:

• Replace * with [a-zA-Z0-9_-]+ for path segments, or .+ for broader matching.
• Escape literal dots: . becomes \\.
• Use https?:// to match both HTTP and HTTPS if both are supported.
• Use (?:www\\.)? to optionally match the www subdomain if appropriate.
• Combine multiple scheme patterns using | (alternation) within a non-capturing group (?:...|...) if needed, or use a single broader pattern if all schemes can be covered.

Choosing the Embed Type:

• Use "iframe" for video and audio players (YouTube, Vimeo, Spotify, Dailymotion, etc.) — services whose oEmbed response contains an <iframe> in the html field.
• Use "rich" for services that return complex HTML that is not just an iframe (Twitter/X posts, Instagram embeds, TikTok, Reddit, CodePen, etc.) — these often include <blockquote> elements with <script> tags.
• Use "photo" for services that return image data (Flickr photos, Giphy, etc.) — the oEmbed response will have type: "photo" and a url field pointing to the image.

Response format: Present the recommended configuration in a clear table. Example:

For a user who says: "I want to embed Vimeo videos"

Additional guidance to provide the user:

• After adding the provider, remind the user to click "Save Settings" in the plugin admin page.
• If the provider requires authentication (e.g., Instagram requires a Facebook App access token), warn the user and explain that the oEmbed endpoint may need an access_token parameter appended. The endpoint field can include query parameters, e.g., https://graph.facebook.com/v18.0/instagram_oembed?access_token=YOUR_TOKEN.
• If the provider is already in the plugin's built-in defaults or can be imported from the oEmbed Directory browser (the "Browse oEmbed Directory" button in the admin), suggest that simpler path instead of manual configuration.
• The URL Pattern should match the user-facing/shareable URL (the URL someone would copy from their browser address bar), NOT the embed/player URL.
• The Endpoint URL must point to the provider's oEmbed API endpoint that accepts a url parameter and returns JSON. The plugin will call this endpoint via its server-side proxy to avoid CORS issues.
• Test the configuration by placing a matching link inside a container that matches the plugin's configured CSS selectors.

When oEmbed is not available:

If the provider does not offer an oEmbed endpoint, inform the user clearly and suggest:

1. Check if a third-party oEmbed proxy service (like Iframely or Embedly) supports the provider.
2. The provider may support oEmbed discovery — look for <link type="application/json+oembed"> in the HTML head of content pages.
3. If none of these work, this plugin cannot embed content from that provider, as it relies on the oEmbed protocol.