@kadanza/extension-sdk 0.0.14 → 0.2.0

package/dist/index.d.ts

@@ -31,7 +31,9 @@ export declare const CONNECTION_EVENTS: {
     readonly updatePageSettings: "UPDATE_PAGE_SETTINGS";
     /** Parent → child: result of a page settings update. */
     readonly pageSettingsUpdated: "PAGE_SETTINGS_UPDATED";
-    /** Child → parent: extension route changed. */
+    /** Parent → child: ask the SPA to navigate without reloading the iframe. */
+    readonly requestNavigationChange: "REQUEST_NAVIGATION_CHANGE";
+    /** Child → parent: extension route changed (ack or spontaneous). */
     readonly navigationChange: "NAVIGATION_CHANGE";
 };
 
@@ -42,6 +44,11 @@ export declare type ConnectionEvent = (typeof CONNECTION_EVENTS)[keyof typeof CO
 export declare interface ConnectOptions {
     /** Handshake timeout in milliseconds (default 10_000). */
     timeoutMs?: number;
+    /**
+     * Routing mode announced to the parent on `HANDSHAKE_INIT`.
+     * HashRouter SPAs should pass `client-hash`. Default: `server`.
+     */
+    routingType?: RoutingType;
     /**
      * Enables proactive auth-token refresh. After the handshake, the SDK reads
      * the auth token's Unix-seconds `expires` value and arms a one-shot timer
@@ -78,11 +85,26 @@ export declare interface ConnectOptions {
  */
 export declare const createExtensionSDK: () => IExtensionSDK;
 
-/** Branding tokens from the parent for aligning extension UI. */
+/** Default when `routingType` is omitted or unrecognized. */
+export declare const DEFAULT_ROUTING_TYPE: RoutingType;
+
+/**
+ * Tenant branding from the parent, for aligning extension UI with the host.
+ *
+ * The host should send this whenever a tenant is in context (Experience Pages
+ * and Admin Console). Handshake still succeeds if it is omitted — treat every
+ * field as optional.
+ *
+ * - `primaryColor` — tenant palette primary; accents, buttons, links
+ * - `fontFamily` — tenant font family; body and UI type
+ * - `borderRadius` — tenant roundness; controls and cards
+ *
+ * Values may be missing when the tenant has no setting configured.
+ */
 export declare interface DesignTokens {
-    primaryColor: string;
-    fontFamily: string;
-    borderRadius: string;
+    primaryColor?: string;
+    fontFamily?: string;
+    borderRadius?: string;
 }
 
 /**
@@ -94,17 +116,28 @@ export declare interface DesignTokens {
  */
 export declare function enrichExtensionUrl(urlRaw: string | null | undefined, tenantUrl?: string): URL | null;
 
-/** Context about the embedded extension and its host page from handshake. */
+/**
+ * Host context from handshake. Only set when the parent includes it.
+ *
+ * Field availability depends on where the iframe is mounted:
+ * - Experience Pages typically send `spaceId` and `pageId`.
+ * - Admin Console Pages typically omit those — there is no space page.
+ *
+ * Other identity fields are sent when the host knows them. Handshake does not
+ * require this object.
+ */
 export declare interface ExtensionDetails {
-    extensionId: string;
-    tenantId: string;
-    tenantDomain: string;
-    /** Base URL of the parent application. */
-    baseUrl: string;
-    spaceId: string;
-    pageId: string;
+    extensionId?: string;
+    tenantId?: string;
+    tenantDomain?: string;
+    /** Base URL of the parent application (used to derive the Platform API origin). */
+    baseUrl?: string;
+    /** Space that owns the Experience Page. Omitted in Admin Console. */
+    spaceId?: string;
+    /** Experience Page id. Omitted in Admin Console. */
+    pageId?: string;
     /** BCP 47 locale from the parent. */
-    locale: string;
+    locale?: string;
 }
 
 /** Envelope for parent/child `postMessage` traffic. */
@@ -130,6 +163,7 @@ export declare class ExtensionSDK implements IExtensionSDK {
     emitRequestAuthTokenRefresh(options?: RequestOptions): Promise<AuthToken>;
     emitUpdatePageSettings(payload: UpdatePageSettingsPayload, options?: RequestOptions): Promise<PageSettingsUpdatedPayload>;
     onLoadPageSettings(handler: (settings: PageSettings) => void): () => void;
+    onNavigate(handler: (payload: RequestNavigationChangePayload) => void): () => void;
     onAuthTokenRefresh(handler: (authToken: AuthToken) => void): () => void;
     emitNavigationChange(payload: NavigationChangePayload): void;
 }
@@ -140,7 +174,9 @@ export declare class ExtensionSDKHost implements IExtensionSDKHost {
     constructor(options: ExtensionSDKHostOptions);
     start(): void;
     destroy(): void;
+    getRoutingType(): RoutingType;
     emitLoadPageSettings(settings: PageSettings | null): void;
+    requestNavigationChange(payload: RequestNavigationChangePayload, options?: RequestOptions): Promise<NavigationChangePayload>;
 }
 
 /**
@@ -155,10 +191,11 @@ export declare interface ExtensionSDKHostOptions {
     /** Extension origin used as `postMessage` targetOrigin / source filter. */
     origin: string;
     /**
-     * Builds the handshake payload (including auth token) when the child sends
-     * `HANDSHAKE_INIT`.
+     * Builds the handshake payload when the child sends `HANDSHAKE_INIT`.
+     * Context fields are optional; send `designTokens` whenever a tenant is in
+     * context. `spaceId` / `pageId` apply to Experience Pages only.
      */
-    resolveHandshakePayload: () => HandshakePayload | Promise<HandshakePayload>;
+    resolveHandshakePayload: (extensionSDKHost: IExtensionSDKHost) => Partial<HandshakePayload> | Promise<Partial<HandshakePayload>>;
     /**
      * Resolves a fresh auth token when the child sends `REQUEST_TOKEN_REFRESH`.
      */
@@ -168,13 +205,33 @@ export declare interface ExtensionSDKHostOptions {
      * Return `true` on success; the host emits `PAGE_SETTINGS_UPDATED`.
      */
     onUpdatePageSettings?: (settings: PageSettings) => boolean | Promise<boolean>;
+    /**
+     * Called when the child reports a route change via `NAVIGATION_CHANGE`
+     * (spontaneous or as ACK to {@link IExtensionSDKHost.requestNavigationChange}).
+     */
+    onNavigationChange?: (payload: NavigationChangePayload) => void;
 }
 
-/** Payload delivered with a successful `HANDSHAKE_ACK`. */
+/** Payload for `HANDSHAKE_INIT` (child → parent). */
+export declare interface HandshakeInitPayload {
+    /**
+     * Declares how the extension routes. Omit or unknown → `server`.
+     * Soft navigation requires `client-hash`.
+     */
+    routingType?: RoutingType;
+}
+
+/**
+ * Context delivered with `HANDSHAKE_ACK`.
+ *
+ * Handshake completes as soon as the parent ACKs. Every property is optional
+ * and only populated when that host surface provides it. After `connect()`,
+ * omitted wire fields are normalized to `null`.
+ */
 export declare interface HandshakePayload {
-    authToken: AuthToken;
-    extensionDetails: ExtensionDetails;
-    designTokens: DesignTokens;
+    authToken: AuthToken | null;
+    extensionDetails: ExtensionDetails | null;
+    designTokens: DesignTokens | null;
     pageSettings: PageSettings | null;
 }
 
@@ -200,10 +257,19 @@ export declare interface IExtensionSDK {
      * Opt-in proactive refresh can be enabled with
      * `authTokenAutoRefresh: true` (optional `authTokenBufferMs`).
      *
-     * @param options - Handshake timeout and optional auth-token auto-refresh.
+     * 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).
+     *
+     * @param options - Handshake timeout, routing type, and optional auth-token auto-refresh.
      * @throws {InvalidOriginError} When `tenantUrl` is missing or invalid.
      * @throws When not embedded in a parent frame, destroyed, or the handshake
-     *   times out / returns an invalid payload.
+     *   times out.
      */
     connect(options?: ConnectOptions): Promise<HandshakePayload>;
     /**
@@ -215,11 +281,20 @@ export declare interface IExtensionSDK {
     destroy(): void;
     /** Whether a successful handshake has completed and not been destroyed. */
     readonly isConnected: boolean;
-    /** Last auth token from handshake or refresh; `null` until connected. */
+    /**
+     * Last auth token from handshake or refresh.
+     * `null` until connected, or when the host omitted it.
+     */
     getAuthToken(): AuthToken | null;
-    /** Extension context from handshake; `null` until connected. */
+    /**
+     * Extension context from handshake.
+     * `null` until connected, or when the host omitted it.
+     */
     getExtensionDetails(): ExtensionDetails | null;
-    /** Design tokens from handshake; `null` until connected. */
+    /**
+     * Tenant branding from handshake.
+     * `null` until connected, or when the host omitted it.
+     */
     getDesignTokens(): DesignTokens | null;
     /**
      * Latest page settings from handshake or `LOAD_PAGE_SETTINGS`;
@@ -237,8 +312,8 @@ export declare interface IExtensionSDK {
      */
     getTenantUrl(): string | null;
     /**
-     * Platform API origin derived from handshake `baseUrl`;
-     * `null` until connected.
+     * Platform API origin derived from handshake `baseUrl`.
+     * `null` until connected, or when `extensionDetails.baseUrl` was omitted.
      */
     getApiUrl(): string | null;
     /**
@@ -250,8 +325,9 @@ export declare interface IExtensionSDK {
      * @typeParam T - Expected JSON response body.
      * @param endpoint - Root-relative API path.
      * @param options - Standard fetch options.
-     * @throws When not connected, the endpoint is invalid, the request fails,
-     *   or the response is not successful JSON.
+     * @throws When not connected, handshake did not include `authToken` and
+     *   `extensionDetails` (`baseUrl`, `tenantDomain`), the endpoint is invalid,
+     *   the request fails, or the response is not successful JSON.
      */
     apiCall<T>(endpoint: string, options?: RequestInit): Promise<T>;
     /**
@@ -277,6 +353,14 @@ export declare interface IExtensionSDK {
      * @returns Unsubscribe function.
      */
     onLoadPageSettings(handler: (settings: PageSettings) => void): () => void;
+    /**
+     * Registers a handler for parent-initiated `REQUEST_NAVIGATION_CHANGE`.
+     * Navigate the SPA to `payload.path` and acknowledge with
+     * {@link emitNavigationChange}.
+     *
+     * @returns Unsubscribe function.
+     */
+    onNavigate(handler: (payload: RequestNavigationChangePayload) => void): () => void;
     /**
      * Registers a handler for auth-token updates (requested or parent-pushed).
      *
@@ -286,7 +370,8 @@ export declare interface IExtensionSDK {
     /**
      * Notifies the parent that the extension's route changed.
      *
-     * Wire: `NAVIGATION_CHANGE` (fire-and-forget).
+     * Wire: `NAVIGATION_CHANGE` (fire-and-forget). Also used as the ACK after
+     * handling {@link onNavigate}.
      *
      * @param payload - Navigation change payload (`path` within the extension).
      * @throws When not connected or destroyed.
@@ -310,12 +395,30 @@ export declare interface IExtensionSDKHost {
      * Tears down the listener. The instance cannot be restarted after destroy.
      */
     destroy(): void;
+    /**
+     * Routing type from the last `HANDSHAKE_INIT`. Defaults to `server` until
+     * the child connects (and for omit / unrecognized values).
+     */
+    getRoutingType(): RoutingType;
     /**
      * Asks the child to open page settings UI with the given values.
      *
      * Wire: `LOAD_PAGE_SETTINGS` (fire-and-forget).
      */
     emitLoadPageSettings(settings: PageSettings | null): void;
+    /**
+     * Asks the child SPA to navigate to `payload.path` without reloading the
+     * iframe. Resolves when the child ACKs with a matching `NAVIGATION_CHANGE`.
+     *
+     * Soft navigation is intended for `client-hash` extensions; the host decides
+     * whether to call this or fall back to an iframe `src` reload.
+     *
+     * @param payload - Target path within the extension.
+     * @param options - Optional request timeout (default 10s).
+     * @throws When destroyed, a request is already in progress, the payload is
+     *   invalid, or the request times out.
+     */
+    requestNavigationChange(payload: RequestNavigationChangePayload, options?: RequestOptions): Promise<NavigationChangePayload>;
 }
 
 /** Thrown when `tenantUrl` is missing or not a safe postMessage origin. */
@@ -333,9 +436,21 @@ export declare function isValidExtensionUrl(urlRaw: string | null | undefined, c
 
 /** Payload for `NAVIGATION_CHANGE` (child → parent). */
 export declare interface NavigationChangePayload {
+    /** Path within the extension (e.g. `/settings`). */
     path: string;
+    /**
+     * Query string of the child's current route, including the leading `?`
+     * (e.g. `?tab=history`). Omitted or empty means no query.
+     *
+     * For `client-hash` extensions the child reads this from its hash fragment,
+     * not from `window.location.search`.
+     */
+    search?: string;
 }
 
+/** Normalize a wire / option value to a known {@link RoutingType}. */
+export declare function normalizeRoutingType(value: unknown): RoutingType;
+
 /** Opaque page-level settings bag owned by the extension and synced with the parent. */
 export declare type PageSettings = Record<string, unknown>;
 
@@ -364,6 +479,20 @@ export declare function postToChild(contentWindow: Window, origin: string, type:
  */
 export declare function readTenantUrlFromLocation(search?: string): string | null;
 
+/** Payload for `REQUEST_NAVIGATION_CHANGE` (parent → child). */
+export declare interface RequestNavigationChangePayload {
+    /** Path within the extension (e.g. `/settings`). */
+    path: string;
+    /**
+     * Query string for the target route, including the leading `?`
+     * (e.g. `?tab=history`). Omitted or empty means no query.
+     *
+     * For `client-hash` extensions the query belongs inside the hash fragment;
+     * the child SDK consumer is responsible for applying it to its router.
+     */
+    search?: string;
+}
+
 /** Options for request/response SDK methods that wait on a parent reply. */
 export declare interface RequestOptions {
     /** Request timeout in milliseconds (default 10_000). */
@@ -380,6 +509,15 @@ export declare interface RequestOptions {
  */
 export declare function resolveAllowedOrigin(tenantUrl: string | null): string;
 
+/**
+ * How the extension handles in-app routing.
+ *
+ * - `server` — full document loads (iframe `src` reload). Default.
+ * - `client-hash` — hash router SPA; supports soft navigation via
+ *   `REQUEST_NAVIGATION_CHANGE` / `NAVIGATION_CHANGE`.
+ */
+export declare type RoutingType = "server" | "client-hash";
+
 /**
  * Subscribes to `message` events from a child frame at `origin`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadanza/extension-sdk",
-  "version": "0.0.14",
+  "version": "0.2.0",
   "description": "Helpers for building extensions",
   "keywords": [
     "kadanza",