@metagptx/support-sdk

The Atoms Support SDK is a small, framework-agnostic browser client. It owns the host-side lifecycle and communicates with the hosted Messenger application through a versioned, origin-checked postMessage protocol.

Install

npm install @metagptx/[email protected]

This prerelease is published on the public npm registry under the beta dist-tag. Pin the exact beta version while evaluating it.

The package is SSR-safe to import. Call boot only from a browser/client lifecycle hook. Identity tokens are requested on demand and are never stored in the URL or persistent browser storage.

import { createAtomsSupport } from "@metagptx/support-sdk";

const support = createAtomsSupport({
  // Include the deployment prefix in the public Support API base URL.
  endpoint: "https://support-api.example.com/api",
  widgetUrl: "https://support.example.com/messenger",
  productKey: "atoms-web",
  environment: "production",
  getIdentityToken: () => api.getSupportIdentityToken(),
});

const bootResult = await support.boot({
  locale: "en-US",
  identityKey: currentUser.id,
});

if (bootResult.state === "ready") {
  await support.openChat({ entryPoint: "help_button" });
  // For a feedback-only entry point, use this instead of openChat():
  // await support.openFeedback({ entryPoint: "chat_message", context: { messageId } });
} else {
  console.warn("Support is temporarily unavailable", bootResult.error);
}

Always pass a stable identityKey for authenticated users. A changed key forces teardown before the next identity token is requested. If it is omitted, repeated boot calls conservatively rebuild the session so a switched account cannot inherit the previous iframe; cross-tab shutdown broadcasting is disabled because there is no safe identity to match. With an identity key, shutdown broadcasts only a metadata-only signal scoped to this package's productKey/environment and the same identity key.

onTelemetry receives lifecycle names, timing, state and error codes only. It never receives identity tokens, user IDs, message text or page context.

boot is fail-open: a widget/network failure produces a degraded result and an error event, without blocking the host application's main flow. Calls to the identity provider, iframe handshake, Messenger commands, and commands queued behind boot are all bounded. identityTokenTimeoutMs, commandTimeoutMs, and queueTimeoutMs can be tuned independently.

Public Support sessions are short lived. When the Messenger reports expiry, the SDK calls getIdentityToken again, exchanges the new token in the existing iframe, and queues host commands behind that renewal. A failed renewal moves the SDK to degraded and emits both sessionExpired and error. Opening the Messenger moves keyboard focus into the iframe; closing it restores the host element that was focused before openChat, openFeedback, or show.

Version-pinned CDN loader

The package also contains dist/loader.global.js, a minified, self-contained IIFE for non-module pages. Always pin its exact package version. Set window.AtomsSupportConfig before loading it; the bundle installs window.AtomsSupport automatically and replays a pre-existing command queue.

<script>
  window.AtomsSupportConfig = {
    endpoint: "https://support-api.example.com/api",
    widgetUrl: "https://support.example.com/messenger",
    productKey: "atoms-web",
    environment: "production",
    getIdentityToken: () => window.appApi.getSupportIdentityToken(),
  };
  window.AtomsSupport = Object.assign(
    (command, payload) => {
      window.AtomsSupport.q.push([command, payload]);
      return Promise.resolve();
    },
    { q: [] },
  );
  window.AtomsSupport("boot", {
    identityKey: window.currentUser.id,
    locale: "en-US",
  });
</script>
<script src="https://cdn.jsdelivr.net/npm/@metagptx/[email protected]/dist/loader.global.js"></script>

Each queued command has an independent error boundary, so a rejected entry does not block later entries or leak an unhandled rejection. After the bundle loads, window.AtomsSupport.ready resolves when the captured queue is drained. Loading the IIFE without AtomsSupportConfig fails closed with INVALID_GLOBAL_CONFIGURATION.

Distribution contents

The published tarball omits source-map files and embedded sourcesContent. It still contains the executable JavaScript and type declarations required by consumers; omitting source maps is packaging hygiene, not a source-code secrecy or security boundary.