Widget SDK

Methods and Constructors

Complete reference for the WidgetServiceSDK constructor, the connectors.execute method, and error behavior.

Constructor

const sdk = new window.WidgetServiceSDK(config);

The config argument is optional. Pass a configuration object when creating the SDK instance:

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

Option	Type	Default	Description
headers	Record<string, string>	{}	Headers included with every request
timeout	number	30000	Request timeout in milliseconds

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" },
  pathParams: { user_id: 42 }
});

Parameters

Parameter	Type	Required	Default	Description
permalink	string	Yes	—	The connector's unique permalink identifier
method	"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS"	Yes	—	HTTP method
payload	Record<string, JsonValue>	No	undefined	The request body, as a plain JSON object. Pass it via payload (not body). Only sent for POST, PUT, PATCH methods
queryParams	Record<string, string>	No	{}	Query parameters appended to the request URL
pathParams	Record<string, string | number>	No	{}	Values substituted into {{ pathParams.X }} URL template references on the connector. See Dynamic URL Path Segments
headers	Record<string, string>	No	{}	Additional headers for this request

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

Pass the request body via payload, not body

The request body goes in the payload option as a plain JSON object. body is not a recognized option — and execute() silently ignores any option it does not recognize, so a call using body sends an empty request body.

Returns Promise<Record<string, JsonValue>>

Path parameter validation

pathParams is validated synchronously at the SDK boundary before any network call. The SDK throws ConnectorBoundaryError on:

• An empty or whitespace-only key (e.g. { "": "x" })
• A value whose type is not string | number — catches untyped JS callers passing null, undefined, booleans, objects, or arrays
• A serialized header value over 4096 characters (gateway / CDN per-header limits typically sit around 8–16 KB; this cap leaves headroom)
• Passing pathParams to sdk.connectors.composite.execute (composite connectors don't accept path parameters)

Omitting pathParams or passing {} sends no header — the request goes out unchanged. See Dynamic URL Path Segments — Validation and errors for the server-side error codes returned when validation passes the SDK but fails server-side.

Error handling

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

import {
  ConnectorBoundaryError,
  ConnectorExecuteError
} from "@gainsight-hub/connectors-sdk";

try {
  const data = await sdk.connectors.execute({
    permalink: "my-connector",
    method: "GET",
    pathParams: { user_id: 42 }
  });
  console.log(data);
} catch (error) {
  if (error instanceof ConnectorBoundaryError) {
    // Client-side rejection — invalid pathParams shape, composite + pathParams, etc.
    console.error("Boundary rejection:", error.reason);
  } else if (error instanceof ConnectorExecuteError) {
    switch (error.code) {
      case "MISSING_PATH_PARAMETERS":
      case "INVALID_PATH_PARAMETERS":
        // error.params: string[] — the failing keys
        console.error("Path params failed:", error.code, error.params);
        break;
      case "CONNECTOR_MISCONFIGURED":
        // error.detail: string — operator-facing detail
        console.error("Misconfigured:", error.detail);
        break;
      default:
        // Legacy shape — error.failureScope / error.reason / error.requestId / error.status
        console.error("Execute failed:", error.failureScope, error.reason, error.status);
    }
  } else {
    // Network / timeout / unknown
    console.error("Connector execution failed:", error.message);
  }
}

ConnectorBoundaryError is thrown synchronously before any HTTP call — it signals a malformed call. ConnectorExecuteError normalises two server-error shapes: the envelope { success: false, errors: { code, detail, scope?, params? }, request_id } returned for connector execution errors — path-parameter validation (HTTP 400) as well as connection, template, and authentication failures (HTTP 422/502/500) — exposed as optional code / params / detail fields, and the legacy { failure_scope, reason, request_id } (exposed as failureScope / reason). Branch on error.code to handle envelope errors; fall back to failureScope for legacy ones.

Common failure scenarios:

Scenario	Cause	Error class
Network error	The backend is unreachable	Error
Timeout	Request exceeded the configured timeout (default 30s)	Error
Connector not found	The permalink does not match any existing connector	Error (HTTP 404)
Authentication failure	The connector's auth credentials are invalid or expired	ConnectorExecuteError
Upstream error	The destination API returned an error	ConnectorExecuteError
Invalid pathParams shape	Empty key, wrong value type, oversized payload, or passed to composite	ConnectorBoundaryError
Missing required path param value	URL references {{ pathParams.X }} but caller omitted one or more keys from pathParams	ConnectorExecuteError (code: "MISSING_PATH_PARAMETERS")
Path param value fails URL-safe validation	Caller supplied a value containing characters outside [A-Za-z0-9._~-], or a path-traversal segment (..)	ConnectorExecuteError (code: "INVALID_PATH_PARAMETERS")

Next Steps

• 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