Skip to main content

JavaScript API​

AI‑Kit exposes a public runtime surface under the WP Suite global:

  • globalThis.WpSuite.plugins.aiKit — the plugin object (registered by the AI‑Kit plugin)
  • globalThis.WpSuite.plugins.aiKit.features — feature methods + UI helpers

All feature methods are async and return a Promise.

Defensive access

Always use optional chaining (?.) in case AI‑Kit is not installed on the current site/page.

Runtime helpers (shared WP Suite contract)​

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

Helper accessors​

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

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

(These are thin wrappers around globalThis.WpSuite.)

Plugin status​

WpSuite.plugins.aiKit.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 AI‑Kit is ready​

You can wait in three common ways:

1) onReady(cb)

globalThis.WpSuite?.plugins?.aiKit?.onReady?.(() => {
  console.log("AI‑Kit is ready");
});

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

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

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

3) AI‑Kit core wrappers (waitForAiKitReady)

If your build includes the AI‑Kit core package, you can use its convenience wrappers:

  • getAiKitPlugin()
  • waitForAiKitReady(timeoutMs = 8000)
  • getStore(timeoutMs = 10000) (awaits readiness, then returns the store promise)

These are thin helpers on top of the events below.

Readiness / error events​

AI‑Kit emits DOM events you can listen to:

  • wpsuite:ai-kit:ready
  • wpsuite:ai-kit:error
window.addEventListener("wpsuite:ai-kit:ready", () => console.log("ready"));
window.addEventListener("wpsuite:ai-kit:error", () => console.log("error"));
WordPress wp.events

Some builds also re-emit these via WpSuite.events / wp.events. The DOM events above are the safest cross-context option.

Feature APIs (programmatic calls)​

The async helpers under WpSuite.plugins.aiKit.features mirror the functions exported from @smart-cloud/ai-kit-core.

Shared options (FeatureOptions)​

  • context: "admin" | "frontend" (defaults to "admin"; the front-end wrappers pass "frontend" automatically)
  • modeOverride: force a one-off capability mode — "local-only" | "backend-fallback" | "backend-only"
  • onDeviceTimeoutOverride: override the default 45 s (or 5 s for quick features) on-device timeout when using Chrome APIs
  • signal, headers, query: forwarded to the backend dispatcher
  • onStatus(event): receive progress steps such as decide, on-device:download, backend:request, done
  • Feature-specific extras may be read from the same object (for example maxCandidates for backend language detection)

Methods​

write(args, options?) → { result: string }

  • args: { prompt, context?, sharedContext?, tone?, format?, length?, outputLanguage? }
  • Backend calls also honour knowledgeBaseId / disableKB

rewrite(args, options?) → { result: string }

  • args: { text, context?, sharedContext?, tone?, format?, length?, outputLanguage? }

summarize(args, options?) → { result: string }

  • args: { text, context?, sharedContext?, type?, format?, length?, outputLanguage? }

translate(args, options?) → { result: string }

  • args: { text, sourceLanguage, targetLanguage }

detectLanguage(args, options?) → { result: { candidates: LanguageDetectionResult[] } }

  • args: { text }
  • For backend-only flows you can add options.maxCandidates

proofread(args, options?) → { result: ProofreadResult }

  • args: { text, expectedInputLanguages?, includeCorrectionTypes?, includeCorrectionExplanations?, correctionExplanationLanguage? }

prompt(args, options?) → { result: string, sessionId?, metadata? }

  • args: { messages, sharedContext?, outputLanguage?, images?, responseConstraint?, topK?, temperature?, maxTokens?, knowledgeBaseId?, disableKB? }
  • metadata.stopReason === "max_tokens" means the model hit the output cap; metadata.maxTokens shows the applied backend limit.

sendChatMessage(args, options?) → { result: string, sessionId?, metadata? }

  • args: { sessionId?, message, sharedContext?, images?, topK?, temperature?, maxTokens?, knowledgeBaseId?, disableKB? }
  • Saves chat history automatically when sessionId is omitted

sendFeedbackMessage(args, options?) → { result: string, sessionId?, metadata? }

  • args: { feedbackType: "accepted" | "rejected", feedbackMessageId, sessionId }

sendSearchMessage(args, options?) → { result: string, sessionId?, citations?, metadata? }

  • args: { query, sessionId?, sharedContext?, knowledgeBaseId?, topK?, temperature?, maxTokens? }
  • Returns a short answer/summary in result plus optional citations (docs + chunks) when available.

Feature option helpers​

When you need the raw Chrome API create() options (for example to pre-cache models), use:

  • getWriteOptions(partialArgs) / getRewriteOptions(partialArgs)
  • getSummarizeOptions(partialArgs) / getTranslateOptions(partialArgs)
  • getProofreadOptions() / getPromptOptions(partialArgs)

Each helper returns the corresponding *CreateCoreOptions structure from Chrome’s built-in AI APIs.

Example: translate a string​

const f = globalThis.WpSuite?.plugins?.aiKit?.features;
if (!f) return;

const { result } = await f.translate({
  text: "Hello world",
  sourceLanguage: "en",
  targetLanguage: "de",
});

console.log(result);

Example: summarize current content (with progress)​

const aiKit = globalThis.WpSuite?.plugins?.aiKit;
const f = aiKit?.features;
if (!aiKit || !f) return;

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

const { result } = await f.summarize(
  { text: "Long article text...", type: "tldr", length: "short" },
  {
    onStatus: (ev) => {
      // ev.step: "decide" | "on-device:download" | "backend:request" | ...
      console.log(ev.step, ev.progress);
    },
  },
);

console.log(result);

UI injection (renderFeature)​

For custom themes/plugins, AI‑Kit can render its interactive UI into a target element:

  • WpSuite.plugins.aiKit.features.renderFeature(args) → returns an AiWorkerHandle

This is how the AI‑Kit Feature block / shortcode can create UI on the front-end.

Minimal example: render a modal translate UI​

const f = globalThis.WpSuite?.plugins?.aiKit?.features;
if (!f) return;

let handle;
handle = await f.renderFeature({
  mode: "translate",
  title: "Translate",
  variation: "modal",
  onClose: () => handle?.close?.(),
  autoRun: false,
  default: {
    text: "Hello world",
    inputLanguage: "en",
    outputLanguage: "de",
  },
});

Cleaning up​

The returned handle typically includes:

  • container — the root element
  • close() — close the UI (if applicable)
  • unmount() — unmount + cleanup

For custom themes/plugins, AI‑Kit can also render the Doc Search UI into a target element:

  • WpSuite.plugins.aiKit.features.renderSearchComponent(args) → returns an AiWorkerHandle

This is what the AI‑Kit Doc Search block / shortcode uses on the front-end.

Minimal example: render Doc Search into a container​

const f = globalThis.WpSuite?.plugins?.aiKit?.features;
if (!f) return;

let handle;
handle = await f.renderSearchComponent({
  target: "#doc-search",
  title: "Search docs",
  autoRun: false,
  topK: 10,
  snippetMaxChars: 160,
});

Store access (advanced)​

AI‑Kit exposes a lazily created store:

  • WpSuite.plugins.aiKit.features.store → Promise<Store>

This is useful if you build custom UI and want to observe settings/diagnostics.

const storePromise = globalThis.WpSuite?.plugins?.aiKit?.features?.store;
const store = storePromise ? await storePromise : null;