@kadanza/extension-sdk
    Preparing search index...

    Interface IExtensionSDK

    Public contract for talking to the Kadanza parent frame over postMessage.

    Requires a tenantUrl search param on the extension URL so connect can validate the parent origin.

    interface IExtensionSDK {
        isConnected: boolean;
        apiCall<T>(endpoint: string, options?: RequestInit): Promise<T>;
        connect(options?: ConnectOptions): Promise<HandshakePayload>;
        destroy(): void;
        emitNavigationChange(payload: NavigationChangePayload): void;
        emitRequestAuthTokenRefresh(options?: RequestOptions): Promise<AuthToken>;
        emitUpdatePageSettings(
            payload: UpdatePageSettingsPayload,
            options?: RequestOptions,
        ): Promise<PageSettingsUpdatedPayload>;
        getAllowedOrigin(): string | null;
        getApiUrl(): string | null;
        getAuthToken(): AuthToken | null;
        getDesignTokens(): DesignTokens | null;
        getExtensionDetails(): ExtensionDetails | null;
        getPageSettings(): PageSettings | null;
        getTenantUrl(): string | null;
        onAuthTokenRefresh(handler: (authToken: AuthToken) => void): () => void;
        onLoadPageSettings(handler: (settings: PageSettings) => void): () => void;
        onNavigate(
            handler: (payload: RequestNavigationChangePayload) => void,
        ): () => void;
    }

    Implemented by

    Index
    isConnected: boolean

    Whether a successful handshake has completed and not been destroyed.

    • Calls the Kadanza Platform API with the current connection credentials.

      Requests go to getApiUrl + endpoint. Authorization and tenant headers are managed by the SDK and cannot be overridden.

      Type Parameters

      • T

        Expected JSON response body.

      Parameters

      • endpoint: string

        Root-relative API path.

      • Optionaloptions: RequestInit

        Standard fetch options.

      Returns Promise<T>

      When not connected, handshake did not include authToken and extensionDetails (apiUrl or baseUrl, tenantDomain), the endpoint is invalid, the request fails, or the response is not successful JSON.

    • Establishes the parent connection and waits for HANDSHAKE_ACK.

      Safe to call repeatedly (e.g. from a React useEffect with deps):

      • Already connected: returns the cached handshake and re-applies authTokenAutoRefresh / authTokenBufferMs without another init. timeoutMs is ignored after connect.
      • Handshake in progress: returns the same in-flight promise. Options from the first connecting call apply until the handshake completes.

      Opt-in proactive refresh can be enabled with authTokenAutoRefresh: true (optional authTokenBufferMs).

      Pass routingType: "client-hash" for HashRouter SPAs so the parent can soft-navigate without reloading the iframe. Default is "server".

      Handshake completes when the parent sends HANDSHAKE_ACK. Context fields (authToken, extensionDetails, designTokens, pageSettings) are optional — omitted values are null. Use them only when the current host surface provides them (e.g. spaceId / pageId on Experience Pages, designTokens when a tenant is in context).

      Parameters

      • Optionaloptions: ConnectOptions

        Handshake timeout, routing type, and optional auth-token auto-refresh.

      Returns Promise<HandshakePayload>

      When tenantUrl is missing or invalid.

      When not embedded in a parent frame, destroyed, or the handshake times out.

    • Tears down listeners, proactive refresh timers, and cached state. Rejects any in-flight requests. The instance cannot be reused after destroy. When created via createExtensionSDK, clears the singleton so a later create call can return a fresh instance.

      Returns void

    • Notifies the parent that the extension's route changed.

      Wire: NAVIGATION_CHANGE (fire-and-forget). Also used as the ACK after handling onNavigate.

      Parameters

      Returns void

      When not connected or destroyed.

    • Asks the parent for a new auth token and waits for TOKEN_REFRESH.

      Parameters

      • Optionaloptions: RequestOptions

        Optional request timeout (default 10s).

      Returns Promise<AuthToken>

      When not connected, a refresh is already in progress, or the request times out / returns an invalid payload.

    • Validated parent postMessage origin from tenantUrl; null until connect resolves it.

      Returns string | null

    • Platform API base URL the parent uses for its own API calls.

      Returns handshake extensionDetails.apiUrl as sent. When the host omits it, falls back to deriving api.{hostname} from extensionDetails.baseUrl. null until connected, or when neither field is usable.

      Returns string | null

    • Last auth token from handshake or refresh. null until connected, or when the host omitted it.

      Returns AuthToken | null

    • Raw tenantUrl search-param value used for the allowed origin; null until connect reads it.

      Returns string | null

    • Registers a handler for auth-token updates (requested or parent-pushed).

      Parameters

      Returns () => void

      Unsubscribe function.

    • Registers a handler for parent-initiated LOAD_PAGE_SETTINGS.

      Parameters

      Returns () => void

      Unsubscribe function.