@kadanza/extension-sdk 0.0.13 → 0.1.0

package/dist/index.d.cts

@@ -78,24 +78,56 @@ export declare interface ConnectOptions {
  */
 export declare const createExtensionSDK: () => IExtensionSDK;
 
-/** Branding tokens from the parent for aligning extension UI. */
+/**
+ * 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;
 }
 
-/** Context about the embedded extension and its host page from handshake. */
+/**
+ * Clones `urlRaw` and sets the `tenantUrl` search param (parent origin).
+ *
+ * @param urlRaw - Absolute extension URL string.
+ * @param tenantUrl - Parent origin to embed (defaults to `window.location.origin`).
+ * @returns Enriched `URL`, or `null` when `urlRaw` is missing or unparsable.
+ */
+export declare function enrichExtensionUrl(urlRaw: string | null | undefined, tenantUrl?: string): URL | null;
+
+/**
+ * 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. */
@@ -125,14 +157,59 @@ export declare class ExtensionSDK implements IExtensionSDK {
     emitNavigationChange(payload: NavigationChangePayload): void;
 }
 
-/** Payload delivered with a successful `HANDSHAKE_ACK`. */
+/** Default {@link IExtensionSDKHost} implementation. */
+export declare class ExtensionSDKHost implements IExtensionSDKHost {
+    #private;
+    constructor(options: ExtensionSDKHostOptions);
+    start(): void;
+    destroy(): void;
+    emitLoadPageSettings(settings: PageSettings | null): void;
+}
+
+/**
+ * Options for {@link ExtensionSDKHost}.
+ *
+ * Platform code supplies token minting and page-settings persistence via
+ * callbacks; the host owns only the postMessage protocol.
+ */
+export declare interface ExtensionSDKHostOptions {
+    /** Returns the iframe `contentWindow`, or `null` if not ready. */
+    getContentWindow: () => Window | null;
+    /** Extension origin used as `postMessage` targetOrigin / source filter. */
+    origin: string;
+    /**
+     * 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: () => Partial<HandshakePayload> | Promise<Partial<HandshakePayload>>;
+    /**
+     * Resolves a fresh auth token when the child sends `REQUEST_TOKEN_REFRESH`.
+     */
+    resolveAuthToken: () => AuthToken | Promise<AuthToken>;
+    /**
+     * Persists page settings from `UPDATE_PAGE_SETTINGS`.
+     * Return `true` on success; the host emits `PAGE_SETTINGS_UPDATED`.
+     */
+    onUpdatePageSettings?: (settings: PageSettings) => boolean | Promise<boolean>;
+}
+
+/**
+ * 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;
 }
 
+export declare type HostMessageHandler = (event: MessageEvent<ExtensionMessage>) => void;
+
 /**
  * Public contract for talking to the Kadanza parent frame over `postMessage`.
  *
@@ -153,10 +230,16 @@ export declare interface IExtensionSDK {
      * Opt-in proactive refresh can be enabled with
      * `authTokenAutoRefresh: true` (optional `authTokenBufferMs`).
      *
+     * 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.
      * @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>;
     /**
@@ -168,11 +251,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`;
@@ -190,8 +282,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;
     /**
@@ -203,8 +295,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>;
     /**
@@ -247,11 +340,43 @@ export declare interface IExtensionSDK {
     emitNavigationChange(payload: NavigationChangePayload): void;
 }
 
+/**
+ * Parent-frame counterpart to {@link IExtensionSDK}.
+ *
+ * Listens for child messages and replies with the shared wire protocol.
+ * Create one instance per iframe.
+ */
+export declare interface IExtensionSDKHost {
+    /**
+     * Attaches the child message listener. Safe to call once; no-ops if already
+     * started or destroyed.
+     */
+    start(): void;
+    /**
+     * Tears down the listener. The instance cannot be restarted after destroy.
+     */
+    destroy(): void;
+    /**
+     * Asks the child to open page settings UI with the given values.
+     *
+     * Wire: `LOAD_PAGE_SETTINGS` (fire-and-forget).
+     */
+    emitLoadPageSettings(settings: PageSettings | null): void;
+}
+
 /** Thrown when `tenantUrl` is missing or not a safe postMessage origin. */
 export declare class InvalidOriginError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Returns whether `urlRaw` is a valid HTTPS extension URL.
+ *
+ * When `checkOrigin` is provided, the URL's origin must also pass that predicate
+ * (e.g. hostname ends with `.kadanza.app`).
+ */
+export declare function isValidExtensionUrl(urlRaw: string | null | undefined, checkOrigin?: (origin: string) => boolean): boolean;
+
 /** Payload for `NAVIGATION_CHANGE` (child → parent). */
 export declare interface NavigationChangePayload {
     path: string;
@@ -265,6 +390,16 @@ export declare interface PageSettingsUpdatedPayload {
     success: boolean;
 }
 
+/**
+ * Posts a typed extension message to an embedded child frame.
+ *
+ * @param contentWindow - The iframe's `contentWindow`.
+ * @param origin - Target origin for `postMessage` (extension origin).
+ * @param type - Wire event type from {@link CONNECTION_EVENTS}.
+ * @param payload - Optional message payload.
+ */
+export declare function postToChild(contentWindow: Window, origin: string, type: ConnectionEvent, payload?: unknown): void;
+
 /**
  * Reads the parent-supplied `tenantUrl` from a URL search string.
  *
@@ -291,6 +426,15 @@ export declare interface RequestOptions {
  */
 export declare function resolveAllowedOrigin(tenantUrl: string | null): string;
 
+/**
+ * Subscribes to `message` events from a child frame at `origin`.
+ *
+ * Ignores events from other origins and payloads without a `type` field.
+ *
+ * @returns Unsubscribe function.
+ */
+export declare function subscribeToChildMessages(origin: string, handler: HostMessageHandler): () => void;
+
 /** Payload for `UPDATE_PAGE_SETTINGS` (child → parent). */
 export declare interface UpdatePageSettingsPayload {
     settings: PageSettings;

package/dist/index.d.ts

@@ -78,24 +78,56 @@ export declare interface ConnectOptions {
  */
 export declare const createExtensionSDK: () => IExtensionSDK;
 
-/** Branding tokens from the parent for aligning extension UI. */
+/**
+ * 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;
 }
 
-/** Context about the embedded extension and its host page from handshake. */
+/**
+ * Clones `urlRaw` and sets the `tenantUrl` search param (parent origin).
+ *
+ * @param urlRaw - Absolute extension URL string.
+ * @param tenantUrl - Parent origin to embed (defaults to `window.location.origin`).
+ * @returns Enriched `URL`, or `null` when `urlRaw` is missing or unparsable.
+ */
+export declare function enrichExtensionUrl(urlRaw: string | null | undefined, tenantUrl?: string): URL | null;
+
+/**
+ * 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. */
@@ -125,14 +157,59 @@ export declare class ExtensionSDK implements IExtensionSDK {
     emitNavigationChange(payload: NavigationChangePayload): void;
 }
 
-/** Payload delivered with a successful `HANDSHAKE_ACK`. */
+/** Default {@link IExtensionSDKHost} implementation. */
+export declare class ExtensionSDKHost implements IExtensionSDKHost {
+    #private;
+    constructor(options: ExtensionSDKHostOptions);
+    start(): void;
+    destroy(): void;
+    emitLoadPageSettings(settings: PageSettings | null): void;
+}
+
+/**
+ * Options for {@link ExtensionSDKHost}.
+ *
+ * Platform code supplies token minting and page-settings persistence via
+ * callbacks; the host owns only the postMessage protocol.
+ */
+export declare interface ExtensionSDKHostOptions {
+    /** Returns the iframe `contentWindow`, or `null` if not ready. */
+    getContentWindow: () => Window | null;
+    /** Extension origin used as `postMessage` targetOrigin / source filter. */
+    origin: string;
+    /**
+     * 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: () => Partial<HandshakePayload> | Promise<Partial<HandshakePayload>>;
+    /**
+     * Resolves a fresh auth token when the child sends `REQUEST_TOKEN_REFRESH`.
+     */
+    resolveAuthToken: () => AuthToken | Promise<AuthToken>;
+    /**
+     * Persists page settings from `UPDATE_PAGE_SETTINGS`.
+     * Return `true` on success; the host emits `PAGE_SETTINGS_UPDATED`.
+     */
+    onUpdatePageSettings?: (settings: PageSettings) => boolean | Promise<boolean>;
+}
+
+/**
+ * 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;
 }
 
+export declare type HostMessageHandler = (event: MessageEvent<ExtensionMessage>) => void;
+
 /**
  * Public contract for talking to the Kadanza parent frame over `postMessage`.
  *
@@ -153,10 +230,16 @@ export declare interface IExtensionSDK {
      * Opt-in proactive refresh can be enabled with
      * `authTokenAutoRefresh: true` (optional `authTokenBufferMs`).
      *
+     * 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.
      * @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>;
     /**
@@ -168,11 +251,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`;
@@ -190,8 +282,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;
     /**
@@ -203,8 +295,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>;
     /**
@@ -247,11 +340,43 @@ export declare interface IExtensionSDK {
     emitNavigationChange(payload: NavigationChangePayload): void;
 }
 
+/**
+ * Parent-frame counterpart to {@link IExtensionSDK}.
+ *
+ * Listens for child messages and replies with the shared wire protocol.
+ * Create one instance per iframe.
+ */
+export declare interface IExtensionSDKHost {
+    /**
+     * Attaches the child message listener. Safe to call once; no-ops if already
+     * started or destroyed.
+     */
+    start(): void;
+    /**
+     * Tears down the listener. The instance cannot be restarted after destroy.
+     */
+    destroy(): void;
+    /**
+     * Asks the child to open page settings UI with the given values.
+     *
+     * Wire: `LOAD_PAGE_SETTINGS` (fire-and-forget).
+     */
+    emitLoadPageSettings(settings: PageSettings | null): void;
+}
+
 /** Thrown when `tenantUrl` is missing or not a safe postMessage origin. */
 export declare class InvalidOriginError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Returns whether `urlRaw` is a valid HTTPS extension URL.
+ *
+ * When `checkOrigin` is provided, the URL's origin must also pass that predicate
+ * (e.g. hostname ends with `.kadanza.app`).
+ */
+export declare function isValidExtensionUrl(urlRaw: string | null | undefined, checkOrigin?: (origin: string) => boolean): boolean;
+
 /** Payload for `NAVIGATION_CHANGE` (child → parent). */
 export declare interface NavigationChangePayload {
     path: string;
@@ -265,6 +390,16 @@ export declare interface PageSettingsUpdatedPayload {
     success: boolean;
 }
 
+/**
+ * Posts a typed extension message to an embedded child frame.
+ *
+ * @param contentWindow - The iframe's `contentWindow`.
+ * @param origin - Target origin for `postMessage` (extension origin).
+ * @param type - Wire event type from {@link CONNECTION_EVENTS}.
+ * @param payload - Optional message payload.
+ */
+export declare function postToChild(contentWindow: Window, origin: string, type: ConnectionEvent, payload?: unknown): void;
+
 /**
  * Reads the parent-supplied `tenantUrl` from a URL search string.
  *
@@ -291,6 +426,15 @@ export declare interface RequestOptions {
  */
 export declare function resolveAllowedOrigin(tenantUrl: string | null): string;
 
+/**
+ * Subscribes to `message` events from a child frame at `origin`.
+ *
+ * Ignores events from other origins and payloads without a `type` field.
+ *
+ * @returns Unsubscribe function.
+ */
+export declare function subscribeToChildMessages(origin: string, handler: HostMessageHandler): () => void;
+
 /** Payload for `UPDATE_PAGE_SETTINGS` (child → parent). */
 export declare interface UpdatePageSettingsPayload {
     settings: PageSettings;

package/package.json

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