readthedocs · humitos · Apr 15, 2024 · Apr 27, 2023 · Sep 13, 2023 · Sep 13, 2023
@@ -1,8 +1,18 @@
 <html>
   <head>
+    <meta name="readthedocs-addons-api-version" content="1" />
     <title>Documentation Addons - Read the Docs</title>
     <meta name="readthedocs-project-slug" content="test-builds" />
     <meta name="readthedocs-version-slug" content="latest" />
+    <script>
+      // Example of using "readthedocs-addons-data-ready" with a different API version supported
+      document.addEventListener(
+        "readthedocs-addons-data-ready",
+        function (event) {
+          console.debug(event.detail);
+        }
+      );
+    </script>
     <meta name="readthedocs-resolver-filename" content="/index.html" />
   </head>
   <body>

@@ -5,3 +5,5 @@ export const EVENT_READTHEDOCS_DOCDIFF_ADDED_REMOVED_SHOW =
 export const EVENT_READTHEDOCS_DOCDIFF_HIDE = "readthedocs-docdiff-hide";
 export const EVENT_READTHEDOCS_FLYOUT_SHOW = "readthedocs-flyout-show";
 export const EVENT_READTHEDOCS_FLYOUT_HIDE = "readthedocs-flyout-hide";
+export const EVENT_READTHEDOCS_ADDONS_DATA_READY =
+  "readthedocs-addons-data-ready";
@@ -1,11 +1,26 @@
 import { default as fetch } from "unfetch";
+import { EVENT_READTHEDOCS_ADDONS_DATA_READY } from "./events";
 import {
   CLIENT_VERSION,
+  IS_TESTING,
   ADDONS_API_VERSION,
   ADDONS_API_ENDPOINT,
-  IS_TESTING,
 } from "./utils";
 
+/**
+ * Get the Read the Docs API version supported by user's integrations.
+ *
+ */
+function _getMetadataAddonsAPIVersion() {
+  const meta = document.querySelector(
+    "meta[name=readthedocs-addons-api-version]",
+  );
+  if (meta !== undefined) {
+    return meta.getAttribute("content");
+  }
+  return undefined;
+}
+
 /**
  * Load Read the Docs configuration from API endpoint.
  *
@@ -46,11 +61,64 @@ export function getReadTheDocsConfig(sendUrlParam) {
 
   return fetch(url, {
     method: "GET",
-  }).then((response) => {
-    if (!response.ok) {
-      console.debug("Error parsing configuration data");
-      return undefined;
-    }
-    return response.json();
-  });
+  })
+    .then((response) => {
+      if (!response.ok) {
+        throw "Error parsing configuration data";
+      }
+      return response.json();
+    })
+    .then((data) => {
+      // We force the user to define the `<meta>` tag to be able to use Read the Docs data directly.
+      // This is to keep forward/backward compatibility without breaking integrations.
+      const metadataAddonsAPIVersion = _getMetadataAddonsAPIVersion();
+      if (metadataAddonsAPIVersion !== undefined) {
+        if (metadataAddonsAPIVersion !== data.api_version) {
+          // When the API scheme version returned doesn't match the one defined via `<meta>` tag by the user,
+          // we perform another request to get the Read the Docs response in the structure
+          // that's supported by the user and dispatch a custom event letting them know
+          // this data is ready to be consumed under `event.detail`.
+
+          url =
+            ADDONS_API_ENDPOINT +
+            new URLSearchParams({
+              url: window.location.href,
+              "client-version": CLIENT_VERSION,
+              "api-version": metadataAddonsAPIVersion,
+            });
+
+          fetch(url, {
+            method: "GET",
+          })
+            .then((response) => {
+              if (!response.ok) {
+                throw "Error parsing configuration data";
+              }
+              return response.json();
+            })
+            .then((data) => {
+              dispatchEvent(
+                EVENT_READTHEDOCS_ADDONS_DATA_READY,
+                document,
+                data,
+              );
+            })
+            .catch((error) => {
+              console.error(error);
+            });
+        } else {
+          dispatchEvent(EVENT_READTHEDOCS_ADDONS_DATA_READY, document, data);
+        }
+      }
+
+      return data;
+    })
+    .catch((error) => {
+      console.error(error);
+    });
+}
+
+function dispatchEvent(eventName, element, data) {
+  const event = new CustomEvent(eventName, { detail: data });
+  element.dispatchEvent(event);
 }
@@ -86,6 +86,13 @@ module.exports = (env, argv) => {
       ignored: ["/node_modules/", "**/node_modules/"],
     },
     devServer: {
+      // Allow CORS when working locally
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods":
+          "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "*",
+      },
       open: false,
       port: 8000,
       hot: false,