Widget SDK

The SDK is a JavaScript library that your widget code uses to call connectors — the secure backend proxies that connect widgets to external APIs. Instead of making API calls directly from the browser (which would expose your credentials), you use the SDK to route requests through the platform.

Available as UMD and ES modules with full TypeScript support.

Installation

Package manager

yarn

yarn add @gainsight-customer-hub/widget-service-sdk

npm

npm install @gainsight-customer-hub/widget-service-sdk

ES module import

import { WidgetServiceSDK } from "@gainsight-customer-hub/widget-service-sdk";

const sdk = new WidgetServiceSDK();

UMD (script tag)

When loaded via a <script> tag, the SDK attaches to window:

<script src="https://static.customer-hub.northpass.com/widget-sdk/latest/index.umd.js"></script>
<script>
  const sdk = new window.WidgetServiceSDK();
</script>

Place the SDK <script> tag before the code that uses it. The browser loads scripts in order, so window.WidgetServiceSDK is available in any subsequent <script> block.

The SDK is not auto-injected

You must include the <script> tag in your widget HTML file. If window.WidgetServiceSDK is undefined, add the script tag shown above before your code.

Quick start

In a widget HTML file (no build step — the most common case):

<script src="https://static.customer-hub.northpass.com/widget-sdk/latest/index.umd.js"></script>
<script>
  // Async IIFE required — top-level await is not available in plain <script> tags
  (async () => {
    const sdk = new window.WidgetServiceSDK();

    const data = await sdk.connectors.execute({
      permalink: "weather-api",
      method: "GET",
      queryParams: { q: "Warsaw" }
    });

    console.log(data);
  })();
</script>

In a bundled app (Vite, Webpack, Rollup — after installing via npm/yarn):

import { WidgetServiceSDK } from "@gainsight-customer-hub/widget-service-sdk";

const sdk = new WidgetServiceSDK();

const data = await sdk.connectors.execute({
  permalink: "weather-api",
  method: "GET",
  queryParams: { q: "Warsaw" }
});

console.log(data);

Constructor options

Pass an optional configuration object when creating the SDK instance:

const sdk = new WidgetServiceSDK({
  timeout: 15000,
  headers: { "X-Custom-Header": "value" }
});

Option	Type	Default	Description
csrfToken	string	Auto-detected	Managed automatically by the SDK. You do not need to set this.
headers	Record<string, string>	{}	Headers included with every request
timeout	number	30000	Request timeout in milliseconds

Module formats

The package ships three builds:

Format	Entry point	Use case
ES module	dist/index.es.js	Bundlers (Vite, Webpack, Rollup)
UMD	dist/index.umd.js	Script tags, legacy environments
TypeScript	dist/index.d.ts	Type definitions

Modern bundlers pick the correct format automatically via the exports field in package.json.

Next Steps

• API Reference — full method signatures, types, and error handling
• Examples — real-world usage patterns
• Configuration — set up connectors to call with the SDK