onPanelEvent

Delivers panel events to the host application for handling.

Overview

The onPanelEvent method is called when a panel interaction or internal SDK event requires a response from the host. Each event has a type and payload so the host can act accordingly.

Method Signature

onPanelEvent(event: PanelEvent): void;

Event types

Important: The table below lists the public panel events. Some additional events are client-specific and are not documented here.

Event type	Event payload	Description
general:error	{ message: string; code: number; details: { panel: string; url: string } }	An SDK-managed API request failed (e.g. an authorization error). See Authorization errors.
fantasy:request:login	{ onLoginSuccess: () => void }	A panel needs the user to log in. Run your login flow, then call onLoginSuccess() so the SDK can refresh its state.

Authorization errors (401)

When an SDK-managed request returns HTTP 401, the SDK fires general:error. The host is expected to refresh the user's credentials/headers and push them back to the affected panel via setDataToPanel.

The SDK gates these events to avoid loops:

• A second general:error is not fired until the host has supplied refreshed headers via setDataToPanel and a request has been retried with them.
• general:error fires at most 3 times per session.

The details payload tells you which panel and request failed:

• details.panel — the panel that issued the failed request.
• details.url — the request URL that failed.

Return Value

This method does not return a value.

Example

class Delegate implements IMaestroEventDelegate {
  onPanelEvent(event: PanelEvent): void {
    switch (event.type) {
      case "general:error": {
        const { message, code, details } = event.payload as {
          message: string;
          code: number;
          details: { panel: string; url: string };
        };
        console.warn(`Panel "${details.panel}" request failed (${code}): ${message}`);

        if (code === 401) {
          // Refresh credentials, then hand fresh headers back to the panel.
          const headers = await refreshAuthHeaders();
          SDK.getMaestroEventViewModel().setDataToPanel({
            [details.panel]: { headers },
          });
        }
        break;
      }

      case "fantasy:request:login": {
        const { onLoginSuccess } = event.payload as { onLoginSuccess: () => void };
        // Run your app's login flow, then notify the SDK so it can refresh.
        await showLoginFlow();
        onLoginSuccess();
        break;
      }
    }
  }
}

Notes

• PanelEvent.payload is typed as unknown. Always check event.type first, then narrow/cast payload to the shape for that type before reading its fields.