@netsapiens/horizon-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,861 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import loglevel from 'loglevel';
+
+/**
+ * Public type contract for @netsapiens/horizon-sdk.
+ *
+ * This file defines the shape of the runtime context that Horizon passes to
+ * remote applications, plus the registration payloads remote apps emit back
+ * through the event bus.
+ *
+ * Horizon's host implementation imports these same types so the host and the
+ * SDK cannot drift out of sync.
+ */
+
+/**
+ * User information passed to remote apps. Additional fields may be present.
+ */
+interface HorizonUser {
+    displayName: string;
+    domain: string;
+    email?: string;
+    extension?: string;
+    scope?: string;
+    department?: string;
+    site?: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration for remote vendor authentication request
+ */
+interface RemoteAuthRequest {
+    /** Unique identifier for the vendor system */
+    vendorId: string;
+    /** Callback URL where vendor will receive authcode webhook */
+    callbackUrl: string;
+    /** Optional scopes/permissions requested from vendor */
+    scopes?: string[];
+    /** Optional metadata to pass to vendor */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from remote authentication flow
+ */
+interface RemoteAuthResponse {
+    /** Unique identifier for the vendor system */
+    vendorId: string;
+    /** Access token or JWT from vendor */
+    accessToken: string;
+    /** Token type (Bearer, etc.) */
+    tokenType?: string;
+    /** Token expiration timestamp (Unix seconds) */
+    expiresAt?: number;
+    /** Refresh token if provided by vendor */
+    refreshToken?: string;
+    /** Additional vendor-specific data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Error response from remote authentication
+ */
+interface RemoteAuthError {
+    vendorId: string;
+    error: string;
+    errorDescription?: string;
+}
+/**
+ * Options for remote auth request
+ */
+interface RemoteAuthOptions {
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Authentication interface with remote vendor authentication support.
+ * Remote apps use this to authenticate with third-party systems.
+ */
+interface HorizonAuth {
+    isAuthenticated: () => boolean;
+    /**
+     * Request authentication with a remote vendor system.
+     * Returns a promise that resolves when vendor auth completes.
+     *
+     * @param request - Configuration for the auth request
+     * @param options - Optional timeout and retry configuration
+     * @returns Promise<RemoteAuthResponse>
+     * @throws RemoteAuthError if authentication fails
+     *
+     * @example
+     * const response = await auth.requestRemoteAuth({
+     *   vendorId: 'salesforce',
+     *   callbackUrl: 'https://vendor.example.com/oauth/callback',
+     *   scopes: ['read', 'write']
+     * });
+     * // Use response.accessToken for vendor API calls
+     */
+    requestRemoteAuth: (request: RemoteAuthRequest, options?: RemoteAuthOptions) => Promise<RemoteAuthResponse>;
+    /**
+     * Get stored token for a vendor (if previously authenticated)
+     */
+    getRemoteAuthToken: (vendorId: string) => RemoteAuthResponse | null;
+    /**
+     * Clear stored token for a vendor (logout)
+     */
+    clearRemoteAuthToken: (vendorId: string) => void;
+}
+/**
+ * Authenticated client for NetSapiens v2 API calls. Routed through the host's
+ * audited proxy — remote apps never see credentials directly.
+ */
+interface HorizonApiClient {
+    get: <T = unknown>(path: string, params?: Record<string, unknown>) => Promise<T>;
+    post: <T = unknown>(path: string, data: unknown) => Promise<T>;
+    put: <T = unknown>(path: string, data: unknown) => Promise<T>;
+    delete: <T = unknown>(path: string) => Promise<T>;
+    getBaseUrl: () => string;
+}
+/**
+ * Pub/sub event bus used for everything that crosses the host/remote boundary:
+ * route registration, dynamic extension registration, theme changes, call
+ * events, and app-defined custom events.
+ */
+interface HorizonEventBus {
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (data: unknown) => void) => void;
+    off: (event: string, handler: (data: unknown) => void) => void;
+}
+/**
+ * Theme tokens for advanced styling. Remote apps usually consume these
+ * indirectly through `ui.styles`.
+ */
+interface ThemeTokens {
+    colors: Record<string, unknown>;
+    spacing: Record<string, string>;
+    typography: Record<string, unknown>;
+    borderRadius: Record<string, string>;
+    shadows: Record<string, string>;
+}
+/**
+ * UI templates and primitives provided by the host. Remote apps render these
+ * components instead of bringing their own MUI/styling stack — that keeps the
+ * remote bundle small and ensures visual consistency with Horizon.
+ */
+interface HorizonUITemplates {
+    PageTemplate: React.ComponentType<unknown>;
+    PageTemplateWithExtensions: React.ComponentType<unknown>;
+    FormTemplate: React.ComponentType<unknown>;
+    SideTrayTemplate: React.ComponentType<unknown>;
+    DatagridTemplate: React.ComponentType<unknown>;
+    Icon: React.ComponentType<{
+        name: string;
+        size?: number | string;
+        color?: string;
+    }>;
+    SideTrayComponents: {
+        Section: React.ComponentType<{
+            title?: string;
+            children: React.ReactNode;
+        }>;
+        Field: React.ComponentType<{
+            label: string;
+            value?: React.ReactNode;
+        }>;
+        Input: React.ComponentType<{
+            label?: string;
+            placeholder?: string;
+            value?: string;
+            onChange?: (value: string) => void;
+            helperText?: string;
+            error?: boolean;
+            required?: boolean;
+            disabled?: boolean;
+            type?: string;
+            multiline?: boolean;
+            rows?: number;
+        }>;
+        Button: React.ComponentType<unknown>;
+        UserCard: React.ComponentType<{
+            avatarUrl?: string;
+            name: string;
+            subtitle?: string;
+            trailing?: React.ReactNode;
+        }>;
+        Divider: React.ComponentType;
+    };
+    PageComponents: Record<string, React.ComponentType<unknown>>;
+}
+interface HorizonUI {
+    templates: HorizonUITemplates;
+    theme?: ThemeTokens;
+    /** Pre-built semantic style objects derived from the active theme */
+    styles?: Record<string, unknown>;
+    /** Individual MUI-backed components for direct use */
+    Button?: React.ComponentType<unknown>;
+    /**
+     * Pre-themed IconButton. Takes the icon name as a string prop — children
+     * are intentionally not supported. Renders an Iconify icon inside an MUI
+     * IconButton with the host's Aurora theming applied.
+     *
+     * ```tsx
+     * <IconButton icon="mdi:account" aria-label="Account" />
+     * ```
+     *
+     * Do NOT use the MUI children pattern (`<IconButton><Icon ... /></IconButton>`) —
+     * it will render an empty button at 0×0 because children are dropped.
+     */
+    IconButton?: React.ComponentType<{
+        icon: string;
+        iconSize?: number | string;
+        'aria-label'?: string;
+        color?: 'default' | 'inherit' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning';
+        disabled?: boolean;
+        edge?: 'start' | 'end' | false;
+        size?: 'small' | 'medium' | 'large';
+        onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+        sx?: Record<string, unknown>;
+    }>;
+    TextField?: React.ComponentType<unknown>;
+    Select?: React.ComponentType<unknown>;
+    Checkbox?: React.ComponentType<unknown>;
+    Radio?: React.ComponentType<unknown>;
+    RadioGroup?: React.ComponentType<unknown>;
+    Switch?: React.ComponentType<unknown>;
+    ToggleButton?: React.ComponentType<unknown>;
+    ToggleButtonGroup?: React.ComponentType<unknown>;
+    FormLabel?: React.ComponentType<unknown>;
+    Typography?: React.ComponentType<unknown>;
+    Chip?: React.ComponentType<unknown>;
+    Avatar?: React.ComponentType<unknown>;
+    Divider?: React.ComponentType<unknown>;
+    Tooltip?: React.ComponentType<unknown>;
+    Stack?: React.ComponentType<unknown>;
+    Paper?: React.ComponentType<unknown>;
+    /** General-purpose layout primitive with sx prop support. Use this instead of
+     *  importing Box directly from @mui/material in a remote app. */
+    Box?: React.ComponentType<unknown>;
+    Alert?: React.ComponentType<unknown>;
+    Icon?: React.ComponentType<unknown>;
+}
+interface BreadcrumbItem {
+    label: string;
+    url?: string;
+}
+/**
+ * The object passed to a remote app's exported `App` component as props.
+ * Construct this in the host (see HorizonAppsLoader) — never construct it
+ * inside a remote app.
+ */
+interface HorizonContext {
+    user: HorizonUser;
+    auth: HorizonAuth;
+    api: HorizonApiClient;
+    theme: 'light' | 'dark';
+    locale: string;
+    /**
+     * Host's i18next translation function. All host strings (common, telecom,
+     * admin, validation namespaces) are available immediately — no i18next
+     * dependency or install required in the remote app.
+     * Use via the `useLocale()` SDK hook rather than calling directly.
+     */
+    t?: (key: string, options?: Record<string, unknown>) => string;
+    navigate: (path: string) => void;
+    eventBus: HorizonEventBus;
+    ui: HorizonUI;
+    breadcrumbs?: BreadcrumbItem[];
+}
+/**
+ * Semantic placement for menu items.
+ * Allows positioning relative to existing items using anchor-based placement.
+ */
+interface SemanticPlacement {
+    /** Place immediately after this anchor */
+    after?: string;
+    /** Place immediately before this anchor */
+    before?: string;
+    /** Force to start of menu */
+    first?: boolean;
+    /** Force to end of menu */
+    last?: boolean;
+}
+interface RouteConfig {
+    /** Unique route identifier (recommend prefixing with appId) */
+    id: string;
+    /** App identifier — set automatically by RemoteAppSDK */
+    appId: string;
+    /** Parent path to attach under (e.g., '/apps', '/home/settings') */
+    parentPath: string;
+    /** Route segment (e.g., 'my-feature') */
+    path: string;
+    /** Navigation label */
+    label: string;
+    /** Component rendered when this route is active */
+    component: React.ComponentType<unknown>;
+    /** Iconify icon name (e.g., 'mdi:cog') */
+    icon?: string;
+    /**
+     * Semantic placement for positioning in menus (e.g., { after: 'contacts' }).
+     * Supports fuzzy matching with 0.8 similarity threshold.
+     * If not specified or anchor not found, item is placed at end of menu.
+     */
+    placement?: SemanticPlacement;
+}
+/**
+ * Webpack Module Federation reference for `useRouteFromModule`.
+ */
+interface RemoteModuleConfig {
+    scope: string;
+    module: string;
+}
+/**
+ * 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 ExtensionZone = ExtensionZoneId | (string & {});
+/**
+ * Route pattern with wildcard (`*`) and named-parameter (`:param`) support.
+ * Example patterns: `/manage/call-logs`, `/manage/*\/call-logs`, `/manage/:domain/users`.
+ */
+interface RoutePattern {
+    pattern: string;
+    /** Require an exact match (default: prefix match) */
+    exact?: boolean;
+}
+/**
+ * Context passed to extension components when they render.
+ */
+interface ExtensionContext {
+    route: string;
+    params: Record<string, string>;
+    user: {
+        domain: string;
+        username: string;
+        scopes: string[];
+    };
+    pageContext?: unknown;
+    ui?: HorizonUI;
+    eventBus?: HorizonEventBus;
+    /** Current color scheme — reactive to host theme changes. */
+    theme: 'light' | 'dark';
+    /** Host's i18next translation function — all host strings available immediately. */
+    t?: (key: string, options?: Record<string, unknown>) => string;
+}
+/**
+ * Props passed to extension components.
+ */
+interface ExtensionComponentProps {
+    context: ExtensionContext;
+    zone: ExtensionZone;
+    /** Provided by modal/dialog hosts to allow extensions to dismiss themselves */
+    close?: () => void;
+}
+/**
+ * Payload accepted by `sdk.registerDynamicExtension`. `appId` is filled in by
+ * the SDK from the value passed to `createRemoteAppSDK`.
+ */
+interface DynamicExtensionConfig {
+    /** Unique extension ID (recommend prefixing with appId) */
+    id: string;
+    /** Target zone — generic or page-defined */
+    zone: ExtensionZone;
+    /** Routes this extension applies to */
+    routes: RoutePattern[];
+    /** Render order within a zone (higher = first) */
+    priority?: number;
+    /** Component rendered for each match */
+    component: React.ComponentType<ExtensionComponentProps>;
+    /** Permissions the user must have for this extension to render */
+    requiredPermissions?: string[];
+    /** Optional gate evaluated at render time */
+    condition?: (context: ExtensionContext) => boolean;
+}
+/**
+ * Dynamic table column definition. Mirrors a subset of MUI X DataGrid's column
+ * shape — kept as `Record<string, unknown>`-friendly so the SDK doesn't pull
+ * in MUI types.
+ */
+interface DynamicColumnDefinition {
+    field: string;
+    headerName: string;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    flex?: number;
+    sortable?: boolean;
+    filterable?: boolean;
+    hideable?: boolean;
+    resizable?: boolean;
+    type?: 'string' | 'number' | 'date' | 'dateTime' | 'boolean';
+    align?: 'left' | 'center' | 'right';
+    headerAlign?: 'left' | 'center' | 'right';
+    renderCell?: (params: {
+        row: Record<string, unknown>;
+        value?: unknown;
+    }) => React.ReactNode;
+    valueGetter?: (value: unknown, row: Record<string, unknown>) => unknown;
+    valueFormatter?: (value: unknown) => string;
+    initiallyVisible?: boolean;
+}
+/**
+ * Payload accepted by `sdk.registerDynamicColumn`.
+ */
+interface DynamicColumnConfig {
+    id: string;
+    zone: string;
+    routes: RoutePattern[];
+    column: DynamicColumnDefinition;
+    priority?: number;
+    condition?: (context: ExtensionContext) => boolean;
+}
+
+/**
+ * Remote App SDK.
+ *
+ * Wraps Horizon's event bus with a typed, app-scoped API for registering routes
+ * and dynamic extensions. Tracks every registration so `cleanup()` can tear
+ * everything down on unmount — essential when a remote app is reloaded or its
+ * webpack module is replaced during HMR.
+ */
+
+declare class RemoteAppSDK {
+    private eventBus;
+    private appId;
+    private routes;
+    private dynamicExtensions;
+    private dynamicColumns;
+    constructor(eventBus: HorizonEventBus, appId: string);
+    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;
+    unregisterDynamicExtension(extensionId: string): void;
+    registerDynamicColumn(config: Omit<DynamicColumnConfig, 'appId'>): void;
+    unregisterDynamicColumn(columnId: string): void;
+    /**
+     * Unregister everything this SDK instance has registered. Call from your
+     * remote app's unmount/cleanup path — `useRemoteApp` does this for you.
+     */
+    cleanup(): void;
+    getAppId(): string;
+    getRegisteredRoutes(): string[];
+    getRegisteredDynamicExtensions(): string[];
+    getRegisteredDynamicColumns(): string[];
+}
+/** Factory: equivalent to `new RemoteAppSDK(...)`. */
+declare function createRemoteAppSDK(eventBus: HorizonEventBus, appId: string): RemoteAppSDK;
+
+/**
+ * Wrap your registered page components with this provider so they receive a
+ * reactive HorizonContext without any extra event-listener boilerplate.
+ *
+ * The component memoization pattern in App.tsx captures `horizonContext` once
+ * (to keep stable component identity), but `eventBus` is a singleton — the
+ * Provider subscribes to it and pushes theme updates to all descendant pages.
+ *
+ * @example
+ * // In App.tsx, inside useMemo with empty deps:
+ * return (
+ *   <HorizonContextProvider context={horizonContext}>
+ *     <MyPage />
+ *   </HorizonContextProvider>
+ * );
+ */
+declare function HorizonContextProvider({ context, children, }: {
+    context: HorizonContext;
+    children: ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<HorizonContext | null>>;
+/**
+ * Read the live HorizonContext inside any page registered via the SDK.
+ * Returns a context that updates automatically when dark mode changes.
+ *
+ * Must be called inside a component rendered within `HorizonContextProvider`.
+ *
+ * @example
+ * export default function MyPage() {
+ *   const { ui, theme, user, navigate } = useHorizonContext();
+ *   const { PageTemplate, DatagridTemplate } = ui.templates;
+ *   // `theme` is always 'light' | 'dark', reactive to system/user toggle
+ * }
+ */
+declare function useHorizonContext(): HorizonContext;
+/**
+ * Returns the current color scheme, reactive to host theme changes.
+ *
+ * Works in **both** contexts with the same import — no manual event wiring:
+ *
+ * - **Page components** (inside `HorizonContextProvider`): reads directly from
+ *   the provider's React context. No subscription overhead.
+ * - **Standalone extension components** (rendered by the host via
+ *   `registerDynamicExtension`): falls back to `eventBus` subscription.
+ *   Pass `context.eventBus` as the argument.
+ *
+ * @example
+ * // In a page component (HorizonContextProvider ancestor required)
+ * export default function MyPage() {
+ *   const { theme } = useTheme();
+ *   return <div style={{ color: theme === 'dark' ? '#fff' : '#000' }}>...</div>;
+ * }
+ *
+ * @example
+ * // In a standalone extension component
+ * export default function MyButton({ context }: ExtensionComponentProps) {
+ *   const { theme } = useTheme(context.eventBus);
+ *   const { Button } = context.ui ?? {};
+ *   return <Button>{theme === 'dark' ? '🌙' : '☀️'} Export</Button>;
+ * }
+ */
+/**
+ * Returns the current color scheme, reactive to host theme changes.
+ *
+ * @param eventBus - Pass `context.eventBus` when called from a standalone
+ *   extension component (outside a HorizonContextProvider).
+ * @param initialTheme - Pass `context.theme` when called from a standalone
+ *   extension component so the hook initialises with the correct value on
+ *   first render rather than defaulting to `'light'`.
+ *
+ * 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';
+};
+/**
+ * Returns the host's translation function and current locale.
+ *
+ * Because `i18next` is shared as a singleton, this hook reads directly from
+ * the host's already-initialized i18next instance — all host translations
+ * (common, telecom, admin, etc.) are immediately available with no extra
+ * fetch or setup required.
+ *
+ * Reactivity is handled internally by react-i18next: the returned `t` and
+ * `locale` update automatically when the user switches language.
+ *
+ * @param ns - Optional namespace(s). Defaults to `'common'` (the host
+ *   namespace that contains all standard UI strings). Pass your app's own
+ *   registered namespace to access remote-app-specific keys.
+ *
+ * @example
+ * // In a page component — access any host string
+ * export default function MyPage() {
+ *   const { t, locale } = useLocale();
+ *   return <Button>{t('SAVE')}</Button>;
+ * }
+ *
+ * @example
+ * // In an extension component — same API
+ * export function MyButton({ context }: ExtensionComponentProps) {
+ *   const { t } = useLocale();
+ *   const { Button } = context.ui ?? {};
+ *   return <Button>{t('EXPORT')}</Button>;
+ * }
+ */
+/**
+ * Returns the host's `t` translation function and current locale string.
+ *
+ * The `t` function is the host's i18next instance — all 1,375+ host strings
+ * across the common, telecom, admin, and validation namespaces are immediately
+ * available. No i18next dependency, no package install, no init required in
+ * the remote app.
+ *
+ * Both `t` and `locale` update automatically when the user switches language.
+ *
+ * @example
+ * export default function MyPage() {
+ *   const { t, locale } = useLocale();
+ *   return <Button>{t('SAVE')}</Button>;
+ * }
+ *
+ * @example
+ * // In a standalone extension component
+ * export function MyButton({ context }: ExtensionComponentProps) {
+ *   const { t } = useLocale();
+ *   return <span>{t('EXPORT')}</span>;
+ * }
+ */
+declare function useLocale(): {
+    t: HorizonContext['t'];
+    locale: string;
+};
+/**
+ * Get an SDK instance bound to your app, plus a flat view of the Horizon
+ * context. Returned `sdk.cleanup()` is called automatically on unmount.
+ *
+ * @example
+ * export default function MyApp(horizonContext: HorizonContext) {
+ *   const { sdk, user } = useRemoteApp(horizonContext, 'my-app');
+ *
+ *   useEffect(() => {
+ *     sdk.registerDynamicExtension({
+ *       id: 'my-app.button',
+ *       zone: 'page-header-actions',
+ *       routes: [{ pattern: '/manage/*\/users' }],
+ *       component: MyButton,
+ *     });
+ *   }, [sdk]);
+ *
+ *   return <div>Hello {user.displayName}</div>;
+ * }
+ */
+declare function useRemoteApp(horizonContext: HorizonContext, appId: string): {
+    user: HorizonUser;
+    auth: HorizonAuth;
+    api: HorizonApiClient;
+    theme: "light" | "dark";
+    locale: string;
+    t?: (key: string, options?: Record<string, unknown>) => string;
+    navigate: (path: string) => void;
+    eventBus: HorizonEventBus;
+    ui: HorizonUI;
+    breadcrumbs?: BreadcrumbItem[];
+    sdk: RemoteAppSDK;
+};
+/**
+ * Register a route for the lifetime of the calling component.
+ */
+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): {
+    loading: boolean;
+    error: Error | null;
+    sdk: RemoteAppSDK;
+};
+/**
+ * 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;
+/**
+ * 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;
+
+/**
+ * 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';
+interface HorizonSDKErrorOptions {
+    code: HorizonSDKErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+    cause?: Error;
+    statusCode?: number;
+}
+/**
+ * HorizonSDKError class
+ * Provides structured errors with error codes and additional context
+ */
+declare class HorizonSDKError extends Error {
+    readonly code: HorizonSDKErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: Error;
+    readonly statusCode?: number;
+    readonly timestamp: string;
+    constructor(options: HorizonSDKErrorOptions);
+    /**
+     * Check if error is a HorizonSDKError
+     */
+    static isHorizonSDKError(error: unknown): error is HorizonSDKError;
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+    /**
+     * Serialize error to JSON
+     */
+    toJSON(): object;
+    /**
+     * Get formatted error message for logging
+     */
+    toLogString(): string;
+}
+/**
+ * Helper function to create HorizonSDKError instances
+ */
+declare function createHorizonSDKError(code: HorizonSDKErrorCode, message: string, details?: Record<string, unknown>, cause?: Error): HorizonSDKError;
+/**
+ * Permission Denied Error
+ */
+declare function permissionDeniedError(resource: string, details?: Record<string, unknown>): HorizonSDKError;
+/**
+ * Rate Limit Exceeded Error
+ */
+declare function rateLimitError(resetTime: number, details?: Record<string, unknown>): HorizonSDKError;
+/**
+ * API Error
+ */
+declare function apiError(message: string, statusCode: number, details?: Record<string, unknown>, cause?: Error): HorizonSDKError;
+/**
+ * Invalid Extension Point Error
+ */
+declare function invalidExtensionPointError(pointId: string, validPoints: string[]): HorizonSDKError;
+/**
+ * Signature Verification Failed Error
+ */
+declare function signatureVerificationError(reason: string): HorizonSDKError;
+/**
+ * Module Load Failed Error
+ */
+declare function moduleLoadError(appId: string, url: string, cause?: Error): HorizonSDKError;
+
+/**
+ * Logging utility using loglevel for Horizon SDK
+ * Consistent with netsapiens-monorepo logging pattern
+ *
+ * Usage:
+ *   import { createLogger } from '../utils/logger';
+ *   const log = createLogger('ModuleLoader');
+ *   log.info('Loading module...');
+ *   log.error('Failed to load:', error);
+ */
+
+/**
+ * Create a namespaced logger for a specific module
+ * Follows the monorepo pattern from @netsapiens/ns-sdk
+ *
+ * @example
+ * const log = createLogger('ModuleLoader');
+ * log.debug('Starting load...');
+ * log.info('Module loaded successfully');
+ * log.warn('Slow load detected');
+ * log.error('Load failed:', error);
+ */
+declare const createLogger: (namespace: string) => loglevel.Logger;
+/**
+ * Default logger instance for the SDK
+ */
+declare const logger: loglevel.Logger;
+/**
+ * Set log level at runtime
+ * Useful for debugging
+ *
+ * @example
+ * import { setLogLevel } from './utils/logger';
+ * setLogLevel('DEBUG'); // Enable all logs
+ * setLogLevel('WARN');  // Only warnings and errors
+ */
+declare const setLogLevel: (level: "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "SILENT") => void;
+/**
+ * Get current log level
+ */
+declare const getLogLevel: () => 0 | 1 | 2 | 3 | 4 | 5;
+declare global {
+    interface Window {
+        __horizonSDKLogger__: typeof logger;
+        __setHorizonSDKLogLevel__: typeof setLogLevel;
+    }
+}
+
+/**
+ * Stable Anchor IDs for Extension Placement
+ *
+ * These anchor IDs are guaranteed to be stable and can be used by extensions
+ * to specify their menu placement using semantic anchors.
+ *
+ * @example
+ * ```typescript
+ * import { MANAGE_ANCHORS } from '@netsapiens/horizon-sdk';
+ *
+ * sdk.registerRoute({
+ *   id: 'my-crm',
+ *   parentPath: '/apps',
+ *   path: 'crm',
+ *   label: 'CRM',
+ *   placement: { after: MANAGE_ANCHORS.contacts }
+ * });
+ * ```
+ */
+/**
+ * Manage Menu Anchors
+ * Available in both domain and no-domain contexts
+ */
+declare const MANAGE_ANCHORS: {
+    readonly dashboard: "manage-dashboard";
+    readonly users: "manage-users";
+    readonly contacts: "manage-contacts";
+    readonly devices: "manage-devices";
+    readonly phoneNumbers: "manage-phone-numbers";
+    readonly callLogs: "manage-call-logs";
+    readonly voicemail: "manage-voicemail";
+    readonly fax: "manage-fax";
+    readonly settings: "manage-settings";
+};
+/**
+ * Platform Menu Anchors
+ * Available to Admin, Super User, and Reseller scopes
+ */
+declare const PLATFORM_ANCHORS: {
+    readonly dashboard: "platform-dashboard";
+    readonly codeManagement: "platform-code-management";
+    readonly configManagement: "platform-config-management";
+    readonly sdkManagement: "platform-ui-sdk";
+    readonly branding: "platform-branding";
+    readonly recording: "platform-recording";
+    readonly logsAndDiagnostics: "platform-logs-and-diagnostics";
+};
+/**
+ * Apps Menu Anchors
+ * Extension apps typically register here
+ */
+declare const APPS_ANCHORS: {
+    readonly home: "apps-home";
+};
+/**
+ * My Account Menu Anchors
+ * User-specific settings and preferences
+ */
+declare const MY_ACCOUNT_ANCHORS: {
+    readonly profile: "my-account-profile";
+    readonly preferences: "my-account-preferences";
+    readonly security: "my-account-security";
+};
+/**
+ * All anchor constants in one object for convenience
+ */
+declare const ANCHORS: {
+    readonly manage: {
+        readonly dashboard: "manage-dashboard";
+        readonly users: "manage-users";
+        readonly contacts: "manage-contacts";
+        readonly devices: "manage-devices";
+        readonly phoneNumbers: "manage-phone-numbers";
+        readonly callLogs: "manage-call-logs";
+        readonly voicemail: "manage-voicemail";
+        readonly fax: "manage-fax";
+        readonly settings: "manage-settings";
+    };
+    readonly platform: {
+        readonly dashboard: "platform-dashboard";
+        readonly codeManagement: "platform-code-management";
+        readonly configManagement: "platform-config-management";
+        readonly sdkManagement: "platform-ui-sdk";
+        readonly branding: "platform-branding";
+        readonly recording: "platform-recording";
+        readonly logsAndDiagnostics: "platform-logs-and-diagnostics";
+    };
+    readonly apps: {
+        readonly home: "apps-home";
+    };
+    readonly myAccount: {
+        readonly profile: "my-account-profile";
+        readonly preferences: "my-account-preferences";
+        readonly security: "my-account-security";
+    };
+};
+/**
+ * Type-safe anchor ID union
+ */
+type AnchorId = (typeof MANAGE_ANCHORS)[keyof typeof MANAGE_ANCHORS] | (typeof PLATFORM_ANCHORS)[keyof typeof PLATFORM_ANCHORS] | (typeof APPS_ANCHORS)[keyof typeof APPS_ANCHORS] | (typeof MY_ACCOUNT_ANCHORS)[keyof typeof MY_ACCOUNT_ANCHORS];
+
+declare const VERSION = "1.0.0";
+
+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 };