RTO_form_api.js

What it is

RTO_form_api.js is the foundation helper used by the documentation and most sample projects. It hides the raw window.postMessage protocol and gives you a clean async API: detect the extension, open and control tabs (by tabKey), and send predefined commands.

All methods return a Promise. Failures are normalized to an object like { code, message }.

Requirements

• The RTO extension must be installed and enabled.
• Your admin page origin must be allowed in the extension Allow-list.
• Any target host you want to open or automate must also be allow-listed.

Download

Minimal usage

This is the smallest “copy/paste” snippet that reliably works: detect the extension, then open a controlled tab using a stable tabKey.

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script>
(async function () {
  try {
    // detect(timeoutMs:number)
    await RTOForm.detect(1500);

    // focus=true brings the tab/window to front.
    const res = await RTOForm.openTab(
      { "tabKey": "demo", "url": "https://example.com", "focus": true, "newTab": true },
      { "timeoutMs": 20000 }
    );

    // openTab returns tabId at the root (not inside data.*)
    console.log("Controlled tabId:", res && res.tabId);

  } catch (e) {
    console.error("RTO error:", e && e.code, e && e.message);
  }
})();
</script>

Optional configuration

Set these globals before loading RTO_form_api.js:

API quick reference

Exports: window.RTOForm with these methods:

Advanced: using send()

Use send() when you need to pass action-specific fields that are not covered by the convenience wrappers. (send() forwards all payload fields except timeoutMs, which must be provided in opts.)

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script>
(async function () {
  await RTOForm.detect(1500);

  // Low-level openTab with explicit timeout handling
  await RTOForm.send(
    "openTab",
    { "url": "https://example.com", "focus": true, "newTab": true },
    { "tabKey": "demo", "timeoutMs": 20000 }
  );
})();
</script>

Allow-list note

RTO_form_api.js is the core helper. If your page also manages the allow-list, use RTO_domainList.js on top of it. In 7.13.0, page-side allow-list additions go through allowlistAddRequest and the user confirms on the matching master tab.

tabStatus events (status stream)

Subscribe to the extension's tab lifecycle stream (activation, URL changes, loading/complete…).

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script>
(function () {
  function log(ev) {
    if (ev && ev.type === "tabStatus") console.log("tabStatus:", ev);
  }

  RTOForm.onStatus(log);

  // Example: wait until a given tabKey reports "complete"
  RTOForm.waitForStatus(function (ev) {
    return ev && ev.type === "tabStatus" && ev.tabKey === "demo" && ev.event === "complete";
  }, 15000).then(function (ev) {
    console.log("demo tab is complete:", ev);
  });
})();
</script>

Common errors

Next

• Form helpers
• RTO detector