Widget Service SDK

A universal JavaScript SDK for Widget Service connector operations. Available as UMD, ES modules, and TypeScript.

Key Features

• Zero Configuration: Automatically detects base URL from current domain
• Browser-First: Designed for browser environments with automatic CSRF token detection
• Developer Mode: Test against different instances with custom configuration
• TypeScript Support: Full type definitions included

Installation

yarn add @gainsight-customer-hub/widget-service-sdk
# or
npm install @gainsight-customer-hub/widget-service-sdk

Usage

Basic Usage

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

// Simple initialization - baseUrl is automatically set to current domain + /widget-service
const sdk = new WidgetServiceSDK();

// Or with optional configuration
const sdk = new WidgetServiceSDK({
  timeout: 10000, // custom timeout
  headers: { "X-Custom": "value" } // additional headers
});

// Execute a connector
const result = await sdk.connectors.execute({
  permalink: "connector-permalink",
  method: "POST",
  payload: { input: "data" }
});

Browser (UMD)

<script src="https://static.customer-hub.northpass.com/widget-sdk/latest/index.umd.js"></script>
<script>
  // No configuration needed - automatically uses current domain + /widget-service
  const sdk = new window.WidgetServiceSDK();

  // Execute a connector
  sdk.connectors
    .execute({
      permalink: "my-connector",
      method: "GET"
    })
    .then((result) => {
      console.log(result);
    });
</script>

Developer Mode

Test against specific instances:

// Test against a specific instance
sdk.enableDeveloperMode({
  instanceUrl: "https://your-instance.com", // optional
  apiKey: "instance-api-key",
  userContext: {
    identity: { email: "test@example.com", ch: { id: "123" } },
    exp: Math.floor(Date.now() / 1000) + 3600,
    iat: Math.floor(Date.now() / 1000)
  }
});

// Or omit instanceUrl to use the default instance
sdk.enableDeveloperMode({
  apiKey: "instance-api-key",
  userContext: {
    identity: { email: "test@example.com", ch: { id: "123" } },
    exp: Math.floor(Date.now() / 1000) + 3600,
    iat: Math.floor(Date.now() / 1000)
  }
});

// Check current base URL
console.log(sdk.getBaseUrl());

// Disable developer mode (returns to normal operation)
sdk.disableDeveloperMode();

API

Constructor Options

• csrfToken?: string - CSRF token (auto-detected from DOM in browser)
• headers?: Record<string, string> - Additional headers to include with requests
• timeout?: number - Request timeout in ms (default: 30000)

Note: The SDK automatically uses ${window.location.origin}/widget-service as the base URL and only works in browser environments. API keys are only used in developer mode.

Methods

Core Methods

• connectors.execute(options) - Execute a connector

Developer Mode

• enableDeveloperMode(options) - Enable developer mode for testing against specific instances
• disableDeveloperMode() - Disable developer mode and return to normal operation
• isInDeveloperMode() - Check if currently in developer mode

Configuration

• setApiKey(key) / clearApiKey() - Manage API key
• updateHeaders(headers) - Update default headers
• setDefaultTimeout(ms) - Set request timeout

Utilities

• getBaseUrl() - Get current base URL (useful in developer mode)
• getHeaders() - Get current default headers
• getCsrfTokenValue() - Get CSRF token from DOM
• hasCsrfToken() - Check if CSRF token is available

Publishing

The package is automatically published to NPM when version changes are merged to master.

Development

# Install dependencies
yarn install

# Run tests
yarn workspace @gainsight-customer-hub/widget-service-sdk test

# Build
yarn workspace @gainsight-customer-hub/widget-service-sdk build

# Lint + format + test
yarn workspace @gainsight-customer-hub/widget-service-sdk inspect

License

MIT