@shopassist/js

npm i @shopassist/js

No dependencies. The package loads the widget from the ShopAssist CDN rather than containing it.

Loading

ShopAssist(config)

The default export. Configures and loads in one call, and resolves to a handle, or to null on the server.

import ShopAssist from "@shopassist/js";

const widget = await ShopAssist({ shopDomain: "your-shop.com" });

configure(config)

Writes the configuration the widget reads when it loads. Synchronous, never touches the document, and does nothing on the server, so it is safe to call at module scope.

Nothing reaches the network until load(), which is how you gate the widget on cookie consent.

load()

Loads the widget and boots it. Returns one cached promise per page, so calling it from several modules still produces one script tag. If the page already carries the widget script, from a Shopify theme block for instance, this adopts it rather than loading a second copy.

On the server it resolves to null instead of throwing. It rejects only when the bundle fails to load, and a rejection clears the cache so a later call retries.

import { configure, load } from "@shopassist/js";

configure({ shopDomain: "your-shop.com" });
onConsent(() => load());

shutdown()

Unmounts the widget and forgets the configuration. load() boots it again.

update(patch)

Applies new configuration. The widget reads its configuration once at boot, so this unmounts and re-boots it, which closes an open chat. Use it for a language or customer change, not on every render.

Controlling the chat

open(options?)

Opens the chat. Safe to call before the widget has loaded; the call is held and replayed once it is on screen.

open();
open({ message: "Do you ship to Germany?" });

close()

Closes the chat.

isReady()

true once the widget is on screen. false while loading, and false when the shop is disabled or the page is excluded.

status()

"mounted", "disabled", "gated", or null while loading. See configuration for what each means.

Cart and attribution

setCart(bridge)

Replaces the cart bridge. Takes effect on the next add. See add to your cart.

getAttribution()

Returns { sessionId, attribution } for the current shopper. sessionId is null when they never opened the chat. See attribution.

Question pills

fetchQuestions(handle, options)

Reads a product's generated questions.

await fetchQuestions("rain-jacket", {
  shopDomain: "your-shop.com",
  language: "de",
});
// { enabled: true, questions: ["…"], items: [{ id: 42, question: "…" }] }

Returns enabled: false when the shop has the feature off, when the product has no questions enabled, or when the product is not in the catalog. It throws only on a server error.

mountQuestions(el, options)

Renders the pills into el and wires them to the chat. Returns a function that removes them and cancels a request still in flight. See question pills.

Compare

mountCompareButton(el, product, options?)

Adds a compare button inside el. Returns a function that removes it.

compareTwo(a, b, context?)

Compares two products immediately, skipping the picker. See compare products.

Inline

mountInline(config)

Mounts the inline chat surface. Returns { destroy() }. See inline chat.

Snippets

renderSnippet(config)

Builds the paste-in <script> block for a storefront with no build step. Use it to render an install step in a dashboard instead of keeping a second copy of the snippet by hand.

SnippetString

The installer's source text, which is what renderSnippet wraps.