Skip to main content

JavaScript API​

Gatey exposes its public runtime surface under the WP Suite global:

  • globalThis.WpSuite.plugins.gatey (plugin object)
  • globalThis.WpSuite.plugins.gatey.cognito (Cognito/session helpers)

All helper methods are async and return a Promise unless noted otherwise.

Runtime helpers (shared WP Suite contract)​

WP Suite plugins share a small common runtime contract (from @smart-cloud/wpsuite-core).

Helper accessors​

If you are bundling @smart-cloud/wpsuite-core, you can also use:

  • getWpSuite() → returns the global WpSuite object (or undefined)
  • getPlugin("gatey" | "...") → returns a plugin object from the registry

(These are thin wrappers around globalThis.WpSuite.)

Plugin status​

WpSuite.plugins.gatey.status can be one of:

  • unavailable — plugin not present / not initialized yet
  • initializing — booting up
  • available — ready to use
  • error — failed to initialize

Wait until Gatey is ready​

There are three common ways to wait:

1) onReady(cb)

globalThis.WpSuite?.plugins?.gatey?.onReady?.(() => {
  console.log("Gatey is ready");
});

2) availability() (await-ready with timeout)

Resolves to available, unavailable, or error (it never returns initializing).

const res = await globalThis.WpSuite?.plugins?.gatey?.availability?.();
if (res !== "available") {
  console.warn("Gatey not available:", res);
}

3) Gatey core wrappers (waitForGateyReady)

If your build includes the Gatey core package, you can use its convenience wrappers:

  • getGateyPlugin()
  • waitForGateyReady(timeoutMs = 8000)

These are thin helpers on top of the events below.

Readiness / error events​

Gatey emits DOM events you can listen to:

  • wpsuite:gatey:ready
  • wpsuite:gatey:error
window.addEventListener("wpsuite:gatey:ready", () => console.log("ready"));
window.addEventListener("wpsuite:gatey:error", () => console.log("error"));

Cognito helper methods​

The methods below live under WpSuite.plugins.gatey.cognito.

MethodReturnsUse case
getUsername()stringDisplay the current username.
getUserAttributes()objectPrefill a form with profile data.
getMfaPreferences()objectShow MFA status.
clearMfaPreferences()voidOne-click TOTP disable.
isAuthenticated()booleanGuard a route or action.
isInGroup("admin")booleanRole-based UI.
getGroups()string[]Render a badge list.
getRoles()string[]IAM role switcher / role-aware UI.
getScopes()string[]Scope-aware buttons.
getPreferredRole()stringAuto-select a role.
setLanguage("en")voidSwitch the Authenticator’s UI language.

Example: show user and roles​

const gatey = globalThis.WpSuite?.plugins?.gatey;
const cognito = gatey?.cognito;

const ok = (await gatey?.availability?.()) === "available";
if (!ok) return;

console.log("User:", await cognito.getUsername());
console.log("Roles:", await cognito.getRoles());

Notes​

  • Always guard calls with optional chaining (?.) in case Gatey is not installed on the page.
  • If you are writing a plugin/theme that depends on Gatey, prefer availability() / onReady() / waitForGateyReady() over polling.