@kadanza/extension-sdk 0.1.0 → 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,6 +85,9 @@ export declare interface ConnectOptions {
  */
 export declare const createExtensionSDK: () => IExtensionSDK;
 
+/** 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.
  *
@@ -153,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;
 }
@@ -163,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>;
 }
 
 /**
@@ -182,7 +195,7 @@ export declare interface ExtensionSDKHostOptions {
      * Context fields are optional; send `designTokens` whenever a tenant is in
      * context. `spaceId` / `pageId` apply to Experience Pages only.
      */
-    resolveHandshakePayload: () => Partial<HandshakePayload> | Promise<Partial<HandshakePayload>>;
+    resolveHandshakePayload: (extensionSDKHost: IExtensionSDKHost) => Partial<HandshakePayload> | Promise<Partial<HandshakePayload>>;
     /**
      * Resolves a fresh auth token when the child sends `REQUEST_TOKEN_REFRESH`.
      */
@@ -192,6 +205,20 @@ 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 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;
 }
 
 /**
@@ -230,13 +257,16 @@ export declare interface IExtensionSDK {
      * 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).
      *
-     * @param options - Handshake timeout and optional auth-token auto-refresh.
+     * @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.
@@ -323,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).
      *
@@ -332,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.
@@ -356,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. */
@@ -379,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>;
 
@@ -410,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). */
@@ -426,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.1.0",
+  "version": "0.2.0",
   "description": "Helpers for building extensions",
   "keywords": [
     "kadanza",