API Reference

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

WidgetServiceSDK

Constructor

const sdk = new window.WidgetServiceSDK(config);

The config argument is optional — see Constructor options for available fields.

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	Request 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.

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

• 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