@netsapiens/horizon-sdk 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -141,12 +141,86 @@ interface ThemeTokens {
  * components instead of bringing their own MUI/styling stack — that keeps the
  * remote bundle small and ensures visual consistency with Horizon.
  */
+/** One step of a {@link HorizonUITemplates.FormPanel} multi-step wizard. */
+interface FormPanelStep {
+    /** Label shown in the stepper header. */
+    label: string;
+    /** Content rendered when this step is active. */
+    content: React.ReactNode;
+    /**
+     * Optional gate run before advancing past this step (Next / forward header
+     * click). Return false to block. Async supported (e.g. react-hook-form `trigger`).
+     */
+    validate?: () => boolean | Promise<boolean>;
+}
 interface HorizonUITemplates {
     PageTemplate: React.ComponentType<unknown>;
     PageTemplateWithExtensions: React.ComponentType<unknown>;
     FormTemplate: React.ComponentType<unknown>;
-    SideTrayTemplate: React.ComponentType<unknown>;
-    DatagridTemplate: React.ComponentType<unknown>;
+    /**
+     * Shared right-side drawer shell: sticky header (icon/title/subtitle/close),
+     * scrollable body, optional sticky footer. Use for detail/view/settings panels.
+     */
+    SidePanel: React.ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        title: React.ReactNode;
+        subtitle?: React.ReactNode;
+        icon?: React.ReactNode;
+        width?: "sm" | "md" | "lg" | "xl";
+        footer?: React.ReactNode;
+        disableBackdropClick?: boolean;
+        children: React.ReactNode;
+    }>;
+    /**
+     * SidePanel + form semantics: a <form>, a standard Submit/Cancel footer, and
+     * the `form-section-before` / `form-section-after` extension zones built in.
+     * Pass `steps` to render a multi-step wizard (stepper header + Back/Next/Submit
+     * footer) instead. Use this for add/edit forms.
+     */
+    FormPanel: React.ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        title: React.ReactNode;
+        subtitle?: React.ReactNode;
+        icon?: React.ReactNode;
+        width?: "sm" | "md" | "lg" | "xl";
+        formType: string;
+        mode: "add" | "edit";
+        entityId?: string | number;
+        formData?: Record<string, unknown>;
+        onSubmit?: (event?: React.BaseSyntheticEvent) => void | Promise<void>;
+        submitLabel?: React.ReactNode;
+        cancelLabel?: React.ReactNode;
+        isSubmitting?: boolean;
+        submitDisabled?: boolean;
+        error?: Error | string | null;
+        /** Multi-step wizard: pass one step per page of fields. */
+        steps?: FormPanelStep[];
+        onReset?: () => void;
+        isComplete?: boolean;
+        loading?: boolean;
+        children?: React.ReactNode;
+    }>;
+    DatagridTemplate: React.ComponentType<{
+        data: unknown[];
+        columns: unknown[];
+        actions?: unknown[];
+        toolbar?: {
+            enableSearch?: boolean;
+            searchPlaceholder?: string;
+            enableExport?: boolean;
+            enableFilter?: boolean;
+            enableColumns?: boolean;
+        };
+        defaultPageSize?: number;
+        /**
+         * Node rendered inline within the toolbar row, alongside search and date
+         * range controls. Use for status filter chips (ToggleButtonGroup) and
+         * `table-filter-bar` extension zone renderers.
+         */
+        filterBar?: React.ReactNode;
+    }>;
     Icon: React.ComponentType<{
         name: string;
         size?: number | string;
@@ -207,11 +281,11 @@ interface HorizonUI {
     IconButton?: React.ComponentType<{
         icon: string;
         iconSize?: number | string;
-        'aria-label'?: string;
-        color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning';
+        "aria-label"?: string;
+        color?: "default" | "inherit" | "primary" | "secondary" | "error" | "info" | "success" | "warning";
         disabled?: boolean;
-        edge?: 'start' | 'end' | false;
-        size?: 'small' | 'medium' | 'large';
+        edge?: "start" | "end" | false;
+        size?: "small" | "medium" | "large";
         onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
         sx?: Record<string, unknown>;
     }>;
@@ -250,7 +324,7 @@ interface HorizonContext {
     user: HorizonUser;
     auth: HorizonAuth;
     api: HorizonApiClient;
-    theme: 'light' | 'dark';
+    theme: "light" | "dark";
     locale: string;
     /**
      * Host's i18next translation function. All host strings (common, telecom,
@@ -311,8 +385,54 @@ interface RemoteModuleConfig {
  * Generic extension zones available throughout Horizon. Pages may also define
  * custom string zone IDs — `ExtensionZone` accepts both.
  */
-type ExtensionZoneId = 'page-header-actions' | 'page-header-secondary' | 'page-content-before' | 'page-content-after' | 'page-sidebar' | 'table-row-actions' | 'table-toolbar' | 'detail-panel-tabs' | 'detail-panel-actions' | 'inbound-call-content' | 'topbar-actions' | 'form-section-before' | 'form-section-after';
+type ExtensionZoneId = "page-header-actions" | "page-header-secondary" | "page-content-after" | "sidetray" | "table-row-actions" | "table-toolbar" | "table-filter-bar" | "inbound-call-content" | "topbar-actions" | "form-section-before" | "form-section-after";
 type ExtensionZone = ExtensionZoneId | (string & {});
+/**
+ * Context passed via `pageContext` to extension components registered in the
+ * `'table-filter-bar'` zone. Extensions provide a filter function that the host
+ * applies to table rows. This keeps filtering logic in the extension where the
+ * business rules live, and keeps the host generic.
+ *
+ * @example
+ * export function RecordingFilter({ context }: ExtensionComponentProps) {
+ *   const filterCtx = context.pageContext as TableFilterBarContext | undefined;
+ *   const { ToggleButtonGroup } = context.ui ?? {};
+ *   const [active, setActive] = useState(false);
+ *
+ *   function handleChange(_e: React.SyntheticEvent, value: string | null) {
+ *     const next = value === 'recorded';
+ *     setActive(next);
+ *     if (next) {
+ *       filterCtx?.onFilterChange((row) => {
+ *         const r = row as Record<string, unknown>;
+ *         return r['call-record-keep'] === 'yes' || r['call-record-keep'] === true;
+ *       });
+ *     } else {
+ *       filterCtx?.onFilterChange(null);
+ *     }
+ *   }
+ *
+ *   if (!ToggleButtonGroup) return null;
+ *   return (
+ *     <ToggleButtonGroup
+ *       value={active ? 'recorded' : null}
+ *       exclusive
+ *       onChange={handleChange}
+ *       options={[{ value: 'recorded', label: '● Recording' }]}
+ *     />
+ *   );
+ * }
+ *
+ * // NOTE: Track active state locally with useState — TableFilterBarContext does
+ * // not reflect the current filter value back to the extension.
+ */
+interface TableFilterBarContext<TRow = any> {
+    /**
+     * Provide a filter function to apply to table rows. Pass `null` to reset.
+     * The function receives a row and returns true to include it, false to hide it.
+     */
+    onFilterChange: (filterFn: ((row: TRow) => boolean) | null) => void;
+}
 /**
  * Route pattern with wildcard (`*`) and named-parameter (`:param`) support.
  * Example patterns: `/manage/call-logs`, `/manage/*\/call-logs`, `/manage/:domain/users`.
@@ -337,7 +457,7 @@ interface ExtensionContext {
     ui?: HorizonUI;
     eventBus?: HorizonEventBus;
     /** Current color scheme — reactive to host theme changes. */
-    theme: 'light' | 'dark';
+    theme: "light" | "dark";
     /** Host's i18next translation function — all host strings available immediately. */
     t?: (key: string, options?: Record<string, unknown>) => string;
 }
@@ -350,6 +470,22 @@ interface ExtensionComponentProps {
     /** Provided by modal/dialog hosts to allow extensions to dismiss themselves */
     close?: () => void;
 }
+/**
+ * A SIP call lifecycle event delivered to apps subscribed via
+ * `sdk.subscribeToCallEvents`. The host enriches this further, but every event
+ * carries at least a `type` and `callId`.
+ */
+interface CallEvent {
+    type: CallEventType;
+    callId: string;
+    [key: string]: unknown;
+}
+/**
+ * Known call event types. Authored as an open union so the host can introduce
+ * new types without a breaking SDK change, while still offering autocomplete
+ * for the common ones.
+ */
+type CallEventType = "call-started" | "call-answered" | "call-ended" | "call-missed" | (string & {});
 /**
  * Payload accepted by `sdk.registerDynamicExtension`. `appId` is filled in by
  * the SDK from the value passed to `createRemoteAppSDK`.
@@ -386,9 +522,9 @@ interface DynamicColumnDefinition {
     filterable?: boolean;
     hideable?: boolean;
     resizable?: boolean;
-    type?: 'string' | 'number' | 'date' | 'dateTime' | 'boolean';
-    align?: 'left' | 'center' | 'right';
-    headerAlign?: 'left' | 'center' | 'right';
+    type?: "string" | "number" | "date" | "dateTime" | "boolean";
+    align?: "left" | "center" | "right";
+    headerAlign?: "left" | "center" | "right";
     renderCell?: (params: {
         row: Record<string, unknown>;
         value?: unknown;
@@ -424,19 +560,33 @@ declare class RemoteAppSDK {
     private routes;
     private dynamicExtensions;
     private dynamicColumns;
+    private callEventsSubscribed;
     constructor(eventBus: HorizonEventBus, appId: string);
-    registerRoute(config: Omit<RouteConfig, 'appId'>): Promise<void>;
+    registerRoute(config: Omit<RouteConfig, "appId">): Promise<void>;
     unregisterRoute(routeId: string): void;
     /**
      * Convenience: load a component out of a federated module's webpack
      * container and register it as a route in one step. Useful when the route
      * component lives in a sibling exposed module rather than the entry App.
      */
-    registerRouteFromModule(routeConfig: Omit<RouteConfig, 'appId' | 'component'>, moduleConfig: RemoteModuleConfig): Promise<void>;
-    registerDynamicExtension(config: Omit<DynamicExtensionConfig, 'appId'>): void;
+    registerRouteFromModule(routeConfig: Omit<RouteConfig, "appId" | "component">, moduleConfig: RemoteModuleConfig): Promise<void>;
+    registerDynamicExtension(config: Omit<DynamicExtensionConfig, "appId">): void;
     unregisterDynamicExtension(extensionId: string): void;
-    registerDynamicColumn(config: Omit<DynamicColumnConfig, 'appId'>): void;
+    registerDynamicColumn(config: Omit<DynamicColumnConfig, "appId">): void;
     unregisterDynamicColumn(columnId: string): void;
+    /**
+     * Subscribe to live SIP call events. Routes through the host's
+     * `CallEventsManager`, which enforces the `call-events:listen` capability and
+     * records the subscription against this app — so the platform knows which
+     * apps consume call events and can disable the capability platform-wide.
+     *
+     * Prefer this over listening to `eventBus.on('call-event')` directly: the raw
+     * bus is neither gated nor attributed to your app.
+     *
+     * @returns an unsubscribe function (also torn down by `cleanup()`).
+     */
+    subscribeToCallEvents(eventTypes: CallEventType[], callback: (event: CallEvent) => void): () => void;
+    unsubscribeFromCallEvents(): void;
     /**
      * Unregister everything this SDK instance has registered. Call from your
      * remote app's unmount/cleanup path — `useRemoteApp` does this for you.
@@ -522,8 +672,8 @@ declare function useHorizonContext(): HorizonContext;
  * Inside a page component wrapped by `HorizonContextProvider`, both params
  * can be omitted — the provider context is used automatically.
  */
-declare function useTheme(eventBus?: HorizonContext['eventBus'], initialTheme?: 'light' | 'dark'): {
-    theme: 'light' | 'dark';
+declare function useTheme(eventBus?: HorizonContext["eventBus"], initialTheme?: "light" | "dark"): {
+    theme: "light" | "dark";
 };
 /**
  * Returns the host's translation function and current locale.
@@ -579,7 +729,7 @@ declare function useTheme(eventBus?: HorizonContext['eventBus'], initialTheme?:
  * }
  */
 declare function useLocale(): {
-    t: HorizonContext['t'];
+    t: HorizonContext["t"];
     locale: string;
 };
 /**
@@ -618,12 +768,12 @@ declare function useRemoteApp(horizonContext: HorizonContext, appId: string): {
 /**
  * Register a route for the lifetime of the calling component.
  */
-declare function useRoute(eventBus: HorizonContext['eventBus'], appId: string, config: Omit<RouteConfig, 'appId'>): RemoteAppSDK;
+declare function useRoute(eventBus: HorizonContext["eventBus"], appId: string, config: Omit<RouteConfig, "appId">): RemoteAppSDK;
 /**
  * Register a route by pulling its component out of a federated module's
  * webpack container.
  */
-declare function useRouteFromModule(eventBus: HorizonContext['eventBus'], appId: string, routeConfig: Omit<RouteConfig, 'appId' | 'component'>, moduleConfig: RemoteModuleConfig): {
+declare function useRouteFromModule(eventBus: HorizonContext["eventBus"], appId: string, routeConfig: Omit<RouteConfig, "appId" | "component">, moduleConfig: RemoteModuleConfig): {
     loading: boolean;
     error: Error | null;
     sdk: RemoteAppSDK;
@@ -632,17 +782,41 @@ declare function useRouteFromModule(eventBus: HorizonContext['eventBus'], appId:
  * Register a dynamic extension (pattern-based UI injection) for the lifetime
  * of the calling component.
  */
-declare function useDynamicExtension(eventBus: HorizonContext['eventBus'], appId: string, config: Omit<DynamicExtensionConfig, 'appId'>): RemoteAppSDK;
+declare function useDynamicExtension(eventBus: HorizonContext["eventBus"], appId: string, config: Omit<DynamicExtensionConfig, "appId">): RemoteAppSDK;
+/**
+ * Returns the current page context as a typed value.
+ *
+ * The host passes page-specific data (e.g. active filters, date range, selected
+ * row) through `ExtensionContext.pageContext`. This hook casts it to the caller's
+ * expected shape and keeps it reactive — when the host updates `pageContext` the
+ * extension re-renders automatically because it flows in as a React prop.
+ *
+ * Define a typed interface for each page's context in your remote app and pass
+ * it as the type parameter. Returns `undefined` when the host has not populated
+ * any context for the current zone.
+ *
+ * @example
+ * interface CallLogsPageContext {
+ *   dateRange?: [Date | null, Date | null];
+ * }
+ *
+ * export function AnalyticsWidget({ context }: ExtensionComponentProps) {
+ *   const pageCtx = usePageContext<CallLogsPageContext>(context);
+ *   const [start, end] = pageCtx?.dateRange ?? [null, null];
+ *   // ...
+ * }
+ */
+declare function usePageContext<T = unknown>(context: ExtensionContext): T | undefined;
 /**
  * Register a dynamic table column for the lifetime of the calling component.
  */
-declare function useDynamicColumn(eventBus: HorizonContext['eventBus'], appId: string, config: Omit<DynamicColumnConfig, 'appId'>): RemoteAppSDK;
+declare function useDynamicColumn(eventBus: HorizonContext["eventBus"], appId: string, config: Omit<DynamicColumnConfig, "appId">): RemoteAppSDK;
 
 /**
  * Federation Error
  * Structured error class with error codes for better error handling
  */
-type HorizonSDKErrorCode = 'PERMISSION_DENIED' | 'RATE_LIMIT_EXCEEDED' | 'INVALID_MESSAGE' | 'SIGNATURE_VERIFICATION_FAILED' | 'API_ERROR' | 'NETWORK_ERROR' | 'INVALID_EXTENSION_POINT' | 'INVALID_CONFIGURATION' | 'APP_NOT_FOUND' | 'MODULE_LOAD_FAILED' | 'INITIALIZATION_FAILED' | 'UNKNOWN_ERROR';
+type HorizonSDKErrorCode = "PERMISSION_DENIED" | "RATE_LIMIT_EXCEEDED" | "INVALID_MESSAGE" | "SIGNATURE_VERIFICATION_FAILED" | "API_ERROR" | "NETWORK_ERROR" | "INVALID_EXTENSION_POINT" | "INVALID_CONFIGURATION" | "APP_NOT_FOUND" | "MODULE_LOAD_FAILED" | "INITIALIZATION_FAILED" | "UNKNOWN_ERROR";
 interface HorizonSDKErrorOptions {
     code: HorizonSDKErrorCode;
     message: string;
@@ -858,4 +1032,4 @@ type AnchorId = (typeof MANAGE_ANCHORS)[keyof typeof MANAGE_ANCHORS] | (typeof P
 
 declare const VERSION: string;
 
-export { ANCHORS, APPS_ANCHORS, type AnchorId, type BreadcrumbItem, type DynamicColumnConfig, type DynamicColumnDefinition, type DynamicExtensionConfig, type ExtensionComponentProps, type ExtensionContext, type ExtensionZone, type ExtensionZoneId, type HorizonApiClient, type HorizonAuth, type HorizonContext, HorizonContextProvider, type HorizonEventBus, HorizonSDKError, type HorizonSDKErrorCode, type HorizonSDKErrorOptions, type HorizonUI, type HorizonUITemplates, type HorizonUser, MANAGE_ANCHORS, MY_ACCOUNT_ANCHORS, PLATFORM_ANCHORS, RemoteAppSDK, type RemoteAuthError, type RemoteAuthOptions, type RemoteAuthRequest, type RemoteAuthResponse, type RemoteModuleConfig, type RouteConfig, type RoutePattern, type SemanticPlacement, type ThemeTokens, VERSION, apiError, createHorizonSDKError, createLogger, createRemoteAppSDK, getLogLevel, invalidExtensionPointError, moduleLoadError, permissionDeniedError, rateLimitError, setLogLevel, signatureVerificationError, useDynamicColumn, useDynamicExtension, useHorizonContext, useLocale, useRemoteApp, useRoute, useRouteFromModule, useTheme };
+export { ANCHORS, APPS_ANCHORS, type AnchorId, type BreadcrumbItem, type CallEvent, type CallEventType, type DynamicColumnConfig, type DynamicColumnDefinition, type DynamicExtensionConfig, type ExtensionComponentProps, type ExtensionContext, type ExtensionZone, type ExtensionZoneId, type FormPanelStep, type HorizonApiClient, type HorizonAuth, type HorizonContext, HorizonContextProvider, type HorizonEventBus, HorizonSDKError, type HorizonSDKErrorCode, type HorizonSDKErrorOptions, type HorizonUI, type HorizonUITemplates, type HorizonUser, MANAGE_ANCHORS, MY_ACCOUNT_ANCHORS, PLATFORM_ANCHORS, RemoteAppSDK, type RemoteAuthError, type RemoteAuthOptions, type RemoteAuthRequest, type RemoteAuthResponse, type RemoteModuleConfig, type RouteConfig, type RoutePattern, type SemanticPlacement, type TableFilterBarContext, type ThemeTokens, VERSION, apiError, createHorizonSDKError, createLogger, createRemoteAppSDK, getLogLevel, invalidExtensionPointError, moduleLoadError, permissionDeniedError, rateLimitError, setLogLevel, signatureVerificationError, useDynamicColumn, useDynamicExtension, useHorizonContext, useLocale, usePageContext, useRemoteApp, useRoute, useRouteFromModule, useTheme };