JavaScript SDK reference

@revokegpt/js is a typed wrapper over the RevokeGPT browser script. It loads the script once, renders widgets and gives you a response token. It has no runtime dependencies and ships ESM and CommonJS. For a walkthrough, see the JavaScript quickstart.

Install

Not published yet

@revokegpt/js is not on its registry yet, so install it from a checkout of the repository as in the quickstart. After the first release the registry command applies.

npm install @revokegpt/js     # after the first release

Exports

load, render, challengeAccount, RevokeGPTLoadError, DEFAULT_ORIGIN, and the types Badge, ChallengeAccountOptions, LoadOptions, Locale, RenderOptions, RevokeGPTApi, Size, Theme, Widget.

Options

load options

Option	Type	Default	Meaning
origin	string	https://js.revokegpt.com	Widget origin. A bare https: origin only (no path, query or credentials). http://localhost:* is accepted only when process.env.NODE_ENV !== 'production'.
nonce	string	none	Set on the injected script as its CSP nonce.
hl	Locale	none	Default language for widgets that set none.

render options

Option	Type	Default	Meaning
sitekey	string	required	Your site key (rgpk_ plus 20 letters or digits).
theme	'light' | 'dark' | 'auto'	none	Widget theme.
size	'normal' | 'compact' | 'invisible'	invisible	normal and compact are the checkbox frame; invisible is a hidden frame plus a badge.
tabindex	number	none	Tab order of the frame.
badge	'bottomright' | 'bottomleft' | 'inline'	bottomright	Invisible size only.
hl	Locale	the hl given to load()	Widget language, one of the 28 launch locales.
action	string	none	The action the token is issued for. Your server checks it.
cdata	string	none	Optional string passed with the widget.
callback	(token: string) => void	none	Receives the response token.
expired-callback	() => void	none	The token expired and was dropped.
error-callback	(code: string) => void	none	Receives the error code, for example network-error.
title	string	none	Optional widget title.
responseField	'revokegpt-response' | 'g-recaptcha-response'	revokegpt-response	Name of the hidden response field.
isolated	boolean	none	The widget has no part in the loader’s default widget rule.
session	boolean	false	Keep a firewall session: the loader runs a hidden session widget at load and again 300 s before each session token expires while the tab is visible, and hands the token to your integration or sets the __Host-rg_s cookie. See session tokens and cookies.

challengeAccount options

Option	Type	Default	Meaning
requestToken	string	required	The requestToken of an assessment’s accountVerification.endpoints entry.
container	Element | string	the body	Holds the temporary response field of the dialog’s hidden widget.
languageCode	Locale	the hl given to load()	Dialog language.

Methods

load

function load(opts?: LoadOptions): Promise<RevokeGPTApi>

Injects <script src="<origin>/v1/api.js"> once and resolves with the loader (window.revokegpt) when it is ready. It is memoised: a second call returns the same load. It rejects with RevokeGPTLoadError on a bad origin, a script error or after 15 seconds, and a failed load can be retried.

await load({ nonce: document.querySelector<HTMLMetaElement>('meta[name=csp-nonce]')?.content });

render

function render(el: Element, opts: RenderOptions): Widget

Renders a widget into el and returns a Widget. Call it after await load(); before that it throws RevokeGPTLoadError.

Widget member	Signature	Meaning
id	number	The widget id.
execute	() => Promise<string>	Runs the challenge and resolves with the response token.
reset	() => void	Resets the widget.
getResponse	() => string	The live token, or '' when there is none.
destroy	() => void	Removes the widget. Safe to call more than once. After it, execute rejects and getResponse gives ''.

const widget = render(document.getElementById('captcha')!, {
  sitekey: 'rgpk_...',
  action: 'login',
  callback: (token) => console.log(token),
});
const token = await widget.execute(); // send it to your server and verify it there
widget.destroy();

challengeAccount

function challengeAccount(sitekey: string, opts: ChallengeAccountOptions): Promise<string>

Runs the email-code step of account verification. A dialog asks for the code the service emailed, and the promise resolves with the verification token. Your server presents that token in a following assessment of the same account; success or failure is read there, not here. It rejects with Error('cancelled') when the person cancels and with Error('busy') while another dialog is open. Call it after await load().

Errors and failure model

• load rejects with RevokeGPTLoadError (name is 'RevokeGPTLoadError'): bad origin, window.revokegpt not the loader, script error, timeout.
• render and challengeAccount throw or reject with RevokeGPTLoadError when the script is not loaded; challengeAccount also does when the loaded loader release has no challengeAccount.
• Widget errors arrive through error-callback as a code string. See errors.
• execute() on a destroyed widget rejects with Error('widget was destroyed'). challengeAccount rejects with Error('cancelled') or Error('busy'), as above.

Configuration

There are no environment variables to set. The only setting that reads the build environment is the localhost rule for origin; where there is no process, the page counts as production.

Content Security Policy:

• script-src: allow the widget origin, or pass nonce to load(). The loader copies it onto everything it adds.
• frame-src: allow the widget origin; each widget is an iframe from it.

Security notes

• The token is only a claim until your server verifies it with an SDK such as Node.js or with siteverify. Never trust it in the browser.
• origin accepts a bare https: origin only. javascript:, data: and http: are rejected before anything is injected.
• There is no option to load the script from an arbitrary URL.