@managespace/sdk 0.1.158-extensions → 0.1.159

package/src/extensions/host-bridge.ts

@@ -1,272 +0,0 @@
-import type {
-    EntityEvent,
-    EntityEventHandler,
-    ExtensionContext,
-    ExtensionMessage,
-    HostMessage,
-} from './types';
-
-let contextResolve: ((context: ExtensionContext) => void) | null = null;
-let currentContext: ExtensionContext | null = null;
-const entityEventHandlers: Set<EntityEventHandler> = new Set();
-
-// Set up message listener when this module loads
-if (typeof window !== 'undefined') {
-    window.addEventListener('message', (event: MessageEvent<HostMessage>) => {
-        if (!event.data?.type) return;
-
-        switch (event.data.type) {
-            case 'CONTEXT_INIT':
-                currentContext = event.data.payload;
-                if (contextResolve) {
-                    contextResolve(event.data.payload);
-                    contextResolve = null;
-                }
-                break;
-
-            case 'ENTITY_EVENT':
-                for (const handler of entityEventHandlers) {
-                    try {
-                        handler(event.data.payload);
-                    } catch (error) {
-                        console.error('Entity event handler error:', error);
-                    }
-                }
-                break;
-        }
-    });
-}
-
-/**
- * Get the extension context from the ManageSpace host.
- *
- * This returns a promise that resolves when the context is received from the host.
- * Call this early in your extension's lifecycle to get authentication and org context.
- *
- * @example
- * ```typescript
- * import { getContext } from '@managespace/sdk/extensions';
- *
- * const context = await getContext();
- * console.log('Org ID:', context.orgId);
- * console.log('API URL:', context.apiBaseUrl);
- * ```
- */
-export function getContext(): Promise<ExtensionContext> {
-    if (currentContext) {
-        return Promise.resolve(currentContext);
-    }
-
-    return new Promise((resolve) => {
-        contextResolve = resolve;
-    });
-}
-
-/**
- * Get the current context synchronously.
- *
- * Returns null if the context has not yet been received from the host.
- * Prefer using `getContext()` which waits for the context to be available.
- *
- * @example
- * ```typescript
- * import { getCurrentContext } from '@managespace/sdk/extensions';
- *
- * const context = getCurrentContext();
- * if (context) {
- *     console.log('Already have context:', context.orgId);
- * }
- * ```
- */
-export function getCurrentContext(): ExtensionContext | null {
-    return currentContext;
-}
-
-/**
- * Navigate the ManageSpace host application to a specific path.
- *
- * Use this to navigate users to pages within ManageSpace, such as
- * customer profiles, asset details, or other views.
- *
- * @param path - The path to navigate to (e.g., "/customer/123")
- *
- * @example
- * ```typescript
- * import { navigate } from '@managespace/sdk/extensions';
- *
- * // Navigate to a customer profile
- * navigate('/customer/abc-123');
- *
- * // Navigate to the assets page
- * navigate('/assets');
- * ```
- */
-export function navigate(path: string): void {
-    const message: ExtensionMessage = {
-        type: 'NAVIGATE',
-        payload: { path },
-    };
-    window.parent.postMessage(message, '*');
-}
-
-/**
- * Show a toast notification in the ManageSpace host application.
- *
- * Use this for user feedback after actions complete.
- *
- * @param message - The message to display
- * @param variant - The toast type: 'success' or 'error' (default: 'success')
- *
- * @example
- * ```typescript
- * import { showToast } from '@managespace/sdk/extensions';
- *
- * // Success notification
- * showToast('Customer updated successfully');
- *
- * // Error notification
- * showToast('Failed to save changes', 'error');
- * ```
- */
-export function showToast(message: string, variant: 'success' | 'error' = 'success'): void {
-    const msg: ExtensionMessage = {
-        type: 'SHOW_TOAST',
-        payload: { message, variant },
-    };
-    window.parent.postMessage(msg, '*');
-}
-
-/**
- * Signal to the ManageSpace host that the extension is ready to receive context.
- *
- * Call this after your extension has loaded and set up its message listeners.
- * The host will respond with a CONTEXT_INIT message containing the ExtensionContext.
- *
- * @example
- * ```typescript
- * import { signalReady, getContext } from '@managespace/sdk/extensions';
- *
- * // Signal ready and wait for context
- * signalReady();
- * const context = await getContext();
- * ```
- */
-export function signalReady(): void {
-    const message: ExtensionMessage = { type: 'READY' };
-    window.parent.postMessage(message, '*');
-}
-
-/**
- * Subscribe to entity events from the ManageSpace host.
- *
- * The host sends events when entities (customers, assets, etc.) are
- * created, updated, or deleted. Use this to keep your extension in sync.
- *
- * @param handler - Callback function to handle entity events
- * @returns Unsubscribe function to remove the handler
- *
- * @example
- * ```typescript
- * import { onEntityEvent } from '@managespace/sdk/extensions';
- *
- * const unsubscribe = onEntityEvent((event) => {
- *     if (event.entityType === 'customer' && event.action === 'updated') {
- *         console.log('Customer updated:', event.entityId);
- *         refreshCustomerData();
- *     }
- * });
- *
- * // Later, to stop listening:
- * unsubscribe();
- * ```
- */
-export function onEntityEvent(handler: EntityEventHandler): () => void {
-    entityEventHandlers.add(handler);
-    return () => {
-        entityEventHandlers.delete(handler);
-    };
-}
-
-/**
- * Create a configured fetch function for calling the ManageSpace API.
- *
- * This returns a fetch wrapper that automatically includes credentials
- * and sets the correct headers for API calls.
- *
- * @param context - The extension context from getContext()
- * @returns A fetch function configured for ManageSpace API calls
- *
- * @example
- * ```typescript
- * import { getContext, createApiFetch } from '@managespace/sdk/extensions';
- *
- * const context = await getContext();
- * const apiFetch = createApiFetch(context);
- *
- * // Fetch customers
- * const response = await apiFetch('/api/crm/customers/queries', {
- *     method: 'POST',
- *     body: JSON.stringify({
- *         pageOptions: { offset: 0, limit: 20 }
- *     })
- * });
- * const data = await response.json();
- * ```
- */
-export function createApiFetch(
-    context: ExtensionContext,
-): (path: string, options?: RequestInit) => Promise<Response> {
-    return (path: string, options: RequestInit = {}) => {
-        const url = `${context.apiBaseUrl}${path}`;
-        return fetch(url, {
-            ...options,
-            credentials: 'include',
-            headers: {
-                'Content-Type': 'application/json',
-                ...options.headers,
-            },
-        });
-    };
-}
-
-/**
- * Create a configured fetch function for calling your extension's BFF.
- *
- * This returns a fetch wrapper that forwards credentials to your BFF,
- * allowing it to make authenticated calls to the ManageSpace API.
- *
- * @param context - The extension context from getContext()
- * @returns A fetch function configured for BFF calls, or null if no BFF is configured
- *
- * @example
- * ```typescript
- * import { getContext, createBffFetch } from '@managespace/sdk/extensions';
- *
- * const context = await getContext();
- * const bffFetch = createBffFetch(context);
- *
- * if (bffFetch) {
- *     const response = await bffFetch('/api/enriched-customers');
- *     const data = await response.json();
- * }
- * ```
- */
-export function createBffFetch(
-    context: ExtensionContext,
-): ((path: string, options?: RequestInit) => Promise<Response>) | null {
-    if (!context.bffUrl) {
-        return null;
-    }
-
-    return (path: string, options: RequestInit = {}) => {
-        const url = `${context.bffUrl}${path}`;
-        return fetch(url, {
-            ...options,
-            credentials: 'include',
-            headers: {
-                'Content-Type': 'application/json',
-                ...options.headers,
-            },
-        });
-    };
-}

package/src/extensions/index.ts

@@ -1,40 +0,0 @@
-/**
- * ManageSpace Extension SDK
- *
- * This module provides utilities for building extensions that run within
- * the ManageSpace platform. Extensions are loaded in iframes and communicate
- * with the host application via postMessage.
- *
- * @example
- * ```typescript
- * import {
- *     getContext,
- *     signalReady,
- *     navigate,
- *     showToast,
- *     createApiFetch,
- * } from '@managespace/sdk/extensions';
- *
- * // Signal ready and get context
- * signalReady();
- * const context = await getContext();
- *
- * // Create API client
- * const apiFetch = createApiFetch(context);
- *
- * // Fetch data
- * const response = await apiFetch('/api/crm/customers/queries', {
- *     method: 'POST',
- *     body: JSON.stringify({ pageOptions: { offset: 0, limit: 20 } })
- * });
- *
- * // Navigate and show feedback
- * navigate('/customer/123');
- * showToast('Customer loaded');
- * ```
- *
- * @module extensions
- */
-
-export * from './types';
-export * from './host-bridge';

package/src/extensions/types.ts

@@ -1,120 +0,0 @@
-/**
- * Extension context injected by the ManageSpace host application.
- * This is received via postMessage when the extension loads.
- */
-export interface ExtensionContext {
-    /**
-     * Authentication token for API calls.
-     * Note: When calling the ManageSpace API, use `credentials: 'include'` instead
-     * of passing this token directly. The token is provided for BFF authentication.
-     */
-    token: string;
-
-    /** The organisation ID the user is currently viewing */
-    orgId: string;
-
-    /** The authenticated user's ID */
-    userId: string;
-
-    /** The site ID the user is currently viewing (may be empty if at org level) */
-    siteId: string;
-
-    /** List of permission strings the user has */
-    permissions: Array<string>;
-
-    /**
-     * Base URL for ManageSpace API calls.
-     * Example: "http://localhost:5173/gateway"
-     */
-    apiBaseUrl: string;
-
-    /**
-     * BFF URL from the extension manifest, if configured.
-     * Use this to call your extension's backend.
-     */
-    bffUrl?: string;
-}
-
-/**
- * Messages sent from the ManageSpace host to the extension.
- */
-export type HostMessage =
-    | { type: 'CONTEXT_INIT'; payload: ExtensionContext }
-    | {
-          type: 'ENTITY_EVENT';
-          payload: {
-              entityType: string;
-              entityId: string;
-              action: 'created' | 'updated' | 'deleted';
-          };
-      };
-
-/**
- * Messages sent from the extension to the ManageSpace host.
- */
-export type ExtensionMessage =
-    | { type: 'NAVIGATE'; payload: { path: string } }
-    | { type: 'SHOW_TOAST'; payload: { message: string; variant: 'success' | 'error' } }
-    | { type: 'READY' };
-
-/**
- * Extension manifest format.
- * This file (manifest.json) must be included in your extension bundle.
- */
-export interface ExtensionManifest {
-    /** Display name of the extension */
-    name: string;
-
-    /** Semantic version (e.g., "1.0.0") */
-    version: string;
-
-    /** Author or company name */
-    author: string;
-
-    /** Short description of what the extension does */
-    description?: string;
-
-    /** Label shown in the navigation menu */
-    navLabel: string;
-
-    /**
-     * Icon name for the navigation menu.
-     * Use Lucide icon names (e.g., "Users", "Settings", "BarChart")
-     */
-    navIcon: string;
-
-    /**
-     * Route path for the extension (e.g., "/extensions/my-extension").
-     * Must start with "/extensions/"
-     */
-    navRoute: string;
-
-    /** Entry point HTML file (usually "index.html") */
-    entryPoint: string;
-
-    /** Optional BFF (Backend for Frontend) configuration */
-    bff?: {
-        /** URL of the BFF server */
-        url: string;
-    };
-}
-
-/**
- * Entity event payload received when ManageSpace entities change.
- * Subscribe to these events to react to changes in the host application.
- */
-export interface EntityEvent {
-    /** Type of entity (e.g., "customer", "asset", "subscription") */
-    entityType: string;
-
-    /** ID of the affected entity */
-    entityId: string;
-
-    /** What happened to the entity */
-    action: 'created' | 'updated' | 'deleted';
-}
-
-/**
- * Callback type for entity event handlers.
- */
-export type EntityEventHandler = (event: EntityEvent) => void;