@managespace/sdk 0.1.156 → 0.1.158-extensions

package/src/extensibility/functions/project/billing.ts

@@ -104,19 +104,19 @@ export namespace Billing {
     }
 
     export class CreateContact implements ExtPlugin {
-        responseType!: Pick<Contact, 'id' | 'externalId'>;
+        responseType!: Pick<Contact, 'id' | 'msExternalId'>;
 
         payload!: CustomCreateContact & {
-            externalId: string;
+            msExternalId: string;
             customerId: string;
         };
     }
 
     export class UpdateContact implements ExtPlugin {
-        responseType!: Pick<Contact, 'id' | 'externalId'>;
+        responseType!: Pick<Contact, 'id' | 'msExternalId'>;
 
         payload!: CustomUpdateContact & {
-            externalId: string;
+            msExternalId: string;
             customerId: string;
         };
     }
@@ -128,14 +128,14 @@ export namespace Billing {
     }
 
     export class CreateCustomer implements ExtPlugin {
-        responseType!: Pick<Customer, 'id' | 'externalId'> & {
-            contacts: Pick<Contact, 'id' | 'externalId'>[];
+        responseType!: Pick<Customer, 'id' | 'msExternalId'> & {
+            contacts: Pick<Contact, 'id' | 'msExternalId'>[];
         };
 
         payload!: Omit<CustomCreateCustomer, 'contacts'> & {
-            externalId: string;
+            msExternalId: string;
             contacts: (CustomCreateContact & {
-                externalId: string;
+                msExternalId: string;
             })[];
         };
     }
@@ -170,8 +170,8 @@ export namespace Billing {
     }
 
     export class GetCustomers implements ExtPlugin {
-        responseType!: (Pick<Customer, 'id' | 'externalId'> & {
-            contacts: Pick<Contact, 'id' | 'externalId'>[];
+        responseType!: (Pick<Customer, 'id' | 'msExternalId'> & {
+            contacts: Pick<Contact, 'id' | 'msExternalId'>[];
         })[];
 
         payload!: BasePaginationQuery & { tenantId?: string; active?: boolean };
@@ -297,9 +297,9 @@ export namespace Billing {
     }
 
     export class UpdateCustomer implements ExtPlugin {
-        responseType!: Pick<Customer, 'id' | 'externalId'>;
+        responseType!: Pick<Customer, 'id' | 'msExternalId'>;
 
-        payload!: CustomUpdateCustomer & { externalId: string };
+        payload!: CustomUpdateCustomer & { msExternalId: string };
     }
 
     export class GetChartOfAccount implements ExtPlugin {

package/src/extensions/host-bridge.ts

@@ -0,0 +1,272 @@
+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

@@ -0,0 +1,40 @@
+/**
+ * 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

@@ -0,0 +1,120 @@
+/**
+ * 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;

package/src/generated/.openapi-generator/FILES

@@ -1,4 +1,5 @@
 apis/default-api.ts
+apis/extensions-api.ts
 apis/index.ts
 index.ts
 models/accounts-receivable-report-filters.ts
@@ -103,6 +104,8 @@ models/extensibility-function-instance.ts
 models/extensibility-function-metadata.ts
 models/extensibility-repo.ts
 models/extensibility-status.ts
+models/extension-org.ts
+models/extension.ts
 models/field-area.ts
 models/field-preferences.ts
 models/field-type.ts