API Reference

Complete reference for the WidgetServiceSDK constructor, the connectors.execute method, and all TypeScript types. Use this page when you need exact parameter names, types, default values, or error behavior.

WidgetServiceSDK

Constructor

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

const sdk = new WidgetServiceSDK(config?: SDKConfig);

connectors.execute(options)

Execute a connector and return the response.

const result = await sdk.connectors.execute({
  permalink: "my-connector",
  method: "POST",
  payload: { name: "Monstera", size: "M" },
  headers: { "X-Request-Id": "abc-123" },
  queryParams: { format: "json" }
});

Parameters

Parameter	Type	Required	Default	Description
permalink	string	Yes	—	The connector's unique permalink identifier
method	HttpMethod	Yes	—	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
payload	ExecutePayload	No	undefined	Request body. Only sent for POST, PUT, PATCH methods
queryParams	Record<string, string>	No	{}	Query parameters appended to the request URL
headers	Record<string, string>	No	{}	Additional headers for this request

Returns Promise<ExecuteResponse>

Types

All types can be imported directly:

import type {
  HttpMethod,
  ExecuteConnectorOptions,
  ExecutePayload,
  ExecuteResponse,
  SDKConfig
} from "@gainsight-customer-hub/widget-service-sdk";

SDKConfig

interface SDKConfig {
  csrfToken?: string;
  headers?: Record<string, string>;
  timeout?: number;
}

Field	Type	Default	Description
csrfToken	string	Auto-detected	CSRF token. Auto-detected from a DOM element with id csrftoken
headers	Record<string, string>	{}	Headers included with every request
timeout	number	30000	Request timeout in milliseconds

HttpMethod

type HttpMethod =
  | "GET"
  | "POST"
  | "PUT"
  | "PATCH"
  | "DELETE"
  | "HEAD"
  | "OPTIONS";

ExecuteConnectorOptions

interface ExecuteConnectorOptions {
  permalink: string;
  method: HttpMethod;
  payload?: ExecutePayload;
  headers?: Record<string, string>;
  queryParams?: Record<string, string>;
}

ExecutePayload

interface ExecutePayload {
  [key: string]: JsonValue;
}

JsonValue covers strings, numbers, booleans, null, arrays, and nested objects.

ExecuteResponse

interface ExecuteResponse {
  [key: string]: JsonValue;
}

Error handling

Wrap execute calls in a try/catch to handle network errors, timeouts, and connector failures:

try {
  const data = await sdk.connectors.execute({
    permalink: "my-connector",
    method: "GET"
  });
  console.log(data);
} catch (error) {
  console.error("Connector execution failed:", error.message);
}

Common failure scenarios:

Scenario	Cause
Network error	The backend is unreachable
Timeout	Request exceeded the configured timeout (default 30s)
Connector not found	The permalink does not match any existing connector
Authentication failure	The connector's auth credentials are invalid or expired
Upstream error	The destination API returned an error

Next Steps

• SDK Examples — See real-world usage patterns with error handling
• Calling from Widget Code — How to call connectors using the SDK
• Rendering & DOM — Understand Shadow DOM context for DOM manipulation